forgeos 0.1.0-alpha.37 → 0.1.0-alpha.39

package/src/forge/cli/main.ts

@@ -17,21 +17,30 @@ function formatHelp(): string {
     "  forge changed --review --json  Show review-focused app/config/docs changes, excluding local agent/browser artifacts",
     "  forge changed --commit-ready --json  Show files suitable for git add, excluding generated and operational artifacts",
     "  forge new my-app --template minimal-web --field-test  Create an installed WorkOS/auth.md field-test app",
+    "  forge field-test create vendor-access --auth workos --template minimal-web --json  Create a real field-test app",
+    "  forge field-test run --templates minimal-web,nuxt-web --package-managers npm,pnpm --runtime-probes --auth-probes --json",
+    "  forge field-test report --json  Summarize the machine-readable field-test report",
     "  forge diff authored       Run the authored-only git diff pathspec",
     "  forge handoff --json      Compact work handoff for the next external code agent",
     "  forge agent onboard --target codex --json  Prepare adapter, hooks, memory, and dev snapshot",
     "  forge doctor agent --target codex --json  Check adapter, hooks, and Agent Memory readiness",
     "  forge doctor delta --json  Check DeltaDB writability, queue drain, redaction, and gitignore posture",
+    "  forge doctor runtime --json  Check generated freshness, local dev lifecycle, and PGlite posture",
     "  forge agent ingest codex --watch --file .forge/agent/events.ndjson --json",
     "  forge docs check --json  Check public docs, ReadTheDocs config, links, and local MkDocs tooling",
     "  forge docs check --build --install-venv --json  Build docs strictly in a local RTD-style venv",
-    "  forge release doctor --json  Aggregate release, sourcemaps, self-host, and docs readiness",
+    "  forge release doctor --json  Check npm publish readiness plus separate production deploy readiness",
     "  forge authmd generate       Write public/auth.md from the generated agent/auth contract",
+    "  forge auth check --production --json  Fail unless auth is jwt/oidc production-ready",
     "  forge authmd check --json   Check public/auth.md drift for CI and agent-ready apps",
     "  forge workos install --yes --json  Delegate AuthKit setup to npx --yes workos@latest install",
     "  forge workos doctor --json  Check WorkOS AuthKit/FGA files, claims, seed, webhook, and tenant guards",
     "  forge workos doctor --yes --json  Run local checks, then delegate to npx --yes workos@latest doctor",
-    "  forge workos seed --file workos-seed.yml --json  Plan WorkOS CLI seed",
+    "  forge workos seed --file workos-seed.yml --dry-run --json  Validate WorkOS seed without hosted changes",
+    "  forge deploy plan --target docker --json  Explain production deploy gates and commands",
+    "  forge deploy check --production --json  Gate auth, DB, metadata, generated artifacts, and liveQuery readiness",
+    "  forge deploy render docker  Write Docker production deploy files under deploy/",
+    "  forge deploy verify --production --url https://app.example.com --json  Probe /health and validate public auth metadata",
     "  forge release check --allow-missing-local-release --json  Gate release readiness without failing on unprepared local artifacts",
     "  forge self-host check --prepared-only --json  Report compose readiness without creating deploy files",
     "  forge delta status --verbose --json  Include Delta schema, lock, and aggregate count details",

package/src/forge/cli/new.ts

@@ -69,6 +69,7 @@ const REQUIRED_GITIGNORE_PATHS = [
   ".forge/impact/",
   ".forge/agent-adapters/",
   ".forge/studio/",
+  ".workos-seed-state.json",
 ] as const;
 
 const DEFAULT_FORGE_PACKAGE_SPEC = "npm:forgeos@alpha";
@@ -570,7 +571,11 @@ export async function runNewCommand(options: NewCommandOptions): Promise<NewComm
   if (options.fieldTest && installed) {
     const steps: Array<{ name: string; command: string; args: string[] }> = [
       { name: "workos", command: options.packageManager, args: ["run", "forge", "--", "add", "auth", "workos", "--json"] },
+      { name: "generate-workos", command: options.packageManager, args: ["run", "forge", "--", "generate"] },
       { name: "authmd", command: options.packageManager, args: ["run", "forge", "--", "authmd", "generate", "--json"] },
+      { name: "authmd-check", command: options.packageManager, args: ["run", "forge", "--", "authmd", "check", "--json"] },
+      { name: "workos-doctor", command: options.packageManager, args: ["run", "forge", "--", "workos", "doctor", "--json"] },
+      { name: "workos-seed", command: options.packageManager, args: ["run", "forge", "--", "workos", "seed", "--file", "workos-seed.yml", "--dry-run", "--json"] },
       { name: "check", command: options.packageManager, args: ["run", "forge", "--", "check", "--json"] },
     ];
     for (const step of steps) {

package/src/forge/cli/output.ts

@@ -232,8 +232,8 @@ export function buildAddJson(
                 "forge workos install --yes --json",
                 "forge workos doctor --json",
                 "forge workos doctor --yes --json",
+                "forge workos seed --file workos-seed.yml --dry-run --json",
                 "forge workos seed --file workos-seed.yml --json",
-                "forge workos seed --file workos-seed.yml --yes --json",
                 "forge auth check --json",
                 "forge auth prove --json",
               ]

package/src/forge/cli/parse.ts

@@ -20,6 +20,8 @@ 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";
@@ -119,7 +121,7 @@ export type ForgeCommand =
       json: boolean;
       workspaceRoot: string;
     }
-  | { kind: "doctor"; target?: "project" | "windows" | "agent" | "delta" | "pglite"; agentTarget?: AgentAdapterTarget; 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";
@@ -155,6 +157,34 @@ export type ForgeCommand =
       dryRun: 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;
+    }
   | {
       kind: "rls";
       subcommand: RlsSubcommand;
@@ -432,6 +462,8 @@ export const TOP_LEVEL_COMMANDS = [
   "auth",
   "authmd",
   "workos",
+  "deploy",
+  "field-test",
   "rls",
   "deps",
   "release",
@@ -544,6 +576,8 @@ const AUTH_SUBCOMMANDS: AuthSubcommand[] = [
 const BASELINE_SUBCOMMANDS: BaselineSubcommand[] = ["create", "status"];
 const AUTHMD_SUBCOMMANDS: AuthMdSubcommand[] = ["generate", "check"];
 const WORKOS_SUBCOMMANDS: WorkOSSubcommand[] = ["install", "doctor", "seed"];
+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[] = [
@@ -811,6 +845,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") {
@@ -1255,8 +1316,8 @@ export function parseCli(argv: string[]): ParsedCli {
       };
     }
     case "doctor":
-      if (rest[0] && rest[0] !== "windows" && rest[0] !== "agent" && rest[0] !== "delta" && rest[0] !== "pglite") {
-        errors.push("forge doctor supports subcommand: windows, agent, delta, or pglite");
+      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 {
@@ -1270,6 +1331,8 @@ export function parseCli(argv: string[]): ParsedCli {
                 ? "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"
@@ -1330,7 +1393,7 @@ export function parseCli(argv: string[]): ParsedCli {
           subcommand,
           json: parseFlag(argv, "--json"),
           token: parseOptionValue(argv, "--token"),
-          prod: parseFlag(argv, "--prod"),
+          prod: parseFlag(argv, "--prod") || parseFlag(argv, "--production"),
           scenario: parseOptionValue(argv, "--scenario"),
           workspaceRoot,
         },
@@ -1376,6 +1439,71 @@ export function parseCli(argv: string[]): ParsedCli {
         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,
+        errors,
+      };
+    }
     case "rls": {
       const subcommand = rest[0] as RlsSubcommand | undefined;
       if (!subcommand || !RLS_SUBCOMMANDS.includes(subcommand)) {
@@ -2860,6 +2988,10 @@ export function hasUnknownOption(argv: string[]): string | null {
     "--no-generate",
     "--no-verify",
     "--keep-failed",
+    "--keep",
+    "--runtime-probes",
+    "--auth-probes",
+    "--write-report",
     "--tenant-scoped",
     "--field",
     "--fields",
@@ -2913,6 +3045,7 @@ export function hasUnknownOption(argv: string[]): string | null {
     "--timeout",
     "--name",
     "--auth-token",
+    "--auth",
     "--update",
     "--allow-high-risk",
     "--to",
@@ -2986,7 +3119,9 @@ export function hasUnknownOption(argv: string[]): string | null {
     "--prompt",
     "--url",
     "--template",
+    "--templates",
     "--package-manager",
+    "--package-managers",
     "--forge-spec",
     "--local-forge",
     "--install",
@@ -3014,6 +3149,7 @@ export function hasUnknownOption(argv: string[]): string | null {
     "--allow-dev-auth",
     "--token",
     "--prod",
+    "--production",
     "--scenario",
     "--reason",
     "--no-preserve-user-sections",
@@ -3091,6 +3227,7 @@ export function hasUnknownOption(argv: string[]): string | null {
         arg === "--name" ||
         arg === "--reason" ||
         arg === "--auth-token" ||
+        arg === "--auth" ||
         arg === "--sandbox-backend" ||
         arg === "--port" ||
         arg === "--host" ||
@@ -3107,6 +3244,7 @@ export function hasUnknownOption(argv: string[]): string | null {
         arg === "--step" ||
         arg === "--sink" ||
         arg === "--file" ||
+        arg === "--write-report" ||
         arg === "--telemetry" ||
         arg === "--user-id" ||
         arg === "--tenant" ||

package/src/forge/cli/workos.ts

@@ -1,5 +1,6 @@
-import { existsSync, readFileSync } from "node:fs";
-import { join } from "node:path";
+import { existsSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { basename, join } from "node:path";
 import { spawnSync } from "node:child_process";
 import { GENERATED_DIR } from "../compiler/emitter/constants.ts";
 import { stripDeterministicHeader } from "../compiler/primitives/header.ts";
@@ -84,6 +85,14 @@ function readText(root: string, path: string): string {
   return stripDeterministicHeader(readFileSync(absolute, "utf8"));
 }
 
+function readRawText(root: string, path: string): string {
+  const absolute = join(root, path);
+  if (!existsSync(absolute)) {
+    return "";
+  }
+  return readFileSync(absolute, "utf8");
+}
+
 function includesAll(haystack: string, needles: string[]): boolean {
   return needles.every((needle) => haystack.includes(needle));
 }
@@ -96,7 +105,7 @@ function quotedValues(text: string): string[] {
   return [...text.matchAll(/["']([^"']+)["']/g)].map((match) => match[1]!).filter(Boolean);
 }
 
-interface WorkOSSeedSummary {
+export interface WorkOSSeedSummary {
   exists: boolean;
   valid: boolean;
   path: string;
@@ -118,7 +127,7 @@ function parseName(line: string): string | null {
   return match?.[1]?.trim() ?? null;
 }
 
-function parseSeedFile(workspaceRoot: string, preferredPath = DEFAULT_SEED_FILE): WorkOSSeedSummary {
+export function parseSeedFile(workspaceRoot: string, preferredPath = DEFAULT_SEED_FILE): WorkOSSeedSummary {
   const seedPath = exists(workspaceRoot, preferredPath)
     ? preferredPath
     : exists(workspaceRoot, GENERATED_SEED_FILE)
@@ -200,7 +209,7 @@ function parseSeedFile(workspaceRoot: string, preferredPath = DEFAULT_SEED_FILE)
   };
 }
 
-function collectPolicyPermissions(workspaceRoot: string): string[] {
+export function collectPolicyPermissions(workspaceRoot: string): string[] {
   const registry = readJson(workspaceRoot, `${GENERATED_DIR}/policyRegistry.json`) as {
     policies?: Array<{ permissions?: string[] }>;
   } | null;
@@ -234,7 +243,7 @@ function singularResourceName(name: string): string {
   return name;
 }
 
-function collectExpectedResourceTypes(workspaceRoot: string): string[] {
+export function collectExpectedResourceTypes(workspaceRoot: string): string[] {
   const dataGraph = readJson(workspaceRoot, `${GENERATED_DIR}/dataGraph.json`) as {
     tables?: Array<{ name?: string; fields?: Array<{ name?: string }> }>;
   } | null;
@@ -257,7 +266,7 @@ function collectExpectedResourceTypes(workspaceRoot: string): string[] {
   return uniqueSorted(resourceTypes);
 }
 
-function missingValues(expected: string[], actual: string[]): string[] {
+export function missingValues(expected: string[], actual: string[]): string[] {
   const actualSet = new Set(actual);
   return expected.filter((value) => !actualSet.has(value));
 }
@@ -389,6 +398,54 @@ function collectWorkOSChecks(workspaceRoot: string): WorkOSCheck[] {
   ];
 }
 
+function prepareSeedFileForWorkOSCli(
+  workspaceRoot: string,
+  file: string,
+): { file: string; sanitized: boolean; cleanup: () => void } {
+  const raw = readRawText(workspaceRoot, file);
+  const stripped = stripDeterministicHeader(raw);
+  if (!raw || raw === stripped) {
+    return { file, sanitized: false, cleanup: () => undefined };
+  }
+
+  const tempDir = mkdtempSync(join(tmpdir(), "forge-workos-seed-"));
+  const preparedFile = join(tempDir, basename(file));
+  writeFileSync(preparedFile, stripped, "utf8");
+  return {
+    file: preparedFile,
+    sanitized: true,
+    cleanup: () => rmSync(tempDir, { recursive: true, force: true }),
+  };
+}
+
+function isWorkOSSeedAlreadyApplied(stdout: string, stderr: string): boolean {
+  const output = `${stdout}\n${stderr}`;
+  return /(?:permission|role|resource type|organization|slug|domain)[^\n]*(?:already in use|already exists|exists already)|already in use/i
+    .test(output);
+}
+
+function seedData(input: {
+  seed: WorkOSSeedSummary;
+  activePermissions: string[];
+  expectedResourceTypes: string[];
+  unusedSeedPermissions: string[];
+  dryRun?: boolean;
+  seedFileSanitized?: boolean;
+  seedAlreadyApplied?: boolean;
+  nextCommand?: string;
+}): Record<string, unknown> {
+  return {
+    seed: input.seed,
+    activePermissions: input.activePermissions,
+    expectedResourceTypes: input.expectedResourceTypes,
+    unusedSeedPermissions: input.unusedSeedPermissions,
+    dryRun: input.dryRun ?? false,
+    seedFileSanitized: input.seedFileSanitized ?? false,
+    seedAlreadyApplied: input.seedAlreadyApplied ?? false,
+    ...(input.nextCommand ? { nextCommand: input.nextCommand } : {}),
+  };
+}
+
 export function runWorkOSDoctorCommand(options: WorkOSCommandOptions): WorkOSCommandResult {
   const checks = collectWorkOSChecks(options.workspaceRoot);
   const ok = checks.every((check) => check.ok);
@@ -505,33 +562,62 @@ export function runWorkOSSeedCommand(options: WorkOSCommandOptions): WorkOSComma
       checks,
       command,
       applied: false,
-      data: { seed, activePermissions, expectedResourceTypes, unusedSeedPermissions },
+      data: seedData({ seed, activePermissions, expectedResourceTypes, unusedSeedPermissions }),
       exitCode: 1,
     };
   }
-  if (!options.yes || options.dryRun) {
+  if (options.dryRun) {
     return {
       ok: true,
       kind: "workos-seed",
       checks,
       command,
       applied: false,
-      data: { seed, activePermissions, expectedResourceTypes, unusedSeedPermissions },
+      data: seedData({
+        seed,
+        activePermissions,
+        expectedResourceTypes,
+        unusedSeedPermissions,
+        dryRun: true,
+        nextCommand: `forge workos seed --file ${file} --json`,
+      }),
       exitCode: 0,
     };
   }
-  const child = runExternalCommand(command, options);
-  return {
-    ok: child.status === 0,
-    kind: "workos-seed",
-    checks,
-    command,
-    applied: child.status === 0,
-    data: { seed, activePermissions, expectedResourceTypes, unusedSeedPermissions },
-    stdout: child.stdout,
-    stderr: child.stderr,
-    exitCode: child.status === 0 ? 0 : 1,
-  };
+  const preparedSeed = prepareSeedFileForWorkOSCli(options.workspaceRoot, seed.path);
+  const delegatedCommand = [
+    "npx",
+    "--yes",
+    "workos@latest",
+    "seed",
+    "--file",
+    preparedSeed.file,
+  ];
+  try {
+    const child = runExternalCommand(delegatedCommand, options);
+    const seedAlreadyApplied =
+      child.status !== 0 && isWorkOSSeedAlreadyApplied(child.stdout, child.stderr);
+    return {
+      ok: child.status === 0 || seedAlreadyApplied,
+      kind: "workos-seed",
+      checks,
+      command: delegatedCommand,
+      applied: child.status === 0,
+      data: seedData({
+        seed,
+        activePermissions,
+        expectedResourceTypes,
+        unusedSeedPermissions,
+        seedFileSanitized: preparedSeed.sanitized,
+        seedAlreadyApplied,
+      }),
+      stdout: child.stdout,
+      stderr: child.stderr,
+      exitCode: child.status === 0 || seedAlreadyApplied ? 0 : 1,
+    };
+  } finally {
+    preparedSeed.cleanup();
+  }
 }
 
 export function runWorkOSCommand(options: WorkOSCommandOptions): WorkOSCommandResult {
@@ -562,7 +648,16 @@ export function formatWorkOSHuman(result: WorkOSCommandResult): string {
     lines.push("external WorkOS doctor not run; pass --yes to execute the WorkOS CLI command");
   }
   if (result.kind === "workos-seed" && !result.applied) {
-    lines.push("seed not applied; pass --yes to execute the WorkOS CLI command");
+    const data = result.data && typeof result.data === "object"
+      ? result.data as { dryRun?: boolean; seedAlreadyApplied?: boolean; nextCommand?: string }
+      : {};
+    if (data.seedAlreadyApplied) {
+      lines.push("seed already appears applied; WorkOS reported existing resources");
+    } else if (data.dryRun) {
+      lines.push(`seed dry-run only; run ${data.nextCommand ?? "forge workos seed --file workos-seed.yml --json"} to execute the WorkOS CLI command`);
+    } else {
+      lines.push("seed not applied; inspect stdout/stderr from the WorkOS CLI command");
+    }
   }
   return `${lines.join("\n")}\n`;
 }

package/src/forge/compiler/integration/plan.ts

@@ -41,11 +41,23 @@ export interface IntegrationPlanInput {
   existingLock: ForgeLock | null;
 }
 
+function headerForGeneratedPath(path: string): EmitFile["header"] {
+  return path.endsWith(".yml") || path.endsWith(".yaml") ? "none" : undefined;
+}
+
+function headerForRootFile(path: string): EmitFile["header"] {
+  if (path.endsWith(".env.example") || path.endsWith(".yml") || path.endsWith(".yaml")) {
+    return "none";
+  }
+  return "deterministic";
+}
+
 function makeEmitFile(path: string, content: string): EmitFile {
   return {
     path,
     content,
     contentHash: hashStable(content),
+    header: headerForGeneratedPath(path),
   };
 }
 
@@ -236,7 +248,7 @@ export function buildIntegrationEmitPlan(input: IntegrationPlanInput): EmitPlan
       path: rootFile,
       content,
       contentHash: hashStable(content),
-      header: rootFile.endsWith(".env.example") ? "none" : "deterministic",
+      header: headerForRootFile(rootFile),
     });
   }
 

package/src/forge/compiler/integration/templates/workos.ts

@@ -184,8 +184,8 @@ export function renderWorkosAuthkit(_input: IntegrationTemplateInput): string {
     '  "forge workos install --yes --json",',
     '  "forge workos doctor --json",',
     '  "forge workos doctor --yes --json",',
+    '  "forge workos seed --file workos-seed.yml --dry-run --json",',
     '  "forge workos seed --file workos-seed.yml --json",',
-    '  "forge workos seed --file workos-seed.yml --yes --json",',
     '  "forge auth check --json",',
     '  "forge auth prove --json",',
     "] as const;",
@@ -1077,8 +1077,8 @@ export function renderWorkosDoc(input: IntegrationTemplateInput): string {
     "forge workos install --yes --json",
     "forge workos doctor --json",
     "forge workos doctor --yes --json",
+    "forge workos seed --file workos-seed.yml --dry-run --json",
     "forge workos seed --file workos-seed.yml --json",
-    "forge workos seed --file workos-seed.yml --yes --json",
     "forge auth check --json",
     "forge auth prove --json",
     "forge check --json",

package/src/forge/version.ts

@@ -1,3 +1,3 @@
-export const FORGEOS_VERSION = "0.1.0-alpha.37";
+export const FORGEOS_VERSION = "0.1.0-alpha.39";
 export const GENERATOR_VERSION = FORGEOS_VERSION;
 export const CLI_VERSION = FORGEOS_VERSION;