dreamteamer 0.20.0 → 0.22.0

package/src/cli.js

@@ -15,13 +15,17 @@ import { execFileSync } from 'node:child_process';
 import { findWorkspace } from './workspace.js';
 import { compile, staleness, warnIfStale, discoverModules, CHANNEL_LABEL, locationOf, KINDS } from './compile.js';
 import { check } from './check.js';
-import { collectionCommand, emit, relationsCommand } from './collections-cli.js';
-import { init, install, installClone, update, listRepos } from './init.js';
+import { collectionCommand, emit, relationsCommand, parseArgs, refuseUnknownFlags } from './collections-cli.js';
+import { init, installClone, update, listRepos } from './init.js';
+import { installCommand, describeCheckout, listWorktrees, worktreeCommand } from './checkout.js';
+import { proveCommand, readLedger, flagEnabled } from './prove.js';
+import { landCommand } from './land.js';
 import { deriveEvents } from './events.js';
 import { commitPending } from './commit.js';
 import { Store } from './store.js';
 import { splitRef } from './ref.js';
 import { envContext, renderTemplate } from './env-vars.js';
+import { exportCommand, EXPORT_FLAGS } from './export-notebooklm.js';
 
 // git calls whose failure we CATCH must not print git's own error: execFileSync forwards the
 // child's stderr to ours unless told otherwise, so a handled "not a git repository" still
@@ -35,6 +39,10 @@ record verbs (hard validation — invalid writes are rejected before disk).
 A <target> is either a collection name or a <collection>/<id> reference; the reference splits at
 the longest DECLARED collection prefix, so finance/transactions/2026/03/coffee is ONE argument:
   list   <collection> [--filter k=v] [--where <json>] [--sort [-]<field>] [--json]
