@metaobjectsdev/cli 0.9.0-rc.1 → 0.10.0

package/src/commands/init.ts

@@ -1,10 +1,16 @@
 import { mkdir, writeFile, readFile, stat } from "node:fs/promises";
 import { join } from "node:path";
-import { basename } from "node:path";
+import { basename, dirname } from "node:path";
+import { existsSync as existsSyncWrap, readFileSync as readFileSyncWrap } from "node:fs";
 import { DEFAULT_CONFIG, ConfigSchema, saveConfig, PACKAGE_MANIFEST_FILE, DEFAULT_METADATA_DIR, DEFAULT_METAOBJECTS_DIR } from "@metaobjectsdev/sdk";
+import {
+  assemble, resolveAgentContextRoot, planScaffold,
+  AGENT_CONTEXT_MANIFEST_PATH, type Manifest,
+} from "@metaobjectsdev/sdk/agent-context";
+import { resolveStack } from "../lib/detect-stack.js";
 import { parseInitArgs } from "../lib/args.js";
 import { log } from "../lib/log.js";
-import { AGENT_DOCS_BODY, withContentHash, isUnmodified } from "@metaobjectsdev/sdk/agent-docs";
+import { cliVersion } from "../lib/version.js";
 import { findWranglerConfig, parseWranglerConfig } from "@metaobjectsdev/migrate-ts";
 
 const META_COMMON_JSON = JSON.stringify(
@@ -32,7 +38,7 @@ import {
 } from "@metaobjectsdev/codegen-ts/generators";
 
 export default defineConfig({
-  outDir:    "./src/db",
+  outDir:    "src/generated",
   extStyle:  "none",
   dbImport:  "../db",
   dialect:   "${dialect}",
@@ -43,6 +49,11 @@ export default defineConfig({
     routesFile(),
     barrel(),
   ],
+  docs: {
+    outDir:   "./docs",        // model + api surfaces both land here (run: meta docs)
+    layout:   "flat",          // or "package" for multi-package models
+    surfaces: ["model", "api"],
+  },
 });
 `;
 }
@@ -53,12 +64,11 @@ Initialized metaobjects/ + .metaobjects/ + metaobjects.config.ts
 Next steps (when later sub-projects ship):
   meta ingest        # propose entities from your existing TS code
   meta gen           # codegen TS targets from entities
+  meta docs          # neutral model docs (entity + template pages, incl. linked template source)
   meta serve         # local viewer
   meta install-hooks # register MCP server + Claude Code hooks
 `;
 
-const AGENT_DOC_FILES = ["AGENTS.md", "CLAUDE.md"] as const;
-
 export interface InitOptions {
   cwd: string;
   force?: boolean;
@@ -66,6 +76,12 @@ export interface InitOptions {
   printOnly?: boolean;
   refreshDocs?: boolean;
   d1?: boolean;
+  servers?: string[];
+  clients?: string[];
+  noSkills?: boolean;
+  wireRoot?: boolean;
+  /** Scaffold ONLY the agent-context (always-on + skills + root wiring), skipping the metaobjects/ project scaffold — for dropping context into an existing/polyglot repo. */
+  docsOnly?: boolean;
 }
 
 export interface InitResult {
@@ -74,29 +90,71 @@ export interface InitResult {
   warnings: string[];
 }
 
-async function writeAgentDocs(agentDir: string, result: InitResult): Promise<void> {
-  const docsBody = withContentHash(AGENT_DOCS_BODY);
-  for (const filename of AGENT_DOC_FILES) {
-    const path = join(agentDir, filename);
-    const exists = await fileExists(path);
+async function readManifest(cwd: string): Promise<Manifest | undefined> {
+  const p = join(cwd, AGENT_CONTEXT_MANIFEST_PATH);
+  if (!(await fileExists(p))) return undefined;
+  try { return JSON.parse(await readFile(p, "utf8")) as Manifest; } catch { return undefined; }
+}
 
-    if (!exists) {
-      await writeFile(path, docsBody, "utf8");
-      result.created.push(`.metaobjects/${filename}`);
-      continue;
-    }
+async function writeAgentContext(opts: InitOptions, result: InitResult): Promise<void> {
+  const stack = resolveStack(opts.cwd, { servers: opts.servers ?? [], clients: opts.clients ?? [] });
+  let assembled = assemble({ contentRoot: resolveAgentContextRoot(), stack });
+  if (opts.noSkills) assembled = assembled.filter((f) => !f.path.startsWith(".claude/skills/"));
+
+  const prior = await readManifest(opts.cwd);
+  const decision = planScaffold({
+    stack, assembled, prior,
+    readCurrent: (rel) => {
+      const abs = join(opts.cwd, rel);
+      return existsSyncWrap(abs) ? readFileSyncWrap(abs, "utf8") : undefined;
+    },
+    generatedBy: cliVersion(),
+  });
+
+  for (const w of decision.writes) {
+    const abs = join(opts.cwd, w.path);
+    await mkdir(dirname(abs), { recursive: true });
+    await writeFile(abs, w.contents, "utf8");
+    result.created.push(w.path);
+  }
+  for (const c of decision.conflicts) {
+    const abs = join(opts.cwd, c.newPath);
+    await mkdir(dirname(abs), { recursive: true });
+    await writeFile(abs, c.contents, "utf8");
+    result.created.push(c.newPath);
+    result.warnings.push(`${c.path} appears hand-edited; refreshed version written to ${c.newPath}`);
+  }
+  const manifestAbs = join(opts.cwd, AGENT_CONTEXT_MANIFEST_PATH);
+  await mkdir(dirname(manifestAbs), { recursive: true });
+  await writeFile(manifestAbs, JSON.stringify(decision.manifest, null, 2) + "\n", "utf8");
 
-    const existingBody = await readFile(path, "utf8");
-    if (isUnmodified(existingBody)) {
-      await writeFile(path, docsBody, "utf8");
-      result.created.push(`.metaobjects/${filename}`);
-    } else {
-      await writeFile(`${path}.new`, docsBody, "utf8");
-      result.created.push(`.metaobjects/${filename}.new`);
-      result.warnings.push(
-        `${filename} appears to have been hand-edited; refreshed docs written to ${filename}.new`,
-      );
-    }
+  for (const orphan of decision.removed) {
+    result.warnings.push(`${orphan} is no longer part of this stack; orphaned (safe to delete).`);
+  }
+
+  if (opts.wireRoot) await wireRootMemory(opts.cwd, result);
+}
+
+const ROOT_IMPORT_LINE = "@.metaobjects/AGENTS.md";
+async function wireRootMemory(cwd: string, result: InitResult): Promise<void> {
+  const claudePath = join(cwd, "CLAUDE.md");
+  const agentsPath = join(cwd, "AGENTS.md");
+  const claudeExists = await fileExists(claudePath);
+  const agentsExists = await fileExists(agentsPath);
+
+  // If neither root memory file exists, create CLAUDE.md (Claude Code's canonical) with the import.
+  if (!claudeExists && !agentsExists) {
+    await writeFile(claudePath, `# Project memory\n\n${ROOT_IMPORT_LINE}\n`, "utf8");
+    result.created.push("CLAUDE.md (created with MetaObjects @import)");
+    return;
+  }
+  // Otherwise append the import to whichever exist (idempotent — never double-add).
+  for (const [path, exists] of [[claudePath, claudeExists], [agentsPath, agentsExists]] as const) {
+    if (!exists) continue;
+    const body = await readFile(path, "utf8");
+    if (body.includes(ROOT_IMPORT_LINE)) continue;
+    await writeFile(path, `${body.replace(/\n*$/, "\n")}\n${ROOT_IMPORT_LINE}\n`, "utf8");
+    result.warnings.push(`wired ${ROOT_IMPORT_LINE} into ${path.endsWith("AGENTS.md") ? "AGENTS.md" : "CLAUDE.md"} so the MetaObjects context loads`);
   }
 }
 
@@ -109,9 +167,15 @@ export async function init(opts: InitOptions): Promise<InitResult> {
   const metaobjectsExists = await dirExists(metaobjectsDir);
   const exists = agentDirExists || metaobjectsExists;
 
+  if (opts.docsOnly) {
+    // Agent-context only: scaffold the always-on + skills + root wiring, never the metaobjects/ project.
+    await writeAgentContext(opts, result);
+    return result;
+  }
+
   if (opts.refreshDocs && exists && !opts.force) {
-    // Refresh-only path: scaffold agent docs, leave everything else alone.
-    await writeAgentDocs(agentDir, result);
+    // Refresh-only path: scaffold the agent-context, leave everything else alone.
+    await writeAgentContext(opts, result);
     return result;
   }
 
@@ -135,7 +199,7 @@ export async function init(opts: InitOptions): Promise<InitResult> {
       ".metaobjects/.gitignore",
       `.metaobjects/${PACKAGE_MANIFEST_FILE}`,
     );
-    for (const filename of AGENT_DOC_FILES) result.created.push(`.metaobjects/${filename}`);
+    result.created.push(".metaobjects/AGENTS.md", ".metaobjects/CLAUDE.md", ".claude/skills/metaobjects-*", AGENT_CONTEXT_MANIFEST_PATH);
     result.created.push("metaobjects.config.ts");
     return result;
   }
@@ -214,7 +278,7 @@ export async function init(opts: InitOptions): Promise<InitResult> {
     result.preserved.push(`.metaobjects/${PACKAGE_MANIFEST_FILE}`);
   }
 
-  await writeAgentDocs(agentDir, result);
+  await writeAgentContext(opts, result);
 
   // Scaffold metaobjects.config.ts at the project root. Never overwrite if it exists.
   const forgeConfigPath = join(opts.cwd, "metaobjects.config.ts");
@@ -283,6 +347,11 @@ export async function initCommand(args: string[], cwd: string): Promise<number>
       printOnly: flags.printOnly,
       refreshDocs: flags.refreshDocs,
       d1: flags.d1,
+      servers: flags.servers,
+      clients: flags.clients,
+      noSkills: flags.noSkills,
+      wireRoot: flags.wireRoot,
+      docsOnly: flags.docsOnly,
     });
 
     if (flags.printOnly) {
@@ -292,7 +361,13 @@ export async function initCommand(args: string[], cwd: string): Promise<number>
     }
 
     if (!flags.quiet) {
-      log.info(nextStepsBlock());
+      if (flags.docsOnly) {
+        log.info(`Scaffolded the MetaObjects agent context (${result.created.length} files): .metaobjects/AGENTS.md + .claude/skills/metaobjects-*.`);
+        for (const w of result.warnings) log.info(`  ${w}`);
+        log.info("Re-run --docs-only --refresh-docs to update; --no-wire-root to skip the root CLAUDE.md @import.");
+      } else {
+        log.info(nextStepsBlock());
+      }
     }
     return 0;
   } catch (err) {

package/src/commands/verify.ts

@@ -10,9 +10,12 @@
 import { join } from "node:path";
 import { parseVerifyArgs } from "../lib/args.js";
 import { log } from "../lib/log.js";
+import { warnIfAgentContextStale } from "../lib/agent-context-staleness.js";
 import { FileProvider } from "../lib/file-provider.js";
 import { derivePayloadFieldTree } from "../lib/payload-field-tree.js";
 import { loadMetaobjectsConfig } from "../lib/load-metaobjects-config.js";
+import { computeCodegenDrift } from "../lib/codegen-drift.js";
+import type { MetaobjectsGenConfig } from "@metaobjectsdev/codegen-ts";
 import { buildKyselyFromUrl, type Dialect } from "../lib/kysely.js";
 import { tokensToAllowOptions, describeChange } from "../lib/allow.js";
 import { computeDrift, type Change } from "@metaobjectsdev/migrate-ts";
@@ -46,18 +49,38 @@ export async function verifyCommand(args: string[], cwd: string): Promise<number
     return 2;
   }
 
-  // Best-effort load of metaobjects.config.ts to pick up consumer-supplied
-  // providers (e.g. a project's `template.toolcall` subtype). verify doesn't
-  // require codegen config; if it's absent or invalid, fall back to defaults
-  // — the loader will surface a stable ERR_UNKNOWN_SUBTYPE if the metadata
-  // actually uses a non-default subtype.
-  let configProviders: NonNullable<Awaited<ReturnType<typeof loadMetaobjectsConfig>>["providers"]> | undefined;
+  // Advisory: nudge to refresh the .claude/skills docs if they predate this CLI.
+  warnIfAgentContextStale(cwd);
+
+  // ADR-0021 D2 — explicit verify subverbs. Each flag selects one drift mode;
+  // any combination runs each and the overall exit code is the MAX (non-zero on
+  // any drift). A bare `verify` (no explicit subverb) keeps its documented
+  // back-compat default: the template/prompt drift gate — plus a one-line note
+  // advertising the explicit subverbs.
+  const runTemplates = flags.templates || !flags.anyExplicit;
+  // The schema (--db) gate is selected by the presence of --db; that check lives
+  // inside runSchemaVerify (where `flags.db === undefined` also narrows the type).
+  const runCodegen = flags.codegen;
+  if (!flags.anyExplicit) {
+    log.info(
+      "meta verify — running --templates (default). Explicit subverbs: " +
+        "--templates (prompt drift), --db (schema drift), --codegen (codegen drift).",
+    );
+  }
+
+  // Best-effort load of metaobjects.config.ts. Two consumers:
+  //  1) consumer-supplied providers (e.g. a `template.toolcall` subtype) threaded
+  //     into loadMemory — verify doesn't REQUIRE codegen config for templates/db;
+  //  2) the full config object, which `--codegen` needs to locate outDir/targets.
+  // If absent/invalid we fall back to defaults; `--codegen` then reports a clear
+  // error (it can't diff without knowing where the committed output lives).
+  let forgeConfig: MetaobjectsGenConfig | undefined;
   try {
-    const forgeConfig = await loadMetaobjectsConfig(cwd);
-    configProviders = forgeConfig.providers;
+    forgeConfig = await loadMetaobjectsConfig(cwd);
   } catch {
-    configProviders = undefined;
+    forgeConfig = undefined;
   }
+  const configProviders = forgeConfig?.providers;
 
   let root: Awaited<ReturnType<typeof loadMemory>>;
   try {
@@ -77,13 +100,13 @@ export async function verifyCommand(args: string[], cwd: string): Promise<number
   const promptsDir = join(cwd, flags.prompts ?? DEFAULT_PROMPTS_DIR);
   const provider = new FileProvider(promptsDir);
 
-  // Exit-code composition: the overall result is max(templateExit, schemaExit)
-  // so either kind of drift fails CI. The schema path only runs when --db is
-  // present (and not --skip-schema); with no --db it is skipped entirely and
-  // the exit reflects the template path alone (unchanged behavior).
-  const templateExit = runTemplateVerify();
+  // Exit-code composition: the overall result is the MAX across every selected
+  // subverb so ANY kind of drift fails CI. Each gate only runs when its mode is
+  // selected; an unselected gate contributes 0.
+  const templateExit = runTemplates ? runTemplateVerify() : 0;
   const schemaExit = await runSchemaVerify();
-  return Math.max(templateExit, schemaExit);
+  const codegenExit = runCodegen ? await runCodegenVerify() : 0;
+  return Math.max(templateExit, schemaExit, codegenExit);
 
   // -- template (prompt / output) drift --------------------------------------
   function runTemplateVerify(): number {
@@ -168,6 +191,8 @@ export async function verifyCommand(args: string[], cwd: string): Promise<number
   // Gated on --db. With no --db (or --skip-schema), this is a no-op returning 0
   // — the DB-free default behavior is unchanged.
   async function runSchemaVerify(): Promise<number> {
+    // `flags.db === undefined` is exactly `!runDb`; written this way so TS
+    // narrows flags.db to `string` for buildKyselyFromUrl below.
     if (flags.db === undefined || flags.skipSchema) return 0;
 
     // d1 has no Kysely-driver introspection path, so the schema-drift gate
@@ -216,6 +241,47 @@ export async function verifyCommand(args: string[], cwd: string): Promise<number
       }
     }
   }
+
+  // -- codegen drift (ADR-0021 D2) -------------------------------------------
+  // Gated on --codegen. Regenerates to a temp dir and diffs against the
+  // committed output (config outDir / per-target outDirs). Requires a config:
+  // without one, there's no committed-output location to diff against, so it
+  // errors clearly (exit 2 — a usage/configuration problem, not a drift result).
+  async function runCodegenVerify(): Promise<number> {
+    if (forgeConfig === undefined) {
+      log.error(
+        "verify --codegen: no metaobjects.config.ts found (or it is invalid) — " +
+          "cannot locate the committed generated output to diff against. " +
+          "Run 'meta init' to scaffold one, or run without --codegen.",
+      );
+      return 2;
+    }
+
+    let result;
+    try {
+      result = await computeCodegenDrift(forgeConfig, root, cwd);
+    } catch (err) {
+      log.error(`verify --codegen: regeneration failed: ${(err as Error).message}`);
+      return 1;
+    }
+
+    if (result.error !== undefined) {
+      log.error(result.error);
+      return 2;
+    }
+
+    if (result.clean) {
+      log.info("meta verify — generated output is in sync with the metadata (no codegen drift).");
+      return 0;
+    }
+
+    log.error(
+      `meta verify — codegen drift (${result.driftedFiles.length} file(s) differ from a fresh regen):`,
+    );
+    for (const line of result.lines) log.error(`  ${line}`);
+    log.error("Run 'meta gen' to regenerate, then commit the result.");
+    return 1;
+  }
 }
 
 /**

package/src/index.ts

@@ -1,33 +1,10 @@
-import { existsSync, readFileSync } from "node:fs";
-import { dirname, join, resolve } from "node:path";
-import { fileURLToPath } from "node:url";
+import { resolve } from "node:path";
 import { log } from "./lib/log.js";
+import { cliVersion } from "./lib/version.js";
 export { defineConfig } from "@metaobjectsdev/codegen-ts";
 export type { MetaobjectsGenConfig } from "@metaobjectsdev/codegen-ts";
 
-// Derive the version from the CLI's own package.json so it never goes stale.
-// The compiled entry is dist/src/index.js while package.json sits at the package
-// root, so walk up from the module location until @metaobjectsdev/cli's manifest.
-function readCliVersion(): string {
-  let dir = dirname(fileURLToPath(import.meta.url));
-  for (let i = 0; i < 6; i++) {
-    const candidate = join(dir, "package.json");
-    if (existsSync(candidate)) {
-      try {
-        const pkg = JSON.parse(readFileSync(candidate, "utf8")) as { name?: string; version?: string };
-        if (pkg.name === "@metaobjectsdev/cli" && pkg.version) return pkg.version;
-      } catch {
-        // not our manifest / unreadable — keep walking up
-      }
-    }
-    const parent = dirname(dir);
-    if (parent === dir) break;
-    dir = parent;
-  }
-  return "0.0.0";
-}
-
-const VERSION = readCliVersion();
+const VERSION = cliVersion();
 
 const HELP_TEXT = `meta — MetaObjects CLI (v${VERSION})
 
@@ -39,7 +16,8 @@ COMMANDS:
   init --refresh-docs   Refresh .metaobjects/AGENTS.md + CLAUDE.md after CLI upgrades
   gen [<entity>...]     Codegen TS targets from metaobjects/ entities
   export                Flatten loaded metadata to one canonical JSON artifact
-  verify                Check template.* text against its payload (drift gate)
+  docs <metadata> --out <dir>  Generate neutral metadata documentation (entity + template pages)
+  verify                Drift gate — subverbs: --templates / --db / --codegen (bare = --templates)
   prompt-snapshot       Snapshot rendered template.* output; --check gates drift
   migrate               Diff metadata vs live DB; emit migration SQL files
   --version, -v         Print version
@@ -56,10 +34,18 @@ GEN FLAGS:
 EXPORT FLAGS:
   --out <file>          Write output to a file (default: stdout)
 
-VERIFY FLAGS:
-  --prompts <dir>       Directory of provider-resolved template text (default: prompts)
-  --db <url>            Live DB URL — enables the schema-drift gate (exit 1 on drift).
+DOCS FLAGS:
+  <metadata>            Project root holding metaobjects/ (default: current directory)
+  --out <dir>, -o       Output directory for the pages (default: ./docs)
+  --templates <dir>     Project root to resolve adopter templates/ overrides (default: <metadata>)
+
+VERIFY FLAGS (ADR-0021 D2 — explicit subverbs; combine any; exit 1 on ANY drift):
+  --templates           Template/prompt {{field}}↔payload drift (the bare-verify default)
+  --codegen             Codegen drift — regenerate to a temp dir and diff the committed
+                        output (config outDir/targets). Needs metaobjects.config.ts; exit 2 if absent.
+  --db <url>            Schema drift — live DB URL enables the schema-drift gate.
                         Supports: file:, libsql:, postgres:, postgresql:. Omit to skip.
+  --prompts <dir>       Directory of provider-resolved template text (default: prompts)
   --dialect sqlite|postgres   Optional override (auto-detected from --db URL scheme)
   --allow <csv>         Accepted for parity with 'migrate'; does NOT affect the
                         verify drift gate (the gate fails on ANY detected change)
@@ -140,6 +126,10 @@ export async function run(argv: string[]): Promise<number> {
       const { exportCommand } = await import("./commands/export.js");
       return exportCommand(rest, cwd);
     }
+    case "docs": {
+      const { docsCommand } = await import("./commands/docs.js");
+      return docsCommand(rest, cwd);
+    }
     case "verify": {
       const { verifyCommand } = await import("./commands/verify.js");
       return verifyCommand(rest, cwd);

package/src/lib/agent-context-staleness.ts

@@ -0,0 +1,24 @@
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { AGENT_CONTEXT_MANIFEST_PATH, agentContextStaleness, type Manifest } from "@metaobjectsdev/sdk";
+import { cliVersion } from "./version.js";
+import { log } from "./log.js";
+
+/**
+ * Advisory: if a scaffolded MetaObjects agent context predates this CLI version,
+ * print a one-line nudge to re-scaffold. Never throws, never blocks — an absent or
+ * corrupt manifest is silently ignored (this is a reminder, not a gate).
+ */
+export function warnIfAgentContextStale(cwd: string): void {
+  const p = join(cwd, AGENT_CONTEXT_MANIFEST_PATH);
+  let manifest: Manifest | undefined;
+  if (existsSync(p)) {
+    try {
+      manifest = JSON.parse(readFileSync(p, "utf8")) as Manifest;
+    } catch {
+      return; // unreadable/corrupt — say nothing
+    }
+  }
+  const msg = agentContextStaleness({ manifest, currentVersion: cliVersion() });
+  if (msg !== null) log.warn(msg);
+}

package/src/lib/args.ts

@@ -10,6 +10,11 @@ export interface InitFlags {
   printOnly: boolean;
   refreshDocs: boolean;
   d1: boolean;
+  servers: string[];
+  clients: string[];
+  noSkills: boolean;
+  wireRoot: boolean;
+  docsOnly: boolean;
 }
 
 export function parseInitArgs(argv: string[]): InitFlags {
@@ -21,6 +26,11 @@ export function parseInitArgs(argv: string[]): InitFlags {
       "print-only": { type: "boolean", default: false },
       "refresh-docs": { type: "boolean", default: false },
       d1: { type: "boolean", default: false },
+      server: { type: "string", multiple: true },
+      client: { type: "string", multiple: true },
+      "no-skills": { type: "boolean", default: false },
+      "no-wire-root": { type: "boolean", default: false },
+      "docs-only": { type: "boolean", default: false },
     },
     strict: true,
     allowPositionals: false,
@@ -31,6 +41,11 @@ export function parseInitArgs(argv: string[]): InitFlags {
     printOnly: !!values["print-only"],
     refreshDocs: !!values["refresh-docs"],
     d1: !!values.d1,
+    servers: (values.server as string[] | undefined) ?? [],
+    clients: (values.client as string[] | undefined) ?? [],
+    noSkills: !!values["no-skills"],
+    wireRoot: !values["no-wire-root"],
+    docsOnly: !!values["docs-only"],
   };
 }
 
@@ -45,6 +60,9 @@ export interface GenFlags {
    *  (existing content becomes the canonical baseline). "fresh" → overwrite
    *  and re-baseline. */
   baseline: "default" | "fresh";
+  /** ADR-0021 D3 — print the stable-name generator registry and exit without
+   *  running codegen. */
+  list: boolean;
 }
 
 export function parseGenArgs(argv: string[]): GenFlags {
@@ -53,6 +71,7 @@ export function parseGenArgs(argv: string[]): GenFlags {
     options: {
       "dry-run": { type: "boolean", default: false },
       "baseline": { type: "string" },
+      "list": { type: "boolean", default: false },
     },
     strict: true,
     allowPositionals: true,
@@ -67,6 +86,7 @@ export function parseGenArgs(argv: string[]): GenFlags {
     dryRun: !!values["dry-run"],
     entities: positionals,
     baseline: (baselineRaw as "default" | "fresh" | undefined) ?? "default",
+    list: !!values.list,
   };
 }
 
@@ -124,6 +144,16 @@ export interface VerifyFlags {
   allow: AllowToken[];
   /** Skip the schema-drift gate even when --db is present. */
   skipSchema: boolean;
+  // ADR-0021 D2 — explicit verify subverbs. Each selects one drift mode; any
+  // combination may be passed and the exit code aggregates (non-zero on any
+  // drift). The boolean flags record which modes were explicitly requested; the
+  // command layer applies the bare-verify default (= --templates) when none are.
+  /** Run the template/prompt {{field}}↔payload drift gate. */
+  templates: boolean;
+  /** Run the codegen-drift gate (regenerate-to-temp and diff committed output). */
+  codegen: boolean;
+  /** Whether ANY explicit subverb flag (--templates/--db/--codegen) was passed. */
+  anyExplicit: boolean;
 }
 
 export function parseVerifyArgs(argv: string[]): VerifyFlags {
@@ -135,6 +165,8 @@ export function parseVerifyArgs(argv: string[]): VerifyFlags {
       dialect: { type: "string" },
       allow: { type: "string" },
       "skip-schema": { type: "boolean", default: false },
+      templates: { type: "boolean", default: false },
+      codegen: { type: "boolean", default: false },
     },
     strict: true,
     allowPositionals: false,
@@ -157,12 +189,21 @@ export function parseVerifyArgs(argv: string[]): VerifyFlags {
     }
   }
 
+  const templates = !!values.templates;
+  const codegen = !!values.codegen;
+  // --db is itself an explicit subverb selector: passing a connection URL means
+  // "run the schema-drift mode". So "any explicit subverb" is templates|codegen|db.
+  const anyExplicit = templates || codegen || values.db !== undefined;
+
   return {
     prompts: values.prompts,
     db: values.db as string | undefined,
     dialect: dialect as Dialect | undefined,
     allow: allowTokens as AllowToken[],
     skipSchema: !!values["skip-schema"],
+    templates,
+    codegen,
+    anyExplicit,
   };
 }