aontu 0.61.0 → 0.63.0

package/src/cli.ts

@@ -1,12 +1,5 @@
 /* Copyright (c) 2025 Richard Rodger, MIT License */
 
-// Command-line interface for Aontu.
-//
-//   aontu [options] [file]
-//
-// With a file argument, the file is evaluated and the result printed.
-// With no file on an interactive terminal, a REPL is started. With no
-// file and piped input, the source is read from stdin. See HELP below.
 
 // Named imports, not `import * as`: the namespace form makes tsc emit the
 import { evalFailure } from './query'
@@ -23,11 +16,16 @@ 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, templateOutputs, markerFor } from './template'
+import {
+  desugarTemplate, resugarTemplate, templateOutputs, markerFor,
+  markerFromProfiles,
+} from './template'
 import { outsideRoot } from './mcp'
 import { sarifReport } from './report-sarif'
 import { main as lspMain } from './lsp-server'
@@ -39,7 +37,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 +57,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...]
@@ -76,14 +86,20 @@ const HELP = `Usage: aontu [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>] <file>
+       aontu template [--resugar] [--check] [--marker <token>]
+                      [--profile <file>] <file>
        aontu hash [options] <file>
        aontu mod tidy|verify|vendor|manifest [options] [dir]
        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] [--marker <token>] <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>]
+                 [--profile <file>] <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 +107,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 +144,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 +179,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
@@ -272,8 +336,9 @@ 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, profile: {lang, ...}, vetted
-                    against aontu:profile; repeatable, one per language
+  --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)
@@ -297,8 +362,8 @@ 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 --marker names the marker for a language the table does
-not know.
+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
@@ -306,7 +371,9 @@ Template options:
   --check         Desugar and resugar, and exit 1 if the file is not
                   what the round trip answers
   --marker <t>    The marker, when the extension does not name it
-                  (default //-, and #- --- /*- by extension)
+                  (default //-, and #- --- /*- <!--- by extension)
+  --profile <f>   A profile file, whose template.ext names the
+                  extensions it marks and template.marker the marker
 
 The template verb prints the canonical aontu form of a generator
 written in the target's own syntax: a marked line is aontu source, and
@@ -334,14 +401,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
@@ -352,7 +466,9 @@ Fmt options:
                   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)
+                  (default //-, and #- --- /*- <!--- by extension)
+  --profile <f>   A profile file, whose template.ext names the
+                  extensions it marks and template.marker the marker
 
 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.
@@ -399,51 +515,78 @@ function version(): string {
 }
 
 
+const EVAL_ANSI = new RegExp('\u001b\\[[0-9;]*m', 'g')
+
+
+function evalFinding(code: string, text: string): VetFinding {
+  return {
+    class: codeClass(code),
+    code,
+    message: text.split('\n')[0].replace(EVAL_ANSI, ''),
+    path: '$',
+    severity: 'error',
+    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
-    // write (D9). The CLI prints INDENTED JSON and the shared suite's
-    // `gens` mode prints COMPACT JSON, but both go through this one
-    // emitter -- an indent argument rather than a second implementation,
-    // so the two cannot drift from each other or from the Go port.
     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 }
+    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
-// entry root or goes through package resolution prints a one-line
-// stderr warning naming the flag a future default will require
-// (phase 6, the staged flip).
 type TrustArg = (
   | { kind: 'system-warn' }
   | { kind: 'system' }
   | { kind: 'none' }
   | { kind: 'root', dir?: string }
-  // EXTENSIONS READ AS TEXT ride with the capability rather than
-  // beside it: both answer "what may an include read", both are
-  // stripped by takeTrust before a verb parses its own tail, and a
-  // verb that threads one and not the other is the G5 defect again --
-  // `aontu vet` running under a flag the bare command honoured and it
-  // did not.
 ) & { textExt: string[] }
 
 
@@ -487,16 +630,6 @@ function trustOpts(trust: TrustArg, entryRoot: string): any {
 }
 
 
-// EVERY VERB honours the include capability, not just the bare
-// command. G5 wired `--trust`/`--include-root` to `aontu <file>` alone,
-// so `aontu vet schema.aon data.json` -- the surface an agent actually
-// scripts -- ran the full system resolver with no flag to confine it
-// and no warning (use-cases/REVIEW.md finding G). The flags are
-// stripped here, before each verb parses its own tail, so a verb only
-// has to pass the profile on to its engine.
-//
-// Returns undefined when the spelling is wrong, with the message
-// already printed: the caller answers the usage class.
 function takeTrust(argv: string[]):
   { argv: string[], trust: TrustArg } | undefined {
   const rest: string[] = []
@@ -600,35 +733,40 @@ 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) {
+    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
   }
 
   const path = resolve(file)
-  // `fs` IS WHAT MAKES A FRAME EXCERPT THE FILE IT NAMES. Without it,
-  // err.ts's resolveSrc falls back to the ENTRY text, so a frame whose
-  // arrow says `lib/types.aon:2:6` printed the entry's line 2 under it
-  // -- a real file name over another file's line, which
-  // docs/reference-api.md forbids in the same words it uses to require
-  // the name.
   const aontu = new Aontu({
     path,
     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')
@@ -636,22 +774,12 @@ 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))
     })
   })
 }
 
 
-// THE REPL AS AN INSPECTION TOOL (G7 phase 7): `:load` holds a
-// document, and `:get`, `:keys` and `:why` ask the query and
-// provenance surfaces about it, so the session is a place to
-// INTERROGATE a definition rather than only to evaluate snippets.
-//
-// The command handler is a PURE FUNCTION of (state, line): a readline
-// loop is untestable, and every answer this REPL gives has to be as
-// checkable as the CLI's. File reading is injected for the same
-// reason.
 export type ReplState = {
   // How a value renders: the `:canon` / `:json` toggle.
   mode: Mode
@@ -660,11 +788,6 @@ export type ReplState = {
   jsonl: boolean
   name?: string
   src?: string
-  // The include capability the session evaluates under. `--trust` and
-  // `--include-root` were parsed and then DROPPED on the way to the
-  // REPL, so `--jsonl` -- the surface built to be driven by a harness
-  // -- ran unconfined however it was invoked (use-cases/REVIEW.md
-  // finding G). The state carries it, so every line honours it.
   trust?: TrustArg
 }
 
@@ -819,14 +942,6 @@ function runRepl(initialMode: Mode, jsonl: boolean, trust: TrustArg): void {
   })
 
   rl.on('close', () => {
-    // The closing newline is for a HUMAN, so it is written only for
-    // one: it moves the terminal off the prompt line that `rl` left
-    // hanging. In `--jsonl` there is no prompt, every answer already
-    // ends in its own newline, and this one appended a bare empty line
-    // to the stream -- a record that is not JSON, at the end of a
-    // protocol whose whole contract is one JSON object per line. A
-    // harness parsing every line it receives failed on it, after the
-    // commands had all succeeded. Mirrors go/cmd/aontu/repl.go.
     if (!jsonl) {
       process.stdout.write('\n')
     }
@@ -838,16 +953,6 @@ function runRepl(initialMode: Mode, jsonl: boolean, trust: TrustArg): void {
 }
 
 
-
-// THE VET VERB (G2 phase 3).
-//
-// Exit codes are VERDICT CLASSES, not a pass/fail bit: an agent loop
-// branches on "the data contradicts the truth" (1) differently from
-// "the data has not supplied everything the truth requires" (3), and
-// differently again from "the schema itself is broken" (4), which is
-// never the data's fault. 2 stays what it already was for this CLI --
-// the caller got the invocation wrong -- which is why an unreadable
-// file is a 2 rather than a 4.
 const VET_EXIT: Record<VetVerdict, number> = {
   valid: 0,
   invalid: 1,
@@ -870,6 +975,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
 }
 
 
@@ -883,6 +993,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]
@@ -909,14 +1022,6 @@ function parseVetArgs(argv: string[]): { args?: VetArgs; err?: string } {
       format = f
     }
     else if ('--max-errors' === arg) {
-      // ONE GRAMMAR, spelled the same way in both ports: decimal
-      // digits, one to nine of them, at least 1. `Number()` alone
-      // accepted `1.0`, `1e2`, `0x10` and ` 3`, which Go's parser
-      // refuses -- so the same documented invocation meant different
-      // things in the two shipped commands. The nine-digit ceiling is
-      // where the ports would part company again: beyond it Go's
-      // integer conversion saturates, and a cap nobody can reach is
-      // not worth a divergence.
       const raw = argv[++i]
       if (!/^[0-9]{1,9}$/.test(raw ?? '') || 1 > Number(raw)) {
         return { err: 'aontu: --max-errors needs a positive whole number' }
@@ -929,6 +1034,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
     }
@@ -954,6 +1077,9 @@ function parseVetArgs(argv: string[]): { args?: VetArgs; err?: string } {
       partial,
       maxErrors,
       watch,
+      coverage,
+      strictCoverage,
+      coverageAt,
     },
   }
 }
@@ -978,10 +1104,6 @@ function renderFinding(f: VetFinding): string {
     out.push(`  actual:   ${f.actual}`)
   }
   for (const s of f.sites) {
-    // Every site carries the canon of the value it stands for: that is
-    // what makes the two sides of a conflict readable side by side. A
-    // site's file is always a string -- empty when the value belongs to
-    // neither document -- so there is nothing to coalesce here.
     out.push(`  ${s.role}: ${s.file}:${s.row}:${s.col} (${s.value})`)
   }
 
@@ -993,14 +1115,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.
@@ -1010,6 +1171,7 @@ function renderVetJson(report: VetReport): string {
     verdict: report.verdict,
     truncated: report.truncated,
     findings: report.findings,
+    ...(null == report.coverage ? {} : { coverage: report.coverage }),
   }, 2)
 }
 
@@ -1051,12 +1213,17 @@ function vetOnce(args: VetArgs, trust: TrustArg): number {
     return 2
   }
 
-  // Each data file is vetted on its own, because a parsed tree is
-  // single-use (docs/reference-api.md) -- and because two data files
-  // are two candidates for the same truth, not one merged candidate.
   let verdict: VetVerdict = 'valid'
   let truncated = false
   const findings: VetFinding[] = []
+  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,14 +1234,10 @@ function vetOnce(args: VetArgs, trust: TrustArg): number {
       maxErrors: args.maxErrors,
       schemaUrl: args.schema,
       dataUrl: source.file,
-      // The paths as well as the labels: a relative `@"file"` load
-      // inside either document resolves from ITS OWN directory, the
-      // way `aontu <file>` already resolves one (runFile above). The
-      // path is passed AS TYPED, not resolved: it doubles as the
-      // label above, and a report that mixed the typed path with an
-      // 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]) {
@@ -1083,40 +1246,59 @@ function vetOnce(args: VetArgs, trust: TrustArg): number {
     truncated = truncated || report.truncated
     findings.push(...report.findings)
 
-    // 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
-    // in docs/reference-api.md) -- so the report the first file
-    // produced is the report every later file would produce, character
-    // for character. Concatenating them repeated one broken schema N
-    // times and, past the cap, marked the report `truncated` over a
-    // single underlying fault. It only became visible once the `error`
-    // verdict started carrying findings at all: while the list was
-    // empty there was nothing to duplicate.
+    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
+    }
+
     if ('error' === report.verdict) {
       break
     }
   }
 
-  // The cap is on the REPORT, not on each file. Capping every file's
-  // list and then concatenating them let `--max-errors 1` emit one
-  // finding PER FILE -- and leave `truncated` false while doing it,
-  // because no single file had been cut. The engine still caps each
-  // run, so a pathological file cannot flood the aggregate before it
-  // gets here; this is the second, honest cut.
   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')
+
+  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]
 }
 
@@ -1144,19 +1326,6 @@ function sleep(ms: number): Promise<void> {
 }
 
 
-// Resolve true when any watched file's signature moves off `before`.
-// This is the real waiter: it never resolves false, so a real watch
-// runs until the process is interrupted; tests inject their own waiter
-// to bound the loop, and pass a short pollMs when they drive this one
-// directly. The interval is a required argument (the command passes
-// WATCH_POLL_MS) so there is no defaulting branch a test could never
-// take.
-//
-// The BASELINE is an argument, not a snapshot taken here: the loop
-// records it BEFORE each vet run, so a save landing between the run's
-// reads and the wait still compares as a change. A waiter that
-// snapshotted on entry would adopt that unvetted save as its baseline
-// and wait indefinitely on a stale report.
 async function watchChange(
   files: string[], before: string, pollMs: number): Promise<boolean> {
   for (;;) {
@@ -1196,9 +1365,6 @@ async function watchVet(
 }
 
 
-// The vet verb. Non-watch runs are synchronous and return the exit
-// class directly; `--watch` returns a promise that resolves only when
-// the waiter says stop (never, for the real one).
 function runVet(argv: string[], wait?: VetWaiter): number | Promise<number> {
   const trusted = takeTrust(argv)
   if (null == trusted) {
@@ -1376,14 +1542,6 @@ type BreakingArgs = {
   file: string
   against: string[]
   mode?: BreakingMode
-  // `--at`: compare a SUBTREE of both versions. The gate's own
-  // sub-question, and the one a real repository needs -- a document's
-  // top level carries the module's version string and its policy
-  // block, which are supposed to change between releases and which
-  // make the whole-document comparison answer about them rather than
-  // about the contract (use-cases/REVIEW.md finding D). `subsume` has
-  // taken it since G3; `breaking` did not, so the only way to gate a
-  // subtree was to split the file.
   at?: string
   allowUndecided: boolean
   allowDeprecatedRemoval: boolean
@@ -1467,36 +1625,10 @@ function parseBreakingArgs(
   }
 }
 
-// One resolved `--against` spelling: the old document's text, the path
-// its own relative includes must resolve from, and (for a git spelling)
-// the temporary tree to remove when the run is done.
 type OldVersion = { src: string, path: string, temp?: string }
 
-// A source file the include resolver can actually load. `git#<rev>`
-// materialises these and nothing else: an include names an Aontu
-// document (`.aon`/`.aontu`, the two extensions `@"foo"` tries) or a
-// JSON one, so the rest of a revision's tree cannot be part of any
-// include closure and copying it would be pure cost.
 const INCLUDABLE = /\.(aon|aontu|jsonic|json)$/
 
