aontu 0.60.0 → 0.62.0

package/src/cli.ts

@@ -23,11 +23,13 @@ import {
   exactJSON, vet, subsume, trimCheck, relationCheck,
   hcanon, canonHash,
   get, why, patch, agentsMd,
+  allow,
   render,
   renderProfile,
 } from './aontu'
+import type { AllowDecision, AllowReport, AllowVerdict } from './allow'
 import type { RenderCoverage, RenderReport } from './render'
-import { desugarTemplate, resugarTemplate, markerFor } from './template'
+import { desugarTemplate, resugarTemplate, templateOutputs, markerFor } from './template'
 import { outsideRoot } from './mcp'
 import { sarifReport } from './report-sarif'
 import { main as lspMain } from './lsp-server'
@@ -39,7 +41,9 @@ import type {
 } from './mod-tool'
 import { modCacheDir } from './mod'
 import { VET_MAX_ERRORS } from './vet'
-import type { VetReport, VetFinding, VetVerdict } from './vet'
+import type {
+  VetReport, VetFinding, VetVerdict, VetCoverage,
+} from './vet'
 import type {
   SubsumeReport, SubsumeVerdict, SubsumeProfile,
 } from './subsume'
@@ -57,11 +61,21 @@ import type { WhyRecord } from './provenance'
 import { agentsMdSplice } from './agentsmd'
 import { format, unifiedDiff } from './format'
 import { includeOpts } from './utility'
+import { HELPDOC, INITDOC } from './helpdoc'
+import type { HelpTopic } from './helpdoc'
+import { hints, codeClasses, codeClass } from './hints'
+import { cmpCodePoint } from './keyorder'
 import type { IncludeOptions } from './utility'
 
 
 type Mode = 'json' | 'canon'
 
+// The REPORT form of the bare command (G11 phase 7), which is a
+// separate axis from Mode: `--canon` chooses what the answer IS,
+// `--format` chooses how the answer is WRAPPED. Every other verb
+// spells the second one this way.
+type EvalFormat = 'text' | 'json'
+
 
 const HELP = `Usage: aontu [options] [file]
        aontu vet [options] <schema> <data> [more-data...]
@@ -82,8 +96,12 @@ const HELP = `Usage: aontu [options] [file]
        aontu get <path> [options] <file>
        aontu why <path> [options] <file>
        aontu set <path>=<value>... --entry <file> --overlay <file>
-       aontu agentsmd [--write <AGENTS.md>] <file>
-       aontu fmt [-w|-l|--check|-d|--lint] <file>...
+       aontu allow --role <role> [--at <path>] <roles-file> <path>...
+       aontu agentsmd [--write <AGENTS.md>] [--depth <n>] <file>
+       aontu fmt [-w|-l|--check|-d|--lint] [--marker <token>] <file>...
+       aontu help [topic] [--format text|json]
+       aontu explain <code> | --list [--format text|json]
+       aontu init [dir]
        aontu lsp
        aontu mcp [--root <dir>]
 
@@ -91,6 +109,34 @@ Evaluate an aontu source file and print the result as JSON.
 With no file on an interactive terminal, start a REPL.
 With no file and piped input, read the source from stdin.
 
+NEW TO THE LANGUAGE? This page documents the TOOL. The documentation
+of the LANGUAGE travels inside this binary, and this is how to reach it:
+
+  aontu help              List the topics this binary carries
+  aontu help tasks        Which verb does the job you have
+  aontu help language     The whole grammar, on one page
+  aontu help examples     The ladder, from plain JSON upward
+  aontu help codes        What a refusal means
+  aontu help grammar      The published ABNF
+  aontu explain <code>    What one error code a report carries means
+  aontu explain --list    Every registered code with its class
+
+Every one of those answers with no network and no checkout. The
+long-form documentation -- the tutorial, the language and API
+references, the how-to guides -- is in docs/ of the repository, which
+is where to go when the topics above are not enough; the contributor
+and agent guide is AGENTS.md beside it.
+
+NOTHING TO EDIT YET? aontu init [dir] writes a working model, an
+instance of it, and the four checks to run -- so the first
+document is an edit of something that already holds, rather than an
+invention. It refuses to overwrite.
+
+The one construct to know before writing anything: &: inside a map is
+a TEMPLATE that every key of that map must satisfy. A quoted "*" is a
+key named *, not a wildcard, and a schema written that way constrains
+nothing while still reporting valid.
+
 The vet verb validates data documents against a schema document and
 reports what does not hold, as text or as a machine-readable object.
 
@@ -100,7 +146,11 @@ query between a document and its own earlier versions.
 
 Options:
   -c, --canon     Print the canonical form instead of generated JSON
-  -h, --help      Show this help and exit
+  --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
+  -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
@@ -131,12 +181,28 @@ Vet options:
   --closed          Refuse keys the anchor does not declare
   --partial         Residue is reported but does not fail the run
   --max-errors <n>  Cap the finding list (default 20)
+  --coverage        Report what the check EXAMINED: how many data
+                    leaves a schema declaration constrained, the
+                    shallowest data paths none did, and the
+                    declarations no data met
+  --strict-coverage --coverage, and exit 1 when the run was VACUOUS --
+                    when no data leaf was constrained at all. The
+                    verdict word is unchanged, so nothing that passes
+                    today starts failing without this flag
+  --coverage-at <p> Measure coverage under this path of the data only
   --format <f>      text (default), json or sarif
   --watch           Re-run whenever a watched file changes
 
+A check that examined NOTHING and a check that passed answer the same
+without --coverage. The usual cause is a schema written with the
+wildcard other tools use: a quoted "*" is a key NAMED *, not a
+template, so it constrains nothing and the run still reports valid.
+The template is &: -- see aontu help language.
+
 Vet exit codes:
   0  valid       data unifies, and is concrete (or --partial)
-  1  invalid     at least one contradiction
+  1  invalid     at least one contradiction, or a vacuous run under
+                 --strict-coverage
   2  usage       bad option, or a file that cannot be read
   3  incomplete  no contradiction, but the truth is not yet satisfied
   4  error       the schema is unusable on its own
@@ -334,14 +400,61 @@ change contradicts a pinned value -- aontu why locates it, and
 --in-place rewrites it), 2 usage, 3 incomplete, 4 the entry does not
 stand up on its own.
 
+Allow options:
+  --role <role>     The role the caller is operating under (required)
+  --at <path>       Where the roles map lives in the role model
+                    (default $.roles)
+  --format <f>      text (default) or json
+
+The allow verb asks a role model whether a role may modify every one
+of the given subtrees, and answers before the change is made. The
+role model is an aontu document: one entry per role, each carrying
+allow (the subtrees it may modify) and optionally deny (the ones it
+may not), as path strings starting at $; * in a path matches any one
+key. A path is allowed when an allow entry is at or above it, and
+refused when a deny entry is at, above or below it, whatever the
+order. Every path starts with $, and may be spelled as set's
+assignment, <path>=<value>, whose value must be one value: a value
+carrying a second pair would write a subtree the gate was not asked
+about.
+
+Allow exit codes: 0 allowed (every path), 1 refused (at least one
+path, or a role the model does not declare), 2 usage, 4 the role
+model does not stand up on its own.
+
 Agentsmd options:
   --write <file>  Splice the stanza into this file between the
                   aontu:begin and aontu:end markers, appending them
                   when they are absent; the rest is left alone
+  --depth <n>     How deep the shape line projects (default 2). Two
+                  levels name the root keys and say top under them; a
+                  caller that wants the fields asks for them
 
 Agentsmd exit codes: 0 generated, 2 usage, 4 the document does not
 stand up on its own.
 
