forgeos 0.1.0-alpha.4 → 0.1.0-alpha.40

package/src/forge/cli/parse.ts

@@ -14,8 +14,14 @@ import type { LiveSubcommand } from "./live.ts";
 import type { ForgeAiProvider } from "../runtime/ai/types.ts";
 import type { NewPackageManager, NewTemplateName } from "./new.ts";
 import type { SelfHostSubcommand } from "./self-host.ts";
+import type { DocsSubcommand } from "./docs.ts";
 import type { AgentContractSubcommand } from "./agent-contract.ts";
 import type { AuthSubcommand } from "./auth.ts";
+import type { BaselineSubcommand } from "./baseline.ts";
+import type { AuthMdSubcommand } from "./authmd.ts";
+import type { WorkOSSubcommand } from "./workos.ts";
+import type { DeploySubcommand, DeployTarget } from "./deploy.ts";
+import type { FieldTestSubcommand } from "./field-test.ts";
 import type { RlsSubcommand } from "./rls.ts";
 import type { SecuritySubcommand } from "./security.ts";
 import type { DepsSubcommand } from "./deps.ts";
@@ -47,8 +53,14 @@ import type {
   UiVideoMode,
 } from "../ui/types.ts";
 import type { ForgeDoOptions } from "../intent/types.ts";
+import type { BenchCommandOptions, BenchSubcommand } from "../bench.ts";
+import type { BrownfieldImportCommandOptions } from "../brownfield-import/types.ts";
+import type { CairCommandOptions, CairSubcommand } from "../cair/types.ts";
 
 export type ForgeCommand =
+  | { kind: "version"; json: boolean }
+  | { kind: "last"; json: boolean; workspaceRoot: string }
+  | { kind: "baseline"; subcommand: BaselineSubcommand; json: boolean; reason?: string; workspaceRoot: string }
   | {
       kind: "new";
       name: string;
@@ -58,6 +70,8 @@ export type ForgeCommand =
       git: boolean;
       forgePackageSpec?: string;
       localForge: boolean;
+      json: boolean;
+      fieldTest: boolean;
       workspaceRoot: string;
     }
   | { kind: "build"; json: boolean; workspaceRoot: string }
@@ -90,6 +104,15 @@ export type ForgeCommand =
       postgresVersion: string;
       runtimePort: number;
       webPort: number;
+      preparedOnly?: boolean;
+      workspaceRoot: string;
+    }
+  | {
+      kind: "docs";
+      subcommand: DocsSubcommand;
+      json: boolean;
+      build: boolean;
+      installVenv: boolean;
       workspaceRoot: string;
     }
   | {
@@ -98,7 +121,7 @@ export type ForgeCommand =
       json: boolean;
       workspaceRoot: string;
     }
-  | { kind: "doctor"; target?: "project" | "windows"; json: boolean; workspaceRoot: string }
+  | { kind: "doctor"; target?: "project" | "windows" | "agent" | "delta" | "pglite" | "runtime"; agentTarget?: AgentAdapterTarget; json: boolean; workspaceRoot: string }
   | { kind: "setup"; target: "windows"; json: boolean; yes: boolean; workspaceRoot: string }
   | {
       kind: "security";
@@ -106,6 +129,7 @@ export type ForgeCommand =
       db: DbAdapterKind;
       databaseUrl?: string;
       json: boolean;
+      runTests: boolean;
       workspaceRoot: string;
     }
   | {
@@ -113,6 +137,53 @@ export type ForgeCommand =
       subcommand: AuthSubcommand;
       json: boolean;
       token?: string;
+      prod?: boolean;
+      scenario?: string;
+      workspaceRoot: string;
+    }
+  | {
+      kind: "authmd";
+      subcommand: AuthMdSubcommand;
+      json: boolean;
+      output?: string;
+      workspaceRoot: string;
+    }
+  | {
+      kind: "workos";
+      subcommand: WorkOSSubcommand;
+      json: boolean;
+      file?: string;
+      yes: boolean;
+      dryRun: boolean;
+      real?: boolean;
+      workspaceRoot: string;
+    }
+  | {
+      kind: "deploy";
+      subcommand: DeploySubcommand;
+      target: DeployTarget;
+      production: boolean;
+      url?: string;
+      json: boolean;
+      workspaceRoot: string;
+    }
+  | {
+      kind: "field-test";
+      subcommand: FieldTestSubcommand;
+      name?: string;
+      template: NewTemplateName;
+      templates?: NewTemplateName[];
+      packageManager: NewPackageManager;
+      packageManagers?: NewPackageManager[];
+      forgeSpec?: string;
+      auth?: "none" | "workos";
+      dryRun: boolean;
+      keep: boolean;
+      runtimeProbes: boolean;
+      authProbes: boolean;
+      timeoutMs: number;
+      writeReport?: string;
+      json: boolean;
       workspaceRoot: string;
     }
   | {
@@ -150,6 +221,7 @@ export type ForgeCommand =
       json: boolean;
       allowDirty: boolean;
       allowPublicSourcemaps: boolean;
+      allowMissingLocalRelease?: boolean;
       workspaceRoot: string;
     }
   | { kind: "make"; options: MakeCommandOptions }
@@ -159,12 +231,71 @@ export type ForgeCommand =
   | { kind: "test"; options: TestCommandOptions }
   | { kind: "repair"; options: RepairCommandOptions }
   | { kind: "do"; options: ForgeDoOptions }
+  | { kind: "bench"; options: BenchCommandOptions }
+  | { kind: "cair"; options: CairCommandOptions }
   | { kind: "agent"; options: AgentCommandOptions }
+  | { kind: "mcp"; subcommand: "serve"; workspaceRoot: string }
   | { kind: "review"; options: ReviewCommandOptions }
   | { kind: "ui"; options: UiCommandOptions }
-  | { kind: "generate"; check: boolean; dryRun: boolean; json: boolean; concurrency: number }
+  | { kind: "manifest"; subcommand: "validate" | "import"; path: string; json: boolean; workspaceRoot: string }
+  | { kind: "import"; options: BrownfieldImportCommandOptions }
+  | {
+      kind: "delta";
+      subcommand: "status" | "repair" | "compact" | "prune" | "export";
+      json: boolean;
+      workspaceRoot: string;
+      dryRun: boolean;
+      yes: boolean;
+      verbose: boolean;
+      olderThan?: string;
+      output?: string;
+      limit?: number;
+      redacted: boolean;
+    }
+  | { kind: "status"; json: boolean; workspaceRoot: string }
+  | { kind: "changed"; json: boolean; authoredOnly: boolean; reviewOnly: boolean; commitReady: boolean; workspaceRoot: string }
+  | { kind: "diff"; target: "authored" | "generated" | "full"; json: boolean; workspaceRoot: string }
+  | { kind: "handoff"; json: boolean; commitReady: boolean; workspaceRoot: string }
+  | {
+      kind: "studio";
+      subcommand: "attach" | "snapshot" | "watch" | "open" | "doctor" | "bridge" | "codex-server";
+      path?: string;
+      previewUrl?: string;
+      previewPort?: number;
+      studioUrl?: string;
+      intervalMs?: number;
+      once: boolean;
+      workspaceId?: string;
+      tenantId?: string;
+      userId?: string;
+      role?: string;
+      targets: string[];
+      install?: boolean;
+      start?: boolean;
+      bridge?: boolean;
+      writeSchemas?: boolean;
+      probeAppServer?: boolean;
+      json: boolean;
+      dryRun: boolean;
+      force: boolean;
+      workspaceRoot: string;
+    }
+  | { kind: "timeline"; target?: string; kindFilter?: string; sessionId?: string; limit?: number; json: boolean; rebuild: boolean; forAgent: boolean; causal: boolean; staleProofs: boolean; workspaceRoot: string }
+  | { kind: "explain"; thing: string; json: boolean; workspaceRoot: string }
+  | {
+      kind: "session";
+      subcommand: "list" | "show" | "rename" | "merge" | "split" | "detach";
+      sessionId?: string;
+      sourceSessionId?: string;
+      operationId?: string;
+      title?: string;
+      limit?: number;
+      json: boolean;
+      workspaceRoot: string;
+    }
+  | { kind: "generate"; check: boolean; dryRun: boolean; json: boolean; concurrency: number; workspaceRoot: string }
   | { kind: "add"; alias: string; options: AddOptions & { workspaceRoot: string } }
-  | { kind: "inspect"; target: InspectTarget; json: boolean; dryRun: boolean }
+  | { kind: "inspect"; target: InspectTarget; json: boolean; dryRun: boolean; full: boolean; brief: boolean; ergonomics: boolean; workspaceRoot: string }
   | { kind: "check"; json: boolean; dryRun: boolean; strictSecrets: boolean }
   | { kind: "verify"; options: VerifyOptions }
   | { kind: "run"; name?: string; list: boolean; json: boolean; mock: boolean; userId?: string; tenantId?: string; role?: string; envFile?: string; workspaceRoot: string; queryMode?: boolean; args?: unknown }