-// Resolve one --against spelling to an old version.
-//
-// A `git#<rev>` spelling is the old version of the WHOLE TREE, not of
-// the entry file alone. It used to be `git show <rev>:./<file>`, whose
-// text was then evaluated with `generalPath`/`specificPath` pointing at
-// the WORKING file -- so every `@"..."` include in the old document
-// resolved against the working tree, and the "old" side was old entry
-// text meeting new includes. A breaking change inside an included file
-// therefore compared against itself and answered `compatible`: the
-// documented CI gate silently un-gated every non-entry file of the
-// multi-file layout real models use (use-cases/BUGS.md §26). The old
-// tree's includable sources are copied into a temporary directory and
-// the old document is evaluated from THERE.
-//
-// Sources outside the revision -- package includes under node_modules,
-// the bundled `std/system` -- still resolve as they do today: they are
-// not in the tree, and their versions travel with the lockfile rather
-// than with this comparison.
 function oldVersion(spec: string, file: string): OldVersion | undefined {
   if (!spec.startsWith('git#')) {
     try {
@@ -1528,24 +1660,10 @@ function oldVersion(spec: string, file: string): OldVersion | undefined {
   // that only some failures take.
   const temp = mkdtempSync(join(tmpdir(), 'aontu-against-'))
   try {
-    // THE REPO-RELATIVE PATH COMES FROM GIT, not from path arithmetic.
-    // Relativising `rev-parse --show-toplevel` against `resolve(file)`
-    // puts two DIFFERENT COORDINATE SYSTEMS on either side of the
-    // subtraction: git prints the real path, while the caller's is
-    // whatever they typed. On macOS a temp file under /var is
-    // /private/var to git, and on Windows a TMP short name
-    // (RUNNER~1) is the long form to git -- so the subtraction gave a
-    // `../..` climb, the entry was "not in that revision", and the
-    // documented CI spelling failed on both platforms while passing on
-    // Linux (this PR's own CI). `--show-prefix` is the same question
-    // asked in git's coordinates: the repo-relative directory of the
-    // cwd, already slash-separated and already normalised.
     const prefix = git(['rev-parse', '--show-prefix'], dir).trim()
     const entryRel = prefix + basename(file)
     const top = git(['rev-parse', '--show-toplevel'], dir).trim()
 
-    // `-z` so a path with a newline or a quote cannot be mistaken for
-    // two paths (git otherwise quotes such names).
     const listed = git(['ls-tree', '-r', '-z', '--name-only', rev], top)
       .split('\0').filter((p) => '' !== p)
     if (!listed.includes(entryRel)) {
@@ -1580,13 +1698,6 @@ function policyCompat(
 ): BreakingMode | undefined {
   const aontu = new Aontu()
   const ctx = aontu.ctx({ collect: true })
-  // The declaration is read by EVALUATING the document, so this leg
-  // runs the include resolver too and has to run it under BOTH of the
-  // verb's include options -- a `breaking --trust none` that read its
-  // own mode through an unconfined resolver would confine the
-  // comparison and not the question (use-cases/REVIEW.md finding G),
-  // and one that took the capability alone read no mode at all when
-  // the declaration arrived through a `--text-ext` include.
   const v: any = aontu.unify(newSrc, { path, ...includeOpts(include) }, ctx)
   if (0 < ctx.err.length || true === v?.isNil) {
     return undefined
@@ -1606,11 +1717,6 @@ function policyCompat(
     ? m : undefined
 }
 
-// Is the evaluated old version's value at the finding path deprecated?
-// The --allow-deprecated-removal downgrade (G3 phase 4): removing (or
-// otherwise changing) a value the old version already deprecated warns
-// instead of breaking. The Go port exports the same reader as
-// aontu.DeprecatedAt.
 function deprecatedAt(oldSrc: string, path: string, filePath: string): boolean {
   const aontu = new Aontu()
   const ctx = aontu.ctx({ collect: true })
@@ -1685,9 +1791,6 @@ function runBreaking(argv: string[]): number {
     return 2
   }
 
-  // The declared mode: --mode overrides the document's own policy;
-  // neither means backward, the index's framing (v1-valid documents
-  // stay valid).
   const mode: BreakingMode =
     args.mode ??
     policyCompat(newSrc, args.file,
@@ -1727,8 +1830,6 @@ function runBreaking(argv: string[]): number {
       temps.push(old.temp)
     }
 
-    // backward: the NEW document is the general side — every old
-    // instance must still be admitted. forward: the old one is.
     const checks: Array<{ general: [string, string], specific: [string, string] }> = []
     if ('backward' === mode || 'full' === mode) {
       checks.push({ general: [newSrc, args.file], specific: [oldSrc, spec] })
@@ -1745,18 +1846,10 @@ function runBreaking(argv: string[]): number {
         at: args.at,
         generalUrl: check.general[1],
         specificUrl: check.specific[1],
-        // The old side's relative loads resolve from ITS own tree --
-        // the materialised revision for a git spelling, the named
-        // file's directory otherwise -- so an included file's change
-        // is part of the comparison rather than invisible to it.
         generalPath: check.general[1] === spec ? oldPath : args.file,
         specificPath: check.specific[1] === spec ? oldPath : args.file,
       })
 
-      // The deprecated-removal downgrade: a finding about a value the
-      // OLD version already deprecated becomes a warning, and warnings
-      // do not move the verdict. Deprecate-then-remove is the
-      // supported rename path (the design's own sequencing).
       let verdict = report.verdict
       if (args.allowDeprecatedRemoval) {
         let liveFindings = 0
@@ -1814,13 +1907,6 @@ function renderBreakingJson(report: SubsumeReport, mode: string): string {
 }
 
 
-// ---------------------------------------------------------------------
-// The trim reporter (G3 phase 6): report redundant entries as paths.
-// Report-only — REWRITING needs G7's format-preserving patch surface —
-// which is why --check is REQUIRED rather than defaulted: `aontu trim
-// f.aon` reads as "trim this file", and doing something else silently
-// is worse than saying so.
-
 const TRIM_HELP = 'aontu trim --check <file> (try --help)'
 
 const TRIM_EXIT: Record<TrimVerdict, number> = {
@@ -1898,8 +1984,6 @@ function runTrim(argv: string[]): number {
 
 function renderTrimText(report: TrimReport): string {
   const head = `verdict: ${report.verdict}`
-  // WHY, when the document could not be evaluated at all: rendered as
-  // vet renders a finding, because it IS one (the review's finding F).
   const errors = report.errors ?? []
   if (0 < errors.length) {
     return [head, ''].concat(errors.map(renderFinding)).join('\n')
@@ -1964,29 +2048,12 @@ const VIEW_EDGES: ViewEdges[] = ['upward', 'all', 'none']
 // the same division err.ts already draws for the error frames.
 const VIEW_STYLES = ['auto', 'none', 'ansi', 'css']
 
-// `--style auto` resolved, which only the CLI can do. The mechanism is
-// the PROFILE's and the library knows it -- an SVG carries its
-// stylesheet unless told not to, which is what makes a figure stand
-// alone. What the library cannot know is whether the DESTINATION is a
-// terminal, so that is the only thing decided here: escapes on the
-// text profile when stdout is a terminal and NO_COLOR is unset, the
-// same two conditions the error frames use. `undefined` leaves the
-// profile's own default in place.
 function viewStyleOf(
   asked: string | undefined, as: ViewProfile | undefined
 ): ViewStyle | undefined {
   if (undefined !== asked && 'auto' !== asked) {
     return asked as ViewStyle
   }
-  // STDOUT'S OWN TERMINAL-NESS, and NO_COLOR read here rather than
-  // through colorActive(). The figure goes to STDOUT and the error
-  // frames go to STDERR, and they are not the same destination: main()
-  // has already called setColor for stderr, so asking colorActive()
-  // would answer the wrong question twice --- no escapes for
-  // `aontu view tree m.aon 2>/dev/null` at a terminal, and escapes
-  // into the pipe for `aontu view tree m.aon | less`. The NO_COLOR
-  // rule is the one no-color.org states and err.ts implements:
-  // set, to anything but empty, means no colour.
   const no = process.env.NO_COLOR
   return 'text' === as && true === process.stdout.isTTY
     && (null == no || '' === no) ? 'ansi' : undefined
@@ -2012,24 +2079,6 @@ const VIEW_USAGE_CODES = [
 
 const MOD_HELP = 'aontu mod tidy|verify|vendor|manifest [dir] (try --help)'
 
-// The module tooling (G6 phase 3, ts/src/mod-tool.ts). All LOCAL:
-// `tidy` resolves the closure from what is in the stores and rewrites
-// the lockfile, `verify` asks whether the stores still mean what the
-// lockfile pins and changes nothing, `vendor` materialises the locked
-// closure into the project, `manifest` prints what a publish would
-// push.
-//
-// TIDY AND VERIFY ARE DIFFERENT QUESTIONS, and that is why both exist.
-// Tidy recomputes and rewrites by design -- a pin is what a module
-// means NOW -- so it makes the lockfile agree with whatever the store
-// holds, tampering included. Verify is the gate: a CI job runs it
-// BEFORE tidy, or instead of it.
-//
-// `get` and `publish` are the NETWORK half of the design and are not in
-// this build. They are named here rather than left to fall out as an
-// unknown subcommand, because a reader of the design will type them and
-// deserves to be told which half is missing rather than that the word
-// is wrong.
 function runMod(argv: string[]): number {
   const rest: string[] = []
   let format: SubsumeFormat = 'text'
@@ -2083,10 +2132,6 @@ function runMod(argv: string[]): number {
     return 2
   }
 
-  // THE OLD LAYOUT IS NAMED, NOT READ. The lockfile and the vendored
-  // closure moved under aontu_meta/; a project that still carries them
-  // at its root would otherwise look untouched by any of these verbs,
-  // which is the one silence worth breaking.
   if (existsSync(join(dir, 'aon_vendor')) || existsSync(join(dir, 'mod-lock.aon'))) {
     process.stderr.write(
       'aontu: aon_vendor/ and mod-lock.aon now live under aontu_meta/: ' +
@@ -2130,9 +2175,6 @@ type ModVerdict =
 const MOD_EXIT: Record<ModVerdict, number> = {
   ok: 0,
   missing: 1,
-  // A REFUSED GATE, with `breaking`: a store that no longer means what
-  // the lockfile pins is the integrity check saying no, and a CI job
-  // reading exit codes should not have to learn a third class for it.
   mismatch: 1,
   // Likewise a lockfile that does not cover the project: the gate has
   // nothing to check, which is a refusal and not a pass.
@@ -2183,11 +2225,6 @@ function modText(sub: string, report: any): string {
     for (const f of report.findings) {
       lines.push(f.path + ': ' + f.message)
     }
-    // What a manifest lacks is a declaration the module does not make
-    // or an entry file that is not there, and neither is something a
-    // fetch would supply -- so this is not the tail the other two
-    // subcommands share. The name says which kind it is: `mod.version`
-    // is a declaration, `service.aon` is a file.
     for (const miss of report.missing) {
       lines.push(miss + ': missing')
     }
@@ -2198,8 +2235,6 @@ function modText(sub: string, report: any): string {
     for (const mod of report.verified) {
       lines.push(mod + ': verified')
     }
-    // BOTH HASHES, because the useful question is which way it moved:
-    // an empty `got` is a module that no longer stands up at all.
     for (const m of report.mismatched) {
       lines.push(m.mod + ': pinned ' + m.want + ' but the store means ' +
         ('' === m.got ? 'nothing (it does not evaluate)' : m.got))
@@ -2235,6 +2270,11 @@ function modText(sub: string, report: any): string {
 }
 
 
+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) {
@@ -2283,12 +2323,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]
 }
 
@@ -2508,12 +2557,6 @@ function runView(argv: string[]): number {
     }
   }
 
-  // ESCAPES NEVER GO INTO A FILE. A pinned golden holding terminal
-  // control codes is not a golden anybody can read, and a byte
-  // comparison against one would fail on the reader's terminal
-  // settings. `auto` resolves to `none` there on its own; asking for
-  // `ansi` explicitly is a usage error rather than a silent downgrade,
-  // so a script that wanted colour is told where it went.
   if ('ansi' === style && (undefined !== out || undefined !== opts.views)) {
     process.stderr.write(
       'aontu: --style ansi writes to a terminal, not to a file\n')
@@ -2523,10 +2566,6 @@ function runView(argv: string[]): number {
   // THE VIEW DOCUMENT draws every figure a document declares, so it
   // names no kind: the declarations do, one each.
   if (undefined !== opts.views) {
-    // A declaration names its own profile, so the style is left to
-    // each figure's own default; `--style none` still reaches every
-    // one of them, which is how a host page that binds the CSS
-    // variables asks for eight figures without eight stylesheets.
     opts.style = viewStyleOf(style, undefined)
     return runViewSet(rest, opts, trust, { format, check, strict, out })
   }
@@ -2591,7 +2630,7 @@ function runView(argv: string[]): number {
     }
   }
 
-  const report = view(srcs[0], {
+  const viewOpts = {
     ...opts,
     style: viewStyleOf(style, opts.as ?? viewDefaultProfile(kind)),
     kind,
@@ -2599,7 +2638,17 @@ 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)
+
+  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')
@@ -2645,13 +2694,6 @@ function runView(argv: string[]): number {
   return strict && 'lossy' === report.verdict ? 1 : VIEW_EXIT[report.verdict]
 }
 
-// `aontu view --views <path> <file>`: every figure the document
-// declares, from one evaluation, all or nothing.
-//
-// A declared `out` is resolved against the DOCUMENT's own directory,
-// not the caller's: a view document is committed beside the figures it
-// gates, and a gate that only passes from one working directory is not
-// a gate.
 function runViewSet(
   rest: string[], opts: ViewOptions, trust: TrustArg,
   how: { format: SubsumeFormat, check: boolean, strict: boolean, out?: string }
@@ -2792,8 +2834,6 @@ function renderViewJson(report: ViewReport): string {
 
 function renderRelationsText(report: RelationReport): string {
   const head = `verdict: ${report.verdict}`
-  // WHY, when the document could not be evaluated at all: rendered as
-  // vet renders a finding, because it IS one (the review's finding F).
   const errors = report.errors ?? []
   if (0 < errors.length) {
     return [head, ''].concat(errors.map(renderFinding)).join('\n')
@@ -2819,21 +2859,6 @@ function renderRelationsJson(report: RelationReport): string {
 }
 
 
-
-// ---------------------------------------------------------------------
-// JSON SCHEMA EXPORT (SUPPORT.md act 2, the review's finding I): the
-// bridge to every structured-output API, which constrains generation to
-// JSON Schema and nothing else. Export the model, let the provider
-// generate under it, then `vet` the result against the model itself --
-// the hybrid an enterprise actually deploys, and impossible without
-// this verb.
-//
-// THE SCHEMA GOES TO STDOUT AND THE LOSSES TO STDERR, so `aontu
-// jsonschema x.aon > schema.json` writes a schema and still tells the
-// reader what it could not carry. `--strict` makes a loss a refusal,
-// for the CI job that would rather fail than ship a schema weaker than
-// its model.
-
 const JSONSCHEMA_HELP =
   'aontu jsonschema [--at <path>] [--strict] <file> (try --help)'
 
@@ -2929,14 +2954,6 @@ function runJsonSchema(argv: string[]): number {
     strict && 'lossy' === report.verdict ? 1 : 0
 }
 
-// ---------------------------------------------------------------------
-// THE RENDER VERB (docs/design/RENDER.0.md D8): evaluate a document,
-// vet the value at --at against aontu:code, fold code.units into bytes,
-// and put them where the flag says -- one unit on stdout, every unit
-// below --out (all or nothing), or compared against --check. Exit codes
-// mirror jsonschema's: 0 ok; 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.
 
 const RENDER_HELP =
   'aontu render [--at <path>] [--profile <file>]... [--unit <path>] ' +
@@ -3074,49 +3091,22 @@ function runRender(argv: string[]): number {
     return 2
   }
 
-  // THE ENTRY MAY BE A TEMPLATE (TEMPLATE.0.md; P8), and its EXTENSION
-  // decides, as an include's extension decides what the include is
-  // (ADR-012): a generator is a file in the target's own syntax, so it
-  // carries the target's extension and never `.aon`. Desugared here
-  // rather than anywhere deeper, because a template is an entry
-  // spelling and not a value: an include is still aontu.
-  if (!files[0].endsWith('.aon')) {
-    src = desugarTemplate(src, marker ?? markerFor(files[0]))
+  const loadedProfiles = loadProfiles(profileFiles, trust)
+  if ('number' === typeof loadedProfiles) {
+    return loadedProfiles
   }
+  const profiles = loadedProfiles
 
-  // THE PROFILES (D5): each --profile file is a document whose root is
-  // `profile: {lang, ...}`, evaluated under the verb's trust and vetted
-  // against aontu:profile as a settled value before the fold reads it
-  // (renderProfile, which also fills the defaults). Two files claiming
-  // one lang is a usage error: the fold could not choose.
-  const profiles: any[] = []
-  const langs = new Map<string, string>()
-  for (const pf of profileFiles) {
-    let text: string
-    try {
-      text = readFileSync(pf, 'utf8')
-    }
-    catch (err: any) {
-      process.stderr.write(`aontu: cannot read ${err.path}: ${err.message}\n`)
-      return 2
-    }
-    const loaded = renderProfile(text,
-      { path: resolve(pf), ...verbOpts(trust, entryRootOf(pf)) })
-    if (undefined !== loaded.errors) {
-      process.stderr.write(loaded.errors.map(renderFinding).join('\n') + '\n')
-      return 4
-    }
-    const profile = loaded.profile
-    const prev = langs.get(profile.lang)
-    if (undefined !== prev) {
-      process.stderr.write(
-        `aontu: two profiles claim ${profile.lang}: ${prev} and ${pf}\n`)
-      return 2
-    }
-    langs.set(profile.lang, pf)
-    profiles.push(profile)
+  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,
@@ -3127,6 +3117,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' },
@@ -3252,21 +3251,21 @@ function renderExit(report: RenderReport, drift: number): number {
 }
 
 
-// ---------------------------------------------------------------------
-// THE TEMPLATE SURFACE (docs/design/TEMPLATE.0.md; RENDER.0.md P8): the
-// two transforms and the round trip between them. `render` reads a
-// template directly, by its extension; this verb is for seeing the
-// canonical form, for writing one by hand and sugaring it, and for the
-// check that keeps a committed template and its meaning in agreement.
-
 const TEMPLATE_HELP =
   'aontu template [--resugar] [--check] [--marker <token>] <file> (try --help)'
 
 function runTemplate(argv: string[]): number {
+  const trusted = takeTrust(argv)
+  if (null == trusted) {
+    return 2
+  }
+  argv = trusted.argv
+  const trust = trusted.trust
   const files: string[] = []
   let resugar = false
   let check = false
   let marker: string | undefined = undefined
+  const profileFiles: string[] = []
 
   for (let i = 0; i < argv.length; i++) {
     const arg = argv[i]
@@ -3287,6 +3286,14 @@ function runTemplate(argv: string[]): number {
         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 template option ${arg} (try --help)\n`)
@@ -3301,10 +3308,6 @@ function runTemplate(argv: string[]): number {
     process.stderr.write(`aontu: template needs one file\n${TEMPLATE_HELP}\n`)
     return 2
   }
-  // THE TWO ARE DIRECTIONS, NOT MODES THAT COMPOSE: `--check` reads a
-  // template and asks whether the round trip answers it back, and
-  // `--resugar` reads the canonical form instead. A run cannot be both
-  // at once, because the file is one thing or the other.
   if (resugar && check) {
     process.stderr.write(
       'aontu: template takes one of --resugar or --check\n')
@@ -3320,19 +3323,15 @@ function runTemplate(argv: string[]): number {
     return 2
   }
 
-  const mark = marker ?? markerFor(files[0])
+  const declared = loadProfiles(profileFiles, trust)
+  if ('number' === typeof declared) {
+    return declared
+  }
+
+  const mark = marker ?? markerFromProfiles(declared, files[0]) ??
+    markerFor(files[0])
 
   if (check) {
-    // THE ROUND TRIP IS THE CHECK (D6): the file held to the spelling
-    // the two transforms answer. What that names is a marker line the
-    // transform would not have written -- one without its space, or one
-    // whose aontu is indented after the marker rather than before it,
-    // since the marker keeps its own indentation. It does NOT name a
-    // changed body line: a template's whitespace is output, so a
-    // trimmed trailing space is still a valid template and it is
-    // `render --check` against the committed files that catches it.
-    // The first line that differs is the report, since a whole diff of
-    // a generator is the file again.
     const back = resugarTemplate(desugarTemplate(src, mark), mark)
     if (back === src) {
       return 0
@@ -3343,12 +3342,6 @@ function runTemplate(argv: string[]): number {
     while (n < want.length && n < have.length && want[n] === have[n]) {
       n++
     }
-    // THE TWO ARE THE SAME LENGTH, always: each transform maps one
-    // line to one line and applies the same trailing-newline rule, so
-    // `back` has as many lines as `src`. The loop above therefore stops
-    // at a real difference rather than by running out of either -- an
-    // equal prefix all the way to the end IS `back === src`, which
-    // returned above. So both indexes are in range here.
     process.stderr.write(
       `aontu: ${files[0]}:${n + 1} is not what the round trip answers\n` +
       `  have: ${JSON.stringify(have[n])}\n` +
@@ -3362,13 +3355,43 @@ function runTemplate(argv: string[]): number {
 }
 
 
-// ---------------------------------------------------------------------
-// The canon-hash (G6 phase 1): the pin an agent, a lockfile or a
-// registry stores for "this module, this meaning". The hash covers the
-// module evaluated STANDALONE -- its own include closure resolved and
-// unified at its own root, before any consumer context -- which is what
-// makes the pin transitive: an edit two includes deep changes the
-// unified root, hence the hash.
+// 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.
+function loadProfiles(
+  profileFiles: string[], trust: TrustArg
+): any[] | number {
+  const profiles: any[] = []
+  const langs = new Map<string, string>()
+  for (const pf of profileFiles) {
+    let text: string
+    try {
+      text = readFileSync(pf, 'utf8')
+    }
+    catch (err: any) {
+      process.stderr.write(`aontu: cannot read ${err.path}: ${err.message}\n`)
+      return 2
+    }
+    const loaded = renderProfile(text,
+      { path: resolve(pf), ...verbOpts(trust, entryRootOf(pf)) })
+    if (undefined !== loaded.errors) {
+      process.stderr.write(loaded.errors.map(renderFinding).join('\n') + '\n')
+      return 4
+    }
+    const profile = loaded.profile
+    const prev = langs.get(profile.lang)
+    if (undefined !== prev) {
+      process.stderr.write(
+        `aontu: two profiles claim ${profile.lang}: ${prev} and ${pf}\n`)
+      return 2
+    }
+    langs.set(profile.lang, pf)
+    profiles.push(profile)
+  }
+  return profiles
+}
+
 
 const HASH_HELP = 'aontu hash <file> (try --help)'
 
@@ -3429,14 +3452,6 @@ function runHash(argv: string[]): number {
   const ctx = aontu.ctx({ collect: true })
   const v: any = aontu.unify(src, { path: files[0] }, ctx)
   if (0 < ctx.err.length || true === v?.isNil) {
-    // A document that does not stand up on its own has no meaning to
-    // pin, and a hash of a broken evaluation would be a pin that
-    // silently agrees with every other broken evaluation.
-    // WHY it does not stand up, not just that it does not: the same
-    // diagnosis `aontu <file>` prints (the review's finding F).
-    // evalFailure unconditionally, as every other call site does: it
-    // owns the "ctx.err is never empty here" contract, and a guard
-    // that pretends otherwise is a dead arm asserting nothing.
     process.stderr.write(
       `aontu: ${files[0]} does not evaluate on its own; nothing to hash\n` +
       renderFinding(evalFailure(ctx)) + '\n')
@@ -3455,13 +3470,6 @@ function runHash(argv: string[]): number {
 }
 
 
-// ---------------------------------------------------------------------
-// The query surface (G7 phase 1): one node of an evaluated document,
-// selected by path and rendered. Evaluation is still GLOBAL -- what
-// `get` buys is the size of the ANSWER, not the cost of producing it --
-// and the projections are lattice abstractions, each a valid Aontu
-// document that subsumes the truth it summarises.
-
 const GET_HELP = 'aontu get <path> <file> (try --help)'
 
 function runGet(argv: string[]): number {
@@ -3649,11 +3657,6 @@ function runWhy(argv: string[]): number {
 }
 
 
-// One contribution per line, numbered in source order, each with what
-// was written, where, and how it got here. A siteless contribution
-// prints no location rather than a `-1:-1` that means nothing —
-// exported for the direct test, because the site SHAPE allows one
-// while no document has yet produced one (ADR-002).
 function renderWhyText(record: WhyRecord): string {
   const head = `${record.path} = ${record.value}`
   if (0 === record.conjuncts.length) {
@@ -3671,13 +3674,6 @@ function renderWhyText(record: WhyRecord): string {
 }
 
 
-// ---------------------------------------------------------------------
-// The overlay patch verb (G7 phase 5): change a document by APPENDING
-// to an overlay, not by rewriting it. An overlay entry is just another
-// conjunct and unification is order-independent, so this needs no
-// rewriter — the format-preserving in-place edit is stage 2, and needs
-// a comment-preserving CST the parser stack does not have.
-
 const SET_HELP =
   'aontu set <path>=<value> --entry <file> --overlay <file> (try --help)'
 
@@ -3794,29 +3790,12 @@ function runSet(argv: string[]): number {
     }, 2) + '\n')
   }
   else {
-    // A replacement is REPORTED as the edit it is, not left for the
-    // reader to infer from a changed file: `where: what -> what`, in
-    // source spelling, because the spelling is what changed.
-    //
-    // PAST TENSE ONLY WHERE IT HAPPENED. A refused write leaves the
-    // file exactly as it was, and one assignment can be replaceable
-    // while another makes the whole run invalid — so `replaced:` there
-    // tells an operator the pin was changed when it was not, and unlike
-    // `--dry-run` there is nothing else on the line to say otherwise.
     const verb = wrote ? 'replaced' : 'would replace'
     const edits = report.replaced.map((r) =>
       `${verb}: ${r.file}:${r.row}:${r.col} ${r.from} -> ${r.to}`)
     const head = [`verdict: ${report.verdict}`].concat(edits).join('\n') +
       (wrote ? `\nwrote: ${overlayFile}` : dryRun ? '\n(dry run)' : '')
 
-    // A SUCCESSFUL COMMAND WRITES ITS STATUS TO STDOUT, findings or
-    // not. Routing on `findings.length` was right while every finding
-    // this verb could produce was an ERROR; `--in-place` made a WARNING
-    // possible, and a run that held, wrote the file and exited 0 then
-    // sent its whole report to stderr — leaving stdout empty, so
-    // `$(aontu set ...)` captured nothing and only the JSON form
-    // behaved like a success. The verdict decides the stream; warnings
-    // are diagnostics and go to stderr beside it.
     const failed = 'invalid' === report.verdict || 'error' === report.verdict
     const findingText = report.findings.map(renderFinding)
     if (failed) {
@@ -3838,6 +3817,171 @@ function runSet(argv: string[]): number {
 }
 
 
+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
+  }
+
+  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
@@ -3854,6 +3998,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]
@@ -3868,6 +4016,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`)
@@ -3894,7 +4050,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) {
@@ -3933,35 +4089,23 @@ function runAgentsMd(argv: string[]): number {
 }
 
 
-// Exit without truncating output.
-//
-// process.exit() terminates immediately, discarding anything still
-// queued on stdout. A write to a PIPE is asynchronous once it exceeds
-// the pipe buffer, so `write(big); exit(0)` silently truncated output at
-// 65536 bytes — while a write to a TTY or a file, being synchronous,
-// looked fine. Setting exitCode instead lets the process end naturally,
-// after the queue drains.
-//
-// This predates the exact leaves but they make it trivially reachable
-// (one long biginteger canon exceeds the buffer), and it lands squarely
-// on the parity-probe discipline in AGENTS.md, which derives expected
-// spec values by piping BOTH CLIs and comparing. A truncated pipe there
-// reads as a port divergence.
-// ---------------------------------------------------------------------
-// The source formatter (docs/design/FMT.0.md): one agreed form, in the
-// tradition of gofmt. The verb prints, lists, checks, diffs or rewrites;
-// 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] [--marker <token>] <file>... (try --help)'
+  'aontu fmt [-w|-l|--check|-d|--lint] [--marker <token>] ' +
+  '[--profile <file>] <file>... (try --help)'
 
 type FmtFlags = {
   write: boolean, list: boolean, check: boolean, diff: boolean, lint: boolean, strict: boolean,
 }
 
 function runFmt(argv: string[]): number | Promise<number> {
+  const trusted = takeTrust(argv)
+  if (null == trusted) {
+    return 2
+  }
+  argv = trusted.argv
+  const trust = trusted.trust
   const files: string[] = []
+  const profileFiles: string[] = []
   let marker: string | undefined = undefined
   const flags: FmtFlags = {
     write: false, list: false, check: false, diff: false, lint: false, strict: false,
@@ -4002,6 +4146,14 @@ function runFmt(argv: string[]): number | Promise<number> {
         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 fmt option ${arg} (try --help)\n`)
       return 2
@@ -4027,6 +4179,11 @@ function runFmt(argv: string[]): number | Promise<number> {
     })
   }
 
+  const declared = loadProfiles(profileFiles, trust)
+  if ('number' === typeof declared) {
+    return declared
+  }
+
   // Several files onto standard output would be one stream nobody can
   // split again (the note's X-6): the verb refuses unless an option
   // says what to do with each.
@@ -4047,13 +4204,14 @@ function runFmt(argv: string[]): number | Promise<number> {
       process.stderr.write(`aontu: cannot read ${err.path}: ${err.message}\n`)
       return 2
     }
-    const mark = fmtMarker(file, src, marker)
+    const mark = fmtMarker(file, src,
+      marker ?? markerFromProfiles(declared, file))
     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')
+        'format; --marker names the marker for a language the table ' +
+        'does not know, and --profile reads one that declares it\n')
       return 2
     }
     worst = Math.max(worst, fmtOne(file, src, flags, mark))
@@ -4061,20 +4219,6 @@ function runFmt(argv: string[]): number | Promise<number> {
   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) {
@@ -4136,26 +4280,13 @@ function fmtOne(
 }
 
 
-// ---------------------------------------------------------------------
-// The servers as verbs: `aontu lsp` runs the language server and
-// `aontu mcp` the MCP server over the CLI's own streams, so the one
-// command on PATH is the editor's and the agent's server too, and a
-// version manager (docs/design/ENV.0.md) has one thing to resolve. The
-// standalone bins (aontu-lsp, aontu-mcp) run the same functions. Each
-// server owns its exit; the CLI only dispatches. The pair is a
-// parameter of main so that a test can see the dispatch without a
-// server taking the test's own stdin.
-
 type Servers = {
   lsp: () => void
   mcp: (argv: string[]) => void
 }
 
-// The real pair takes the process's own stdin and stdout, which no
-// in-process test can lend it; the executable-entry tests in
-// cli.test.ts run each through a child process instead, so these two
-// lines are excluded from the in-process count, as the stdio wiring
-// of lsp-server.ts is.
+// Excluded: the real pair takes the process stdio, so ts/test/cli.test.ts
+// drives each server through a child process instead.
 /* node:coverage ignore next 4 */
 const SERVERS: Servers = {
   lsp: () => void lspMain(),
@@ -4202,23 +4333,353 @@ function parseTrustArg(value: string): TrustArg | undefined {
 }
 
 
+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
+}
+
+
+// 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
+}
+
+
+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] ?? '.'
+
+  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
+}
+
+
+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('-')
+}
+
+
+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
+}
+
+
+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`
-  // answer carried terminal control codes into whatever read them (the
-  // review's finding F). `NO_COLOR` is honoured by the library itself;
-  // only the CLI can see whether its stderr is a terminal, so only the
-  // CLI can make this call. `undefined` means "leave it to NO_COLOR".
   setColor(true === process.stderr.isTTY ? undefined : false)
 
   let mode: Mode = 'json'
-  // 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`
-  // printed good.json and exited 0, because `vet2` matched no
-  // subcommand, fell through to this loop as a file name, and was
-  // overwritten twice. In a tool loop that reads as a passing
-  // validation. Counting them is what lets the refusal below happen.
+  // 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'
   const files: string[] = []
   let trust: TrustArg = { kind: 'system-warn', textExt: [] }
   let textExt: string[] = []
@@ -4228,15 +4689,6 @@ function main(argv: string[], servers: Servers = SERVERS): void {
   // mode the REPL already has.
   let jsonl = false
 
-  // Subcommand dispatch, and deliberately only for a FIRST argument:
-  // `aontu vet` is the verb, while `aontu somefile vet` keeps meaning
-  // what it always did. A file named `vet` is still reachable as
-  // `aontu ./vet`.
-  //
-  // Promise.resolve either way: a non-watch run returns its exit class
-  // synchronously (and has already written its report), while `--watch`
-  // resolves only when the watch ends — so one await-shaped line serves
-  // both without a branch to keep covered.
   if ('vet' === argv[2]) {
     return void Promise.resolve(runVet(argv.slice(3))).then(finish)
   }
@@ -4264,6 +4716,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)))
   }
@@ -4276,6 +4732,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)))
   }
@@ -4331,6 +4801,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
@@ -4367,14 +4845,6 @@ function main(argv: string[], servers: Servers = SERVERS): void {
     }
   }
 
-  // ONE DOCUMENT. The bare form has always been `aontu [options]
-  // [file]`, singular, and anything past the first was silently
-  // discarded rather than refused -- so every way of getting the verb
-  // wrong (a typo, a verb this port does not have, a verb spelled for
-  // another tool) ended in a plausible answer about the wrong file.
-  // Exit 2, the usage class, and the message names the cause rather
-  // than the symptom: nothing here can tell a mistyped verb from a
-  // second file, but the reader can.
   if (1 < files.length) {
     process.stderr.write(
       `aontu: the bare command evaluates one document, and ${files.length}` +
@@ -4383,14 +4853,11 @@ function main(argv: string[], servers: Servers = SERVERS): void {
     return finish(2)
   }
 
-  // The extensions ride with the capability from here on, so the three
-  // entry shapes below (file, REPL, stdin) each get them by threading
-  // the one value they already thread.
   trust = { ...trust, textExt }
 
   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
@@ -4400,9 +4867,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
@@ -4417,7 +4884,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,
 }