+  list   proofs [--missing]                   (a proof listing appends two COMPUTED columns:
+                                               availability on THIS machine, and the last verdict
+                                               from its ledger. --missing inverts it — one line per
+                                               artifact no proof is about, so it takes no filter)
                                               (--filter is ONE condition — repeat it to AND more
                                                (--filter a=1 --filter b=2 wants both);
                                                anything compound goes in one --where, operator
@@ -64,14 +72,12 @@ the longest DECLARED collection prefix, so finance/transactions/2026/03/coffee i
   history <collection>/<id> [--json]          (git revisions of this record, newest first)
   diff    <collection>/<id> [--hash <sha>]    (the patch one revision applied; defaults to HEAD)
   revert  <collection>/<id> --hash <sha>      (restore the content at <sha> as a pending write)
-  commands <collection>[/<id>] [--ids <id>,…] (bound commands + per-record state:
-                                               available / done / not-applicable)
+  next    <collection>[/<id>] [--ids <id>,…]  (which bound commands apply, and in which state:
+                                               available / done / not-applicable — what can
+                                               happen to this record next)
   relations [<collection>]                    (every two-way pair: owner.field → target.mirror)
   relations rebuild <collection> [--drop <f>] (regenerate mirror VALUES from the owning side;
                                                --drop removes a stale ex-mirror key from records)
-  ensure  <repos-id> | --all [--json]         (materialize an attached repo's working tree ON
-                                               DEMAND — never at install; --all is the explicit
-                                               opt-in, e.g. before going offline)
   resolve '<string>' | <collection>/<id> <field>
                                               (render \${env:NAME} · \${workspaceFolder} ·
                                                \${userHome} — the ONLY substitution point; a
@@ -79,10 +85,11 @@ the longest DECLARED collection prefix, so finance/transactions/2026/03/coffee i
                                                field prints one item per line)
 
 system verbs — the SAME verbs, on the entities the compiler materializes (modules, collections,
-skills, agents, commands, command-bindings, ui-views, collection-templates). ⚠ ONE difference in
-POLICY, not in spelling: a SYSTEM write commits itself, because an uncompilable or unpublished
-schema is not a state a workspace should sit in; a RECORD write does not — \`commit\` publishes it.
-The commit lands in the repo that holds the source, so a write into a git module commits there.
+skills, agents, commands, command-bindings, ui-views, collection-templates, proofs). ⚠ ONE
+difference in POLICY, not in spelling: a SYSTEM write commits itself, because an uncompilable or
+unpublished schema is not a state a workspace should sit in; a RECORD write does not — \`commit\`
+publishes it. The commit lands in the repo that holds the source, so a write into a git module
+commits there.
   add    collections --name <name> [--module <m>] [--namespace <ns>] [--template docs|entity]
                                               [--description "…"] [--suffix <s>] [--id-shape dated|slug]
                                               (--namespace health --name doctors === --name
@@ -122,7 +129,7 @@ field verbs — a field is the one sub-entity, and it has verbs of its own (ther
 collection: the ENGINE does not read one, and \`rename-field\` was the only capability it would buy):
   add-field    <collection> --name <field> --type <type> [--options a,b] [--default-value v]
                             [--required true] [--description "…"] [--many] [--inverse [name]]
-                            [--inverse-description "…"] [--unique] [--body] [--module <m>]
+                            [--inverse-description "…"] [--unique] [--body] [--sensitive] [--module <m>]
                             [--on-delete restrict|set-null] [--mirror-of <collection>.<field>]
                             types: string text markdown boolean number integer date datetime
                                    enum tags <collection> — a date-time may be written as
@@ -135,8 +142,8 @@ collection: the ENGINE does not read one, and \`rename-field\` was the only capa
                             target to have one.
                             --module writes an OVERLAY in that module (it must declare the base's
                             module in dreamteamer.dependencies).
-  update-field <collection> --name <field> [--type <type>] [--options a,b] [--default-value v]
-                            [--required true|false] [--description "…"] [--body true|false]
+  set-field    <collection> --name <field> [--type <type>] [--options a,b] [--default-value v]
+                            [--required true|false] [--description "…"] [--body true|false] [--sensitive true|false]
                             [--many] [--inverse [name]] [--unique] [--module <m>]
                             [--on-delete restrict|set-null] [--mirror-of <collection>.<field>]
                             (an existing description survives a retype, and so does every relation
@@ -145,7 +152,7 @@ collection: the ENGINE does not read one, and \`rename-field\` was the only capa
                              restating --type. --inverse= drops the mirror; --unique false clears
                              the one-to-one. Records written before the mirror existed are counted
                              for you, with the "relations rebuild" that repairs them.)
-  remove-field <collection> --name <field> [--module <m>] [--dry-run]
+  rm-field     <collection> --name <field> [--module <m>] [--dry-run]
                             (clears the field's VALUES in the same write, and reports the count)
   rename-field <collection> --name <field> --to <new-name> [--module <m>] [--dry-run]
                             (rewrites the key in every record AND everywhere a descriptor or view
@@ -159,13 +166,66 @@ Every verb that MOVES records or CLEARS values takes --dry-run and prints its pl
 workspace verbs:
   init        write the workspace skeleton into the current directory (never compiles)
   --version   print the engine version (works anywhere)
-  install     restore git_modules/ from the lockfile map; --clone <url> [name] adds one
+  install     make THIS checkout ready — the engine, .env (linked from the primary when this is a
+              worktree), declared local assets, git modules, compile, and a declared postinstall.
+              Idempotent: it prints a board of what it found and what it did
+              [--dry-run] plan only  [--json] the board as data
+              [--link-env] link .env even into a worktree OUTSIDE the primary root
+  install     --hook | --print-adapters
+              --hook: read a harness hook's JSON payload from stdin and install the checkout its
+              \`cwd\` names — the process cwd is the harness's, never the worktree's. In a linked
+              worktree the board's last line is the landing instruction.
+              --print-adapters: print the hook snippet for each declared harness. Merging it into
+              the harness's own settings file is the operator's act — the engine never writes one
+  install     repos/<id> | repos --all [--json]
+              materialize an attached repo's working tree ON DEMAND — never as part of making a
+              checkout ready; --all is the explicit opt-in, e.g. before going offline
+  install     --clone <url> [name]            attach a git module to this workspace
+  add         worktrees --name <n> [--path <dir>] [--base <ref>] [--temp] | --hook
+              cut a linked git worktree on branch worktree-<n> and \`install\` it, so it is ready
+              to work in; it prints its absolute path LAST, which is what a creation hook echoes.
+              --temp: detached, no branch, under .worktrees/.tmp-* inside this root — a sandbox
+              --hook: take the name from a WorktreeCreate payload on stdin; implies .worktrees/<n>
+  list        worktrees | get worktrees/<n> | rm worktrees/<n> [--force]
+              observed from \`git worktree list\`, never stored. rm refuses a worktree holding
+              dirty records or commits not on the primary branch — neither is visible from here
+  land        worktrees/<name|path> [--keep] [--dry-run] [--branch <n>] [--json]
+              land a worktree's commits onto the primary branch — the one MOVEMENT verb. It refuses
+              while the primary holds pending record writes, rebases a COPY of the branch under one
+              engine-owned lock, resolves ONLY the generated harness block, fast-forwards, recompiles
+              the primary, then removes the worktree and its branch. A conflict in a record aborts
+              and leaves every tree exactly as it was
+              [--keep] keep the worktree, reset onto what landed
+              [--branch <n>] give a DETACHED worktree the branch worktree-<n> first
+              [--dry-run] print the plan and change nothing
+  land        --hook [--dry-run] [--json]
+              read a WorktreeRemove payload on stdin and report what that worktree still holds.
+              ALWAYS a dry run — the engine never lands while a harness is deleting the tree
   update      pull git_modules clones forward (ff-only on the lockfile ref), rebuild,
               then compile; [<name>] updates just one. dirty clones are skipped
   compile     materialize modules + workspace sources into .dreamteamer (+ harness adapters)
               [--watch] recompile on source changes
   check       validate every record against the compiled descriptors (report-only)
-  status      workspace status: compiled runtime freshness, per-module channel/ref, staleness
+  prove       <proof> | <artifact-ref> | --all
+              run a proof and answer with an EXIT CODE: 0 pass · 1 fail · 3 unavailable (this
+              machine lacks a required var or binary) · 4 no-fixture (the given matched no record)
+              · 5 a \`perform\` step is owed a human/agent · 6 vacuous (every expectation already
+              held, so the proof cannot fail). Evidence lands in .dreamteamer/.proofs/<id>.jsonl
+              <proof>          [--record <c>/<id>] finish the pending run for that record
+                               [--restart] discard a pending run and start over
+                               [--here] run a \`writes\` proof in this workspace, not a sandbox
+                               [--keep] keep the sandbox afterwards — under --json that is
+                               \`kept: true\` beside the \`sandbox\` path  [--json] one object on stdout
+              <artifact-ref>   every proof whose \`about\` names skills/<id>, commands/<id>,
+                               command-bindings/<id> or <module>/bin/<file> — board semantics, so
+                               it takes the same [--kind gate|live] [--external] [--strict] [--json]
+              --all            every proof; a \`perform\` one is LISTED, never started, so this
+                               never exits 5. ONE line per proof — a step transcript is what a
+                               single-proof run is for [--kind gate|live] [--external] include
+                               external proofs [--strict] make an unavailable fatal [--json]
+  status      workspace status: compiled runtime freshness, per-module channel/ref, staleness,
+              and one \`proofs:\` line counting each proof's LAST verdict on this machine
+              [--strict] exit 1 when any proof's ledger tail is a FAIL
   start       serve the clean REST api at /api [--port <n>]
   changes     what changed in every repo that holds records, as record events
               [--since <sha|YYYY-MM-DD>] (default: HEAD~1 — the last commit's own changes) [--json]
@@ -175,10 +235,20 @@ workspace verbs:
               <collection> or one <collection>/<id> — the record form is what keeps a
               concurrent session's pending records out of your commit.
               [<collection>|<collection>/<id> …] [-m <subject>] [--dry-run] [--json]
+  export      render the workspace for a consumer that is not a coding agent, and optionally sync it
+              export notebooklm [--out <dir>] [--plan standard|plus|pro|ultra|<n>] [--max-words <n>]
+                                [--collections a,b] [--instructions <template.md>]
+                                [--notebook <id> | --create "<title>"] [--response-length default|longer|shorter]
+                                [--mode default|learning-guide|concise|detailed] [--wait] [--json]
+              writes one schema source (workspace → module → collection → field), one source per
+              collection (sharded by --max-words, titled \`dt · <c> [n/m]\`), and the persona from a
+              template; a collection marked \`sensitive: true\` and a field marked \`x-sensitive: true\`
+              never travel. Refuses when the sources exceed the plan. With --notebook/--create it
+              adds, replaces and removes its own sources to match and applies the persona.
   help        this text
 `;
 
-// Record verbs, split by what their <target> means. `move` and `commands` are in NEITHER set: both
+// Record verbs, split by what their <target> means. `move` and `next` are in NEITHER set: both
 // accept either shape, and which one it is has to be decided against the declared collections.
 // How many rows a per-record listing prints before it summarises. ONE number, because a report that
 // caps one of its lists and not the next reads as a bug in whichever list ran long.
@@ -186,22 +256,29 @@ const ROWS_SHOWN = 20;
 
 const REF_VERBS = new Set(['get', 'set', 'rm', 'rename', 'history', 'diff', 'revert']);
 const COLLECTION_VERBS = new Set(['list', 'add', 'values']);
-const EITHER_VERBS = new Set(['move', 'commands']);
+const EITHER_VERBS = new Set(['move', 'next']);
 
 // FIELD VERBS. Their <target> is a collection and everything else is flags, which is the one shape
 // that differs from the record verbs — so they get their own case arm rather than being folded into
 // `dispatchRecordVerb`. There is no `schema <op>` table any more: system entities take the record
 // verbs, and `collectionCommand`'s interceptors are the whole dispatch (§4).
-const FIELD_VERBS = ['add-field', 'update-field', 'remove-field', 'rename-field'];
+const FIELD_VERBS = ['add-field', 'set-field', 'rm-field', 'rename-field'];
 
 // WORKSPACE VERBS take a closed set of options, and nothing downstream of here would notice a
 // misspelling — `dt commit --dryrun` COMMITTED, because `rest.includes('--dry-run')` is false for a
 // flag nobody typed correctly. The record/system/field verbs are checked in `collections-cli.js`,
 // beside the parser they share; these nine have no shared parser, so the table is here.
 export const WORKSPACE_FLAGS = {
-	init: ['name', 'data-path', 'harnesses', 'workspace-module'], install: ['clone'], update: [],
-	start: ['port'], compile: ['watch'], check: [], status: [],
+	init: ['name', 'data-path', 'harnesses', 'workspace-module'], update: [],
+	install: ['clone', 'dry-run', 'json', 'link-env', 'all', 'hook', 'print-adapters'],
+	start: ['port'], compile: ['watch'], check: [], status: ['strict'],
 	changes: ['since', 'json'], commit: ['dry-run', 'json'],
+	export: EXPORT_FLAGS,
+	// the UNION of every form's flags — the outer typo gate. Which flags each FORM takes is refused
+	// inside `proveCommand`, where the target has been resolved against the compiled proofs.
+	prove: ['all', 'kind', 'record', 'restart', 'json', 'keep', 'here', 'external', 'strict'],
+	// same shape: the union of both forms, with `--hook`'s vocabulary refused in the arm below
+	land: ['keep', 'dry-run', 'branch', 'hook', 'json'],
 };
 
 export function run(argv) {
@@ -229,10 +306,86 @@ export function run(argv) {
 		}
 		const ws = findWorkspace();
 		switch (cmd) {
+			// ONE verb makes a thing present and ready: this checkout, or an attached repo's
+			// working tree. `ensure` was the second spelling of the same idea and is retired in the
+			// `default` arm below — no alias, per the 0.12.0 policy.
+			//
+			// ⚠ THREE FORMS, ONE FLAG TABLE — so each form REFUSES the other's vocabulary itself.
+			// `WORKSPACE_FLAGS.install` can only say which flags the verb has; it cannot know that
+			// `--dry-run` is meaningless once a target is named. Forwarding just the flags a form
+			// understands DROPS the rest in silence, and that is not a cosmetic loss:
+			// `dt install repos/x --dry-run` materialized the repo for real, driven past a flag
+			// whose entire meaning is "do nothing". A bare positional had the same shape of bug —
+			// `dt install <repo-id>`, the muscle memory `dt ensure <id>` taught for nine releases,
+			// matched neither branch, so the target was ignored and a whole checkout install ran.
+			// Same policy as the retired verbs below: a stale invocation fails loudly.
 			case 'install': {
+				const given = rest.filter((a) => a.startsWith('--'));
+				const refuse = (form, allowed) => {
+					const stray = given.filter((f) => !allowed.includes(f));
+					if (!stray.length) return;
+					throw new Error(`${stray.join(' ')} ${stray.length > 1 ? 'are not flags' : 'is not a flag'} of \`${form}\` — that form takes ${allowed.join(' ')}`);
+				};
 				const ci = rest.indexOf('--clone');
-				if (ci > -1) process.exit(installClone(ws, rest[ci + 1], rest[ci + 2]));
-				process.exit(install(ws));
+				if (ci > -1) {
+					refuse('dt install --clone <url> [name]', ['--clone']);
+					process.exit(installClone(ws, rest[ci + 1], rest[ci + 2]));
+				}
+				const target = rest.find((a) => !a.startsWith('--'));
+				if (target === 'repos' || target?.startsWith('repos/')) {
+					refuse(`dt install ${target}`, ['--all', '--json']);
+					warnIfStale(ws.root);
+					const args = target === 'repos' ? given : [target.slice('repos/'.length), ...given];
+					process.exit(collectionCommand(ws, 'repos', 'ensure', args));
+				}
+				if (target) {
+					throw new Error(`dt install takes no target "${target}" — \`dt install\` makes THIS checkout ready, and \`dt install repos/${target}\` materializes an attached repo`);
+				}
+				// ⚠ TWO MORE FORMS, EACH ITS OWN VOCABULARY. `--hook` reads a JSON payload off stdin
+				// and installs the checkout that payload names; `--print-adapters` installs nothing
+				// at all. Folding either into `dt install`'s flag list would let `--hook --dry-run`
+				// through as a plan of a checkout nobody named, and `--print-adapters --link-env`
+				// as a symlink placed by a verb whose whole job is to print.
+				if (given.includes('--hook')) {
+					refuse('dt install --hook', ['--hook']);
+					process.exit(installCommand(ws, rest));
+				}
+				if (given.includes('--print-adapters')) {
+					refuse('dt install --print-adapters', ['--print-adapters']);
+					process.exit(installCommand(ws, rest));
+				}
+				refuse('dt install', ['--dry-run', '--json', '--link-env']);
+				process.exit(installCommand(ws, rest));
+			}
+			// ⚠ THE EXIT CODE IS THE WHOLE POINT OF THIS VERB, so `proveCommand` RETURNS it and this
+			// line is the only place it becomes a process exit. Six codes are a contract — 0 pass ·
+			// 1 fail · 3 unavailable · 4 no-fixture · 5 an actor is owed a step · 6 vacuous — and a
+			// `throw` inside `prove` becomes 1 through the shared catch below, which is right for
+			// every refusal it makes (a target that names nothing, a resume with nothing to resume,
+			// a stray flag of the other form): those are errors about the INVOCATION, not verdicts
+			// about an artifact, and 2 is already spoken for by "you typed a verb that is gone".
+			//
+			// The per-form flag refusal lives in `proveCommand` rather than here, unlike `install`'s:
+			// deciding which form was typed means resolving the target against the compiled proofs
+			// and artifacts, and a second copy of that resolution in this file — purely to choose
+			// which message to print — is the drift the comment above `case 'install':` describes.
+			case 'prove':
+				warnIfStale(ws.root);
+				process.exit(proveCommand(ws, rest).code);
+			// THE ONE MOVEMENT VERB (decision 309). Two forms and, like `install`'s, each refuses the
+			// other's vocabulary here: the flag table can only say which flags `land` HAS, and a
+			// `--hook --keep` accepted-and-dropped would promise a worktree kept by a form that is
+			// always a dry run. A refusal or a conflict throws or returns 1; 2 stays what it is
+			// everywhere else — "you typed a verb that is gone".
+			case 'land': {
+				const given = rest.filter((a) => a.startsWith('--'));
+				const stray = given.filter((f) => !(given.includes('--hook') ? ['--hook', '--dry-run', '--json'] : ['--keep', '--dry-run', '--branch', '--json']).includes(f));
+				if (stray.length) {
+					const form = given.includes('--hook') ? 'dt land --hook' : 'dt land worktrees/<name>';
+					throw new Error(`${stray.join(' ')} ${stray.length > 1 ? 'are not flags' : 'is not a flag'} of \`${form}\` — that form takes ${(given.includes('--hook') ? ['--hook', '--dry-run', '--json'] : ['--keep', '--dry-run', '--branch', '--json']).join(' ')}`);
+				}
+				warnIfStale(ws.root);
+				process.exit(landCommand(ws, rest));
 			}
 			case 'update': {
 				const code = update(ws, rest.find((a) => !a.startsWith('--')));
@@ -360,6 +513,52 @@ export function run(argv) {
 					if (sh) line += ` — shadows ${CHANNEL_LABEL[sh.loser]} copy`;
 					console.log(line);
 				}
+				// ⚠ WHICH CHECKOUT AM I. Everything `install` decides turns on this, and a linked
+				// worktree is indistinguishable from the primary by eye — so it is stated, with the
+				// count of sibling worktrees holding records and commits that are invisible from
+				// here. Wrapped like every other block below: `status` is the command run when
+				// things are already wrong, and it must still print.
+				try {
+					const co = describeCheckout(ws.root);
+					console.log(`checkout: ${co.kind === 'primary' ? 'primary' : `linked worktree of ${co.primary}`}`);
+					const wts = listWorktrees(ws).filter((w) => !w.primary);
+					console.log(`worktrees: ${wts.length} · ${wts.filter((w) => w.dirtyRecords).length} with dirty records · ${wts.filter((w) => w.ahead).length} ahead`);
+				} catch { /* not a git checkout — nothing to report about worktrees */ }
+				// ⚠ WHAT THIS MACHINE HAS ACTUALLY PROVED. A ledger is per-machine and gitignored, so
+				// this line cannot be derived from the repo — and it is the only place a FAIL from
+				// last week surfaces without being asked for. The TAIL per proof, not every row: a
+				// proof that failed on Monday and passed on Tuesday is passing. Wrapped like every
+				// block here — an older runtime has no `proofs` descriptor, and status must still print.
+				// ⚠ M5 — COUNTED AS THE WALK GOES, NEVER ASSIGNED AT THE END OF IT. `proofsFailed =
+				// tally.FAIL` sat below the loop, inside the try — so a throw partway through (an
+				// unreadable ledger, a record that will not parse) left the gate reading ZERO failures
+				// and `--strict` exiting 0 BECAUSE the count broke. That is the one direction a gate
+				// must never fail: a silent green bought with a swallowed exception.
+				let proofsFailed = 0;
+				try {
+					const tally = { PASS: 0, FAIL: 0, UNAVAILABLE: 0 };
+					let declared = 0; let never = 0; let other = 0;
+					// ⚠ A SANDBOX NOTHING WILL COME BACK FOR. `.worktrees/` is gitignored, so a kept or
+					// un-removable one accumulates in silence and the ledger is the only thing that
+					// knows the directory exists. `kept` is not a row field: a terminal row with a
+					// sandbox and NO removal attempted (`null`) is exactly what `--keep` leaves behind.
+					// `existsSync` because a count nothing can clear is a lie.
+					const left = new Set();
+					for (const { id } of new Store(ws).readAll('proofs')) {
+						declared++;
+						const rows = readLedger(ws.root, id);
+						const t = rows[rows.length - 1];
+						if (!t) never++;
+						else if (t.verdict in tally) { tally[t.verdict]++; if (t.verdict === 'FAIL') proofsFailed++; }
+						else other++;
+						for (const r of rows) {
+							const behind = r.sandbox_removed === false || (r.verdict !== 'PENDING' && r.sandbox_removed === null);
+							if (r.sandbox && behind && fs.existsSync(r.sandbox)) left.add(r.sandbox);
+						}
+					}
+					console.log(`proofs: ${declared} declared · ${tally.PASS} passed · ${tally.FAIL} failed · ${tally.UNAVAILABLE} unavailable · ${never} never${other ? ` · ${other} other` : ''}`);
+					if (left.size) console.log(`  sandboxes left behind: ${left.size} — dt list worktrees`);
+				} catch { /* no proofs descriptor compiled — nothing to report */ }
 				console.log(`entries:  ${Object.keys(s.manifest.entries).length}`);
 				// repos materialize LAZILY, so presence is REPORTED here rather than stored on the
 				// record. Wrapped: an older workspace may predate the repos descriptor, and status
@@ -370,8 +569,8 @@ export function run(argv) {
 						const here = repos.filter((r) => r.present).length;
 						console.log(`repos:    ${here}/${repos.length} materialized`);
 						// an UNRESOLVED path is not the same absence as a repo simply not cloned yet, and
-						// `dreamteamer ensure` is not the fix for it — say which one this is.
-						for (const r of repos) if (!r.present) console.log(`  absent: ${r.id} → ${r.path}${r.unresolved ? ` — ${r.unresolved}` : ` (dreamteamer ensure ${r.id})`}`);
+						// `dreamteamer install repos/<id>` is not the fix for it — say which one this is.
+						for (const r of repos) if (!r.present) console.log(`  absent: ${r.id} → ${r.path}${r.unresolved ? ` — ${r.unresolved}` : ` (dreamteamer install repos/${r.id})`}`);
 					}
 				} catch { /* no repos descriptor compiled — nothing to report */ }
 				// Uncommitted records are invisible to `dt changes` (it diffs commits), so the
@@ -390,25 +589,58 @@ export function run(argv) {
 					process.exit(1);
 				}
 				console.log('✔ .dreamteamer is fresh');
+				// ⚠ THE FAIL IS FATAL ONLY WHEN ASKED. `status` is the command you run when things are
+				// already wrong, so it prints EVERYTHING first and gates last — the same shape the
+				// staleness exit above has.
+				// ⚠ R38/R46 — `--strict=true` IS THE SAME FLAG, AND `--strict=false` IS OFF. The
+				// unknown-flag gate above splits on `=`, so the `=` spelling was ACCEPTED and then read
+				// as "no --strict at all" — a CI step written that way stayed green over a failing
+				// proof, for a reason nothing printed. `flagEnabled` is the one reader of that shape,
+				// shared with `dt prove`, so the two verbs cannot disagree about what was typed.
+				if (flagEnabled(rest, 'strict') && proofsFailed) {
+					console.log(`✖ ${proofsFailed} proof(s) FAILED on this machine — dt list proofs`);
+					process.exit(1);
+				}
 				process.exit(0);
 			}
+			// `export <target>` — the workspace rendered for a consumer that is not a coding agent. One
+			// target today; the map in export-notebooklm.js is where a second one would register, the way
+			// harnesses do. Without --notebook/--create it is a pure render and touches no network.
+			case 'export': {
+				warnIfStale(ws.root);
+				const { flags, pos } = parseArgs(rest);
+				process.exit(exportCommand(ws, pos[0], flags));
+			}
 			case 'help':
 				emit(USAGE);
 				process.exit(0);
 			case 'list': case 'add': case 'values':
 			case 'get': case 'set': case 'rm': case 'rename': case 'history': case 'diff': case 'revert':
-			case 'move': case 'commands':
+			case 'move': case 'next': {
+				// ⚠ `worktrees` IS NOT A COLLECTION — it is observed from git — so it is intercepted
+				// here rather than being dispatched. Which means it never reaches
+				// `collectionCommand`, where every other verb's flags are refused: the parse and the
+				// refusal have to be done HERE or `--tmep` is swallowed and a request for a
+				// throwaway sandbox silently becomes a permanent branch worktree.
+				const target = rest[0];
+				if (target === 'worktrees' || target?.startsWith('worktrees/')) {
+					const { flags } = parseArgs(rest.slice(1));
+					refuseUnknownFlags(null, 'worktrees', cmd, flags);
+					process.exit(worktreeCommand(ws, cmd, target, flags));
+				}
 				warnIfStale(ws.root);
 				process.exit(dispatchRecordVerb(ws, cmd, rest));
+			}
 			// The verb `check`'s stale-mirror message names. It reads the compiled relations, and
 			// rebuild WRITES records, so both want the same staleness warning every record verb gets.
 			// FIELD VERBS — see FIELD_VERBS. Their <target> is a collection and everything else is
 			// flags, so they are their own case rather than being folded into `dispatchRecordVerb`.
 			//
-			// ⚠ `dt schema <op>` is GONE, not aliased. The 0.12.0 policy: a stale invocation must fail
-			// loudly, because a half-working grammar teaches the wrong shape without ever saying so.
-			// The `default` arm below names `schema` specifically.
-			case 'add-field': case 'update-field': case 'remove-field': case 'rename-field': {
+			// ⚠ THE RETIRED SPELLINGS ARE GONE, not aliased. The 0.12.0 policy: a stale invocation
+			// must fail loudly, because a half-working grammar teaches the wrong shape without ever
+			// saying so. The `default` arm below names each one — `schema`, `ensure`, `update-field`,
+			// `remove-field`, `commands` — and carries its replacement.
+			case 'add-field': case 'set-field': case 'rm-field': case 'rename-field': {
 				warnIfStale(ws.root);
 				const [target, ...flagArgs] = rest;
 				if (!target || target.startsWith('--')) {
@@ -419,28 +651,51 @@ export function run(argv) {
 			case 'relations':
 				warnIfStale(ws.root);
 				process.exit(relationsCommand(ws, rest));
-			// `repos ensure` lost its noun: the repos collection is still where the declaration lives,
-			// but materializing one is a verb the operator types, not a record write.
-			case 'ensure':
-				warnIfStale(ws.root);
-				process.exit(collectionCommand(ws, 'repos', 'ensure', rest));
 			case 'resolve':
 				process.exit(resolveVariables(ws, rest));
 			default:
 				// ⚠ NAMED, not just unknown. Every doc, skill and downstream script spelled these
 				// `dt schema <op>` for seven releases, so the failure has to carry the translation —
-				// an "unknown verb" alone sends the reader to `help` to guess which of nine verbs
+				// an "unknown verb" alone sends the reader to `help` to guess which of thirty verbs
 				// replaced the one they typed. No alias layer and no deprecation window: 0.12.0's
 				// policy, and the reason it is the right one is that `dt contacts list` failing
 				// loudly is what taught the verb-first grammar in one command.
+				//
+				// ⚠ ONE EXIT CODE FOR ALL OF THEM: 2, the usage code. "You typed a verb that is
+				// gone" is one answer, so a script (and an operator) asks it once rather than
+				// learning which retirement exits 1 and which exits 2.
 				if (cmd === 'schema') {
 					console.error('✖ unknown verb "schema" — schema verbs are gone since 0.19.0. System entities take the RECORD verbs now:');
 					console.error('    dt add collections --name <c> [--module <m>] · dt rm collections/<c> · dt rename collections/<old> <new>');
 					console.error('    dt set collections/<c> module=<m> | <scalar>=<v>   · dt get collections/<c> [--module <m>]');
-					console.error('    dt add-field <c> … · dt update-field <c> … · dt remove-field <c> … · dt rename-field <c> --name <f> --to <g>');
+					console.error('    dt add-field <c> … · dt set-field <c> … · dt rm-field <c> … · dt rename-field <c> --name <f> --to <g>');
 					console.error('    dt add|set|rm|rename modules/<id> …               · dt add|set|rm|rename ui-views/<id> …');
 					console.error('  the full mapping table is in UPDATING.md (0.18.0 → 0.19.0), and `dt help` has the current spellings.');
-					process.exit(1);
+					process.exit(2);
+				}
+				if (cmd === 'ensure') {
+					console.error('✖ unknown verb "ensure" — gone since 0.22.0 (decision 309: install is the one verb that makes a thing present and ready):');
+					console.error('    dt install                 this checkout — engine, .env, local assets, git modules, compile, postinstall');
+					console.error('    dt install repos/<id>      materialize one attached repo · dt install repos --all');
+					process.exit(2);
+				}
+				// The change verbs spell one way. `add · set · rm · rename` are the record verbs, so
+				// `update-field`/`remove-field` were a second spelling for one action inside one
+				// grammar — the field verbs now say `add-field · set-field · rm-field · rename-field`.
+				if (cmd === 'update-field' || cmd === 'remove-field') {
+					const to = cmd === 'update-field' ? 'set-field' : 'rm-field';
+					console.error(`✖ unknown verb "${cmd}" — gone since 0.22.0 (decision 309: a field verb spells its action the way the record verbs do):`);
+					console.error(`    dt ${to} <collection> --name <field> …`);
+					console.error('    the field verbs are: dt add-field · dt set-field · dt rm-field · dt rename-field');
+					process.exit(2);
+				}
+				// `dt commands <ref>` and `dt list commands` were one word for two things — the read
+				// verb and the system entity. `next` also says what it answers.
+				if (cmd === 'commands') {
+					console.error('✖ unknown verb "commands" — gone since 0.22.0 (decision 309: it collided with the `commands` ENTITY, which `dt list commands` reads):');
+					console.error('    dt next <collection>[/<id>]   which bound commands apply to this record, and in which state');
+					console.error('    dt list commands              the command entities this workspace ships');
+					process.exit(2);
 				}
 				console.error(`✖ unknown verb "${cmd}" — dreamteamer is verb-first since 0.12.0: dt <verb> [<target>]`);
 				emit(USAGE, 2);
@@ -448,6 +703,12 @@ export function run(argv) {
 		}
 	} catch (e) {
 		console.error(`✖ ${e.message}`);
+		// ⚠ AND ON STDOUT UNDER `--hook`, because that is the whole reason the shim exists.
+		// `bin/dt-hook.sh` fails onto stdout with a comment saying why: a hook's stdout is added to
+		// the session's context and its stderr is nobody's problem. Every success path here already
+		// prints to stdout; every FAILURE went to stderr alone, so a mis-wired hook, a bad payload, a
+		// TTY invocation or a refusal was invisible to exactly the reader the shim was built for.
+		if (process.argv.includes('--hook')) console.log(`✖ ${e.message}`);
 		process.exit(1);
 	}
 }
@@ -465,7 +726,7 @@ function dispatchRecordVerb(ws, verb, args) {
 		return collectionCommand(ws, collection, verb, [id, ...rest]);
 	}
 	// EITHER_VERBS from here: a bare collection is legal for both — `move <collection> --init`,
-	// `commands <collection>`.
+	// `next <collection>`.
 	const { descriptors } = new Store(ws);
 	if (descriptors.has(target)) {
 		return verb === 'move'