aontu 0.63.0 → 0.64.0

package/src/cli.ts

@@ -17,16 +17,14 @@ import {
   hcanon, canonHash,
   get, why, patch, agentsMd,
   allow,
-  render,
-  renderProfile,
+  loadProfile,
 } from './aontu'
 import type { AllowDecision, AllowReport, AllowVerdict } from './allow'
-import type { RenderCoverage, RenderReport } from './render'
+import { traceRun } from './trace'
 import {
   desugarTemplate, resugarTemplate, templateOutputs, markerFor,
   markerFromProfiles,
 } from './template'
-import { outsideRoot } from './mcp'
 import { sarifReport } from './report-sarif'
 import { main as lspMain } from './lsp-server'
 import { main as mcpMain } from './mcp-server'
@@ -83,11 +81,10 @@ const HELP = `Usage: aontu [options] [file]
        aontu view <kind> [options] <file>...
        aontu view --views <path> [--check] [options] <file>
        aontu jsonschema [--at <path>] [--strict] [options] <file>
-       aontu render [--at <path>] [--profile <file>]... [--unit <path>]
-                    [--stdout | --out <dir> | --check <dir> | --coverage]
-                    [--coverage-at <path>] [--strict] <file>
        aontu template [--resugar] [--check] [--marker <token>]
                       [--profile <file>] <file>
+       aontu trace [--at <path>] [--format json] [--marker <token>]
+                   [--profile <file>] <file>
        aontu hash [options] <file>
        aontu mod tidy|verify|vendor|manifest [options] [dir]
        aontu get <path> [options] <file>
@@ -333,37 +330,11 @@ 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.
 
-Render options:
-  --at <path>       Render the value at this path ($.a.b); the root by
-                    default
-  --profile <file>  A profile document, aontu: render: Lang: {lang,
-                    ...}, vetted against aontu:render; repeatable,
-                    one per language
-  --unit <path>     Render only the unit with this path
-  --stdout          One unit's bytes and nothing else (with --unit when
-                    the instance has several)
-  --out <dir>       Write every unit below dir, or nothing; never deletes
-  --check <dir>     Compare every unit with dir/<path>; drift is listed
-  --coverage        Report what the render read and what it did not:
-                    model paths no output consumed, and rendered
-                    declarations no rule produced. Writes nothing
-  --coverage-at <p> Measure coverage under this path only, instead of
-                    the document root
-  --strict          Refuse the opaque escapes (a text declaration, a raw
-                    block)
-  --format <f>      text (default) or json, the whole report; json
-                    carries the dispatch trace, one entry per emitted
-                    piece
-
-Render exit codes: 0 rendered, 1 lossy under --strict or drift under
---check, 2 usage or I/O (a refused unit path included), 4 the document
-does not stand up or the instance is not aontu:code.
-
-A render entry file whose extension is not .aon is a TEMPLATE: a
-generator 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, or declares it once in a profile file that --profile reads.
+A template entry file whose extension is not .aon 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,
+or declares it once in a profile file that --profile reads.
 
 Template options:
   --resugar       The file is the canonical aontu; print the template
@@ -473,11 +444,11 @@ 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 render:
-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 in it is
-another language's, and is refused.
+A file whose extension is not .aon 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
+in it is another language's, and is refused.
 
 Fmt exit codes: 0 formatted or clean, 1 a --check file would change or
 a --strict finding, 2 usage, 4 a document does not parse.
@@ -2080,6 +2051,12 @@ const VIEW_USAGE_CODES = [
 const MOD_HELP = 'aontu mod tidy|verify|vendor|manifest [dir] (try --help)'
 
 function runMod(argv: string[]): number {
+  const trusted = takeTrust(argv)
+  if (null == trusted) {
+    return 2
+  }
+  argv = trusted.argv
+  const trust = trusted.trust
   const rest: string[] = []
   let format: SubsumeFormat = 'text'
   let against: string | undefined
@@ -2145,11 +2122,13 @@ function runMod(argv: string[]): number {
     return 2
   }
 
+  const modopts = modToolOptions(trust, resolve(dir))
+
   const report =
-    'tidy' === sub ? modTidy(dir, modToolOptions()) :
-      'verify' === sub ? modVerify(dir, modToolOptions()) :
-        'vendor' === sub ? modVendor(dir, modToolOptions()) :
-          modManifest(dir, modToolOptions(), against)
+    'tidy' === sub ? modTidy(dir, modopts) :
+      'verify' === sub ? modVerify(dir, modopts) :
+        'vendor' === sub ? modVendor(dir, modopts) :
+          modManifest(dir, modopts, against)
 
   process.stdout.write(('json' === format ?
     exactJSON({ aontu: { version: version(), verb: 'mod ' + sub }, ...report },
@@ -2188,11 +2167,16 @@ const MOD_EXIT: Record<ModVerdict, number> = {
 // The tooling's evaluator: the same standalone evaluation the module
 // resolver verifies with (ts/src/mod.ts), and for the same reason —
 // only the engine can say what a module MEANS.
-function modToolOptions() {
+function modToolOptions(trust: TrustArg, entryRoot: string) {
+  const opts = verbOpts(trust, entryRoot)
+  // The user cache lives outside any confinement root, so a confined
+  // run reads the vendor tree only -- as the evaluator's own module
+  // leg already does when a root is set.
+  const rooted = null != (opts.trust as any)?.include?.root
   return {
-    cache: modCacheDir(),
+    ...(rooted ? {} : { cache: modCacheDir() }),
     eval: (src: string, path: string) => {
-      const a0 = new Aontu()
+      const a0 = new Aontu(opts)
       const ctx = a0.ctx({ collect: true })
       const val: any = a0.unify(src, { path }, ctx)
       return {
@@ -2341,6 +2325,120 @@ function runRelations(argv: string[]): number {
   return RELATIONS_EXIT[report.verdict]
 }
 
+const TRACE_HELP =
+  'aontu trace [--at <path>] [--format json] [--marker <token>] ' +
+  '[--profile <file>] <file>'
+
+
+// WHAT WROTE THIS LINE. Every piece a rule stamped, under the
+// component tree, with the file it reached, the rule set that wrote it
+// and the model node the dispatch matched.
+function runTrace(argv: string[]): 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: 'text' | 'json' = 'text'
+  let at: string | undefined = undefined
+  let marker: string | undefined = undefined
+
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i]
+    if ('-h' === arg || '--help' === arg) {
+      process.stdout.write(HELP)
+      return 0
+    }
+    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) {
+        process.stderr.write('aontu: --at needs a path\n')
+        return 2
+      }
+    }
+    else if ('--marker' === arg) {
+      marker = argv[++i]
+      if (null == marker) {
+        process.stderr.write('aontu: --marker needs a token\n')
+        return 2
+      }
+    }
+    else if ('--profile' === arg) {
+      const pf = argv[++i]
+      if (null == pf) {
+        process.stderr.write('aontu: --profile needs a file\n')
+        return 2
+      }
+      profileFiles.push(pf)
+    }
+    else if (arg.startsWith('-')) {
+      process.stderr.write(`aontu: unknown trace option ${arg} (try --help)\n`)
+      return 2
+    }
+    else {
+      rest.push(arg)
+    }
+  }
+
+  if (1 !== rest.length) {
+    process.stderr.write(`aontu: trace needs one file\n${TRACE_HELP}\n`)
+    return 2
+  }
+
+  let src: string
+  try {
+    src = readFileSync(rest[0], 'utf8')
+  }
+  catch (err: any) {
+    process.stderr.write(`aontu: cannot read ${err.path}: ${err.message}\n`)
+    return 2
+  }
+
+  const declared = loadProfiles(profileFiles, trust)
+  if ('number' === typeof declared) {
+    return declared
+  }
+
+  // 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')) {
+    src = desugarTemplate(src, marker ??
+      markerFromProfiles(declared, rest[0]) ?? markerFor(rest[0]))
+  }
+
+  const report = traceRun(src, {
+    path: rest[0], at,
+    ...verbOpts(trust, entryRootOf(rest[0])),
+  })
+  if ('error' === report.verdict) {
+    // An error report always carries its findings.
+    const errors = report.errors as VetFinding[]
+    process.stderr.write(errors.map(renderFinding).join('\n') + '\n')
+    return 4
+  }
+  if ('json' === format) {
+    process.stdout.write(JSON.stringify({ trace: report.trace }) + '\n')
+    return 0
+  }
+  for (const e of report.trace) {
+    process.stdout.write(
+      [e.file, e.at, e.node, e.rule].join('\t') + '\n')
+  }
+  return 0
+}
+
+
 function runReaches(argv: string[]): number {
   const trusted = takeTrust(argv)
   if (null == trusted) {
@@ -2955,302 +3053,6 @@ function runJsonSchema(argv: string[]): number {
 }
 
 
-const RENDER_HELP =
-  'aontu render [--at <path>] [--profile <file>]... [--unit <path>] ' +
-  '[--stdout | --out <dir> | --check <dir> | --coverage] ' +
-  '[--coverage-at <path>] [--strict] [--marker <token>] <file> (try --help)'
-
-function runRender(argv: string[]): number {
-  const trusted = takeTrust(argv)
-  if (null == trusted) {
-    return 2
-  }
-  argv = trusted.argv
-  const trust = trusted.trust
-  const files: string[] = []
-  const profileFiles: string[] = []
-  let format: SubsumeFormat = 'text'
-  let at: string | undefined = undefined
-  let unit: string | undefined = undefined
-  let out: string | undefined = undefined
-  let check: string | undefined = undefined
-  let toStdout = false
-  let strict = false
-  let coverage = false
-  let coverageAt: string | undefined = undefined
-  let marker: string | undefined = undefined
-
-  for (let i = 0; i < argv.length; i++) {
-    const arg = argv[i]
-    if ('-h' === arg || '--help' === arg) {
-      process.stdout.write(HELP)
-      return 0
-    }
-    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) {
-        process.stderr.write('aontu: --at needs a path\n')
-        return 2
-      }
-    }
-    else if ('--unit' === arg) {
-      unit = argv[++i]
-      if (null == unit) {
-        process.stderr.write('aontu: --unit needs a unit path\n')
-        return 2
-      }
-    }
-    else if ('--profile' === arg) {
-      const pf = argv[++i]
-      if (null == pf) {
-        process.stderr.write('aontu: --profile needs a file\n')
-        return 2
-      }
-      profileFiles.push(pf)
-    }
-    else if ('--out' === arg) {
-      out = argv[++i]
-      if (null == out) {
-        process.stderr.write('aontu: --out needs a directory\n')
-        return 2
-      }
-    }
-    else if ('--check' === arg) {
-      check = argv[++i]
-      if (null == check) {
-        process.stderr.write('aontu: --check needs a directory\n')
-        return 2
-      }
-    }
-    else if ('--stdout' === arg) {
-      toStdout = true
-    }
-    else if ('--coverage' === arg) {
-      coverage = true
-    }
-    else if ('--marker' === arg) {
-      marker = argv[++i]
-      if (null == marker) {
-        process.stderr.write('aontu: --marker needs a token\n')
-        return 2
-      }
-    }
-    else if ('--coverage-at' === arg) {
-      coverageAt = argv[++i]
-      if (null == coverageAt) {
-        process.stderr.write('aontu: --coverage-at needs a path\n')
-        return 2
-      }
-    }
-    else if ('--strict' === arg) {
-      strict = true
-    }
-    else if (arg.startsWith('-')) {
-      process.stderr.write(
-        `aontu: unknown render option ${arg} (try --help)\n`)
-      return 2
-    }
-    else {
-      files.push(arg)
-    }
-  }
-
-  if (1 !== files.length) {
-    process.stderr.write(`aontu: render needs one file\n${RENDER_HELP}\n`)
-    return 2
-  }
-  const modes = [toStdout, undefined !== out, undefined !== check, coverage]
-    .filter((on) => on).length
-  if (1 < modes) {
-    process.stderr.write(
-      'aontu: render takes one of --stdout, --out, --check or --coverage\n')
-    return 2
-  }
-  // A NARROWER MEASURE NEEDS SOMETHING TO NARROW. `--coverage-at`
-  // without `--coverage` asks for a report the run does not compute,
-  // and answering silently would be the wrong half of the request.
-  if (undefined !== coverageAt && !coverage) {
-    process.stderr.write('aontu: --coverage-at needs --coverage\n')
-    return 2
-  }
-
-  let src: string
-  try {
-    src = readFileSync(files[0], 'utf8')
-  }
-  catch (err: any) {
-    process.stderr.write(`aontu: cannot read ${err.path}: ${err.message}\n`)
-    return 2
-  }
-
-  const loadedProfiles = loadProfiles(profileFiles, trust)
-  if ('number' === typeof loadedProfiles) {
-    return loadedProfiles
-  }
-  const profiles = loadedProfiles
-
-  if (!files[0].endsWith('.aon')) {
-    src = desugarTemplate(src, marker ??
-      markerFromProfiles(profiles, files[0]) ?? markerFor(files[0]))
-  }
-
-  // A RENDER WITH NO PROFILE PRODUCES NO UNITS, and said so with zero
-  // bytes and exit 0. The profile is what maps a model onto a
-  // language, so without one there is nothing for the renderer to
-  // write -- which is a usable answer only if the caller is told.
-  const noProfiles = 0 === profiles.length
-  const report = render(src, {
-    at, unit, strict, profiles, path: files[0],
-    coverage, coverageAt,
-    // THE JSON REPORT CARRIES THE TRACE (D9), which is what the shape
-    // there has always said; a text run computes it only when the
-    // coverage report needs it.
-    trace: 'json' === format,
-    ...verbOpts(trust, entryRootOf(files[0])),
-  })
-
-  // Said once, whatever the format: stdout stays the report.
-  if ('error' !== report.verdict && 0 === report.units.length) {
-    vacuous('nothing was rendered',
-      noProfiles
-        ? 'no profile was given, and the document declares none' +
-        ' (see aontu help tasks)'
-        : 'the document produced no units under this profile')
-  }
-
-  if ('json' === format) {
-    process.stdout.write(exactJSON({
-      aontu: { version: version(), verb: 'render' },
-      verdict: report.verdict,
-      units: report.units,
-      lossy: report.lossy,
-      ...(null == report.errors ? {} : { errors: report.errors }),
-      ...(null == report.trace ? {} : { trace: report.trace }),
-      ...(null == report.coverage ? {} : { coverage: report.coverage }),
-    }, 2) + '\n')
-    return renderExit(report, 0)
-  }
-  if ('error' === report.verdict) {
-    process.stderr.write(
-      (report.errors as VetFinding[]).map(renderFinding).join('\n') + '\n')
-    return renderExit(report, 0)
-  }
-
-  let drift = 0
-  if (toStdout) {
-    // ONE UNIT'S BYTES AND NOTHING ELSE, so the output can be piped
-    // into a formatter or a file.
-    if (1 !== report.units.length) {
-      process.stderr.write(
-        'aontu: --stdout needs exactly one unit, and the instance has ' +
-        `${report.units.length}; --unit names one\n`)
-      return 2
-    }
-    process.stdout.write(report.units[0].text)
-  }
-  else if (undefined !== out) {
-    // EVERY UNIT BELOW <dir>, OR NOTHING: every unit rendered first
-    // (the report above), and no file touched unless all did. The
-    // directory is realpath-confined; a unit path is already a relative
-    // descent (render_path refuses the rest), and the check here is
-    // against the symlink inside it. render never deletes.
-    for (const u of report.units) {
-      if (outsideRoot(out, resolve(out, u.path))) {
-        process.stderr.write(`aontu: ${u.path} escapes ${out}\n`)
-        return 2
-      }
-    }
-    for (const u of report.units) {
-      const full = resolve(out, u.path)
-      try {
-        mkdirSync(dirname(full), { recursive: true })
-        writeFileSync(full, u.text, 'utf8')
-      }
-      catch (err: any) {
-        process.stderr.write(`aontu: cannot write ${u.path}: ${err.message}\n`)
-        return 2
-      }
-      process.stderr.write(`wrote ${u.path}\n`)
-    }
-  }
-  else if (undefined !== check) {
-    // RENDER AND COMPARE: a unit whose bytes differ from the file at
-    // <dir>/<path>, or whose file is absent, is drift, listed by path.
-    // The CI form.
-    for (const u of report.units) {
-      let have: string | undefined = undefined
-      try {
-        have = readFileSync(resolve(check, u.path), 'utf8')
-      }
-      catch {
-        // Absent is drift, reported below.
-      }
-      if (undefined === have) {
-        drift++
-        process.stderr.write(`aontu: ${u.path} is missing from ${check}\n`)
-      }
-      else if (have !== u.text) {
-        drift++
-        process.stderr.write(`aontu: ${u.path} differs from the rendered unit\n`)
-      }
-    }
-  }
-  else if (coverage) {
-    // THE COVERAGE REPORT (P7), one line per finding and a count at
-    // the end: dead model first, then the declarations no rule
-    // produced. A clean report is the count line alone.
-    const cov = report.coverage as RenderCoverage
-    for (const d of cov.dead) {
-      process.stdout.write(`dead: ${d}\n`)
-    }
-    for (const u of cov.unruled) {
-      process.stdout.write(`unruled: ${u.unit} ${u.path}\n`)
-    }
-    process.stdout.write(
-      `coverage: ${cov.read.length} path(s) read, ${cov.dead.length} ` +
-      `no output consumed, ${cov.unruled.length} declaration(s) ` +
-      'no rule produced\n')
-  }
-  else {
-    // THE SUMMARY: one line per unit -- its path, its language and its
-    // size -- since several units have no one text to print.
-    for (const u of report.units) {
-      process.stdout.write(`${u.path}\t${u.lang}\t${u.text.length} bytes\n`)
-    }
-  }
-  for (const l of report.lossy) {
-    process.stderr.write(
-      `lossy: ${l.unit} ${l.path} tier ${l.tier} ${l.construct}: ${l.reason}\n`)
-  }
-  return renderExit(report, drift)
-}
-
-// D8's exit table over a report: a refused unit path is usage (2), a
-// strict refusal is lossy (1), any other error is the document's (4);
-// drift under --check is 1.
-function renderExit(report: RenderReport, drift: number): number {
-  if ('error' === report.verdict) {
-    const errors = report.errors as VetFinding[]
-    if (errors.every((f) => 'render_path' === f.code)) {
-      return 2
-    }
-    if (errors.every((f) => 'render_strict' === f.code)) {
-      return 1
-    }
-    return 4
-  }
-  return 0 < drift ? 1 : 0
-}
-
-
 const TEMPLATE_HELP =
   'aontu template [--resugar] [--check] [--marker <token>] <file> (try --help)'
 
@@ -3356,9 +3158,9 @@ function runTemplate(argv: string[]): number {
 
 
 // The profiles named by --profile, vetted, or the exit code that says
-// why not. A profile is a language declared as data: `render` matches
-// one to a unit by `lang`, and `template` and `fmt` match one to a file
-// by the extensions its `template.ext` names.
+// why not. A profile is a language declared as data: `template` and
+// `fmt` match one to a file by the extensions its `template.ext`
+// names.
 function loadProfiles(
   profileFiles: string[], trust: TrustArg
 ): any[] | number {
@@ -3373,7 +3175,7 @@ function loadProfiles(
       process.stderr.write(`aontu: cannot read ${err.path}: ${err.message}\n`)
       return 2
     }
-    const loaded = renderProfile(text,
+    const loaded = loadProfile(text,
       { path: resolve(pf), ...verbOpts(trust, entryRootOf(pf)) })
     if (undefined !== loaded.errors) {
       process.stderr.write(loaded.errors.map(renderFinding).join('\n') + '\n')
@@ -4138,8 +3940,8 @@ function runFmt(argv: string[]): number | Promise<number> {
     }
     else if ('--marker' === arg) {
       // THE MARKER SAYS THE FILE IS A GENERATOR, whatever its
-      // extension: `render` and `template` take the same option for
-      // the same reason, a language the table has never seen.
+      // extension: `fmt` and `template` take the same option for the
+      // same reason, a language the table has never seen.
       marker = argv[++i]
       if (null == marker) {
         process.stderr.write('aontu: --marker needs a token\n')
@@ -4616,8 +4418,8 @@ function runInit(argv: string[]): number {
 const KNOWN_VERBS = [
   'agentsmd', 'allow', 'breaking', 'explain', 'fmt', 'get', 'hash',
   'help', 'init', 'jsonschema', 'lsp', 'mcp', 'mod', 'reaches',
-  'relations', 'render', 'set', 'subsume', 'template', 'trim', 'vet',
-  'view', 'why',
+  'relations', 'set', 'subsume', 'template', 'trace', 'trim',
+  'vet', 'view', 'why',
 ]
 
 
@@ -4758,14 +4560,15 @@ function main(argv: string[], servers: Servers = SERVERS): void {
     return finish(runJsonSchema(argv.slice(3)))
   }
 
-  if ('render' === argv[2]) {
-    return finish(runRender(argv.slice(3)))
-  }
 
   if ('template' === argv[2]) {
     return finish(runTemplate(argv.slice(3)))
   }
 
+  if ('trace' === argv[2]) {
+    return finish(runTrace(argv.slice(3)))
+  }
+
   if ('reaches' === argv[2]) {
     return finish(runReaches(argv.slice(3)))
   }
@@ -4869,7 +4672,7 @@ function main(argv: string[], servers: Servers = SERVERS): void {
   else {
     runStdin(mode, format, trust).then((code) => finish(code))
   }
-} /* node:coverage ignore next 20 */
+} /* node:coverage ignore next 21 */
 
 
 // No require.main guard here: bin/aontu.js is the executable entry and
@@ -4881,8 +4684,8 @@ export {
   runReaches,
   runView,
   runJsonSchema,
-  runRender,
   runTemplate,
+  runTrace,
   runMod,
   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## Check code against a model\n\n```\naontu render --check src/ --profile go.aon model.aon\n```\n\n`render` writes code from the model; `--check` writes nothing and\nlists what on disk differs from what the model implies. That is the\ngate: the model is the truth, the code is the claim, and drift is a\nfinding. `--coverage` reports the other direction — model paths no\noutput consumed, and rendered declarations no rule produced.\n\n## Ask what a model says, and why\n\n```\naontu get  $.entity.planet.table model.aon\naontu why  $.entity.planet.table model.aon\naontu get  $.entity --keys       model.aon\naontu 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 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 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 get  $.entity.planet.table model.aon\naontu why  $.entity.planet.table model.aon\naontu get  $.entity --keys       model.aon\naontu 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 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",

package/src/hints.ts

@@ -211,6 +211,9 @@ const hints: Record<string, string> = {
 
   view_kind_unknown: 'The figure kind is not one the verb draws. The kinds are tree, matrix,\ngraph, layer, sets, layers, ladder and poset; the note lists them.',
 
+  // RETIRED with the `render` verb (ADR-038). Registered still,
+  // errcodes.tsv being append-only, so a code a released engine raised
+  // keeps its meaning.
   render_path: 'A unit path is written below the output directory: relative, with no\n`..` segment, and no two units the same. Rename the unit.',
   render_lang: 'A text escape carries verbatim syntax of ONE language, and it must be\nthe unit\'s: a text of another language in this unit would be written\nas if it were this one. Move it to a unit of its own language.',
   render_profile: 'Only fragments and text escapes render without a lowering, under the\ntext profile. A record, enum, alias, const or func needs a profile\nwhose language has one (typescript, go): set the unit\'s lang, or\nwrite the declaration as a fragment.',