forgeos 0.1.0-alpha.7 → 0.1.0-alpha.71

package/src/forge/cli/parse.ts

@@ -1,3 +1,6 @@
+import type { FabricCliOptions } from "./fabric.ts";
+import type { RepositoryCliOptions } from "./repository.ts";
+import { isProgramRunAction, isManagedRunAction, isAttachedTaskAction, isAttachedTaskRead } from "../agent-fabric/local-task-server.ts";
 import type { AddOptions, InspectTarget, VerifyOptions } from "../compiler/types/cli.ts";
 import type { SandboxBackend } from "../compiler/types/runtime.ts";
 import type { DbAdapterKind } from "../runtime/db/adapter.ts";
@@ -14,8 +17,16 @@ 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 { WorkOSFgaAction, WorkOSSubcommand } from "./workos.ts";
+import type { DeploySubcommand, DeployTarget } from "./deploy.ts";
+import type { FieldTestSubcommand } from "./field-test.ts";
+import type { GoldenPathSubcommand } from "./golden-path.ts";
+import type { SeedSubcommand } from "./seed.ts";
 import type { RlsSubcommand } from "./rls.ts";
 import type { SecuritySubcommand } from "./security.ts";
 import type { DepsSubcommand } from "./deps.ts";
@@ -47,9 +58,15 @@ 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";
+import type { EvolutionCliOptions } from "./evolution.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;
@@ -59,6 +76,8 @@ export type ForgeCommand =
       git: boolean;
       forgePackageSpec?: string;
       localForge: boolean;
+      json: boolean;
+      fieldTest: boolean;
       workspaceRoot: string;
     }
   | { kind: "build"; json: boolean; workspaceRoot: string }
@@ -91,6 +110,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;
     }
   | {
@@ -99,7 +127,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";
@@ -115,6 +143,93 @@ export type ForgeCommand =
       subcommand: AuthSubcommand;
       json: boolean;
       token?: string;
+      prod?: boolean;
+      scenario?: string;
+      provider?: "workos";
+      real?: boolean;
+      file?: string;
+      clientId?: string;
+      workspaceRoot: string;
+    }
+  | {
+      kind: "authmd";
+      subcommand: AuthMdSubcommand;
+      json: boolean;
+      output?: string;
+      workspaceRoot: string;
+    }
+  | {
+      kind: "workos";
+      subcommand: WorkOSSubcommand;
+      fgaAction?: WorkOSFgaAction;
+      json: boolean;
+      file?: string;
+      yes: boolean;
+      dryRun: boolean;
+      real?: boolean;
+      write?: boolean;
+      writePath?: string;
+      clientId?: string;
+      workspaceRoot: string;
+    }
+  | {
+      kind: "deploy";
+      subcommand: DeploySubcommand;
+      target: DeployTarget;
+      production: boolean;
+      url?: string;
+      json: boolean;
+      workspaceRoot: string;
+    }
+  | {
+      kind: "golden-path";
+      subcommand: GoldenPathSubcommand;
+      name: string;
+      template: NewTemplateName;
+      packageManager: NewPackageManager;
+      forgeSpec?: string;
+      auth: "none" | "workos";
+      target: DeployTarget;
+      production: boolean;
+      real: boolean;
+      clientId?: string;
+      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;
+      uiProbes: boolean;
+      realistic: boolean;
+      timeoutMs: number;
+      writeReport?: string;
+      json: boolean;
+      workspaceRoot: string;
+    }
+  | {
+      kind: "seed";
+      subcommand: SeedSubcommand;
+      command?: string;
+      args: unknown;
+      url?: string;
+      userId?: string;
+      tenantId?: string;
+      role?: string;
+      permissions?: string[];
+      allTenants?: boolean;
+      json: boolean;
       workspaceRoot: string;
     }
   | {
@@ -152,6 +267,7 @@ export type ForgeCommand =
       json: boolean;
       allowDirty: boolean;
       allowPublicSourcemaps: boolean;
+      allowMissingLocalRelease?: boolean;
       workspaceRoot: string;
     }
   | { kind: "make"; options: MakeCommandOptions }
@@ -161,12 +277,74 @@ 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: "fabric" } & FabricCliOptions)
+  | ({ kind: "evolution" } & EvolutionCliOptions)
+  | { 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: "repository"; options: RepositoryCliOptions }
+  | { 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 }
@@ -179,7 +357,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,8 +365,15 @@ export type ForgeCommand =
       webOnly: boolean;
       open: boolean;
       webPort?: number;
+      publicApiUrl?: string;
       telemetry: string[];
       envFile?: string;
+      skipStartupConsole: boolean;
+      detach: boolean;
+      seed: boolean;
+      seedCommand?: string;
+      seedAllTenants?: boolean;
+      lifecycle?: "status" | "stop";
       workspaceRoot: string;
     }
   | {
@@ -196,6 +381,7 @@ export type ForgeCommand =
       subcommand: DbSubcommand;
       db: DbAdapterKind;
       databaseUrl?: string;
+      local?: boolean;
       json: boolean;
       workspaceRoot: string;
     }
@@ -262,6 +448,7 @@ export type ForgeCommand =
       subcommand: EnvSubcommand;
       json: boolean;
       redacted: boolean;