+Help options:
+  --format <f>    text (default) or json, the topic and its text
+
+The help verb prints the embedded teaching pack: the language, not the
+tool. With no topic it lists them. Topics are tasks, language,
+examples, codes and grammar; the corpus is generated from docs/skill/
+and grammar/aontu.abnf, so it cannot drift from those sources.
+
+Help exit codes: 0 printed, 2 an unknown topic (the topics are listed)
+or a bad option.
+
+Explain options:
+  --list          Every registered error code with its class
+  --format <f>    text (default) or json
+
+The explain verb answers what one error code means, from the same
+table the engine attaches to a finding. Every registered code has an
+entry, so a code read out of a report always resolves.
+
+Explain exit codes: 0 explained, 2 an unknown code (near matches are
+named) or a bad option.
+
 Fmt options:
   -w, --write     Rewrite each file in place, when its form would change
   -l, --list      Print the name of each file whose form would change
@@ -351,10 +464,18 @@ Fmt options:
   --lint          Report the style findings, key case and repeated
                   shapes, on standard error, and print nothing else
   --strict        With --lint, and exit 1 when there is a finding
+  --marker <t>    The file is a generator, and this is its marker
+                  (default //-, and #- --- /*- by extension)
 
 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.
+
 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.
 
@@ -391,13 +512,55 @@ function version(): string {
 }
 
 
+// The terminal colour escapes the parser puts in its message text. A
+// machine-readable report is no place for them, which is the rule
+// findingOf states in ts/src/vet.ts; the twin here rather than an
+// import because go/cmd/aontu carries its own for the same reason (the
+// engine's is not exported to its command).
+const EVAL_ANSI = new RegExp('\u001b\\[[0-9;]*m', 'g')
+
+
+// THE ENGINE'S DIAGNOSIS AS A FINDING (G11 phase 7). The bare command
+// was the one verb whose failure had no machine-readable form, so the
+// default entry point was the one an agent had to parse with a regular
+// expression.
+//
+// THE HEADLINE ONLY, and no `hint`. Both are parity decisions rather
+// than economies: the frames under the headline are drawn for a person
+// reading a terminal and only the first line is held to byte parity
+// between the ports (the rule findingOf states), and the hint TABLES
+// are deliberately not in parity while the code registry is -- so a
+// hint here would make the two ports answer differently for a code
+// only one of them explains. `aontu explain <code>` is where the hint
+// lives, which is what phase 3 built it for.
+//
+// The CLASS comes from the registry rather than from the nil, because
+// the registry is what both ports hold set-equal
+// (test/spec/errcodes.tsv). Mirrors evalFinding in
+// go/cmd/aontu/main.go.
+function evalFinding(code: string, text: string): VetFinding {
+  return {
+    class: codeClass(code),
+    code,
+    message: text.split('\n')[0].replace(EVAL_ANSI, ''),
+    path: '$',
+    severity: 'error',
+    // NO SITE. The bare command's failure is the whole document not
+    // standing up, and the two sites a conflict names are in the
+    // frames the text form prints; naming one of them here would be a
+    // choice the engine has not made.
+    sites: [],
+  }
+}
+
+
 // Evaluate source, returning either the rendered output or the error
-// message. Never throws.
+// message, and the failure in the finding shape. Never throws.
 function evalSource(
   aontu: Aontu,
   src: string,
   mode: Mode,
-): { ok: boolean; text: string } {
+): { ok: boolean; text: string; findings: VetFinding[] } {
   try {
     // exactJSON, not JSON.stringify: a document using the `0d` exact
     // leaves generates bigints and Decimals, which JSON.stringify cannot
@@ -408,17 +571,54 @@ function evalSource(
     const text = 'canon' === mode
       ? aontu.unify(src).canon
       : exactJSON(aontu.generate(src), 2)
-    return { ok: true, text }
+    return { ok: true, text, findings: [] }
   }
   catch (err: any) {
     const msg = (err instanceof AontuError || true === err?.aontu)
       ? err.message
       : String(err?.message ?? err)
-    return { ok: false, text: msg }
+    // WHAT THE ENGINE COLLECTED, when it collected anything: an
+    // AontuError carries the NilVals the run failed on, already
+    // materialised (handleErrors in ts/src/aontu.ts), and their first
+    // is the diagnosis every other verb reports. An error raised
+    // outside the engine's own collection -- exactJSON's circular
+    // refusal, a foreign object claiming to be one -- carries none,
+    // and answers with the text alone rather than an invented code.
+    const errs: any[] = 'function' === typeof err?.errs ? err.errs() : []
+    const first: any = errs[0]
+    return {
+      ok: false,
+      text: msg,
+      findings: null == first ? [] : [evalFinding(first.why, msg)],
+    }
   }
 }
 
 
+// The bare command's answer, in the form the caller asked for. The
+// text form is what it has always printed, on the stream the verdict
+// chooses; `--format json` is the same answer as one object, on
+// stdout, so a harness reads one stream and one shape either way.
+// Mirrors emit in go/cmd/aontu/main.go.
+function emitEval(
+  res: { ok: boolean; text: string; findings: VetFinding[] },
+  format: EvalFormat,
+): number {
+  if ('json' === format) {
+    process.stdout.write(exactJSON({
+      aontu: { version: version(), verb: 'eval' },
+      findings: res.findings,
+      ok: res.ok,
+      out: res.ok ? res.text : '',
+    }, 2) + '\n')
+  }
+  else {
+    ;(res.ok ? process.stdout : process.stderr).write(res.text + '\n')
+  }
+  return res.ok ? 0 : 1
+}
+
+
 // The include capability the main verb runs with (G5, docs/trust.md).
 // `--trust` and `--include-root` set it explicitly; the default is
 // 'system' WITH the warning window: every resolution that escapes the
@@ -592,12 +792,35 @@ function entryRootOf(file: string | undefined): string {
 }
 
 
-function runFile(file: string, mode: Mode, trust: TrustArg): number {
+function runFile(
+  file: string, mode: Mode, format: EvalFormat, trust: TrustArg): number {
   let src: string
   try {
     src = readFileSync(file, 'utf8')
   }
   catch (err: any) {
+    // A MISTYPED VERB READS AS A FILE NAME, and until G11 phase 2 that
+    // was only said when there were TWO of them. The one-argument case
+    // is the one an agent actually produces -- `aontu help`, `aontu
+    // init`, `aontu ontology` -- and it answered `cannot read help:
+    // ...`, which describes the symptom and hides the cause.
+    //
+    // The test is SHAPE, not existence: a bare word (no separator, no
+    // extension) that cannot be read was meant as a verb, while
+    // `./help`, `help.aon` and `/tmp/help` were meant as paths and keep
+    // the file diagnosis and its exit 1. That is the same escape hatch
+    // the subcommand dispatch documents. Mirrors go/cmd/aontu/main.go.
+    if (looksLikeVerb(file)) {
+      process.stderr.write(
+        `aontu: \`${file}\` is not a file, and not a verb this port knows\n`)
+      const near = nearestVerb(file, KNOWN_VERBS)
+      if ('' !== near) {
+        process.stderr.write(`aontu: did you mean \`aontu ${near}\`?\n`)
+      }
+      process.stderr.write(
+        'aontu: `aontu --help` lists the verbs, `aontu help` the topics\n')
+      return 2
+    }
     process.stderr.write(`aontu: cannot read ${file}: ${err.message}\n`)
     return 1
   }
@@ -614,13 +837,12 @@ function runFile(file: string, mode: Mode, trust: TrustArg): number {
     errfs: { existsSync, readFileSync },
     ...trustOpts(trust, dirname(path)),
   })
-  const res = evalSource(aontu, src, mode)
-  ;(res.ok ? process.stdout : process.stderr).write(res.text + '\n')
-  return res.ok ? 0 : 1
+  return emitEval(evalSource(aontu, src, mode), format)
 }
 
 
-function runStdin(mode: Mode, trust: TrustArg): Promise<number> {
+function runStdin(
+  mode: Mode, format: EvalFormat, trust: TrustArg): Promise<number> {
   return new Promise((resolve) => {
     let src = ''
     process.stdin.setEncoding('utf8')
@@ -628,8 +850,7 @@ function runStdin(mode: Mode, trust: TrustArg): Promise<number> {
     process.stdin.on('end', () => {
       const res = evalSource(
         new Aontu(trustOpts(trust, process.cwd())), src, mode)
-      ;(res.ok ? process.stdout : process.stderr).write(res.text + '\n')
-      resolve(res.ok ? 0 : 1)
+      resolve(emitEval(res, format))
     })
   })
 }
@@ -862,6 +1083,11 @@ type VetArgs = {
   partial?: boolean
   maxErrors?: number
   watch?: boolean
+  // G11 phase 5. `strictCoverage` implies `coverage`; `coverageAt`
+  // narrows the data side and implies it too.
+  coverage?: boolean
+  strictCoverage?: boolean
+  coverageAt?: string
 }
 
 
@@ -875,6 +1101,9 @@ function parseVetArgs(argv: string[]): { args?: VetArgs; err?: string } {
   let partial = false
   let maxErrors: number | undefined
   let watch = false
+  let coverage = false
+  let strictCoverage = false
+  let coverageAt: string | undefined
 
   for (let i = 0; i < argv.length; i++) {
     const arg = argv[i]
@@ -921,6 +1150,24 @@ function parseVetArgs(argv: string[]): { args?: VetArgs; err?: string } {
     else if ('--partial' === arg) {
       partial = true
     }
+    else if ('--coverage' === arg) {
+      coverage = true
+    }
+    else if ('--strict-coverage' === arg) {
+      // IMPLIES THE ACCOUNTING, because a gate cannot fire on what was
+      // never measured. Asking for the strict form and having to
+      // remember `--coverage` beside it is a usage trap with one
+      // correct answer, so the flag takes it.
+      coverage = true
+      strictCoverage = true
+    }
+    else if ('--coverage-at' === arg) {
+      coverageAt = argv[++i]
+      if (null == coverageAt) {
+        return { err: 'aontu: --coverage-at needs a path' }
+      }
+      coverage = true
+    }
     else if ('--watch' === arg) {
       watch = true
     }
@@ -946,6 +1193,9 @@ function parseVetArgs(argv: string[]): { args?: VetArgs; err?: string } {
       partial,
       maxErrors,
       watch,
+      coverage,
+      strictCoverage,
+      coverageAt,
     },
   }
 }
@@ -985,14 +1235,53 @@ function renderVetText(report: VetReport): string {
   const head = `verdict: ${report.verdict}` +
     (report.truncated ? ' (findings truncated)' : '')
 
-  if (0 === report.findings.length) {
-    return head
-  }
+  const body = 0 === report.findings.length ? []
+    : ['', ...report.findings.map(renderFinding)]
+  const cover = null == report.coverage ? []
+    : ['', ...renderVetCoverage(report.coverage)]
 
-  return [head, ''].concat(report.findings.map(renderFinding)).join('\n')
+  return [head, ...body, ...cover].join('\n')
 }
 
 
+// The coverage block (G11 phase 5). VACUOUS FIRST and in the
+// imperative, because it is the one line that changes what the reader
+// should do: a `valid` verdict above it means nothing.
+function renderVetCoverage(c: VetCoverage): string[] {
+  const out: string[] = []
+  if (c.vacuous) {
+    out.push('coverage: VACUOUS — no data leaf was constrained' +
+      ' by the schema; this run checked nothing')
+  }
+  out.push(`coverage: ${c.checked}/${c.leaves} data leaves checked,` +
+    ` ${c.declared} schema declarations`)
+  // The lists are the SHALLOWEST paths, so each names a subtree rather
+  // than every leaf under it, and both are capped: a report a reader
+  // scrolls past is a report nobody reads.
+  for (const [label, paths] of [
+    ['unchecked', c.unchecked], ['unused', c.unused],
+  ] as [string, string[]][]) {
+    if (0 === paths.length) {
+      continue
+    }
+    const shown = paths.slice(0, COVERAGE_LIST_MAX)
+    for (const p of shown) {
+      out.push(`  ${label}: ${p}`)
+    }
+    if (shown.length < paths.length) {
+      out.push(`  ${label}: … and ${paths.length - shown.length} more`)
+    }
+  }
+  return out
+}
+
+
+// How many coverage paths the TEXT form prints per list. The JSON form
+// carries every one: a machine reads the whole list, a person reads the
+// first few and the count.
+const COVERAGE_LIST_MAX = 10
+
+
 // The machine-readable form. `aontu` names the producer, so a report
 // read from a file or a pipe says which version and which verb made it
 // without the consumer having to know.
@@ -1002,6 +1291,7 @@ function renderVetJson(report: VetReport): string {
     verdict: report.verdict,
     truncated: report.truncated,
     findings: report.findings,
+    ...(null == report.coverage ? {} : { coverage: report.coverage }),
   }, 2)
 }
 
@@ -1049,6 +1339,20 @@ function vetOnce(args: VetArgs, trust: TrustArg): number {
   let verdict: VetVerdict = 'valid'
   let truncated = false
   const findings: VetFinding[] = []
+  // COVERAGE ACROSS SEVERAL DATA FILES (G11 phase 5). Two data files
+  // are two candidates for one truth, so the schema side is the SAME
+  // for each: `declared` is taken once, and a declaration is unused
+  // only when NO file met it -- the intersection, because a
+  // declaration one file exercised is exercised. The data side adds
+  // up: leaves and checked leaves sum, and `unchecked` is the union.
+  let cov: VetCoverage | undefined
+  // Initialised rather than left undefined: it is filled in the same
+  // block that sets `cov`, so a fallback at the read below would be an
+  // arm nothing can take. The FIRST file replaces it wholesale, which
+  // is what makes the fold an intersection rather than an empty set.
+  let unusedEvery = new Set<string>()
+  let unusedSeen = false
+  const uncheckedAll = new Set<string>()
 
   for (const source of sources) {
     const report = vet(schemaSrc, source.src, {
@@ -1067,6 +1371,8 @@ function vetOnce(args: VetArgs, trust: TrustArg): number {
       // absolute one would name the same file two ways.
       schemaPath: args.schema,
       dataPath: source.file,
+      coverage: args.coverage,
+      coverageAt: args.coverageAt,
     })
 
     if (VET_RANK[verdict] < VET_RANK[report.verdict]) {
@@ -1075,6 +1381,25 @@ function vetOnce(args: VetArgs, trust: TrustArg): number {
     truncated = truncated || report.truncated
     findings.push(...report.findings)
 
+    if (null != report.coverage) {
+      const c = report.coverage
+      cov = null == cov ? { ...c } : {
+        checked: cov.checked + c.checked,
+        declared: c.declared,
+        leaves: cov.leaves + c.leaves,
+        unchecked: [],
+        unused: [],
+        vacuous: false,
+      }
+      for (const p of c.unchecked) {
+        uncheckedAll.add(p)
+      }
+      const mine = new Set(c.unused)
+      unusedEvery = unusedSeen
+        ? new Set([...unusedEvery].filter((u) => mine.has(u))) : mine
+      unusedSeen = true
+    }
+
     // A SCHEMA-SIDE FAULT IS THE SAME FAULT FOR EVERY DATA FILE, so it
     // is reported ONCE. `error` means exactly that -- the run could not
     // be set up from the truth's side, never the data's (the exit table
@@ -1099,16 +1424,38 @@ function vetOnce(args: VetArgs, trust: TrustArg): number {
   const cap = args.maxErrors ?? VET_MAX_ERRORS
   const kept = cap < findings.length ? findings.slice(0, cap) : findings
 
+  if (null != cov) {
+    cov.unchecked = [...uncheckedAll].sort(cmpCodePoint)
+    cov.unused = [...unusedEvery].sort(cmpCodePoint)
+    cov.vacuous = 0 === cov.checked && 0 < cov.leaves
+  }
+
   const report: VetReport = {
     verdict,
     truncated: truncated || cap < findings.length,
     findings: kept,
+    ...(null == cov ? {} : { coverage: cov }),
   }
   const text = 'json' === args.format ? renderVetJson(report) :
     'sarif' === args.format ? renderVetSarif(report) :
       renderVetText(report)
 
   process.stdout.write(text + '\n')
+
+  // A VACUOUS CHECK IS A FAILED GATE UNDER `--strict-coverage`, and
+  // only under it: the verdict WORD is unchanged, so nothing that
+  // passes today starts failing, and a caller who wants the stronger
+  // gate asks for it. The reason goes to stderr, because stdout is a
+  // report contract -- a JSON consumer reads `coverage.vacuous` and a
+  // person reads this.
+  if (true === args.strictCoverage && true === report.coverage?.vacuous) {
+    process.stderr.write(
+      'aontu: no data leaf was constrained by the schema:' +
+      ' this run checked nothing\n' +
+      'aontu: `aontu help language` — a map template is `&:`,' +
+      ' and a quoted "*" is a key named *\n')
+    return 1
+  }
   return VET_EXIT[verdict]
 }
 
@@ -2227,6 +2574,31 @@ function modText(sub: string, report: any): string {
 }
 
 
+// VACUITY SIGNALS (G11 phase 4,
+// docs/capability-review/g11-agent-onramp.md).
+//
+// The same principle phase 5 applied to `vet`: a verb that did NOTHING
+// and a verb that did its job answer the same. `aontu view tree` over a
+// document declaring no relations printed one newline and exited 0;
+// `aontu render` with no profile printed nothing and exited 0; `aontu
+// relations` over a document declaring none answered `verdict: pass`.
+// For a person at a terminal that is a shrug. For an unattended agent
+// it is a green check mark on an empty box.
+//
+// ON STDERR, ALWAYS. stdout is a report contract -- a `--format json`
+// consumer parses it -- and the exit code is a verdict class that
+// callers already branch on. Neither changes here: what changes is
+// that the caller is TOLD. A caller who wants it to be fatal has
+// `vet --strict-coverage`, and the same argument would give the other
+// verbs a flag of their own if one is ever asked for.
+//
+// The repository already ruled this for one verb, in G8 phase 6 on
+// `trim`: "doing something else silently is worse than refusing".
+function vacuous(what: string, why: string): void {
+  process.stderr.write(`aontu: ${what}: ${why}\n`)
+}
+
+
 function runRelations(argv: string[]): number {
   const trusted = takeTrust(argv)
   if (null == trusted) {
@@ -2275,12 +2647,21 @@ function runRelations(argv: string[]): number {
   }
 
   const report = relationCheck(src, {
-    path: files[0], ...verbOpts(trust, entryRootOf(files[0])),
+    path: files[0], count: true,
+    ...verbOpts(trust, entryRootOf(files[0])),
   })
   const text = 'json' === format
     ? renderRelationsJson(report)
     : renderRelationsText(report)
   process.stdout.write(text + '\n')
+  // `pass` over NO declarations is the vacuous case, and the engine
+  // knows it exactly: `_reldecls` is empty. The count is asked for
+  // here rather than derived, so the answer costs no second
+  // evaluation.
+  if (0 === report.declared) {
+    vacuous('this document declares no relations',
+      '`pass` means nothing was checked, not that the graph is sound')
+  }
   return RELATIONS_EXIT[report.verdict]
 }
 
@@ -2583,7 +2964,7 @@ function runView(argv: string[]): number {
     }
   }
 
-  const report = view(srcs[0], {
+  const viewOpts = {
     ...opts,
     style: viewStyleOf(style, opts.as ?? viewDefaultProfile(kind)),
     kind,
@@ -2591,7 +2972,28 @@ function runView(argv: string[]): number {
     roots,
     ...verbOpts(trust, entryRootOf(files[0])),
     docs: files.slice(1).map((path, i) => ({ src: srcs[i + 1], path })),
-  })
+  }
+  const report = view(srcs[0], viewOpts)
+
+  // AN EMPTY FIGURE IS THE SAME BYTES AS A DRAWN ONE MINUS ITS
+  // CONTENT, and every profile spells "empty" differently: text draws
+  // nothing at all, mermaid still draws its `flowchart LR` header, the
+  // matrix still prints its count line. Rather than teach this one
+  // place each of those spellings -- a list that goes stale the first
+  // time a profile gains a header -- ASK THE SAME KIND TO DRAW AN
+  // EMPTY DOCUMENT and compare. Equal texts mean this document
+  // contributed nothing to the figure, whatever the profile.
+  //
+  // It costs one drawing of `{}`, which is the cheapest document
+  // there is, and only on a run that produced a figure at all.
+  if ('error' !== report.verdict && null != report.text) {
+    const bare = view('{}', viewOpts)
+    if ('error' !== bare.verdict && bare.text === report.text) {
+      vacuous('nothing to draw',
+        'this figure is what the same view draws for an empty document' +
+        ' — the model declares nothing this kind can show')
+    }
+  }
 
   if ('json' === format) {
     process.stdout.write(renderViewJson(report) + '\n')
@@ -3109,6 +3511,11 @@ function runRender(argv: string[]): number {
     profiles.push(profile)
   }
 
+  // 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,
@@ -3119,6 +3526,15 @@ function runRender(argv: string[]): number {
     ...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' },
@@ -3830,6 +4246,188 @@ function runSet(argv: string[]): number {
 }
 
 
+// ---------------------------------------------------------------------
+// The role gate (docs/design/ALLOW.0.md): may the role the caller is
+// operating under modify these subtrees? Asked before `set`, by an
+// agent whose skill names its role, and answered from a role model
+// that is itself an aontu document. The verdict is the exit code, as
+// it is for every gate here: 0 is yes, 1 is no, 4 is "the model that
+// was to decide does not stand up", and an agent branches on nothing
+// else.
+
+const ALLOW_HELP =
+  'aontu allow --role <role> <roles-file> <path> [more-paths...] (try --help)'
+
+const ALLOW_EXIT: Record<AllowVerdict, number> = {
+  allowed: 0,
+  refused: 1,
+  error: 4,
+}
+
+
+// One line per asked path: the answer, and the entry that gave it, as
+// a path into the role model so `aontu why` can locate the rule.
+function renderAllowDecision(d: AllowDecision, role: string): string {
+  const head = `${d.path}: ${d.allowed ? 'allowed' : 'refused'}`
+  switch (d.reason) {
+    case 'allow':
+    case 'deny':
+      return `${head} by ${d.by} (${d.pattern})`
+    case 'uncovered':
+      return `${head} (no allow entry of ${role} covers it)`
+    default:
+      return `${head} (role ${role} is not declared)`
+  }
+}
+
+
+function renderAllowText(report: AllowReport): string {
+  const lines = [`verdict: ${report.verdict}`, `role: ${report.role}`]
+    .concat(report.paths.map((d) => renderAllowDecision(d, report.role)))
+  if (0 === report.findings.length) {
+    return lines.join('\n')
+  }
+  return lines.concat('', report.findings.map(renderFinding)).join('\n')
+}
+
+
+// Does the text after `=` parse as exactly one value? Parsed, never
+// evaluated, with loads denied: the question is the shape of the
+// argument, and reading a file to answer it would be the write the
+// gate exists to precede.
+function oneValue(value: string): boolean {
+  try {
+    const probe: any = new Aontu({ trust: { include: 'none' } })
+      .parse('v: ' + value)
+    return 1 === Object.keys(probe.peg).length
+  }
+  catch {
+    return false
+  }
+}
+
+
+function runAllow(argv: string[]): number {
+  const trusted = takeTrust(argv)
+  if (null == trusted) {
+    return 2
+  }
+  argv = trusted.argv
+  const trust = trusted.trust
+  const rest: string[] = []
+  let role: string | undefined
+  let at: string | undefined
+  let format: SubsumeFormat = 'text'
+
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i]
+    if ('-h' === arg || '--help' === arg) {
+      process.stdout.write(HELP)
+      return 0
+    }
+    if ('--role' === arg) {
+      role = argv[++i]
+      if (null == role) {
+        process.stderr.write('aontu: --role needs a role name\n')
+        return 2
+      }
+    }
+    else if ('--at' === arg) {
+      at = argv[++i]
+      if (null == at) {
+        process.stderr.write('aontu: --at needs a path\n')
+        return 2
+      }
+    }
+    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 (arg.startsWith('-')) {
+      process.stderr.write(`aontu: unknown allow option ${arg} (try --help)\n`)
+      return 2
+    }
+    else {
+      rest.push(arg)
+    }
+  }
+
+  if (null == role || rest.length < 2) {
+    process.stderr.write(
+      `aontu: allow needs --role, a role model and at least one path\n` +
+      `${ALLOW_HELP}\n`)
+    return 2
+  }
+  const [file, ...asked] = rest
+
+  // A role is ONE KEY of the roles map. A dotted name would be read as
+  // a path by `why` when it follows the entry the report names, and an
+  // empty one names the map itself.
+  if ('' === role || role.includes('.')) {
+    process.stderr.write('aontu: --role needs one key, without dots\n')
+    return 2
+  }
+
+  // A path may arrive in `set`'s spelling, `$.a.b=1`, so a skill can
+  // hand the gate the very arguments the write will get. The text up
+  // to the first `=` is the path, and it starts with `$`: an empty
+  // argument, or a second file name, would otherwise read as a path
+  // and be answered. The VALUE is checked to be one value. `set`
+  // appends it as source after the flattened path, so a value carrying
+  // a second pair -- `3 secrets: key: "x"` -- writes a sibling of the
+  // overlay root, a subtree the gate was never asked about.
+  const paths: string[] = []
+  for (const arg of asked) {
+    const eq = arg.indexOf('=')
+    const path = eq < 0 ? arg : arg.slice(0, eq)
+    if (!path.startsWith('$')) {
+      process.stderr.write(
+        `aontu: a path starts with $ (got ${JSON.stringify(arg)})\n`)
+      return 2
+    }
+    if (0 <= eq && !oneValue(arg.slice(eq + 1))) {
+      process.stderr.write(
+        `aontu: the value of ${path} is not one value\n`)
+      return 2
+    }
+    paths.push(path)
+  }
+
+  let src: string
+  try {
+    src = readFileSync(file, 'utf8')
+  }
+  catch (err: any) {
+    process.stderr.write(`aontu: cannot read ${err.path}: ${err.message}\n`)
+    return 2
+  }
+
+  const report = allow(src, role, paths, {
+    at, path: file, ...verbOpts(trust, entryRootOf(file)),
+  })
+
+  const text = 'json' === format ?
+    exactJSON({
+      aontu: { version: version(), verb: 'allow' },
+      findings: report.findings,
+      paths: report.paths,
+      role: report.role,
+      verdict: report.verdict,
+    }, 2) :
+    renderAllowText(report)
+
+  // The report IS the answer, refused or not, so it goes to stdout as
+  // vet's does; the exit code carries the verdict for a caller that
+  // reads nothing else.
+  process.stdout.write(text + '\n')
+  return ALLOW_EXIT[report.verdict]
+}
+
+
 // ---------------------------------------------------------------------
 // The generated AGENTS.md stanza (G7 phase 6): the prose entrypoint,
 // derived from the definition, so it cannot drift from the formal
@@ -3846,6 +4444,10 @@ function runAgentsMd(argv: string[]): number {
   const trust = trusted.trust
   const files: string[] = []
   let write: string | undefined
+  // The SHAPE's depth (G11 phase 7). Default 2, unchanged: the stanza
+  // is spliced into a file people read, and a deeper shape is a
+  // question the caller asks rather than one it is handed.
+  let depth = 2
 
   for (let i = 0; i < argv.length; i++) {
     const arg = argv[i]
@@ -3860,6 +4462,14 @@ function runAgentsMd(argv: string[]): number {
         return 2
       }
     }
+    else if ('--depth' === arg) {
+      const n = Number(argv[++i])
+      if (!Number.isInteger(n) || n < 1) {
+        process.stderr.write('aontu: --depth needs a positive integer\n')
+        return 2
+      }
+      depth = n
+    }
     else if (arg.startsWith('-')) {
       process.stderr.write(
         `aontu: unknown agentsmd option ${arg} (try --help)\n`)
@@ -3886,7 +4496,7 @@ function runAgentsMd(argv: string[]): number {
   }
 
   const report = agentsMd(src, {
-    name: files[0], path: files[0],
+    depth, name: files[0], path: files[0],
     ...verbOpts(trust, entryRootOf(files[0])),
   })
   if (!report.ok) {
@@ -3945,7 +4555,8 @@ function runAgentsMd(argv: string[]): number {
 // the form itself is the library's (ts/src/format.ts), and the two
 // ports agree on it row by row in test/spec/fmt.tsv.
 
-const FMT_HELP = 'aontu fmt [-w|-l|--check|-d|--lint] <file>... (try --help)'
+const FMT_HELP =
+  'aontu fmt [-w|-l|--check|-d|--lint] [--marker <token>] <file>... (try --help)'
 
 type FmtFlags = {
   write: boolean, list: boolean, check: boolean, diff: boolean, lint: boolean, strict: boolean,
@@ -3953,11 +4564,13 @@ type FmtFlags = {
 
 function runFmt(argv: string[]): number | Promise<number> {
   const files: string[] = []
+  let marker: string | undefined = undefined
   const flags: FmtFlags = {
     write: false, list: false, check: false, diff: false, lint: false, strict: false,
   }
 
-  for (const arg of argv) {
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i]
     if ('-h' === arg || '--help' === arg) {
       process.stdout.write(HELP)
       return 0
@@ -3981,6 +4594,16 @@ function runFmt(argv: string[]): number | Promise<number> {
       flags.lint = true
       flags.strict = true
     }
+    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.
+      marker = argv[++i]
+      if (null == marker) {
+        process.stderr.write('aontu: --marker needs a token\n')
+        return 2
+      }
+    }
     else if (arg.startsWith('-')) {
       process.stderr.write(`aontu: unknown fmt option ${arg} (try --help)\n`)
       return 2
@@ -4002,7 +4625,7 @@ function runFmt(argv: string[]): number | Promise<number> {
       let src = ''
       process.stdin.setEncoding('utf8')
       process.stdin.on('data', (d) => (src += d))
-      process.stdin.on('end', () => resolve(fmtOne('<stdin>', src, flags)))
+      process.stdin.on('end', () => resolve(fmtOne('<stdin>', src, flags, marker)))
     })
   }
 
@@ -4018,23 +4641,6 @@ function runFmt(argv: string[]): number | Promise<number> {
 
   let worst = 0
   for (const file of files) {
-    // FMT FORMATS AONTU SOURCE, AND THE EXTENSION SAYS WHAT A FILE IS
-    // (ADR-012's rule, and the one `render` reads a template by).
-    // A TEMPLATE FILE IS NOT AONTU (docs/design/TEMPLATE.0.md; P8):
-    // its marker lines are fragments of a document and its other lines
-    // are the target's, so there is nothing here to format that would
-    // not also rewrite the output. Refused rather than attempted, and
-    // refused BY NAME rather than by a parse failure, because a `#-`
-    // template parses: `#` opens a comment, so every marker line
-    // vanishes and what is left is read as a document that was never
-    // written. The verb answered `0` over one, having understood none
-    // of it.
-    if (!/[.](aon|aontu)$/.test(file)) {
-      process.stderr.write(
-        `aontu: ${file} is not aontu source (.aon, .aontu); a generator ` +
-        'written in the target\'s own syntax is aontu template\'s\n')
-      return 2
-    }
     let src: string
     try {
       src = readFileSync(file, 'utf8')
@@ -4043,11 +4649,46 @@ function runFmt(argv: string[]): number | Promise<number> {
       process.stderr.write(`aontu: cannot read ${err.path}: ${err.message}\n`)
       return 2
     }
-    worst = Math.max(worst, fmtOne(file, src, flags))
+    const mark = fmtMarker(file, src, marker)
+    if (false === mark) {
+      process.stderr.write(
+        `aontu: ${file} is not aontu source (.aon, .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\n')
+      return 2
+    }
+    worst = Math.max(worst, fmtOne(file, src, flags, mark))
   }
   return worst
 }
 
+// WHAT A FILE IS, BY ITS EXTENSION (ADR-012's rule, and the one
+// `render` reads an entry by): `.aon` and `.aontu` are aontu source,
+// and anything else is a GENERATOR written in the target's own syntax
+// (docs/design/TEMPLATE.0.md), whose marker lines carry the document
+// this formats and whose other lines are output. `undefined` is aontu,
+// a string is the generator's marker, and `false` is neither.
+//
+// A FILE WITH NO MARKER LINE IN IT IS NEITHER, and that is what keeps
+// FMT.0.md §9's boundary where it stood: a `.json`, `.yaml` or `.toml`
+// include is another language's file, and reading one as a generator
+// would answer it back unchanged having understood none of it. The
+// marker is the evidence that a file was written to carry aontu at
+// all. `--marker` says so outright, and then the file is a generator
+// whatever it is called.
+function fmtMarker(
+  file: string, src: string, marker: string | undefined): string | undefined | false {
+  if (undefined !== marker) {
+    return marker
+  }
+  if (/[.](aon|aontu)$/.test(file)) {
+    return undefined
+  }
+  const mark = markerFor(file)
+  return templateOutputs(src, mark).some((out) => !out) ? mark : false
+}
+
 // An option that says what to do with a file, in place of printing
 // it: what to do when its form would change, or the lint.
 function fmtQuiet(flags: FmtFlags): boolean {
@@ -4059,8 +4700,9 @@ function fmtQuiet(flags: FmtFlags): boolean {
 // document that does not format, with the finding that says why. The
 // style findings go to standard error, one line each, in the shape
 // every linter prints: `file:line:col: rule: message`.
-function fmtOne(name: string, src: string, flags: FmtFlags): number {
-  const report = format(src, { path: name, lint: flags.lint })
+function fmtOne(
+  name: string, src: string, flags: FmtFlags, marker?: string): number {
+  const report = format(src, { path: name, lint: flags.lint, template: marker })
   if ('error' === report.verdict) {
     process.stderr.write(`aontu: ${name} was not formatted\n` +
       report.errors.map(renderFinding).join('\n') + '\n')
@@ -4162,6 +4804,410 @@ function parseTrustArg(value: string): TrustArg | undefined {
 }
 
 
+// THE TEACHING PACK, SERVED FROM THE COMMAND (G11 phase 1,
+// docs/capability-review/g11-agent-onramp.md; mirrors
+// go/cmd/aontu/help.go).
+//
+// HELP documents the TOOLCHAIN and says nothing about the LANGUAGE:
+// `&`, the map template and the one construct an ontology cannot be
+// written without, occurs zero times in it, while `template` occurs
+// fourteen times and names an unrelated verb every time. docs/skill/
+// was already the right content and already gated; the gap was
+// DELIVERY, since it reached an installation as
+// node_modules/aontu/skill/ where nothing looks. ts/src/helpdoc.ts is
+// generated from those sources by ts/scripts/helpdoc.cjs and asserted
+// byte-identical with them by ts/test/helpdoc.test.ts.
+
+const HELP_VERB_HELP = 'aontu help [topic] (try `aontu help` for the topics)'
+const EXPLAIN_HELP = 'aontu explain <code> (try `aontu explain --list`)'
+
+
+function helpIndexText(index: HelpTopic[]): string {
+  const width = index.reduce((w, t) => Math.max(w, t.topic.length), 0)
+  return 'aontu help <topic> — the language, offline.\n\n' +
+    index.map((t) =>
+      '  ' + t.topic.padEnd(width) + '  ' + t.summary).join('\n') +
+    '\n\n' +
+    '`aontu --help` documents the verbs, their flags and their exit\n' +
+    'codes. `aontu explain <code>` explains one error code.\n' +
+    'Start at `aontu help tasks` if you know the job but not the verb.'
+}
+
+
+function runHelp(argv: string[]): number {
+  let format: SubsumeFormat = 'text'
+  const topics: string[] = []
+
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i]
+    if ('-h' === arg || '--help' === arg) {
+      process.stdout.write(HELP)
+      return 0
+    }
+    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 (arg.startsWith('-')) {
+      process.stderr.write(`aontu: unknown help option ${arg} (try --help)\n`)
+      return 2
+    }
+    else {
+      topics.push(arg)
+    }
+  }
+
+  if (1 < topics.length) {
+    process.stderr.write(`aontu: help takes one topic\n${HELP_VERB_HELP}\n`)
+    return 2
+  }
+
+  if (0 === topics.length) {
+    process.stdout.write(('json' === format
+      ? exactJSON({
+        aontu: { version: version(), verb: 'help' },
+        topics: HELPDOC.map(
+          (t) => ({ topic: t.topic, summary: t.summary, source: t.source })),
+      }, 2)
+      : helpIndexText(HELPDOC)) + '\n')
+    return 0
+  }
+
+  const found = HELPDOC.find((t) => topics[0] === t.topic)
+  if (null != found) {
+    if ('json' === format) {
+      process.stdout.write(exactJSON({
+        aontu: { version: version(), verb: 'help' },
+        topic: found.topic,
+        summary: found.summary,
+        source: found.source,
+        text: found.text,
+      }, 2) + '\n')
+      return 0
+    }
+    process.stdout.write(found.text)
+    return 0
+  }
+
+  // AN UNKNOWN TOPIC IS A USAGE ERROR AND NAMES THE ALTERNATIVES,
+  // because the caller who typed it has no other way to find out what
+  // exists -- that is the whole condition this verb was added for.
+  process.stderr.write(
+    `aontu: no help topic \`${topics[0]}\`\n` +
+    `aontu: topics are ${HELPDOC.map((t) => t.topic).join(', ')}\n`)
+  return 2
+}
+
+
+// `aontu explain <code>` (G11 phase 3; mirrors
+// go/cmd/aontu/explain.go).
+//
+// THE REGISTRY IS THE LIST, NOT THE HINT TABLE. test/spec/errcodes.tsv
+// registers 157 codes and the spec suite asserts set equality between
+// the file and codeClasses IN BOTH PORTS, so listing from codeClasses
+// is listing the shared contract. The hint tables are smaller and are
+// NOT in parity -- 130 entries here against 131 in Go, the extra being
+// decimal_syntax, which this port never raises -- so listing from them
+// would make `aontu explain --list` differ between ports over a
+// difference that is not about what either port can report.
+//
+// A REGISTERED CODE WITH NO HINT ANSWERS WITH ITS CLASS AND SAYS SO.
+// Twenty-seven registered codes carry no explanation text here; before
+// this verb their absence was invisible, because a hint is only ever
+// seen beside the error that raises it.
+
+// The dynamic prefixes a generated code extends (`func:upper`,
+// `op[+]`). Mirrors CODE_PREFIXES in ts/src/hints.ts, which is not
+// exported; a code that extends one is registered through its prefix
+// and carries that prefix's hint.
+const EXPLAIN_PREFIXES = ['func:', 'op:', 'op[', 'var[', 'ref[']
+
+
+function explainCode(
+  code: string): { cls: string, hint: string, registered: boolean } {
+  const cls = codeClass(code)
+  let hint = hints[code] ?? ''
+  let registered = null != codeClasses[code]
+  if (!registered) {
+    for (const prefix of EXPLAIN_PREFIXES) {
+      if (code.startsWith(prefix)) {
+        // No guard on `hint` here: every hint key is also a registry
+        // key (the spec suite asserts codeClasses set-equal with
+        // test/spec/errcodes.tsv, and hints is a subset of it), so a
+        // code that reaches this loop is unregistered and therefore
+        // has no hint of its own.
+        registered = true
+        hint = hints[prefix] ?? ''
+        break
+      }
+    }
+  }
+  return { cls, hint, registered }
+}
+
+
+// Every code in the shared registry, sorted by code point so both
+// ports list them in the same order.
+function explainCodes(): string[] {
+  return Object.keys(codeClasses).sort(cmpCodePoint)
+}
+
+
+function explainListText(format: SubsumeFormat): string {
+  const codes = explainCodes()
+  if ('json' === format) {
+    return exactJSON({
+      aontu: { version: version(), verb: 'explain' },
+      codes: codes.map((code) => ({
+        code,
+        class: codeClass(code),
+        // Whether this port carries explanation text for the code. The
+        // registry is in parity; the hint tables are not, so a consumer
+        // that wants only explained codes can filter rather than guess.
+        explained: '' !== explainCode(code).hint,
+      })),
+    }, 2)
+  }
+  const width = codes.reduce((w, c) => Math.max(w, c.length), 0)
+  return codes.map((c) =>
+    c.padEnd(width) + '  ' + codeClass(c) +
+    ('' === explainCode(c).hint ? '  (no text)' : '')).join('\n')
+}
+
+
+function runExplain(argv: string[]): number {
+  let format: SubsumeFormat = 'text'
+  let list = false
+  const codes: string[] = []
+
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i]
+    if ('-h' === arg || '--help' === arg) {
+      process.stdout.write(HELP)
+      return 0
+    }
+    else if ('--list' === arg) {
+      list = 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 (arg.startsWith('-')) {
+      process.stderr.write(
+        `aontu: unknown explain option ${arg} (try --help)\n`)
+      return 2
+    }
+    else {
+      codes.push(arg)
+    }
+  }
+
+  if (list) {
+    if (0 < codes.length) {
+      process.stderr.write(`aontu: --list takes no code\n${EXPLAIN_HELP}\n`)
+      return 2
+    }
+    process.stdout.write(explainListText(format) + '\n')
+    return 0
+  }
+
+  if (1 !== codes.length) {
+    process.stderr.write(`aontu: explain needs one code\n${EXPLAIN_HELP}\n`)
+    return 2
+  }
+
+  const code = codes[0]
+  const { cls, hint, registered } = explainCode(code)
+  if (!registered) {
+    // AN UNKNOWN CODE IS A USAGE ERROR AND NAMES NEAR MATCHES. A
+    // caller reading a code out of a report has almost certainly typed
+    // it correctly, so the likely cause is a code from another tool or
+    // a truncated one, and the near matches say which.
+    process.stderr.write(`aontu: no such error code \`${code}\`\n`)
+    const near = nearestVerb(code, explainCodes())
+    if ('' !== near) {
+      process.stderr.write(`aontu: did you mean \`${near}\`?\n`)
+    }
+    process.stderr.write(
+      'aontu: `aontu explain --list` lists every registered code\n')
+    return 2
+  }
+
+  if ('json' === format) {
+    process.stdout.write(exactJSON({
+      aontu: { version: version(), verb: 'explain' },
+      code,
+      class: cls,
+      hint,
+    }, 2) + '\n')
+    return 0
+  }
+  // A REGISTERED CODE WITH NO HINT SAYS SO rather than printing an
+  // empty block, which would read as an explanation that happened to
+  // be blank.
+  const body = '' === hint
+    ? '(no explanation text is registered for this code)'
+    : hint
+  process.stdout.write(`code:  ${code}\nclass: ${cls}\n\n${body}\n`)
+  return 0
+}
+
+
+// `aontu init` (G11 phase 6,
+// docs/capability-review/g11-agent-onramp.md).
+//
+// NOT SCAFFOLDING CONVENIENCE. The agent's most expensive failure is
+// writing a FIRST document at all: the measurement that opened G11
+// found one reaching for the wildcard its neighbours use and getting
+// `verdict: valid` over data that violates it. A known-good starting
+// document turns generation into editing, which is the operation a
+// model is reliably good at.
+//
+// The trio is real, runnable and tested where it lives
+// (docs/skill/init/, run by ts/test/helpdoc.test.ts), and staged into
+// both ports by the same generator that stages the teaching pack, so
+// the two write the same bytes.
+
+const INIT_HELP = 'aontu init [dir] (try --help)'
+
+
+function runInit(argv: string[]): number {
+  const dirs: string[] = []
+
+  for (const arg of argv) {
+    if ('-h' === arg || '--help' === arg) {
+      process.stdout.write(HELP)
+      return 0
+    }
+    if (arg.startsWith('-')) {
+      process.stderr.write(`aontu: unknown init option ${arg} (try --help)\n`)
+      return 2
+    }
+    dirs.push(arg)
+  }
+
+  if (1 < dirs.length) {
+    process.stderr.write(`aontu: init takes one directory\n${INIT_HELP}\n`)
+    return 2
+  }
+  const dir = dirs[0] ?? '.'
+
+  // REFUSES TO OVERWRITE, and checks every member BEFORE writing any of
+  // them: a scaffold that wrote two files and then refused the third
+  // would leave a directory in a state neither the caller nor a re-run
+  // can reason about.
+  const standing = INITDOC.filter((f) => existsSync(join(dir, f.name)))
+  if (0 < standing.length) {
+    process.stderr.write(
+      `aontu: ${dir} already holds ${standing.map((f) => f.name).join(', ')}\n` +
+      'aontu: init never overwrites; move them aside or name an' +
+      ' empty directory\n')
+    return 2
+  }
+
+  try {
+    mkdirSync(dir, { recursive: true })
+    for (const f of INITDOC) {
+      writeFileSync(join(dir, f.name), f.text, { mode: f.mode })
+    }
+  }
+  catch (err: any) {
+    process.stderr.write(`aontu: cannot write in ${dir}: ${err.message}\n`)
+    return 2
+  }
+
+  process.stdout.write(
+    INITDOC.map((f) => join(dir, f.name)).join('\n') + '\n' +
+    '\nA model, an instance of it, and the four questions to ask.\n' +
+    'Run the checks:  sh ' + join(dir, 'check.sh') + '\n' +
+    'Learn the language:  aontu help language\n')
+  return 0
+}
+
+
+// EVERY VERB THIS PORT DISPATCHES, for the nearest-verb suggestion
+// G11 phase 2 prints. A separate list from the if-chain in main()
+// because the chain's arms have three different shapes and cannot be
+// a table; ts/test/cli-help.test.ts keeps the two from drifting by
+// running each name and requiring it not to fall through to the bare
+// command.
+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',
+]
+
+
+// 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
+// and keep the file diagnosis. Mirrors go/cmd/aontu/main.go.
+function looksLikeVerb(arg: string): boolean {
+  return '' !== arg &&
+    !/[/\\.]/.test(arg) &&
+    !arg.startsWith('-')
+}
+
+
+// NEAREST-VERB SUGGESTION (G11 phase 2). Restricted
+// Damerau-Levenshtein with a cap that grows with the word and stops at
+// three: one edit is a convincing suggestion on any length, three is
+// the most that can be believed on a long one, and an UNCAPPED
+// nearest match on a three-letter typo names something unrelated with
+// confidence. Mirrors go/cmd/aontu/help.go, including the sort, so
+// the two ports suggest the same verb on a tie.
+function nearestVerb(word: string, verbs: string[]): string {
+  let best = ''
+  let bestDist = Infinity
+  const limit = Math.min(3, 1 + Math.floor(word.length / 4))
+  for (const v of [...verbs].sort(cmpCodePoint)) {
+    const d = editDistance(word.toLowerCase(), v)
+    if (d < bestDist) {
+      best = v
+      bestDist = d
+    }
+  }
+  return bestDist > limit ? '' : best
+}
+
+
+// Levenshtein with a transposition, iterative over two rows. Mirrors
+// editDistance in go/cmd/aontu/help.go exactly.
+function editDistance(a: string, b: string): number {
+  const ar = [...a]
+  const br = [...b]
+  let prev2 = new Array(br.length + 1).fill(0)
+  let prev = new Array(br.length + 1).fill(0).map((_, j) => j)
+  let cur = new Array(br.length + 1).fill(0)
+  for (let i = 1; i <= ar.length; i++) {
+    cur[0] = i
+    for (let j = 1; j <= br.length; j++) {
+      const cost = ar[i - 1] === br[j - 1] ? 0 : 1
+      let m = Math.min(prev[j] + 1, cur[j - 1] + 1, prev[j - 1] + cost)
+      if (1 < i && 1 < j &&
+        ar[i - 1] === br[j - 2] && ar[i - 2] === br[j - 1] &&
+        prev2[j - 2] + 1 < m) {
+        m = prev2[j - 2] + 1
+      }
+      cur[j] = m
+    }
+    prev2 = [...prev]
+    prev = [...cur]
+  }
+  return prev[br.length]
+}
+
+
 function main(argv: string[], servers: Servers = SERVERS): void {
   // COLOUR OFF WHEN THE DESTINATION IS NOT A TERMINAL. Error frames
   // hardcoded their ANSI escapes, so a piped report and a `--jsonl`
@@ -4172,6 +5218,10 @@ function main(argv: string[], servers: Servers = SERVERS): void {
   setColor(true === process.stderr.isTTY ? undefined : false)
 
   let mode: Mode = 'json'
+  // THE REPORT FORM (G11 phase 7), default text: every existing caller
+  // reads exactly what it always read, and a caller that asks for json
+  // gets the failure in the finding shape every other verb reports.
+  let format: EvalFormat = 'text'
   // A LIST, though the bare command evaluates exactly one document.
   // It used to be one variable and the last argument won, which made a
   // MISTYPED VERB a silent success: `aontu vet2 schema.aon good.json`
@@ -4224,6 +5274,10 @@ function main(argv: string[], servers: Servers = SERVERS): void {
     return finish(runSet(argv.slice(3)))
   }
 
+  if ('allow' === argv[2]) {
+    return finish(runAllow(argv.slice(3)))
+  }
+
   if ('why' === argv[2]) {
     return finish(runWhy(argv.slice(3)))
   }
@@ -4236,6 +5290,20 @@ function main(argv: string[], servers: Servers = SERVERS): void {
     return finish(runHash(argv.slice(3)))
   }
 
+  // G11 phases 1 and 3. Dispatched with the rest, so `aontu ./help`
+  // still reads a file named help exactly as `aontu ./vet` does.
+  if ('help' === argv[2]) {
+    return finish(runHelp(argv.slice(3)))
+  }
+
+  if ('explain' === argv[2]) {
+    return finish(runExplain(argv.slice(3)))
+  }
+
+  if ('init' === argv[2]) {
+    return finish(runInit(argv.slice(3)))
+  }
+
   if ('mod' === argv[2]) {
     return finish(runMod(argv.slice(3)))
   }
@@ -4291,6 +5359,14 @@ function main(argv: string[], servers: Servers = SERVERS): void {
       }
       trust = parsed
     }
+    else if ('--format' === arg) {
+      const f = args[++i]
+      if ('text' !== f && 'json' !== f) {
+        process.stderr.write('aontu: --format needs text or json\n')
+        return finish(2)
+      }
+      format = f
+    }
     else if ('--jsonl' === arg) {
       jsonl = true
       // A JSONL answer is machine-read by definition, even when the
@@ -4350,7 +5426,7 @@ function main(argv: string[], servers: Servers = SERVERS): void {
 
   const file = files[0]
   if (null != file) {
-    finish(runFile(file, mode, trust))
+    finish(runFile(file, mode, format, trust))
   }
   // `--jsonl` overrides the TTY gate: the mode exists to be DRIVEN by
   // a harness over a pipe, so gating it on an interactive terminal
@@ -4360,9 +5436,9 @@ function main(argv: string[], servers: Servers = SERVERS): void {
     runRepl(mode, jsonl, trust)
   }
   else {
-    runStdin(mode, trust).then((code) => finish(code))
+    runStdin(mode, format, trust).then((code) => finish(code))
   }
-} /* node:coverage ignore next 18 */
+} /* node:coverage ignore next 20 */
 
 
 // No require.main guard here: bin/aontu.js is the executable entry and
@@ -4377,7 +5453,9 @@ export {
   runRender,
   runTemplate,
   runMod,
-  runHash, runGet,
-  runWhy, renderWhyText, runSet, runAgentsMd, runFmt,
+  runHash, runGet, runHelp, runExplain, runInit, nearestVerb,
+  looksLikeVerb,
+  KNOWN_VERBS,
+  runWhy, renderWhyText, runSet, runAllow, runAgentsMd, runFmt,
   watchChange, watchSignature, vetWaiter, deprecatedAt,
 }