@@ -177,7 +308,7 @@ export type ForgeCommand =
       once: boolean;
       watch: boolean;
       json: boolean;
-      db: "pglite" | "postgres" | "none";
+      db: "memory" | "pglite" | "postgres" | "none";
       databaseUrl?: string;
       worker: boolean;
       withWeb: boolean;
@@ -187,6 +318,9 @@ export type ForgeCommand =
       webPort?: number;
       telemetry: string[];
       envFile?: string;
+      skipStartupConsole: boolean;
+      detach: boolean;
+      lifecycle?: "status" | "stop";
       workspaceRoot: string;
     }
   | {
@@ -194,6 +328,7 @@ export type ForgeCommand =
       subcommand: DbSubcommand;
       db: DbAdapterKind;
       databaseUrl?: string;
+      local?: boolean;
       json: boolean;
       workspaceRoot: string;
     }
@@ -293,6 +428,8 @@ export type ForgeCommand =
       model?: string;
       prompt?: string;
       mock: boolean;
+      modelLevel: boolean;
+      live: boolean;
       traceId?: string;
       db?: DbAdapterKind;
       databaseUrl?: string;
@@ -306,19 +443,28 @@ export interface ParsedCli {
 }
 
 export const TOP_LEVEL_COMMANDS = [
+  "version",
+  "last",
+  "baseline",
   "new",
   "build",
   "serve",
   "worker",
   "self-host",
+  "docs",
   "agent-contract",
   "agent",
+  "mcp",
   "review",
   "ui",
   "doctor",
   "setup",
   "security",
   "auth",
+  "authmd",
+  "workos",
+  "deploy",
+  "field-test",
   "rls",
   "deps",
   "release",
@@ -329,6 +475,19 @@ export const TOP_LEVEL_COMMANDS = [
   "test",
   "repair",
   "do",
+  "bench",
+  "cair",
+  "delta",
+  "session",
+  "timeline",
+  "explain",
+  "manifest",
+  "import",
+  "status",
+  "changed",
+  "diff",
+  "handoff",
+  "studio",
   "generate",
   "add",
   "inspect",
@@ -365,6 +524,7 @@ export const INSPECT_TARGETS: InspectTarget[] = [
   "ai",
   "queries",
   "api",
+  "external",
   "client",
   "frontend",
   "auth",
@@ -383,7 +543,12 @@ export const INSPECT_TARGETS: InspectTarget[] = [
   "agent-tools",
   "agent-adapters",
   "capability-map",
+  "summary",
+  "schema",
+  "drift",
+  "handoff",
   "framework",
+  "imported",
   "ui",
   "ui-scenarios",
   "ui-routes",
@@ -392,7 +557,7 @@ export const INSPECT_TARGETS: InspectTarget[] = [
   "map",
 ];
 
-const NEW_TEMPLATES: NewTemplateName[] = ["b2b-support-web", "minimal-web"];
+const NEW_TEMPLATES: NewTemplateName[] = ["agent-workroom", "b2b-support-web", "minimal-web", "nuxt-web"];
 const NEW_PACKAGE_MANAGERS: NewPackageManager[] = ["bun", "npm", "pnpm", "yarn"];
 const SELF_HOST_SUBCOMMANDS: SelfHostSubcommand[] = ["compose", "env", "check", "clean"];
 const AGENT_CONTRACT_SUBCOMMANDS: AgentContractSubcommand[] = [
@@ -407,7 +572,13 @@ const AUTH_SUBCOMMANDS: AuthSubcommand[] = [
   "test-token",
   "jwks",
   "prove",
+  "status",
 ];
+const BASELINE_SUBCOMMANDS: BaselineSubcommand[] = ["create", "status"];
+const AUTHMD_SUBCOMMANDS: AuthMdSubcommand[] = ["generate", "check"];
+const WORKOS_SUBCOMMANDS: WorkOSSubcommand[] = ["install", "doctor", "seed", "setup"];
+const DEPLOY_SUBCOMMANDS: DeploySubcommand[] = ["plan", "check", "render", "verify"];
+const FIELD_TEST_SUBCOMMANDS: FieldTestSubcommand[] = ["create", "run", "report"];
 const SECURITY_SUBCOMMANDS: SecuritySubcommand[] = ["prove"];
 const RLS_SUBCOMMANDS: RlsSubcommand[] = ["generate", "check", "apply", "test", "mutate-test"];
 const DEPS_SUBCOMMANDS: DepsSubcommand[] = [
@@ -484,7 +655,7 @@ const RENAME_TARGETS: RenameTarget[] = [
   "workflow",
   "event",
 ];
-const TEST_SUBCOMMANDS: TestSubcommand[] = ["plan", "run", "explain"];
+const TEST_SUBCOMMANDS: TestSubcommand[] = ["plan", "run", "explain", "authz"];
 const TEST_COSTS: TestCost[] = ["instant", "fast", "standard", "slow", "docker", "browser"];
 const REPAIR_SUBCOMMANDS: RepairSubcommand[] = [
   "diagnose",
@@ -501,10 +672,18 @@ const AGENT_SUBCOMMANDS: AgentSubcommand[] = [
   "export",
   "check",
   "doctor",
+  "onboard",
   "print-context",
   "clean",
+  "prepare",
+  "hooks",
+  "install",
+  "ingest",
+  "context",
+  "memory",
+  "timeline",
 ];
-const REVIEW_SUBCOMMANDS: ReviewSubcommand[] = ["inspect", "list", "explain"];
+const REVIEW_SUBCOMMANDS: ReviewSubcommand[] = ["run", "inspect", "list", "explain"];
 const REVIEW_MODES: ReviewMode[] = ["quick", "standard", "strict"];
 const REVIEW_FAIL_ON: ReviewFailOn[] = ["warning", "error", "blocking"];
 const REVIEW_CATEGORIES: ReviewFindingCategory[] = [
@@ -522,6 +701,7 @@ const REVIEW_CATEGORIES: ReviewFindingCategory[] = [
   "agent",
 ];
 const UI_SUBCOMMANDS: UiSubcommand[] = [
+  "audit",
   "smoke",
   "test",
   "scenario",
@@ -545,6 +725,8 @@ const AI_SUBCOMMANDS: AiSubcommand[] = [
   "redteam",
   "trace",
 ];
+const BENCH_SUBCOMMANDS: BenchSubcommand[] = ["compiler"];
+const CAIR_SUBCOMMANDS: CairSubcommand[] = ["snapshot", "query", "action"];
 
 function parseFlag(args: string[], flag: string): boolean {
   return args.includes(flag);
@@ -569,8 +751,8 @@ function parseOptionValues(args: string[], flag: string): string[] {
   return values;
 }
 
-function parseDbKind(value: string | undefined): "pglite" | "postgres" | "none" {
-  if (value === "postgres" || value === "none") {
+function parseDbKind(value: string | undefined): "memory" | "pglite" | "postgres" | "none" {
+  if (value === "memory" || value === "postgres" || value === "none") {
     return value;
   }
   return "pglite";
@@ -597,7 +779,10 @@ function parseSandboxBackend(value: string | undefined): SandboxBackend {
 function parseAddOptions(
   args: string[],
   workspaceRoot: string,
+  mode: AddOptions["mode"] = "auto",
 ): AddOptions & { workspaceRoot: string } {
+  const frontend = parseFlag(args, "--frontend");
+  const backend = parseFlag(args, "--backend");
   return {
     workspaceRoot,
     json: parseFlag(args, "--json"),
@@ -607,6 +792,9 @@ function parseAddOptions(
       parseOptionValue(args, "--sandbox-backend"),
     ),
     allowScripts: parseFlag(args, "--allow-scripts"),
+    mode,
+    installWorkspace: parseOptionValue(args, "--workspace"),
+    packageTarget: frontend && !backend ? "frontend" : backend ? "backend" : undefined,
   };
 }
 
@@ -658,6 +846,33 @@ function parseNewPackageManager(value: string | undefined): NewPackageManager {
     : "bun";
 }
 
+function parseCommaList(value: string | undefined): string[] {
+  return String(value ?? "")
+    .split(",")
+    .map((item) => item.trim())
+    .filter(Boolean);
+}
+
+function parseTemplateList(value: string | undefined, errors: string[], optionName: string): NewTemplateName[] | undefined {
+  if (!value) return undefined;
+  const values = parseCommaList(value);
+  const unsupported = values.filter((item) => !NEW_TEMPLATES.includes(item as NewTemplateName));
+  if (unsupported.length > 0) {
+    errors.push(`${optionName} contains unsupported template(s): ${unsupported.join(", ")}; supported: ${NEW_TEMPLATES.join(", ")}`);
+  }
+  return values.filter((item) => NEW_TEMPLATES.includes(item as NewTemplateName)) as NewTemplateName[];
+}
+
+function parsePackageManagerList(value: string | undefined, errors: string[], optionName: string): NewPackageManager[] | undefined {
+  if (!value) return undefined;
+  const values = parseCommaList(value);
+  const unsupported = values.filter((item) => !NEW_PACKAGE_MANAGERS.includes(item as NewPackageManager));
+  if (unsupported.length > 0) {
+    errors.push(`${optionName} contains unsupported package manager(s): ${unsupported.join(", ")}; supported: ${NEW_PACKAGE_MANAGERS.join(", ")}`);
+  }
+  return values.filter((item) => NEW_PACKAGE_MANAGERS.includes(item as NewPackageManager)) as NewPackageManager[];
+}
+
 function parseDoObjective(rest: string[], argv: string[]): string {
   const [action, name, ...tail] = rest;
   if (action === "add-resource") {
@@ -686,6 +901,14 @@ export function parseCli(argv: string[]): ParsedCli {
   const positional = argv.filter((arg) => !arg.startsWith("-"));
   const workspaceRoot = process.cwd().replace(/\\/g, "/");
 
+  if (parseFlag(argv, "--version") || parseFlag(argv, "-v")) {
+    return {
+      command: { kind: "version", json: parseFlag(argv, "--json") },
+      workspaceRoot,
+      errors,
+    };
+  }
+
   if (positional.length === 0) {
     errors.push(
       `missing command; expected ${TOP_LEVEL_COMMANDS.join(", ")}`,
@@ -696,6 +919,36 @@ export function parseCli(argv: string[]): ParsedCli {
   const [commandName, ...rest] = positional;
 
   switch (commandName) {
+    case "version":
+      return {
+        command: { kind: "version", json: parseFlag(argv, "--json") },
+        workspaceRoot,
+        errors,
+      };
+    case "last":
+      return {
+        command: { kind: "last", json: parseFlag(argv, "--json"), workspaceRoot },
+        workspaceRoot,
+        errors,
+      };
+    case "baseline": {
+      const subcommand = (rest[0] ?? "status") as BaselineSubcommand;
+      if (!BASELINE_SUBCOMMANDS.includes(subcommand)) {
+        errors.push("forge baseline requires subcommand: create or status");
+        return { command: null, workspaceRoot, errors };
+      }
+      return {
+        command: {
+          kind: "baseline",
+          subcommand,
+          reason: parseOptionValue(argv, "--reason"),
+          json: parseFlag(argv, "--json"),
+          workspaceRoot,
+        },
+        workspaceRoot,
+        errors,
+      };
+    }
     case "new": {
       const name = rest[0];
       if (!name) {
@@ -725,6 +978,9 @@ export function parseCli(argv: string[]): ParsedCli {
       if (install && noInstall) {
         errors.push("use either --install or --no-install, not both");
       }
+      if (parseFlag(argv, "--field-test") && noInstall) {
+        errors.push("forge new --field-test requires installation; remove --no-install");
+      }
 
       return {
         command: {
@@ -736,6 +992,8 @@ export function parseCli(argv: string[]): ParsedCli {
           git: !parseFlag(argv, "--no-git"),
           forgePackageSpec,
           localForge,
+          json: parseFlag(argv, "--json"),
+          fieldTest: parseFlag(argv, "--field-test"),
           workspaceRoot,
         },
         workspaceRoot,
@@ -825,6 +1083,26 @@ export function parseCli(argv: string[]): ParsedCli {
           postgresVersion: parseOptionValue(argv, "--postgres-version") ?? "16",
           runtimePort: Math.floor(runtimePort),
           webPort: Math.floor(webPort),
+          preparedOnly: parseFlag(argv, "--prepared-only"),
+          workspaceRoot,
+        },
+        workspaceRoot,
+        errors,
+      };
+    }
+    case "docs": {
+      const subcommand = rest[0] as DocsSubcommand | undefined;
+      if (subcommand !== "check") {
+        errors.push("forge docs requires subcommand: check");
+        return { command: null, workspaceRoot, errors };
+      }
+      return {
+        command: {
+          kind: "docs",
+          subcommand,
+          json: parseFlag(argv, "--json"),
+          build: parseFlag(argv, "--build"),
+          installVenv: parseFlag(argv, "--install-venv"),
           workspaceRoot,
         },
         workspaceRoot,
@@ -851,12 +1129,54 @@ export function parseCli(argv: string[]): ParsedCli {
     case "agent": {
       const subcommand = rest[0] as AgentSubcommand | undefined;
       if (!subcommand || !AGENT_SUBCOMMANDS.includes(subcommand)) {
-        errors.push("forge agent requires subcommand: list-targets, export, check, doctor, print-context, or clean");
+        errors.push("forge agent requires subcommand: list-targets, export, check, doctor, onboard, print-context, clean, prepare, hooks, install, ingest, context, memory, or timeline");
         return { command: null, workspaceRoot, errors };
       }
+      const inputRaw = parseOptionValue(argv, "--input");
+      let input: unknown;
+      if (inputRaw !== undefined) {
+        try {
+          input = JSON.parse(inputRaw);
+        } catch {
+          errors.push("--input must be valid JSON");
+        }
+      }
+      const limitRaw = parseOptionValue(argv, "--limit");
+      const limit = limitRaw ? Number(limitRaw) : undefined;
+      const pollIntervalRaw = parseOptionValue(argv, "--poll-interval");
+      const pollIntervalMs = pollIntervalRaw ? Number(pollIntervalRaw) : undefined;
+      if (limitRaw !== undefined && (!Number.isFinite(limit) || limit! < 1)) {
+        errors.push("--limit must be a number >= 1");
+      }
+      if (
+        pollIntervalRaw !== undefined &&
+        (!Number.isFinite(pollIntervalMs) || pollIntervalMs! < 100)
+      ) {
+        errors.push("--poll-interval must be a number >= 100");
+      }
       const target =
         (parseOptionValue(argv, "--target") as AgentAdapterTarget | undefined) ??
-        (subcommand === "export" || subcommand === "clean" ? "generic" : "generic");
+        (subcommand === "install" || subcommand === "ingest" ? rest[1] : undefined) ??
+        (subcommand === "hooks" ? rest[2] : undefined) ??
+        (subcommand === "timeline" ? rest[1] : undefined) ??
+        (subcommand === "timeline" ? "all" : undefined) ??
+        (subcommand === "hooks" || subcommand === "onboard" ? "codex" : "generic");
+      const contextOptionValues = new Set(
+        [
+          parseOptionValue(argv, "--entry"),
+          parseOptionValue(argv, "--change"),
+          parseOptionValue(argv, "--proof"),
+          parseOptionValue(argv, "--event"),
+          parseOptionValue(argv, "--input"),
+          parseOptionValue(argv, "--target"),
+          parseOptionValue(argv, "--file"),
+          limitRaw,
+          pollIntervalRaw,
+        ].filter((value): value is string => typeof value === "string"),
+      );
+      const contextEntry = subcommand === "context"
+        ? rest.slice(1).find((part) => !part.startsWith("--") && !contextOptionValues.has(part))
+        : undefined;
       return {
         command: {
           kind: "agent",
@@ -870,12 +1190,40 @@ export function parseCli(argv: string[]): ParsedCli {
             preserveUserSections: !parseFlag(argv, "--no-preserve-user-sections"),
             skills: !parseFlag(argv, "--no-skills"),
             rules: !parseFlag(argv, "--no-rules"),
+            eventName: parseOptionValue(argv, "--event"),
+            hookAction: subcommand === "hooks" ? rest[1] : undefined,
+            input,
+            entry: parseOptionValue(argv, "--entry") ?? contextEntry,
+            change: parseOptionValue(argv, "--change"),
+            proof: parseOptionValue(argv, "--proof"),
+            handoff: parseFlag(argv, "--handoff"),
+            current: parseFlag(argv, "--current"),
+            limit: limit ? Math.floor(limit) : undefined,
+            watch: parseFlag(argv, "--watch"),
+            file: parseOptionValue(argv, "--file"),
+            pollIntervalMs: pollIntervalMs ? Math.floor(pollIntervalMs) : undefined,
           },
         },
         workspaceRoot,
         errors,
       };
     }
+    case "mcp": {
+      const subcommand = rest[0];
+      if (subcommand !== "serve") {
+        errors.push("forge mcp requires subcommand: serve");
+        return { command: null, workspaceRoot, errors };
+      }
+      return {
+        command: {
+          kind: "mcp",
+          subcommand,
+          workspaceRoot,
+        },
+        workspaceRoot,
+        errors,
+      };
+    }
     case "review": {
       const requested = rest[0] as ReviewSubcommand | undefined;
       const subcommand =
@@ -898,6 +1246,7 @@ export function parseCli(argv: string[]): ParsedCli {
             json: parseFlag(argv, "--json"),
             md: parseFlag(argv, "--md"),
             sarif: parseFlag(argv, "--sarif"),
+            full: parseFlag(argv, "--full"),
             write: positionalWrite || parseFlag(argv, "--write"),
             changed: parseFlag(argv, "--changed") || noSourceFlag,
             staged: parseFlag(argv, "--staged"),
@@ -921,7 +1270,7 @@ export function parseCli(argv: string[]): ParsedCli {
     case "ui": {
       const subcommand = (rest[0] ?? "smoke") as UiSubcommand;
       if (!UI_SUBCOMMANDS.includes(subcommand)) {
-        errors.push("forge ui requires subcommand: smoke, test, scenario, route, snapshot, report, doctor, or list");
+        errors.push("forge ui requires subcommand: audit, smoke, test, scenario, route, snapshot, report, doctor, or list");
         return { command: null, workspaceRoot, errors };
       }
       const timeoutRaw = parseOptionValue(argv, "--timeout");
@@ -968,14 +1317,27 @@ export function parseCli(argv: string[]): ParsedCli {
       };
     }
     case "doctor":
-      if (rest[0] && rest[0] !== "windows") {
-        errors.push("forge doctor supports subcommand: windows");
+      if (rest[0] && rest[0] !== "windows" && rest[0] !== "agent" && rest[0] !== "delta" && rest[0] !== "pglite" && rest[0] !== "runtime") {
+        errors.push("forge doctor supports subcommand: windows, agent, delta, pglite, or runtime");
         return { command: null, workspaceRoot, errors };
       }
       return {
         command: {
           kind: "doctor",
-          target: rest[0] === "windows" ? "windows" : "project",
+          target: rest[0] === "windows"
+            ? "windows"
+            : rest[0] === "agent"
+              ? "agent"
+              : rest[0] === "delta"
+                ? "delta"
+                : rest[0] === "pglite"
+                  ? "pglite"
+                  : rest[0] === "runtime"
+                    ? "runtime"
+                  : "project",
+          agentTarget: rest[0] === "agent"
+            ? (parseOptionValue(argv, "--target") as AgentAdapterTarget | undefined) ?? (rest[1] as AgentAdapterTarget | undefined) ?? "codex"
+            : undefined,
           json: parseFlag(argv, "--json"),
           workspaceRoot,
         },
@@ -1013,6 +1375,7 @@ export function parseCli(argv: string[]): ParsedCli {
           db: parseAdapterKind(parseOptionValue(argv, "--db")),
           databaseUrl: parseOptionValue(argv, "--database-url"),
           json: parseFlag(argv, "--json"),
+          runTests: parseFlag(argv, "--full") || parseFlag(argv, "--run-tests"),
           workspaceRoot,
         },
         workspaceRoot,
@@ -1022,7 +1385,7 @@ export function parseCli(argv: string[]): ParsedCli {
     case "auth": {
       const subcommand = rest[0] as AuthSubcommand | undefined;
       if (!subcommand || !AUTH_SUBCOMMANDS.includes(subcommand)) {
-        errors.push("forge auth requires subcommand: check, config, decode, test-token, jwks, or prove");
+        errors.push("forge auth requires subcommand: check, config, decode, test-token, jwks, prove, or status");
         return { command: null, workspaceRoot, errors };
       }
       return {
@@ -1031,6 +1394,112 @@ export function parseCli(argv: string[]): ParsedCli {
           subcommand,
           json: parseFlag(argv, "--json"),
           token: parseOptionValue(argv, "--token"),
+          prod: parseFlag(argv, "--prod") || parseFlag(argv, "--production"),
+          scenario: parseOptionValue(argv, "--scenario"),
+          workspaceRoot,
+        },
+        workspaceRoot,
+        errors,
+      };
+    }
+    case "authmd": {
+      const subcommand = rest[0] as AuthMdSubcommand | undefined;
+      if (!subcommand || !AUTHMD_SUBCOMMANDS.includes(subcommand)) {
+        errors.push("forge authmd requires subcommand: generate or check");
+        return { command: null, workspaceRoot, errors };
+      }
+      return {
+        command: {
+          kind: "authmd",
+          subcommand,
+          json: parseFlag(argv, "--json"),
+          output: parseOptionValue(argv, "--output"),
+          workspaceRoot,
+        },
+        workspaceRoot,
+        errors,
+      };
+    }
+    case "workos": {
+      const subcommand = rest[0] as WorkOSSubcommand | undefined;
+      if (!subcommand || !WORKOS_SUBCOMMANDS.includes(subcommand)) {
+        errors.push("forge workos requires subcommand: install, doctor, seed, or setup");
+        return { command: null, workspaceRoot, errors };
+      }
+      return {
+        command: {
+          kind: "workos",
+          subcommand,
+          json: parseFlag(argv, "--json"),
+          file: parseOptionValue(argv, "--file"),
+          yes: parseFlag(argv, "--yes"),
+          dryRun: parseFlag(argv, "--dry-run"),
+          real: parseFlag(argv, "--real"),
+          workspaceRoot,
+        },
+        workspaceRoot,
+        errors,
+      };
+    }
+    case "deploy": {
+      const subcommand = rest[0] as DeploySubcommand | undefined;
+      if (!subcommand || !DEPLOY_SUBCOMMANDS.includes(subcommand)) {
+        errors.push("forge deploy requires subcommand: plan, check, render, or verify");
+        return { command: null, workspaceRoot, errors };
+      }
+      const targetRaw = parseOptionValue(argv, "--target") ?? (subcommand === "render" ? rest[1] : undefined) ?? "docker";
+      if (targetRaw !== "docker" && targetRaw !== "forge-cloud") {
+        errors.push("forge deploy --target must be docker or forge-cloud");
+      }
+      return {
+        command: {
+          kind: "deploy",
+          subcommand,
+          target: targetRaw as DeployTarget,
+          production: parseFlag(argv, "--production") || parseFlag(argv, "--prod"),
+          url: parseOptionValue(argv, "--url"),
+          json: parseFlag(argv, "--json"),
+          workspaceRoot,
+        },
+        workspaceRoot,
+        errors,
+      };
+    }
+    case "field-test": {
+      const subcommand = rest[0] as FieldTestSubcommand | undefined;
+      if (!subcommand || !FIELD_TEST_SUBCOMMANDS.includes(subcommand)) {
+        errors.push("forge field-test requires subcommand: create, run, or report");
+        return { command: null, workspaceRoot, errors };
+      }
+      const timeoutRaw = parseOptionValue(argv, "--timeout-ms");
+      const timeoutMs = timeoutRaw ? Number(timeoutRaw) : 180_000;
+      if (!Number.isFinite(timeoutMs) || timeoutMs < 1) {
+        errors.push("--timeout-ms must be a positive integer");
+      }
+      const authRaw = parseOptionValue(argv, "--auth") ?? "none";
+      if (authRaw !== "none" && authRaw !== "workos") {
+        errors.push("forge field-test --auth must be none or workos");
+      }
+      const templates = parseTemplateList(parseOptionValue(argv, "--templates"), errors, "--templates");
+      const packageManagers = parsePackageManagerList(parseOptionValue(argv, "--package-managers"), errors, "--package-managers");
+      return {
+        command: {
+          kind: "field-test",
+          subcommand,
+          name: subcommand === "create" ? rest[1] : undefined,
+          template: parseNewTemplate(parseOptionValue(argv, "--template") ?? "minimal-web"),
+          templates,
+          packageManager: parseNewPackageManager(parseOptionValue(argv, "--package-manager") ?? "npm"),
+          packageManagers,
+          forgeSpec: parseOptionValue(argv, "--forge-spec"),
+          auth: authRaw as "none" | "workos",
+          dryRun: parseFlag(argv, "--dry-run"),
+          keep: parseFlag(argv, "--keep"),
+          runtimeProbes: parseFlag(argv, "--runtime-probes"),
+          authProbes: parseFlag(argv, "--auth-probes"),
+          timeoutMs: Math.floor(timeoutMs),
+          writeReport: parseOptionValue(argv, "--write-report") ?? parseOptionValue(argv, "--file"),
+          json: parseFlag(argv, "--json"),
           workspaceRoot,
         },
         workspaceRoot,
@@ -1113,6 +1582,7 @@ export function parseCli(argv: string[]): ParsedCli {
           json: parseFlag(argv, "--json"),
           allowDirty: parseFlag(argv, "--allow-dirty"),
           allowPublicSourcemaps: parseFlag(argv, "--allow-public-sourcemaps"),
+          allowMissingLocalRelease: parseFlag(argv, "--allow-missing-local-release"),
           workspaceRoot,
         },
         workspaceRoot,
@@ -1184,7 +1654,7 @@ export function parseCli(argv: string[]): ParsedCli {
             event: parseOptionValue(argv, "--event"),
             trigger: parseOptionValue(argv, "--trigger"),
             component: parseOptionValue(argv, "--component"),
-            framework: parseOptionValue(argv, "--framework") as "vite" | "next" | undefined,
+            framework: parseOptionValue(argv, "--framework") as "vite" | "next" | "nuxt" | undefined,
             withAi: parseFlag(argv, "--with-ai"),
             withCrud: parseFlag(argv, "--with-crud"),
             withLiveQuery: parseFlag(argv, "--with-livequery"),
@@ -1358,7 +1828,7 @@ export function parseCli(argv: string[]): ParsedCli {
     case "test": {
       const subcommand = rest[0] as TestSubcommand | undefined;
       if (!subcommand || !TEST_SUBCOMMANDS.includes(subcommand)) {
-        errors.push("forge test requires subcommand: plan, run, or explain");
+        errors.push("forge test requires subcommand: plan, run, explain, or authz");
         return { command: null, workspaceRoot, errors };
       }
       const timeoutRaw = parseOptionValue(argv, "--timeout-ms");
@@ -1377,7 +1847,7 @@ export function parseCli(argv: string[]): ParsedCli {
             workspaceRoot,
             json: parseFlag(argv, "--json"),
             write: parseFlag(argv, "--write"),
-            changed: parseFlag(argv, "--changed") || (!parseFlag(argv, "--staged") && !parseOptionValue(argv, "--since") && !parseOptionValue(argv, "--feature") && !parseOptionValue(argv, "--refactor") && !parseOptionValue(argv, "--upgrade") && !parseOptionValue(argv, "--plan") && subcommand !== "explain"),
+            changed: parseFlag(argv, "--changed") || (!parseFlag(argv, "--staged") && !parseOptionValue(argv, "--since") && !parseOptionValue(argv, "--feature") && !parseOptionValue(argv, "--refactor") && !parseOptionValue(argv, "--upgrade") && !parseOptionValue(argv, "--plan") && subcommand !== "explain" && subcommand !== "authz"),
             staged: parseFlag(argv, "--staged"),
             since: parseOptionValue(argv, "--since"),
             featureId: parseOptionValue(argv, "--feature"),
@@ -1391,6 +1861,8 @@ export function parseCli(argv: string[]): ParsedCli {
             bail: parseFlag(argv, "--bail"),
             report: parseOptionValue(argv, "--report"),
             timeoutMs: timeoutMs ? Math.floor(timeoutMs) : undefined,
+            tenant: parseOptionValue(argv, "--tenant") ?? "acme",
+            otherTenant: parseOptionValue(argv, "--other-tenant") ?? "globex",
           },
         },
         workspaceRoot,
@@ -1463,6 +1935,218 @@ export function parseCli(argv: string[]): ParsedCli {
         errors,
       };
     }
+    case "bench": {
+      const subcommand = rest[0] as BenchSubcommand | undefined;
+      if (!subcommand || !BENCH_SUBCOMMANDS.includes(subcommand)) {
+        errors.push("forge bench requires subcommand: compiler");
+        return { command: null, workspaceRoot, errors };
+      }
+      const iterationsRaw = parseOptionValue(argv, "--iterations");
+      const warmupsRaw = parseOptionValue(argv, "--warmups");
+      const concurrencyRaw = parseOptionValue(argv, "--concurrency");
+      const iterations = iterationsRaw !== undefined ? Number(iterationsRaw) : 5;
+      const warmups = warmupsRaw !== undefined ? Number(warmupsRaw) : 1;
+      const concurrency = concurrencyRaw !== undefined ? Number(concurrencyRaw) : 4;
+      if (!Number.isFinite(iterations) || iterations < 1) {
+        errors.push("--iterations must be a number >= 1");
+      }
+      if (!Number.isFinite(warmups) || warmups < 0) {
+        errors.push("--warmups must be a number >= 0");
+      }
+      if (!Number.isFinite(concurrency) || concurrency < 1) {
+        errors.push("--concurrency must be a number >= 1");
+      }
+      return {
+        command: {
+          kind: "bench",
+          options: {
+            subcommand,
+            workspaceRoot,
+            json: parseFlag(argv, "--json"),
+            iterations: Math.floor(iterations),
+            warmups: Math.floor(warmups),
+            concurrency: Math.floor(concurrency),
+          },
+        },
+        workspaceRoot,
+        errors,
+      };
+    }
+    case "cair": {
+      const subcommand = rest[0] as CairSubcommand | undefined;
+      if (!subcommand || !CAIR_SUBCOMMANDS.includes(subcommand)) {
+        errors.push("forge cair requires subcommand: snapshot, query, or action");
+        return { command: null, workspaceRoot, errors };
+      }
+      const formatRaw = parseOptionValue(argv, "--format");
+      if (formatRaw !== undefined && formatRaw !== "text" && formatRaw !== "json") {
+        errors.push("--format must be text or json");
+      }
+      const query = subcommand === "query" ? rest.slice(1).join(" ").trim() : undefined;
+      if (subcommand === "query" && !query) {
+        errors.push("forge cair query requires a CAIR query, for example: forge cair query \"Q STATUS\"");
+      }
+      const inputPath = parseOptionValue(argv, "--input");
+      const action = subcommand === "action"
+        ? rest.slice(1).filter((part, index, parts) => {
+          const previous = parts[index - 1];
+          if (part === "--dry-run" || part === "--plan" || part === "--json" || part === "--include-generated") {
+            return false;
+          }
+          if (part === "--format" || part === "--input") {
+            return false;
+          }
+          if (previous === "--format" || previous === "--input") {
+            return false;
+          }
+          return true;
+        }).join(" ").trim()
+        : undefined;
+      if (subcommand === "action" && !action && !inputPath) {
+        errors.push("forge cair action requires a CAIR action, for example: forge cair action \"A CREATE.FILE path=src/example.ts\"");
+      }
+      return {
+        command: {
+          kind: "cair",
+          options: {
+            subcommand,
+            workspaceRoot,
+            json: parseFlag(argv, "--json"),
+            format: formatRaw === "json" ? "json" : "text",
+            ...(query ? { query } : {}),
+            ...(action ? { action } : {}),
+            ...(inputPath ? { inputPath } : {}),
+            dryRun: parseFlag(argv, "--dry-run"),
+            plan: parseFlag(argv, "--plan"),
+            allowGenerated: parseFlag(argv, "--include-generated"),
+          },
+        },
+        workspaceRoot,
+        errors,
+      };
+    }
+    case "status":
+      return {
+        command: {
+          kind: "status",
+          json: parseFlag(argv, "--json"),
+          workspaceRoot,
+        },
+        workspaceRoot,
+        errors,
+      };
+    case "changed":
+      return {
+        command: {
+          kind: "changed",
+          json: parseFlag(argv, "--json"),
+          authoredOnly: parseFlag(argv, "--authored"),
+          reviewOnly: parseFlag(argv, "--review"),
+          commitReady: parseFlag(argv, "--commit-ready"),
+          workspaceRoot,
+        },
+        workspaceRoot,
+        errors,
+      };
+    case "diff": {
+      const target = (rest[0] ?? "authored") as "authored" | "generated" | "full";
+      if (!["authored", "generated", "full"].includes(target)) {
+        errors.push("forge diff requires target: authored, generated, or full");
+        return { command: null, workspaceRoot, errors };
+      }
+      return {
+        command: {
+          kind: "diff",
+          target,
+          json: parseFlag(argv, "--json"),
+          workspaceRoot,
+        },
+        workspaceRoot,
+        errors,
+      };
+    }
+    case "handoff":
+      return {
+        command: {
+          kind: "handoff",
+          json: parseFlag(argv, "--json"),
+          commitReady: parseFlag(argv, "--commit-ready"),
+          workspaceRoot,
+        },
+        workspaceRoot,
+        errors,
+      };
+    case "studio": {
+      const subcommand = rest[0];
+      if (
+        subcommand !== "attach" &&
+        subcommand !== "snapshot" &&
+        subcommand !== "watch" &&
+        subcommand !== "open" &&
+        subcommand !== "doctor" &&
+        subcommand !== "bridge" &&
+        subcommand !== "codex-server"
+      ) {
+        errors.push("forge studio requires subcommand: attach, snapshot, watch, open, doctor, bridge, or codex-server");
+        return { command: null, workspaceRoot, errors };
+      }
+      const previewPortRaw = parseOptionValue(argv, "--preview-port");
+      const previewPort = previewPortRaw !== undefined ? Number(previewPortRaw) : undefined;
+      if (
+        previewPortRaw !== undefined &&
+        (!Number.isInteger(previewPort) || previewPort! < 1)
+      ) {
+        errors.push("--preview-port must be an integer >= 1");
+      }
+      const intervalRaw = parseOptionValue(argv, "--interval-ms");
+      const intervalMs = intervalRaw !== undefined ? Number(intervalRaw) : undefined;
+      if (intervalRaw !== undefined && (!Number.isFinite(intervalMs) || intervalMs! < 1000)) {
+        errors.push("--interval-ms must be a number >= 1000");
+      }
+      const targets = parseOptionValues(argv, "--target");
+      const ignoredOptionValues = new Set(
+        [
+          ...targets,
+          parseOptionValue(argv, "--preview-url"),
+          parseOptionValue(argv, "--studio-url"),
+          parseOptionValue(argv, "--workspace-id"),
+          parseOptionValue(argv, "--tenant-id"),
+          parseOptionValue(argv, "--user-id"),
+          parseOptionValue(argv, "--role"),
+          previewPortRaw,
+          intervalRaw,
+        ].filter((value): value is string => typeof value === "string"),
+      );
+      const studioPath = rest.slice(1).find((item) => !ignoredOptionValues.has(item));
+      return {
+        command: {
+          kind: "studio",
+          subcommand,
+          path: studioPath,
+          previewUrl: parseOptionValue(argv, "--preview-url"),
+          previewPort: previewPort ? Math.floor(previewPort) : undefined,
+          studioUrl: parseOptionValue(argv, "--studio-url"),
+          intervalMs: intervalMs ? Math.floor(intervalMs) : undefined,
+          once: parseFlag(argv, "--once"),
+          workspaceId: parseOptionValue(argv, "--workspace-id"),
+          tenantId: parseOptionValue(argv, "--tenant-id"),
+          userId: parseOptionValue(argv, "--user-id"),
+          role: parseOptionValue(argv, "--role"),
+          targets: targets.length > 0 ? targets : ["codex"],
+          install: parseFlag(argv, "--install"),
+          start: !parseFlag(argv, "--no-start"),
+          bridge: !parseFlag(argv, "--no-bridge"),
+          writeSchemas: parseFlag(argv, "--write"),
+          probeAppServer: parseFlag(argv, "--probe") || parseFlag(argv, "--probe-codex-server"),
+          json: parseFlag(argv, "--json"),
+          dryRun: parseFlag(argv, "--dry-run"),
+          force: parseFlag(argv, "--force"),
+          workspaceRoot,
+        },
+        workspaceRoot,
+        errors,
+      };
+    }
     case "generate": {
       const concurrencyRaw = parseOptionValue(argv, "--concurrency");
       const concurrency = concurrencyRaw ? Number(concurrencyRaw) : 4;
@@ -1476,30 +2160,189 @@ export function parseCli(argv: string[]): ParsedCli {
           dryRun: parseFlag(argv, "--dry-run"),
           json: parseFlag(argv, "--json"),
           concurrency: Math.max(1, Math.floor(concurrency || 4)),
+          workspaceRoot,
+        },
+        workspaceRoot,
+        errors,
+      };
+    }
+    case "delta": {
+      const subcommand = rest[0];
+      if (subcommand !== "status" && subcommand !== "repair" && subcommand !== "compact" && subcommand !== "prune" && subcommand !== "export") {
+        errors.push("forge delta requires subcommand: status, repair, compact, prune, or export");
+        return { command: null, workspaceRoot, errors };
+      }
+      const limitRaw = parseOptionValue(argv, "--limit");
+      const limit = limitRaw ? Number(limitRaw) : undefined;
+      return {
+        command: {
+          kind: "delta",
+          subcommand,
+          json: parseFlag(argv, "--json"),
+          dryRun: parseFlag(argv, "--dry-run"),
+          yes: parseFlag(argv, "--yes"),
+          verbose: parseFlag(argv, "--verbose"),
+          olderThan: parseOptionValue(argv, "--older-than"),
+          output: parseOptionValue(argv, "--output"),
+          limit: Number.isFinite(limit) ? limit : undefined,
+          redacted: parseFlag(argv, "--redacted"),
+          workspaceRoot,
+        },
+        workspaceRoot,
+        errors,
+      };
+    }
+    case "session": {
+      const subcommand = rest[0];
+      if (subcommand !== "list" && subcommand !== "show" && subcommand !== "rename" && subcommand !== "merge" && subcommand !== "split" && subcommand !== "detach") {
+        errors.push("forge session requires subcommand: list, show, rename, merge, split, or detach");
+        return { command: null, workspaceRoot, errors };
+      }
+      const limitRaw = parseOptionValue(argv, "--limit");
+      const limit = limitRaw ? Number(limitRaw) : undefined;
+      if (limitRaw !== undefined && (!Number.isFinite(limit) || limit! < 1)) {
+        errors.push("--limit must be a number >= 1");
+      }
+      const sessionId = rest[1];
+      return {
+        command: {
+          kind: "session",
+          subcommand,
+          sessionId: subcommand === "detach" ? undefined : sessionId,
+          sourceSessionId: subcommand === "merge" ? rest[2] : undefined,
+          operationId: subcommand === "split" ? rest[2] : subcommand === "detach" ? rest[1] : undefined,
+          title: subcommand === "rename" ? rest.slice(2).join(" ") : undefined,
+          limit: limit ? Math.floor(limit) : undefined,
+          json: parseFlag(argv, "--json"),
+          workspaceRoot,
+        },
+        workspaceRoot,
+        errors,
+      };
+    }
+    case "timeline": {
+      const limitRaw = parseOptionValue(argv, "--limit");
+      const kindFilter = parseOptionValue(argv, "--kind");
+      const sessionId = parseOptionValue(argv, "--session");
+      const rebuild = rest[0] === "rebuild";
+      const optionValues = new Set([limitRaw, kindFilter, sessionId].filter((value): value is string => typeof value === "string"));
+      const target = rebuild
+        ? undefined
+        : rest.find((item) => !item.startsWith("--") && !optionValues.has(item));
+      const limit = limitRaw ? Number(limitRaw) : undefined;
+      if (limitRaw !== undefined && (!Number.isFinite(limit) || limit! < 1)) {
+        errors.push("--limit must be a number >= 1");
+      }
+      return {
+        command: {
+          kind: "timeline",
+          target,
+            kindFilter,
+            sessionId,
+            limit: limit ? Math.floor(limit) : undefined,
+            json: parseFlag(argv, "--json"),
+            rebuild,
+            forAgent: parseFlag(argv, "--for-agent"),
+            causal: parseFlag(argv, "--causal"),
+            staleProofs: parseFlag(argv, "--stale-proofs"),
+            workspaceRoot,
+          },
+        workspaceRoot,
+        errors,
+      };
+    }
+    case "explain": {
+      const thing = rest[0] === "session" ? `session:${rest[1] ?? "current"}` : rest[0];
+      if (!thing) {
+        errors.push("forge explain requires a target");
+        return { command: null, workspaceRoot, errors };
+      }
+      return {
+        command: {
+          kind: "explain",
+          thing,
+          json: parseFlag(argv, "--json"),
+          workspaceRoot,
+        },
+        workspaceRoot,
+        errors,
+      };
+    }
+    case "manifest": {
+      const subcommand = rest[0];
+      const path = rest[1];
+      if (subcommand !== "validate" && subcommand !== "import") {
+        errors.push("forge manifest requires subcommand validate or import");
+        return { command: null, workspaceRoot, errors };
+      }
+      if (!path) {
+        errors.push(`forge manifest ${subcommand} requires a manifest file path`);
+        return { command: null, workspaceRoot, errors };
+      }
+      return {
+        command: {
+          kind: "manifest",
+          subcommand,
+          path,
+          json: parseFlag(argv, "--json"),
+          workspaceRoot,
+        },
+        workspaceRoot,
+        errors,
+      };
+    }
+    case "import": {
+      const subcommand = rest[0];
+      if (subcommand !== "analyze" && subcommand !== "inspect") {
+        errors.push("forge import requires subcommand analyze or inspect");
+        return { command: null, workspaceRoot, errors };
+      }
+      return {
+        command: {
+          kind: "import",
+          options: {
+            subcommand,
+            json: parseFlag(argv, "--json"),
+            dryRun: parseFlag(argv, "--dry-run"),
+            workspaceRoot,
+            entry: parseOptionValue(argv, "--entry"),
+            target: parseOptionValue(argv, "--target"),
+          },
         },
         workspaceRoot,
         errors,
       };
     }
     case "add": {
-      const alias = rest[0];
+      const subcommand = rest[0];
+      const explicitMode =
+        subcommand === "package"
+          ? "package"
+          : subcommand === "integration" || subcommand === "auth"
+            ? "integration"
+            : "auto";
+      const alias = explicitMode === "auto" ? rest[0] : rest[1];
       if (!alias) {
-        errors.push("forge add requires an integration alias");
+        errors.push(
+          explicitMode === "auto"
+            ? "forge add requires a package name or integration alias"
+            : `forge add ${subcommand} requires a target`,
+        );
         return { command: null, workspaceRoot, errors };
       }
       return {
         command: {
           kind: "add",
           alias,
-          options: parseAddOptions(argv, workspaceRoot),
+          options: parseAddOptions(argv, workspaceRoot, explicitMode),
         },
         workspaceRoot,
         errors,
       };
     }
     case "inspect": {
-      const target = rest[0] as InspectTarget | undefined;
-      if (!target || !INSPECT_TARGETS.includes(target)) {
+      const target = (rest[0] as InspectTarget | undefined) ?? "summary";
+      if (!INSPECT_TARGETS.includes(target)) {
         errors.push(
           `unsupported inspect target; supported: ${INSPECT_TARGETS.join(", ")}`,
         );
@@ -1511,6 +2354,10 @@ export function parseCli(argv: string[]): ParsedCli {
           target,
           json: parseFlag(argv, "--json"),
           dryRun: parseFlag(argv, "--dry-run"),
+          full: parseFlag(argv, "--full"),
+          brief: parseFlag(argv, "--brief"),
+          ergonomics: parseFlag(argv, "--ergonomics"),
+          workspaceRoot,
         },
         workspaceRoot,
         errors,
@@ -1531,12 +2378,58 @@ export function parseCli(argv: string[]): ParsedCli {
       {
         const scriptTimeoutRaw = parseOptionValue(argv, "--script-timeout-ms");
         const scriptTimeoutMs = scriptTimeoutRaw ? Number(scriptTimeoutRaw) : undefined;
+        const testJobsRaw = parseOptionValue(argv, "--test-jobs");
+        const testJobs = testJobsRaw ? Number(testJobsRaw) : undefined;
+        const typechecker = parseOptionValue(argv, "--typechecker");
+        const verifyOptionValues = new Set(
+          [scriptTimeoutRaw, testJobsRaw, typechecker]
+            .filter((value): value is string => typeof value === "string"),
+        );
+        const profileAlias = rest.find((item) => !verifyOptionValues.has(item));
+        const verifyProfiles = new Set([
+          "quick",
+          "smoke",
+          "agent",
+          "standard",
+          "release",
+          "strict",
+          "changed",
+          "framework",
+          "internal",
+          "maintainer",
+        ]);
+        if (profileAlias && !verifyProfiles.has(profileAlias)) {
+          errors.push(
+            `unknown forge verify profile '${profileAlias}'; expected quick, smoke, agent, standard, release, strict, changed, framework, internal, or maintainer`,
+          );
+        }
+        const internal =
+          parseFlag(argv, "--internal") ||
+          profileAlias === "framework" ||
+          profileAlias === "internal" ||
+          profileAlias === "maintainer";
         if (
           scriptTimeoutRaw !== undefined &&
           (!Number.isFinite(scriptTimeoutMs) || scriptTimeoutMs! < 1)
         ) {
           errors.push("--script-timeout-ms must be a number >= 1");
         }
+        if (
+          testJobsRaw !== undefined &&
+          (!Number.isInteger(testJobs) || testJobs! < 1)
+        ) {
+          errors.push("--test-jobs must be an integer >= 1");
+        }
+        if (
+          typechecker !== undefined &&
+          typechecker !== "tsc" &&
+          typechecker !== "native" &&
+          typechecker !== "ts7" &&
+          typechecker !== "tsgo" &&
+          typechecker !== "auto"
+        ) {
+          errors.push("--typechecker must be one of: tsc, native, ts7, tsgo, auto");
+        }
       return {
         command: {
           kind: "verify",
@@ -1546,12 +2439,17 @@ export function parseCli(argv: string[]): ParsedCli {
             skipTests: parseFlag(argv, "--skip-tests"),
             skipTypecheck: parseFlag(argv, "--skip-typecheck"),
             skipEslint: parseFlag(argv, "--skip-eslint"),
-            strict: parseFlag(argv, "--strict"),
-            changed: parseFlag(argv, "--changed"),
-            fast: parseFlag(argv, "--fast"),
-            smoke: parseFlag(argv, "--smoke"),
-            standard: parseFlag(argv, "--standard"),
+            strict: internal || parseFlag(argv, "--strict") || profileAlias === "release" || profileAlias === "strict",
+            changed: parseFlag(argv, "--changed") || profileAlias === "changed",
+            fast: parseFlag(argv, "--fast") || profileAlias === "quick",
+            smoke: parseFlag(argv, "--smoke") || profileAlias === "smoke",
+            standard: parseFlag(argv, "--standard") || profileAlias === "agent" || profileAlias === "standard",
             scriptTimeoutMs: scriptTimeoutMs ? Math.floor(scriptTimeoutMs) : undefined,
+            testJobs: testJobs ? Math.floor(testJobs) : undefined,
+            typechecker: typechecker as "tsc" | "native" | "ts7" | "tsgo" | "auto" | undefined,
+            fullTests: parseFlag(argv, "--full"),
+            testPlan: parseFlag(argv, "--test-plan"),
+            internal,
           },
         },
         workspaceRoot,
@@ -1595,6 +2493,15 @@ export function parseCli(argv: string[]): ParsedCli {
 
       const name = rest[0];
       const list = parseFlag(argv, "--list") || !name;
+      const argsRaw = parseOptionValue(argv, "--args");
+      let args: unknown = {};
+      if (argsRaw !== undefined) {
+        try {
+          args = JSON.parse(argsRaw);
+        } catch {
+          errors.push("--args must be valid JSON");
+        }
+      }
       return {
         command: {
           kind: "run",
@@ -1607,19 +2514,30 @@ export function parseCli(argv: string[]): ParsedCli {
           role: parseOptionValue(argv, "--role"),
           envFile: parseOptionValue(argv, "--env-file"),
           workspaceRoot,
+          args,
         },
         workspaceRoot,
         errors,
       };
     }
     case "query": {
-      const subcommand = (rest[0] ?? "list") as QuerySubcommand;
+      const requested = rest[0] as QuerySubcommand | undefined;
+      const subcommand =
+        !requested
+          ? "list"
+          : ["list", "run"].includes(requested)
+            ? requested
+            : "run";
       if (!["list", "run"].includes(subcommand)) {
         errors.push("forge query requires subcommand: list or run");
         return { command: null, workspaceRoot, errors };
       }
 
-      const queryName = subcommand === "run" ? rest[1] : undefined;
+      const queryName = subcommand === "run"
+        ? requested === "run"
+          ? rest[1]
+          : rest[0]
+        : undefined;
       if (subcommand === "run" && !queryName) {
         errors.push("forge query run requires a query name");
       }
@@ -1692,6 +2610,7 @@ export function parseCli(argv: string[]): ParsedCli {
       };
     }
     case "dev": {
+      const lifecycle = rest[0] === "status" || rest[0] === "stop" ? rest[0] : undefined;
       const portRaw = parseOptionValue(argv, "--port");
       const port = portRaw !== undefined ? Number(portRaw) : undefined;
       if (portRaw !== undefined && (!Number.isFinite(port) || port! < 0)) {
@@ -1728,6 +2647,9 @@ export function parseCli(argv: string[]): ParsedCli {
             .map((value) => value.trim())
             .filter(Boolean),
           envFile: parseOptionValue(argv, "--env-file"),
+          skipStartupConsole: parseFlag(argv, "--skip-startup-console"),
+          detach: parseFlag(argv, "--detach"),
+          lifecycle,
           workspaceRoot,
         },
         workspaceRoot,
@@ -1736,16 +2658,17 @@ export function parseCli(argv: string[]): ParsedCli {
     }
     case "db": {
       const subcommand = rest[0] as DbSubcommand | undefined;
-      if (!subcommand || !["diff", "migrate", "reset", "status", "rls-check"].includes(subcommand)) {
-        errors.push("forge db requires subcommand: diff, migrate, reset, status, or rls-check");
+      if (!subcommand || !["diff", "migrate", "reset", "status", "doctor", "repair", "rls-check"].includes(subcommand)) {
+        errors.push("forge db requires subcommand: diff, migrate, reset, status, doctor, repair, or rls-check");
         return { command: null, workspaceRoot, errors };
       }
       return {
         command: {
           kind: "db",
           subcommand,
-          db: parseAdapterKind(parseOptionValue(argv, "--db")),
+          db: parseAdapterKind(parseOptionValue(argv, "--adapter") ?? parseOptionValue(argv, "--db")),
           databaseUrl: parseOptionValue(argv, "--database-url"),
+          local: parseFlag(argv, "--local"),
           json: parseFlag(argv, "--json"),
           workspaceRoot,
         },
@@ -1998,6 +2921,8 @@ export function parseCli(argv: string[]): ParsedCli {
           model: parseOptionValue(argv, "--model"),
           prompt: parseOptionValue(argv, "--prompt"),
           mock: parseFlag(argv, "--mock"),
+          modelLevel: parseFlag(argv, "--model-level"),
+          live: parseFlag(argv, "--live"),
           traceId,
           db: parsePersistentDbKind(parseOptionValue(argv, "--db")),
           databaseUrl: parseOptionValue(argv, "--database-url"),
@@ -2015,8 +2940,13 @@ export function parseCli(argv: string[]): ParsedCli {
 
 export function hasUnknownOption(argv: string[]): string | null {
   const known = new Set([
+    "--version",
     "--check",
     "--json",
+    "--human",
+    "--for-agent",
+    "--causal",
+    "--stale-proofs",
     "--dry-run",
     "--plan",
     "--staged",
@@ -2047,15 +2977,23 @@ export function hasUnknownOption(argv: string[]): string | null {
     "--smoke",
     "--standard",
     "--script-timeout-ms",
+    "--test-plan",
+    "--typechecker",
     "--timeout-ms",
     "--apply",
     "--runtime-inspect",
     "--allow-scripts",
+    "--frontend",
+    "--backend",
     "--yes",
     "--force",
     "--no-generate",
     "--no-verify",
     "--keep-failed",
+    "--keep",
+    "--runtime-probes",
+    "--auth-probes",
+    "--write-report",
     "--tenant-scoped",
     "--field",
     "--fields",
@@ -2068,6 +3006,11 @@ export function hasUnknownOption(argv: string[]): string | null {
     "--policy",
     "--emit",
     "--event",
+    "--entry",
+    "--change",
+    "--proof",
+    "--handoff",
+    "--current",
     "--trigger",
     "--component",
     "--framework",
@@ -2095,6 +3038,7 @@ export function hasUnknownOption(argv: string[]): string | null {
     "--video",
     "--base-url",
     "--runtime-url",
+    "--workspace",
     "--reuse-servers",
     "--start-servers",
     "--scenario",
@@ -2103,10 +3047,13 @@ export function hasUnknownOption(argv: string[]): string | null {
     "--timeout",
     "--name",
     "--auth-token",
+    "--auth",
     "--update",
     "--allow-high-risk",
     "--to",
     "--changed",
+    "--authored",
+    "--review",
     "--env",
     "--input",
     "--provider",
@@ -2114,10 +3061,17 @@ export function hasUnknownOption(argv: string[]): string | null {
     "--release",
     "--allow-dirty",
     "--allow-public-sourcemaps",
+    "--allow-missing-local-release",
+    "--prepared-only",
+    "--build",
+    "--install-venv",
     "--with-release",
     "--concurrency",
+    "--iterations",
+    "--warmups",
     "--sandbox-backend",
     "--skip-tests",
+    "--test-jobs",
     "--skip-typecheck",
     "--skip-eslint",
     "--mock",
@@ -2127,11 +3081,19 @@ export function hasUnknownOption(argv: string[]): string | null {
     "--watch",
     "--no-watch",
     "--db",
+    "--adapter",
+    "--local",
     "--database-url",
     "--worker",
     "--no-worker",
+    "--no-start",
+    "--no-bridge",
+    "--probe",
+    "--probe-codex-server",
     "--once",
     "--limit",
+    "--kind",
+    "--session",
     "--input",
     "--args",
     "--step",
@@ -2140,12 +3102,18 @@ export function hasUnknownOption(argv: string[]): string | null {
     "--telemetry",
     "--user-id",
     "--tenant-id",
+    "--tenant",
+    "--other-tenant",
     "--role",
     "--strict-policies",
     "--strict",
     "--strict-secrets",
+    "--internal",
     "--env-file",
+    "--skip-startup-console",
     "--redacted",
+    "--older-than",
+    "--output",
     "--mock-ai",
     "--ai",
     "--provider",
@@ -2153,12 +3121,19 @@ export function hasUnknownOption(argv: string[]): string | null {
     "--prompt",
     "--url",
     "--template",
+    "--templates",
     "--package-manager",
+    "--package-managers",
     "--forge-spec",
     "--local-forge",
     "--install",
     "--no-install",
+    "--git",
     "--no-git",
+    "--field-test",
+    "--commit-ready",
+    "--detach",
+    "--ergonomics",
     "--with-web",
     "--no-web",
     "--api-only",
@@ -2167,12 +3142,29 @@ export function hasUnknownOption(argv: string[]): string | null {
     "--postgres-version",
     "--runtime-port",
     "--web-port",
+    "--preview-port",
+    "--preview-url",
+    "--studio-url",
+    "--interval-ms",
+    "--workspace-id",
     "--poll-interval",
     "--allow-dev-auth",
     "--token",
+    "--prod",
+    "--production",
+    "--scenario",
+    "--reason",
     "--no-preserve-user-sections",
     "--no-skills",
     "--no-rules",
+    "--full",
+    "--brief",
+    "--verbose",
+    "--run-tests",
+    "--model-level",
+    "--live",
+    "--no-delta",
+    "--format",
   ]);
 
   for (let index = 0; index < argv.length; index++) {
@@ -2183,6 +3175,8 @@ export function hasUnknownOption(argv: string[]): string | null {
     if (known.has(arg)) {
       if (
         arg === "--concurrency" ||
+        arg === "--iterations" ||
+        arg === "--warmups" ||
         arg === "--field" ||
         arg === "--fields" ||
         arg === "--type" ||
@@ -2193,6 +3187,9 @@ export function hasUnknownOption(argv: string[]): string | null {
         arg === "--policy" ||
         arg === "--emit" ||
         arg === "--event" ||
+        arg === "--entry" ||
+        arg === "--change" ||
+        arg === "--proof" ||
         arg === "--trigger" ||
         arg === "--component" ||
         arg === "--package" ||
@@ -2223,24 +3220,37 @@ export function hasUnknownOption(argv: string[]): string | null {
         arg === "--video" ||
         arg === "--base-url" ||
         arg === "--runtime-url" ||
+        arg === "--workspace" ||
         arg === "--scenario" ||
         arg === "--timeout" ||
         arg === "--timeout-ms" ||
+        arg === "--test-jobs" ||
+        arg === "--typechecker" ||
         arg === "--name" ||
+        arg === "--reason" ||
         arg === "--auth-token" ||
+        arg === "--auth" ||
         arg === "--sandbox-backend" ||
         arg === "--port" ||
         arg === "--host" ||
         arg === "--db" ||
+        arg === "--adapter" ||
         arg === "--database-url" ||
         arg === "--limit" ||
+        arg === "--older-than" ||
+        arg === "--output" ||
+        arg === "--kind" ||
+        arg === "--session" ||
         arg === "--input" ||
         arg === "--args" ||
         arg === "--step" ||
         arg === "--sink" ||
         arg === "--file" ||
+        arg === "--write-report" ||
         arg === "--telemetry" ||
         arg === "--user-id" ||
+        arg === "--tenant" ||
+        arg === "--other-tenant" ||
         arg === "--tenant-id" ||
         arg === "--role" ||
         arg === "--strict-policies" ||
@@ -2249,6 +3259,7 @@ export function hasUnknownOption(argv: string[]): string | null {
         arg === "--provider" ||
         arg === "--model" ||
         arg === "--prompt" ||
+        arg === "--format" ||
         arg === "--url" ||
         arg === "--template" ||
         arg === "--package-manager" ||
@@ -2256,6 +3267,11 @@ export function hasUnknownOption(argv: string[]): string | null {
         arg === "--postgres-version" ||
         arg === "--runtime-port" ||
         arg === "--web-port" ||
+        arg === "--preview-port" ||
+        arg === "--preview-url" ||
+        arg === "--studio-url" ||
+        arg === "--interval-ms" ||
+        arg === "--workspace-id" ||
         arg === "--poll-interval" ||
         arg === "--token"
         || arg === "--to" ||