+      target?: "local" | "staging" | "production";
       workspaceRoot: string;
     }
   | {
@@ -311,19 +498,31 @@ export interface ParsedCli {
 
 export const TOP_LEVEL_COMMANDS = [
   "version",
+  "last",
+  "baseline",
   "new",
   "build",
   "serve",
   "worker",
   "self-host",
+  "docs",
   "agent-contract",
   "agent",
+  "fabric",
+  "evolution",
+  "mcp",
   "review",
   "ui",
   "doctor",
   "setup",
   "security",
   "auth",
+  "authmd",
+  "workos",
+  "deploy",
+  "golden-path",
+  "field-test",
+  "seed",
   "rls",
   "deps",
   "release",
@@ -334,6 +533,20 @@ export const TOP_LEVEL_COMMANDS = [
   "test",
   "repair",
   "do",
+  "bench",
+  "cair",
+  "delta",
+  "session",
+  "timeline",
+  "explain",
+  "manifest",
+  "repository",
+  "import",
+  "status",
+  "changed",
+  "diff",
+  "handoff",
+  "studio",
   "generate",
   "add",
   "inspect",
@@ -370,6 +583,7 @@ export const INSPECT_TARGETS: InspectTarget[] = [
   "ai",
   "queries",
   "api",
+  "external",
   "client",
   "frontend",
   "auth",
@@ -388,7 +602,12 @@ export const INSPECT_TARGETS: InspectTarget[] = [
   "agent-tools",
   "agent-adapters",
   "capability-map",
+  "summary",
+  "schema",
+  "drift",
+  "handoff",
   "framework",
+  "imported",
   "ui",
   "ui-scenarios",
   "ui-routes",
@@ -397,7 +616,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", "vendor-access"];
 const NEW_PACKAGE_MANAGERS: NewPackageManager[] = ["bun", "npm", "pnpm", "yarn"];
 const SELF_HOST_SUBCOMMANDS: SelfHostSubcommand[] = ["compose", "env", "check", "clean"];
 const AGENT_CONTRACT_SUBCOMMANDS: AgentContractSubcommand[] = [
@@ -412,7 +631,15 @@ 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", "prove", "env", "fga"];
+const WORKOS_FGA_ACTIONS: WorkOSFgaAction[] = ["plan", "sync", "prove", "doctor"];
+const DEPLOY_SUBCOMMANDS: DeploySubcommand[] = ["plan", "init", "check", "readiness", "render", "package", "verify"];
+const GOLDEN_PATH_SUBCOMMANDS: GoldenPathSubcommand[] = ["plan", "status"];
+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[] = [
@@ -489,7 +716,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",
@@ -506,10 +733,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[] = [
@@ -527,6 +762,7 @@ const REVIEW_CATEGORIES: ReviewFindingCategory[] = [
   "agent",
 ];
 const UI_SUBCOMMANDS: UiSubcommand[] = [
+  "audit",
   "smoke",
   "test",
   "scenario",
@@ -550,6 +786,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);
@@ -563,6 +801,11 @@ function parseOptionValue(args: string[], flag: string): string | undefined {
   return args[index + 1];
 }
 
+function parseOptionalOptionValue(args: string[], flag: string): string | undefined {
+  const value = parseOptionValue(args, flag);
+  return value && !value.startsWith("--") ? value : undefined;
+}
+
 function parseOptionValues(args: string[], flag: string): string[] {
   const values: string[] = [];
   for (let index = 0; index < args.length; index++) {
@@ -574,8 +817,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";
@@ -602,7 +845,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"),
@@ -612,6 +858,10 @@ function parseAddOptions(
       parseOptionValue(args, "--sandbox-backend"),
     ),
     allowScripts: parseFlag(args, "--allow-scripts"),
+    withFga: parseFlag(args, "--with-fga"),
+    mode,
+    installWorkspace: parseOptionValue(args, "--workspace"),
+    packageTarget: frontend && !backend ? "frontend" : backend ? "backend" : undefined,
   };
 }
 
@@ -663,6 +913,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") {
@@ -691,6 +968,55 @@ export function parseCli(argv: string[]): ParsedCli {
   const positional = argv.filter((arg) => !arg.startsWith("-"));
   const workspaceRoot = process.cwd().replace(/\\/g, "/");
 
+  if (argv[0] === "repository" || (argv[0] === "manifest" && argv[1] === "discover")) {
+    const action = argv[0] === "manifest" ? "discover" : argv[1];
+    if (!["discover", "analyze", "context", "quality", "cache-gc", "benchmark-plan", "benchmark-report", "runtime-plan", "runtime-observe", "runtime-context"].includes(action ?? "")) errors.push("Unsupported repository action");
+    const values = ["--root", "--project-id", "--manifest", "--cache-root", "--query", "--snapshot-id", "--limit", "--max-chars", "--cursor", "--output", "--cases", "--model-config", "--repetitions", "--plan", "--observations", "--grace-hours", "--environment-id", "--observation-id"];
+    const flags = ["--json", "--write", "--no-delta", "--execute"];
+    for (let i = 2; i < argv.length; i++) {
+      if (values.includes(argv[i]!)) {
+        if (!argv[i + 1] || argv[i + 1]!.startsWith("--")) errors.push(`${argv[i]} requires a value`); else i++;
+      } else if (!flags.includes(argv[i]!)) errors.push(`Unexpected repository argument ${argv[i]}`);
+    }
+    const numeric = (flag: string, min: number, max: number) => { const raw = parseOptionValue(argv, flag); if (raw === undefined) return undefined; const number = Number(raw); if (!Number.isSafeInteger(number) || number < min || number > max) errors.push(`${flag} must be an integer ${min}..${max}`); return number; };
+    const limit = numeric("--limit", 1, 100), maxChars = numeric("--max-chars", 2048, 50000);
+    const repetitions = numeric("--repetitions", 1, 10), graceHours = numeric("--grace-hours", 1, 720);
+    for (const [flag, max] of [["--query", 2000], ["--snapshot-id", 2000], ["--cursor", 1000]] as const) {
+      if ((parseOptionValue(argv, flag)?.length ?? 0) > max) errors.push(`${flag} exceeds ${max} characters`);
+    }
+    const write = parseFlag(argv, "--write");
+    const runtime = action?.startsWith("runtime-");
+    const execute = parseFlag(argv, "--execute"), environmentId = parseOptionValue(argv, "--environment-id"), observationId = parseOptionValue(argv, "--observation-id");
+    if (!runtime && (execute || environmentId !== undefined || observationId !== undefined)) errors.push("Runtime options require a runtime action");
+    if (execute && action !== "runtime-observe") errors.push("--execute requires runtime-observe");
+    if (["runtime-plan", "runtime-observe"].includes(action ?? "") && !environmentId) errors.push("Runtime plan/observe requires --environment-id");
+    if (action === "runtime-observe" && !execute) errors.push("runtime-observe requires explicit --execute after reviewing runtime-plan");
+    if (["runtime-plan", "runtime-context"].includes(action ?? "") && write) errors.push("Runtime plan/context is read-only");
+    if (runtime && (parseOptionValue(argv, "--cache-root") || parseOptionValue(argv, "--cursor"))) errors.push("Runtime actions do not support --cache-root/--cursor");
+    if (runtime && maxChars !== undefined && maxChars > 16000) errors.push("Runtime context is bounded to 16000 characters");
+    if (runtime && limit !== undefined) errors.push("Runtime actions do not support --limit");
+    if (runtime && action !== "runtime-context" && parseOptionValue(argv, "--query") !== undefined) errors.push("Runtime --query requires runtime-context");
+    if (action === "runtime-context" && observationId) errors.push("--observation-id requires runtime-plan/observe");
+    for (const label of [environmentId, observationId]) if (label !== undefined && !/^[a-zA-Z0-9][a-zA-Z0-9._-]{0,79}$/.test(label)) errors.push("Invalid runtime label");
+    if (["context", "quality", "benchmark-plan", "benchmark-report"].includes(action ?? "") && write) errors.push("context/quality/benchmark is read-only");
+    if (["quality", "benchmark-plan"].includes(action ?? "") && !parseOptionValue(argv, "--cases")) errors.push("quality/benchmark-plan requires --cases <file>");
+    if (!["quality", "benchmark-plan"].includes(action ?? "") && parseOptionValue(argv, "--cases")) errors.push("--cases only supported for quality/benchmark-plan");
+    if (action === "benchmark-plan" && !parseOptionValue(argv, "--model-config")) errors.push("benchmark-plan requires --model-config <file>");
+    if (action !== "benchmark-plan" && (parseOptionValue(argv, "--model-config") || repetitions !== undefined)) errors.push("Model options require benchmark-plan");
+    if (action === "benchmark-report" && (!parseOptionValue(argv, "--plan") || !parseOptionValue(argv, "--observations"))) errors.push("benchmark-report requires --plan and --observations");
+    if (action !== "benchmark-report" && (parseOptionValue(argv, "--plan") || parseOptionValue(argv, "--observations"))) errors.push("--plan/--observations require benchmark-report");
+    if (action !== "cache-gc" && graceHours !== undefined) errors.push("--grace-hours requires cache-gc");
+    if (action === "cache-gc" && ["--query", "--snapshot-id", "--limit", "--max-chars", "--cursor"].some(flag => argv.includes(flag))) errors.push("cache-gc does not support context or snapshot guard options");
+    if (action !== "discover" && parseOptionValue(argv, "--output")) errors.push("--output only supported for discovery");
+    return { workspaceRoot, errors, command: errors.length ? null : { kind: "repository", options: {
+      action: action as RepositoryCliOptions["action"], cwd: workspaceRoot, write, json: parseFlag(argv, "--json"),
+      root: parseOptionValue(argv, "--root"), projectId: parseOptionValue(argv, "--project-id"), manifestPath: parseOptionValue(argv, "--manifest"),
+      cacheRoot: parseOptionValue(argv, "--cache-root"), query: parseOptionValue(argv, "--query"), snapshotId: parseOptionValue(argv, "--snapshot-id"),
+      limit, maxChars, cursor: parseOptionValue(argv, "--cursor"), output: parseOptionValue(argv, "--output"), cases: parseOptionValue(argv, "--cases"),
+      modelConfig: parseOptionValue(argv, "--model-config"), repetitions, plan: parseOptionValue(argv, "--plan"), observations: parseOptionValue(argv, "--observations"), graceHours, execute, environmentId, observationId,
+    } } };
+  }
+
   if (parseFlag(argv, "--version") || parseFlag(argv, "-v")) {
     return {
       command: { kind: "version", json: parseFlag(argv, "--json") },
@@ -709,6 +1035,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) {
@@ -738,6 +1094,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: {
@@ -749,6 +1108,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,
@@ -838,6 +1199,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,
@@ -864,12 +1245,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",
@@ -880,15 +1303,125 @@ export function parseCli(argv: string[]): ParsedCli {
             target,
             dryRun: parseFlag(argv, "--dry-run"),
             force: parseFlag(argv, "--force"),
+            mcpServer: parseOptionValue(argv, "--mcp-server"),
             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 "fabric": {
+      const subcommand = rest[0];
+      if (!isProgramRunAction(subcommand) && !isManagedRunAction(subcommand) && !isAttachedTaskAction(subcommand) && subcommand !== "install-skill" && subcommand !== "doctor" && subcommand !== "ensure-owner" && subcommand !== "project-register" && subcommand !== "project-list" && subcommand !== "capabilities" && subcommand !== "propose" && subcommand !== "status" && subcommand !== "evidence" && subcommand !== "review" && subcommand !== "run" && subcommand !== "cancel" && subcommand !== "reconcile" && subcommand !== "verify" && subcommand !== "recover-verification" && subcommand !== "review-result" && subcommand !== "serve" && subcommand !== "memory-add" && subcommand !== "memory-list" && subcommand !== "memory-delete" && subcommand !== "adaptive-propose" && subcommand !== "adaptive-review" && subcommand !== "adaptive-run" && subcommand !== "adaptive-status" && subcommand !== "change-propose" && subcommand !== "change-status" && subcommand !== "change-review" && subcommand !== "change-evidence") {
+        errors.push("forge fabric requires a supported task or memory subcommand");
+        return { command: null, workspaceRoot, errors };
+      }
+      const file = parseOptionValue(argv, "--file");
+      const runId = parseOptionValue(argv, "--run-id");
+      const projectId = parseOptionValue(argv, "--project-id");
+      if (projectId && subcommand !== "project-register") errors.push("--project-id is only supported by fabric project-register; MCP routes by registered projectId");
+      if (["install-skill", "doctor", "ensure-owner", "project-register", "project-list"].includes(subcommand) && (file || parseOptionValue(argv, "--task-id"))) errors.push("Project lifecycle commands do not accept task request files or task ids");
+      if (parseFlag(argv, "--dry-run") && subcommand !== "install-skill") errors.push("fabric --dry-run is only supported by install-skill");
+      const adaptiveChannel = parseOptionValue(argv, "--channel");
+      if (adaptiveChannel && (subcommand !== "adaptive-propose" || (adaptiveChannel !== "canary" && adaptiveChannel !== "stable"))) errors.push("--channel requires adaptive-propose and canary or stable");
+      const isChangeReadOrReview = subcommand === "change-status" || subcommand === "change-review" || subcommand === "change-evidence";
+      const taskId = (isAttachedTaskAction(subcommand) && isAttachedTaskRead(subcommand)) || isChangeReadOrReview ? parseOptionValue(argv, "--task-id")
+        : subcommand === "status" || subcommand === "evidence" || subcommand === "review" || subcommand === "run" || subcommand === "cancel" || subcommand === "reconcile" || subcommand === "verify" || subcommand === "recover-verification" || subcommand === "review-result" || subcommand === "memory-delete" || subcommand === "adaptive-review" || subcommand === "adaptive-run" || subcommand === "adaptive-status" ? rest[1] : undefined;
+      if (isManagedRunAction(subcommand) || isProgramRunAction(subcommand)) {
+        if (["run-status", "program-status", "program-history", "program-explain"].includes(subcommand ?? "")) {
+          if (!runId || runId.startsWith("--")) errors.push("forge fabric run-status requires --run-id <run-id>");
+          if (file) errors.push("forge fabric run-status does not accept --file");
+        } else {
+          if (!file || file.startsWith("--")) errors.push(`forge fabric ${subcommand} requires --file <request.json>`);
+          if (runId) errors.push(`forge fabric ${subcommand} requires runId in the request file`);
+        }
+        if (parseOptionValue(argv, "--task-id")) errors.push("Managed execution uses runId, not taskId");
+      } else if (runId) errors.push("--run-id is only supported by fabric run-status/program-status");
+      if (isAttachedTaskAction(subcommand)) {
+        if (isAttachedTaskRead(subcommand)) {
+          if (!taskId || taskId.startsWith("--")) errors.push(`forge fabric ${subcommand} requires --task-id <task-id>`);
+          if (file) errors.push(`forge fabric ${subcommand} does not accept --file`);
+        } else {
+          if (!file || file.startsWith("--")) errors.push(`forge fabric ${subcommand} requires --file <request.json>`);
+          if (parseOptionValue(argv, "--task-id")) errors.push(`forge fabric ${subcommand} requires taskId in the request file`);
+        }
+      }
+      if (subcommand === "propose" && (!file || file.startsWith("--"))) errors.push("forge fabric propose requires --file <proposal.json>");
+      if (subcommand === "change-propose" && (!file || file.startsWith("--"))) errors.push("forge fabric change-propose requires --file <request.json>");
+      if (isChangeReadOrReview && (!taskId || taskId.startsWith("--"))) errors.push(`forge fabric ${subcommand} requires --task-id <change-id>`);
+      if (subcommand === "adaptive-propose" && (!file || file.startsWith("--"))) errors.push("forge fabric adaptive-propose requires --file <input.json>");
+      if ((subcommand === "memory-add" || subcommand === "memory-list") && (!file || file.startsWith("--"))) errors.push(`forge fabric ${subcommand} requires --file <request.json>`);
+      if ((subcommand === "status" || subcommand === "evidence" || subcommand === "review" || subcommand === "run" || subcommand === "cancel" || subcommand === "reconcile" || subcommand === "verify" || subcommand === "recover-verification" || subcommand === "review-result" || subcommand === "memory-delete") && !taskId) errors.push(`forge fabric ${subcommand} requires an id`);
+      if ((subcommand === "adaptive-review" || subcommand === "adaptive-run" || subcommand === "adaptive-status") && !taskId) errors.push(`forge fabric ${subcommand} requires an id`);
+      return {
+        command: errors.length === 0 ? {
+          kind: "fabric", subcommand, workspaceRoot, json: parseFlag(argv, "--json"),
+          ...(file ? { file } : {}), ...(taskId ? { taskId } : {}), ...(runId ? { runId } : {}), ...(projectId ? { projectId } : {}),
+          ...(subcommand === "install-skill" ? { dryRun: parseFlag(argv, "--dry-run") } : {}),
+          ...(adaptiveChannel === "canary" || adaptiveChannel === "stable" ? { channel: adaptiveChannel } : {}),
+        } : null,
+        workspaceRoot,
+        errors,
+      };
+    }
+    case "evolution": {
+      const subcommand = rest[0];
+      if (subcommand !== "register" && subcommand !== "evaluate" && subcommand !== "status" &&
+          subcommand !== "review" && subcommand !== "load") {
+        errors.push("forge evolution requires register, evaluate, status, review, or load");
+        return { command: null, workspaceRoot, errors };
+      }
+      const manifest = parseOptionValue(argv, "--manifest");
+      const channel = parseOptionValue(argv, "--channel");
+      const action = rest[1];
+      const versionId = subcommand === "review" ? rest[2] : rest[1];
+      const extensionKey = rest[1];
+      if (subcommand === "register" && !manifest) errors.push("forge evolution register requires --manifest <file>");
+      if ((subcommand === "evaluate" || subcommand === "status" || subcommand === "review") &&
+          !versionId) errors.push(`forge evolution ${subcommand} requires a version id`);
+      if (subcommand === "review" && !["canary", "promote", "rollback", "revoke"].includes(action ?? ""))
+        errors.push("forge evolution review requires canary, promote, rollback, or revoke");
+      if (subcommand === "load" && (!extensionKey || (channel !== "canary" && channel !== "stable")))
+        errors.push("forge evolution load requires <extension-key> --channel canary|stable");
+      return { command: errors.length === 0 ? {
+        kind: "evolution", subcommand, workspaceRoot, json: parseFlag(argv, "--json"),
+        ...(manifest ? { manifest } : {}),
+        ...(subcommand === "review" || subcommand === "evaluate" || subcommand === "status" ? { versionId } : {}),
+        ...(subcommand === "review" ? { action: action as "canary" | "promote" | "rollback" | "revoke" } : {}),
+        ...(subcommand === "load" ? { extensionKey, channel: channel as "canary" | "stable" } : {}),
+      } : null, 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 =
@@ -911,6 +1444,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"),
@@ -934,7 +1468,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");
@@ -981,14 +1515,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,
         },
@@ -1036,15 +1583,219 @@ 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 };
+      }
+      const providerValue = parseOptionValue(argv, "--provider");
+      if (providerValue && providerValue !== "workos") {
+        errors.push("forge auth --provider supports: workos");
         return { command: null, workspaceRoot, errors };
       }
+      const provider = providerValue === "workos" ? "workos" : undefined;
       return {
         command: {
           kind: "auth",
           subcommand,
           json: parseFlag(argv, "--json"),
           token: parseOptionValue(argv, "--token"),
+          prod: parseFlag(argv, "--prod") || parseFlag(argv, "--production"),
+          scenario: parseOptionValue(argv, "--scenario"),
+          provider,
+          real: parseFlag(argv, "--real"),
+          file: parseOptionValue(argv, "--file"),
+          clientId: parseOptionValue(argv, "--client-id") ?? parseOptionValue(argv, "--workos-client-id"),
+          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, setup, prove, env, or fga");
+        return { command: null, workspaceRoot, errors };
+      }
+      const fgaAction = subcommand === "fga" ? rest[1] as WorkOSFgaAction | undefined : undefined;
+      if (subcommand === "fga" && (!fgaAction || !WORKOS_FGA_ACTIONS.includes(fgaAction))) {
+        errors.push("forge workos fga requires action: plan, sync, prove, or doctor");
+        return { command: null, workspaceRoot, errors };
+      }
+      const workOSWritePath = parseOptionalOptionValue(argv, "--write");
+      return {
+        command: {
+          kind: "workos",
+          subcommand,
+          ...(fgaAction ? { fgaAction } : {}),
+          json: parseFlag(argv, "--json"),
+          file: parseOptionValue(argv, "--file"),
+          yes: parseFlag(argv, "--yes"),
+          dryRun: parseFlag(argv, "--dry-run"),
+          real: parseFlag(argv, "--real"),
+          write: parseFlag(argv, "--write"),
+          ...(workOSWritePath ? { writePath: workOSWritePath } : {}),
+          clientId: parseOptionValue(argv, "--client-id") ?? parseOptionValue(argv, "--workos-client-id"),
+          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, init, check, readiness, render, package, or verify");
+        return { command: null, workspaceRoot, errors };
+      }
+      const targetRaw = parseOptionValue(argv, "--target") ?? (subcommand === "init" || subcommand === "render" || subcommand === "package" ? 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 "golden-path": {
+      const maybeSubcommand = rest[0];
+      if (maybeSubcommand && !maybeSubcommand.startsWith("--") && !GOLDEN_PATH_SUBCOMMANDS.includes(maybeSubcommand as GoldenPathSubcommand)) {
+        errors.push("forge golden-path requires subcommand: plan or status");
+        return { command: null, workspaceRoot, errors };
+      }
+      const subcommand = (maybeSubcommand && GOLDEN_PATH_SUBCOMMANDS.includes(maybeSubcommand as GoldenPathSubcommand)
+        ? maybeSubcommand
+        : "plan") as GoldenPathSubcommand;
+      const authRaw = parseOptionValue(argv, "--auth") ?? "workos";
+      if (authRaw !== "none" && authRaw !== "workos") {
+        errors.push("forge golden-path --auth must be none or workos");
+      }
+      const targetRaw = parseOptionValue(argv, "--target") ?? "docker";
+      if (targetRaw !== "docker" && targetRaw !== "forge-cloud") {
+        errors.push("forge golden-path --target must be docker or forge-cloud");
+      }
+      return {
+        command: {
+          kind: "golden-path",
+          subcommand,
+          name: parseOptionValue(argv, "--name") ?? "vendor-access",
+          template: parseNewTemplate(parseOptionValue(argv, "--template") ?? "vendor-access"),
+          packageManager: parseNewPackageManager(parseOptionValue(argv, "--package-manager") ?? "npm"),
+          forgeSpec: parseOptionValue(argv, "--forge-spec"),
+          auth: authRaw as "none" | "workos",
+          target: targetRaw as DeployTarget,
+          production: parseFlag(argv, "--production") || parseFlag(argv, "--prod") || subcommand === "status",
+          real: parseFlag(argv, "--real"),
+          clientId: parseOptionValue(argv, "--client-id") ?? parseOptionValue(argv, "--workos-client-id"),
+          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 realistic = parseFlag(argv, "--realistic");
+      const authRaw = parseOptionValue(argv, "--auth") ?? (realistic ? "workos" : "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") ?? (realistic || authRaw === "workos" ? "vendor-access" : "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") || realistic,
+          authProbes: parseFlag(argv, "--auth-probes") || realistic,
+          uiProbes: parseFlag(argv, "--ui-probes") || realistic,
+          realistic,
+          timeoutMs: Math.floor(timeoutMs),
+          writeReport: parseOptionValue(argv, "--write-report") ?? parseOptionValue(argv, "--file"),
+          json: parseFlag(argv, "--json"),
+          workspaceRoot,
+        },
+        workspaceRoot,
+        errors,
+      };
+    }
+    case "seed": {
+      const subcommandRaw = (rest[0] ?? "status") as SeedSubcommand;
+      if (!["status", "dev", "reset"].includes(subcommandRaw)) {
+        errors.push("forge seed requires subcommand: status, dev, or reset");
+      }
+      const argsRaw = parseOptionValue(argv, "--args");
+      let args: unknown = {};
+      if (argsRaw !== undefined) {
+        try {
+          args = JSON.parse(argsRaw);
+        } catch {
+          errors.push("--args must be valid JSON");
+        }
+      }
+      const permissionsRaw = parseOptionValue(argv, "--permissions");
+      return {
+        command: {
+          kind: "seed",
+          subcommand: subcommandRaw,
+          command: parseOptionValue(argv, "--command"),
+          args,
+          url: parseOptionValue(argv, "--url"),
+          userId: parseOptionValue(argv, "--user-id"),
+          tenantId: parseOptionValue(argv, "--tenant-id") ?? parseOptionValue(argv, "--tenant"),
+          role: parseOptionValue(argv, "--role"),
+          permissions: permissionsRaw
+            ?.split(",")
+            .map((permission) => permission.trim())
+            .filter(Boolean),
+          allTenants: parseFlag(argv, "--all-tenants"),
+          json: parseFlag(argv, "--json"),
           workspaceRoot,
         },
         workspaceRoot,
@@ -1127,6 +1878,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,
@@ -1198,7 +1950,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"),
@@ -1372,7 +2124,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");
@@ -1391,7 +2143,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"),
@@ -1405,6 +2157,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,
@@ -1477,6 +2231,212 @@ 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 cairValues = ["--root", "--project-id", "--manifest", "--cache-root", "--snapshot-id", "--format", "--input"];
+      for (let i = 2; i < argv.length; i++) if (cairValues.includes(argv[i]!) && (!argv[i + 1] || argv[i + 1]!.startsWith("--"))) errors.push(`${argv[i]} requires a value`);
+      const cairText = argv.slice(2).filter((part, index, parts) => !part.startsWith("--") && !cairValues.includes(parts[index - 1] ?? ""));
+      const query = subcommand === "query" ? cairText.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" ? cairText.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"),
+            snapshotId: parseOptionValue(argv, "--snapshot-id"),
+            manifestPath: parseOptionValue(argv, "--manifest"),
+            cacheRoot: parseOptionValue(argv, "--cache-root"),
+            root: parseOptionValue(argv, "--root"),
+            projectId: parseOptionValue(argv, "--project-id"),
+          },
+        },
+        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;
@@ -1490,30 +2450,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(", ")}`,
         );
@@ -1525,6 +2644,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,
@@ -1545,12 +2668,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",
@@ -1560,12 +2729,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,
@@ -1609,6 +2783,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",
@@ -1621,19 +2804,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");
       }
@@ -1706,6 +2900,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)) {
@@ -1713,12 +2908,22 @@ export function parseCli(argv: string[]): ParsedCli {
       }
       const webPortRaw = parseOptionValue(argv, "--web-port");
       const webPort = webPortRaw !== undefined ? Number(webPortRaw) : undefined;
-      if (webPortRaw !== undefined && (!Number.isFinite(webPort) || webPort! < 1)) {
-        errors.push("--web-port must be a positive integer");
+      if (webPortRaw !== undefined && (!Number.isFinite(webPort) || webPort! < 0)) {
+        errors.push("--web-port must be a non-negative integer");
       }
       const aiMode = parseOptionValue(argv, "--ai");
       const mockAi =
         parseFlag(argv, "--mock-ai") || aiMode === "mock" || process.env.FORGE_MOCK_AI === "1";
+      const seed = parseFlag(argv, "--seed");
+      if (seed && parseFlag(argv, "--once")) {
+        errors.push("forge dev --seed cannot be combined with --once; use forge dev --seed or forge seed dev");
+      }
+      if (seed && parseFlag(argv, "--web-only")) {
+        errors.push("forge dev --seed cannot be combined with --web-only because seeding requires the API runtime");
+      }
+      if (parseFlag(argv, "--all-tenants") && !seed) {
+        errors.push("forge dev --all-tenants requires --seed; use forge dev --seed --all-tenants");
+      }
       return {
         command: {
           kind: "dev",
@@ -1737,11 +2942,18 @@ export function parseCli(argv: string[]): ParsedCli {
           webOnly: parseFlag(argv, "--web-only"),
           open: parseFlag(argv, "--open"),
           webPort,
+          publicApiUrl: parseOptionValue(argv, "--public-api-url"),
           telemetry: (parseOptionValue(argv, "--telemetry") ?? "local")
             .split(",")
             .map((value) => value.trim())
             .filter(Boolean),
           envFile: parseOptionValue(argv, "--env-file"),
+          skipStartupConsole: parseFlag(argv, "--skip-startup-console"),
+          detach: parseFlag(argv, "--detach"),
+          seed,
+          seedCommand: parseOptionValue(argv, "--seed-command"),
+          seedAllTenants: parseFlag(argv, "--all-tenants"),
+          lifecycle,
           workspaceRoot,
         },
         workspaceRoot,
@@ -1750,16 +2962,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,
         },
@@ -1972,10 +3185,14 @@ export function parseCli(argv: string[]): ParsedCli {
     }
     case "env": {
       const subcommand = rest[0] as EnvSubcommand | undefined;
-      if (!subcommand || !["list", "check", "print"].includes(subcommand)) {
-        errors.push("forge env requires subcommand: list, check, or print");
+      if (!subcommand || !["list", "check", "print", "doctor"].includes(subcommand)) {
+        errors.push("forge env requires subcommand: list, check, print, or doctor");
         return { command: null, workspaceRoot, errors };
       }
+      const targetRaw = parseOptionValue(argv, "--target") ?? "local";
+      if (!["local", "staging", "production"].includes(targetRaw)) {
+        errors.push("forge env --target must be local, staging, or production");
+      }
 
       return {
         command: {
@@ -1983,6 +3200,7 @@ export function parseCli(argv: string[]): ParsedCli {
           subcommand,
           json: parseFlag(argv, "--json"),
           redacted: parseFlag(argv, "--redacted"),
+          target: targetRaw as "local" | "staging" | "production",
           workspaceRoot,
         },
         workspaceRoot,
@@ -2031,9 +3249,21 @@ export function parseCli(argv: string[]): ParsedCli {
 
 export function hasUnknownOption(argv: string[]): string | null {
   const known = new Set([
+    "--cases",
+    "--model-config", "--repetitions", "--observations", "--grace-hours", "--environment-id", "--observation-id", "--execute",
+    "--root",
+    "--cache-root",
+    "--snapshot-id",
+    "--max-chars",
+    "--cursor",
+    "--query",
     "--version",
     "--check",
     "--json",
+    "--human",
+    "--for-agent",
+    "--causal",
+    "--stale-proofs",
     "--dry-run",
     "--plan",
     "--staged",
@@ -2064,15 +3294,26 @@ 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",
+    "--ui-probes",
+    "--realistic",
+    "--real",
+    "--write-report",
     "--tenant-scoped",
     "--field",
     "--fields",
@@ -2085,8 +3326,14 @@ export function hasUnknownOption(argv: string[]): string | null {
     "--policy",
     "--emit",
     "--event",
+    "--entry",
+    "--change",
+    "--proof",
+    "--handoff",
+    "--current",
     "--trigger",
     "--component",
+    "--command",
     "--framework",
     "--package",
     "--action",
@@ -2095,6 +3342,7 @@ export function hasUnknownOption(argv: string[]): string | null {
     "--with-livequery",
     "--with-react",
     "--with-ui",
+    "--with-fga",
     "--with-tests",
     "--with-create-form",
     "--write",
@@ -2112,6 +3360,7 @@ export function hasUnknownOption(argv: string[]): string | null {
     "--video",
     "--base-url",
     "--runtime-url",
+    "--workspace",
     "--reuse-servers",
     "--start-servers",
     "--scenario",
@@ -2120,10 +3369,13 @@ export function hasUnknownOption(argv: string[]): string | null {
     "--timeout",
     "--name",
     "--auth-token",
+    "--auth",
     "--update",
     "--allow-high-risk",
     "--to",
     "--changed",
+    "--authored",
+    "--review",
     "--env",
     "--input",
     "--provider",
@@ -2131,10 +3383,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",
@@ -2144,25 +3403,47 @@ 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",
     "--sink",
     "--file",
+    "--task-id",
+    "--run-id",
+    "--project-id",
+    "--manifest",
+    "--channel",
     "--telemetry",
     "--user-id",
     "--tenant-id",
+    "--tenant",
+    "--client-id",
+    "--workos-client-id",
+    "--other-tenant",
     "--role",
+    "--permissions",
     "--strict-policies",
     "--strict",
     "--strict-secrets",
+    "--internal",
     "--env-file",
+    "--skip-startup-console",
     "--redacted",
+    "--older-than",
+    "--output",
     "--mock-ai",
     "--ai",
     "--provider",
@@ -2170,12 +3451,22 @@ 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",
+    "--seed",
+    "--seed-command",
+    "--all-tenants",
+    "--ergonomics",
     "--with-web",
     "--no-web",
     "--api-only",
@@ -2184,16 +3475,31 @@ export function hasUnknownOption(argv: string[]): string | null {
     "--postgres-version",
     "--runtime-port",
     "--web-port",
+    "--public-api-url",
+    "--preview-port",
+    "--preview-url",
+    "--studio-url",
+    "--interval-ms",
+    "--workspace-id",
     "--poll-interval",
+    "--mcp-server",
     "--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++) {
@@ -2204,6 +3510,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" ||
@@ -2214,8 +3522,12 @@ export function hasUnknownOption(argv: string[]): string | null {
         arg === "--policy" ||
         arg === "--emit" ||
         arg === "--event" ||
+        arg === "--entry" ||
+        arg === "--change" ||
+        arg === "--proof" ||
         arg === "--trigger" ||
         arg === "--component" ||
+        arg === "--command" ||
         arg === "--package" ||
         arg === "--action" ||
         arg === "--since" ||
@@ -2244,32 +3556,52 @@ 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 === "--task-id" ||
+        arg === "--run-id" ||
+        arg === "--project-id" ||
+        arg === "--manifest" ||
+        arg === "--channel" ||
+        arg === "--write-report" ||
         arg === "--telemetry" ||
         arg === "--user-id" ||
+        arg === "--tenant" ||
+        arg === "--other-tenant" ||
         arg === "--tenant-id" ||
         arg === "--role" ||
+        arg === "--permissions" ||
         arg === "--strict-policies" ||
         arg === "--env-file" ||
         arg === "--ai" ||
         arg === "--provider" ||
         arg === "--model" ||
         arg === "--prompt" ||
+        arg === "--format" ||
         arg === "--url" ||
         arg === "--template" ||
         arg === "--package-manager" ||
@@ -2277,7 +3609,14 @@ export function hasUnknownOption(argv: string[]): string | null {
         arg === "--postgres-version" ||
         arg === "--runtime-port" ||
         arg === "--web-port" ||
+        arg === "--public-api-url" ||
+        arg === "--preview-port" ||
+        arg === "--preview-url" ||
+        arg === "--studio-url" ||
+        arg === "--interval-ms" ||
+        arg === "--workspace-id" ||
         arg === "--poll-interval" ||
+        arg === "--mcp-server" ||
         arg === "--token"
         || arg === "--to" ||
         arg === "--env" ||