forgeos 0.1.0-alpha.55 → 0.1.0-alpha.56

package/AGENTS.md

@@ -1,4 +1,4 @@
-// @forge-generated generator=0.1.0-alpha.55 input=bbd63535f88ad4d382f6da1f26a2898e49fa00849042fcd683e316054e3b3959 content=721818a6f9a664aa898092d4aa5cd68cbbd8ad6e150c7d3ad3ef785a2e3fcf53
+// @forge-generated generator=0.1.0-alpha.56 input=a013874c7856b533aae64f467111c45bd707703fd9db6f0b8115898afc97af53 content=721818a6f9a664aa898092d4aa5cd68cbbd8ad6e150c7d3ad3ef785a2e3fcf53
 # AGENTS.md
 
 <!-- forge-generated:start -->

package/CHANGELOG.md

@@ -1,5 +1,30 @@
 # forgeos
 
+## 0.1.0-alpha.56
+
+### Patch Changes
+
+- Add the production deploy golden path as an explicit CLI workflow.
+
+  - `forge deploy init --target docker` now acts as the canonical Docker
+    production bootstrap command for runtime files, `deploy/.env.production`
+    guidance, and production handoff docs.
+  - `forge deploy readiness --production --json` now summarizes whether an app
+    can publish, grouped blockers/warnings, readiness score, and the next
+    command an agent should run.
+  - `forge env doctor --target local|staging|production --json` now reports the
+    effective auth mode, database posture, provider detection, missing env
+    names, and safe source metadata without printing secret values.
+  - `forge deploy check --production --json` now includes blocking/warning
+    summaries and the readiness object used by the deploy gate.
+  - `forge deploy verify --production --url ... --json` now validates required
+    public auth metadata and probes optional runtime endpoints such as
+    `/ready`, `/live/status`, `/outbox/status`, and `/webhooks/workos`.
+  - Production docs now present the canonical flow:
+    `deploy init -> env doctor -> auth/auth.md/WorkOS proof -> field-test ->
+    readiness -> check -> package -> verify`, while keeping WorkOS FGA
+    explicitly optional unless the app opts into FGA artifacts.
+
 ## 0.1.0-alpha.55
 
 ### Patch Changes

package/docs/changelog.md

@@ -6,6 +6,22 @@ The canonical source file in the repository is `CHANGELOG.md`.
 
 ## Unreleased
 
+## 0.1.0-alpha.56
+
+- Added `forge deploy init --target docker` as the canonical production Docker
+  bootstrap command.
+- Added `forge deploy readiness --production --json` to answer whether an app
+  can publish, what blocks production, and which command should run next.
+- Added `forge env doctor --target local|staging|production --json` for safe,
+  target-specific env source reporting without exposing secret values.
+- `forge deploy check --production --json` now includes grouped
+  blockers/warnings and a readiness summary for agent handoffs.
+- `forge deploy verify --production --url ... --json` now validates required
+  public auth metadata and optional operational endpoints.
+- Production docs now describe the canonical flow from deploy init through
+  field-test, readiness, package, and verify, with WorkOS FGA kept optional
+  unless the app opts into FGA artifacts.
+
 ## 0.1.0-alpha.55
 
 - `forge add auth workos` now defaults to AuthKit/RBAC, permission claims,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "forgeos",
-  "version": "0.1.0-alpha.55",
+  "version": "0.1.0-alpha.56",
   "description": "Agent-native application framework and compiler for building Forge apps without a mandatory dashboard.",
   "type": "module",
   "license": "MIT",

package/src/forge/_generated/releaseManifest.json

@@ -1 +1 @@
-{"defaultProvider":"local","diagnostics":[],"env":{"deployEnv":"FORGE_DEPLOY_ENV","deployId":"FORGE_DEPLOY_ID","publicReleaseId":"NEXT_PUBLIC_FORGE_RELEASE_ID","releaseId":"FORGE_RELEASE_ID"},"gitSha":"unknown","optionalProviders":["local","sentry-compatible","sentry","glitchtip","bugsink","otel","custom"],"packageName":"forgeos","packageVersion":"0.1.0-alpha.55","releaseId":"forgeos@0.1.0-alpha.55+unknown","schemaVersion":"0.1.0"}
+{"defaultProvider":"local","diagnostics":[],"env":{"deployEnv":"FORGE_DEPLOY_ENV","deployId":"FORGE_DEPLOY_ID","publicReleaseId":"NEXT_PUBLIC_FORGE_RELEASE_ID","releaseId":"FORGE_RELEASE_ID"},"gitSha":"unknown","optionalProviders":["local","sentry-compatible","sentry","glitchtip","bugsink","otel","custom"],"packageName":"forgeos","packageVersion":"0.1.0-alpha.56","releaseId":"forgeos@0.1.0-alpha.56+unknown","schemaVersion":"0.1.0"}

package/src/forge/_generated/releaseManifest.ts

@@ -1,4 +1,4 @@
-// @forge-generated generator=0.1.0-alpha.55 input=bbd63535f88ad4d382f6da1f26a2898e49fa00849042fcd683e316054e3b3959 content=c6fc38ddd436db8a660ed2e37713bc2d76c3d305cd1ebcb207de25ac1830b307
+// @forge-generated generator=0.1.0-alpha.56 input=a013874c7856b533aae64f467111c45bd707703fd9db6f0b8115898afc97af53 content=a9688092f903ceb0263f9581e3ab71ecc968284ffd530d9112a5467ea10baf63
 export const releaseManifest = {
   "defaultProvider": "local",
   "diagnostics": [],
@@ -19,7 +19,7 @@ export const releaseManifest = {
     "custom"
   ],
   "packageName": "forgeos",
-  "packageVersion": "0.1.0-alpha.55",
-  "releaseId": "forgeos@0.1.0-alpha.55+unknown",
+  "packageVersion": "0.1.0-alpha.56",
+  "releaseId": "forgeos@0.1.0-alpha.56+unknown",
   "schemaVersion": "0.1.0"
 } as const;

package/src/forge/cli/commands.ts

@@ -2863,6 +2863,7 @@ export async function executeCommand(command: ForgeCommand): Promise<number> {
         workspaceRoot: command.workspaceRoot,
         json: command.json,
         redacted: command.redacted,
+        target: command.target,
       });
 
       if (command.json) {

package/src/forge/cli/deploy.ts

@@ -13,7 +13,7 @@ import { runAuthCommand } from "./auth.ts";
 import { runAuthMdCommand } from "./authmd.ts";
 import { runWorkOSCommand } from "./workos.ts";
 
-export type DeploySubcommand = "plan" | "check" | "render" | "package" | "verify";
+export type DeploySubcommand = "plan" | "init" | "check" | "readiness" | "render" | "package" | "verify";
 export type DeployTarget = "docker" | "forge-cloud";
 
 export interface DeployCommandOptions {
@@ -42,6 +42,8 @@ export interface DeployCommandResult {
   target: DeployTarget;
   production: boolean;
   checks: DeployCheck[];
+  blocking?: string[];
+  warnings?: string[];
   files?: string[];
   plan?: {
     summary: string;
@@ -50,6 +52,7 @@ export interface DeployCommandResult {
     notes: string[];
   };
   probes?: Array<{ method: string; url: string; ok: boolean; status?: number; contentType?: string; error?: string; jsonValid?: boolean }>;
+  readiness?: DeployReadinessSummary;
   nextActions: string[];
   exitCode: 0 | 1;
 }
@@ -57,6 +60,27 @@ export interface DeployCommandResult {
 interface DeployProbeExpectation {
   contentTypeIncludes?: string;
   json?: boolean;
+  required?: boolean;
+}
+
+export interface DeployReadinessSummary {
+  score: number;
+  status: "ready" | "blocked" | "warning";
+  blocking: string[];
+  warnings: string[];
+  stages: Array<{
+    name: string;
+    ok: boolean;
+    score: number;
+    checks: string[];
+    blocking: string[];
+    warnings: string[];
+  }>;
+  answers: {
+    canPublish: boolean;
+    ifNotWhatIsMissing: string[];
+    nextCommand: string | null;
+  };
 }
 
 function readGeneratedJson<T>(workspaceRoot: string, relative: string): T | null {
@@ -93,6 +117,74 @@ function unique(values: string[]): string[] {
   return [...new Set(values)];
 }
 
+function deployStageForCheck(name: string): string {
+  if (["generated", "package-lockfile", "frontend-build-script"].includes(name)) return "build";
+  if (["database-url"].includes(name)) return "database";
+  if (name.startsWith("auth-") || ["production-auth-mode", "auth-issuer", "auth-audience", "auth-jwks", "tenant-claim"].includes(name)) return "auth";
+  if (name.startsWith("workos")) return "workos";
+  if (name.startsWith("auth-md") || name === "oauth-protected-resource") return "auth metadata";
+  if (name.startsWith("field-test")) return "field test";
+  if (name === "live-production") return "live/runtime";
+  if (name === "deploy-env-sources") return "environment";
+  return "production";
+}
+
+function summarizeDeployReadiness(checks: DeployCheck[], nextActions: string[]): DeployReadinessSummary {
+  const blocking = checks
+    .filter((check) => !check.ok && check.severity === "error")
+    .map((check) => `${check.name}: ${check.message}`);
+  const warnings = checks
+    .filter((check) => !check.ok && check.severity === "warning")
+    .map((check) => `${check.name}: ${check.message}`);
+  const stageNames = [
+    "build",
+    "environment",
+    "database",
+    "auth",
+    "workos",
+    "auth metadata",
+    "field test",
+    "live/runtime",
+    "production",
+  ];
+  const stages = stageNames
+    .map((stage) => {
+      const stageChecks = checks.filter((check) => deployStageForCheck(check.name) === stage);
+      const stageBlocking = stageChecks
+        .filter((check) => !check.ok && check.severity === "error")
+        .map((check) => `${check.name}: ${check.message}`);
+      const stageWarnings = stageChecks
+        .filter((check) => !check.ok && check.severity === "warning")
+        .map((check) => `${check.name}: ${check.message}`);
+      const passed = stageChecks.filter((check) => check.ok || check.severity === "warning").length;
+      const score = stageChecks.length === 0 ? 100 : Math.round((passed / stageChecks.length) * 100);
+      return {
+        name: stage,
+        ok: stageBlocking.length === 0,
+        score,
+        checks: stageChecks.map((check) => check.name),
+        blocking: stageBlocking,
+        warnings: stageWarnings,
+      };
+    })
+    .filter((stage) => stage.checks.length > 0);
+  const passed = checks.filter((check) => check.ok || check.severity === "warning").length;
+  const score = checks.length === 0 ? 100 : Math.round((passed / checks.length) * 100);
+  const canPublish = blocking.length === 0;
+  return {
+    score,
+    status: blocking.length > 0 ? "blocked" : warnings.length > 0 ? "warning" : "ready",
+    blocking,
+    warnings,
+    stages,
+    answers: {
+      canPublish,
+      ifNotWhatIsMissing: blocking,
+      nextCommand: canPublish ? "forge deploy verify --production --url https://app.example.com --json" : nextActions[0] ?? null,
+    },
+  };
+}
+
 function hasWorkOSIntegration(workspaceRoot: string): boolean {
   const secrets = new Set(requiredSecretNames(workspaceRoot));
   return secrets.has("WORKOS_API_KEY") ||
@@ -596,7 +688,7 @@ function databaseReadyCommand(options: DeployCommandOptions): string {
 function renderProductionReadme(): string {
   return `# ForgeOS Production Deploy
 
-This directory is generated by \`forge deploy package --target docker\`.
+This directory is generated by \`forge deploy init --target docker\` or \`forge deploy package --target docker\`.
 
 ## 1. Prepare production env
 
@@ -619,13 +711,17 @@ For WorkOS-backed apps, local dry-runs are not enough for production deploy
 readiness. Run:
 
 \`\`\`bash
+forge workos setup --real --file workos-seed.yml --json
 forge workos prove --real --file workos-seed.yml --json
 \`\`\`
 
-This applies or confirms hosted WorkOS config/seed through the WorkOS CLI and
-writes \`.workos-seed-state.json\`. \`forge deploy check --production\` requires
-that state to match the current \`workos-seed.yml\` before treating WorkOS
-posture as production evidence.
+This applies or confirms hosted redirect/CORS/webhook config and seed data
+through the WorkOS CLI and writes \`.workos-seed-state.json\`. \`forge deploy
+check --production\` requires that state to match the current \`workos-seed.yml\`
+before treating WorkOS posture as production evidence. WorkOS FGA is optional:
+most apps can ship with AuthKit, RBAC permission claims, Forge policies, and
+tenant isolation; use \`forge add auth workos --with-fga\` only when the app needs
+resource-level authorization outside normal role/permission checks.
 
 ## 2. Prove the app before traffic
 
@@ -633,9 +729,12 @@ posture as production evidence.
 forge generate --check --json
 forge check --json
 forge authmd generate --json
+forge env doctor --target production --json
 forge auth prove --scenario multi-tenant --json
+forge workos setup --real --file workos-seed.yml --json
 forge workos prove --real --file workos-seed.yml --json
 forge field-test run --realistic --json
+forge deploy readiness --production --json
 forge deploy check --production --json
 \`\`\`
 
@@ -654,7 +753,7 @@ forge auth prove --prod --token <jwt> --json
 forge deploy verify --production --url https://app.example.com --json
 \`\`\`
 
-\`forge auth prove --prod\` verifies a real JWT/OIDC token against the configured issuer/audience/JWKS. \`forge deploy verify --production\` probes \`GET /health\`, \`HEAD /auth.md\`, \`GET /auth.md\`, \`HEAD /.well-known/oauth-protected-resource\`, and \`GET /.well-known/oauth-protected-resource\`; it also validates auth metadata content-types and requires the OAuth protected-resource metadata body to be valid JSON.
+\`forge auth prove --prod\` verifies a real JWT/OIDC token against the configured issuer/audience/JWKS. \`forge deploy verify --production\` probes required endpoints \`GET /health\`, \`HEAD /auth.md\`, \`GET /auth.md\`, \`HEAD /.well-known/oauth-protected-resource\`, and \`GET /.well-known/oauth-protected-resource\`; it also validates auth metadata content-types and requires the OAuth protected-resource metadata body to be valid JSON. Optional probes check \`GET /ready\`, \`GET /live/status\`, \`GET /outbox/status\`, and \`HEAD /webhooks/workos\` when the app exposes those operational endpoints.
 `;
 }
 
@@ -669,10 +768,17 @@ function buildPlan(options: DeployCommandOptions): DeployCommandResult {
         "forge deploy verify --production --url https://<your-forge-cloud-app> --json",
       ]
     : [
-        "forge deploy package --target docker",
+        "forge deploy init --target docker",
         "cp deploy/.env.production.example deploy/.env.production",
-        "forge deploy check --production --json",
+        "forge authmd generate --json",
+        "forge env doctor --target production --json",
+        "forge auth prove --scenario multi-tenant --json",
+        "forge workos setup --real --file workos-seed.yml --json",
+        "forge workos prove --real --file workos-seed.yml --json",
         FIELD_TEST_PRODUCTION_COMMAND,
+        "forge deploy readiness --production --json",
+        "forge deploy check --production --json",
+        "forge deploy package --target docker",
         "docker compose -f deploy/docker-compose.yml up --build",
         "forge deploy verify --production --url https://app.example.com --json",
       ];
@@ -699,10 +805,12 @@ function buildPlan(options: DeployCommandOptions): DeployCommandResult {
         "field-test report exists with runtime/auth/UI probes",
         "runtime /health responds",
         "tenant and policy proof is run before public traffic",
+        "readiness score has no blocking items",
       ],
       notes: [
         "dev-headers auth is local-only and must not be enabled for public runtime.",
         "Use forge workos doctor/seed when WorkOS is configured.",
+        "WorkOS FGA is optional; ordinary WorkOS apps can be production-ready with AuthKit/RBAC permission claims, Forge policies, and tenant isolation.",
         "Use forge test authz or HTTP probes to prove cross-tenant denial.",
       ],
     },
@@ -971,6 +1079,10 @@ async function buildChecks(options: DeployCommandOptions): Promise<DeployCommand
   const failureActions = unique(checks.flatMap((check) =>
     !check.ok && check.command ? expandDeployFailureCommand(check.command) : []
   ));
+  const nextActions = errorFree
+    ? ["forge deploy verify --production --url https://app.example.com --json"]
+    : failureActions;
+  const readiness = summarizeDeployReadiness(checks, nextActions);
   return normalizeForgeCliCommandsInValue(options.workspaceRoot, {
     schemaVersion: "0.1.0",
     ok: errorFree,
@@ -979,9 +1091,10 @@ async function buildChecks(options: DeployCommandOptions): Promise<DeployCommand
     target: options.target,
     production: options.production,
     checks,
-    nextActions: errorFree
-      ? ["forge deploy verify --production --url https://app.example.com --json"]
-      : failureActions,
+    blocking: readiness.blocking,
+    warnings: readiness.warnings,
+    readiness,
+    nextActions,
     exitCode: errorFree ? 0 : 1,
   });
 }
@@ -1020,6 +1133,7 @@ function renderDocker(options: DeployCommandOptions): DeployCommandResult {
     files: files.map(([file]) => file),
     nextActions: [
       "cp deploy/.env.production.example deploy/.env.production",
+      "forge deploy readiness --production --json",
       "forge deploy check --production --json",
       "docker compose -f deploy/docker-compose.yml up --build",
     ],
@@ -1087,22 +1201,32 @@ async function verifyUrl(options: DeployCommandOptions): Promise<DeployCommandRe
       exitCode: 1,
     };
   }
-  const probes = await Promise.all([
-    probe("GET", `${base}/health`),
-    probe("HEAD", `${base}/auth.md`, { contentTypeIncludes: "text/markdown" }),
-    probe("GET", `${base}/auth.md`, { contentTypeIncludes: "text/markdown" }),
-    probe("HEAD", `${base}/.well-known/oauth-protected-resource`, { contentTypeIncludes: "application/json" }),
-    probe("GET", `${base}/.well-known/oauth-protected-resource`, { contentTypeIncludes: "application/json", json: true }),
-  ]);
+  const probeSpecs: Array<{ method: "GET" | "HEAD"; path: string; expectation?: DeployProbeExpectation }> = [
+    { method: "GET", path: "/health", expectation: { required: true } },
+    { method: "HEAD", path: "/auth.md", expectation: { contentTypeIncludes: "text/markdown", required: true } },
+    { method: "GET", path: "/auth.md", expectation: { contentTypeIncludes: "text/markdown", required: true } },
+    { method: "HEAD", path: "/.well-known/oauth-protected-resource", expectation: { contentTypeIncludes: "application/json", required: true } },
+    { method: "GET", path: "/.well-known/oauth-protected-resource", expectation: { contentTypeIncludes: "application/json", json: true, required: true } },
+    { method: "GET", path: "/ready", expectation: { contentTypeIncludes: "application/json" } },
+    { method: "GET", path: "/live/status", expectation: { contentTypeIncludes: "application/json" } },
+    { method: "GET", path: "/outbox/status", expectation: { contentTypeIncludes: "application/json" } },
+    { method: "HEAD", path: "/webhooks/workos" },
+  ];
+  const probes = await Promise.all(probeSpecs.map((item) =>
+    probe(item.method, `${base}${item.path}`, item.expectation ?? {})
+  ));
   const checks = probes.map((item): DeployCheck => ({
     name: `${item.method} ${item.url.replace(base, "") || "/"}`,
     ok: item.ok,
-    severity: item.url.endsWith("/health") || options.production ? "error" : "warning",
+    severity: probeSpecs.find((spec) => `${base}${spec.path}` === item.url && spec.method === item.method)?.expectation?.required || item.url.endsWith("/health")
+      ? "error"
+      : "warning",
     message: item.ok
       ? `HTTP ${item.status}${item.contentType ? ` ${item.contentType}` : ""}`
       : item.error ?? `HTTP ${item.status ?? "failed"}`,
   }));
   const ok = checks.every((check) => check.ok || check.severity === "warning");
+  const readiness = summarizeDeployReadiness(checks, ok ? [] : ["check runtime logs", "forge deploy check --production --json"]);
   return {
     schemaVersion: "0.1.0",
     ok,
@@ -1111,16 +1235,33 @@ async function verifyUrl(options: DeployCommandOptions): Promise<DeployCommandRe
     target: options.target,
     production: options.production,
     checks,
+    blocking: readiness.blocking,
+    warnings: readiness.warnings,
     probes,
-    nextActions: ok ? ["forge handoff --json"] : ["check runtime logs", "forge deploy check --production --json"],
+    readiness,
+    nextActions: ok
+      ? [
+          "forge auth prove --prod --token <jwt> --json",
+          "forge auth prove --scenario multi-tenant --json",
+          "forge handoff --json",
+        ]
+      : ["check runtime logs", "forge deploy check --production --json"],
     exitCode: ok ? 0 : 1,
   };
 }
 
 export async function runDeployCommand(options: DeployCommandOptions): Promise<DeployCommandResult> {
   if (options.subcommand === "plan") return buildPlan(options);
+  if (options.subcommand === "readiness") {
+    const result = await buildChecks({ ...options, subcommand: "check", production: true });
+    return {
+      ...result,
+      action: "readiness",
+      nextActions: result.readiness?.answers.nextCommand ? [result.readiness.answers.nextCommand] : result.nextActions,
+    };
+  }
   if (options.subcommand === "check") return buildChecks(options);
-  if (options.subcommand === "render" || options.subcommand === "package") return renderDocker(options);
+  if (options.subcommand === "init" || options.subcommand === "render" || options.subcommand === "package") return renderDocker(options);
   return verifyUrl(options);
 }
 
@@ -1132,7 +1273,13 @@ export function formatDeployHuman(result: DeployCommandResult): string {
   const lines = [
     `deploy ${result.action} ${result.ok ? "ok" : "failed"}`,
     `target: ${result.target}`,
+    ...(result.readiness ? [
+      `readiness: ${result.readiness.status} (${result.readiness.score}/100)`,
+      `can publish: ${result.readiness.answers.canPublish ? "yes" : "no"}`,
+    ] : []),
     ...result.checks.map((check) => `${check.ok ? "ok" : check.severity === "warning" ? "warn" : "fail"} ${check.name}: ${check.message}`),
+    ...(result.blocking?.length ? ["", "Blocking:", ...result.blocking.map((item) => `  ${item}`)] : []),
+    ...(result.warnings?.length ? ["", "Warnings:", ...result.warnings.map((item) => `  ${item}`)] : []),
     ...(result.files?.length ? ["", "Files:", ...result.files.map((file) => `  ${file}`)] : []),
     ...(result.plan ? ["", result.plan.summary, "", "Commands:", ...result.plan.commands.map((command) => `  ${command}`)] : []),
     ...(result.nextActions.length ? ["", "Next:", ...result.nextActions.map((action) => `  ${action}`)] : []),

package/src/forge/cli/main.ts

@@ -20,6 +20,9 @@ function formatHelp(): string {
     "  forge field-test create vendor-access --auth workos --install --git --json  Create a real field-test app",
     "  forge field-test run --realistic --templates vendor-access --package-managers npm --json",
     "  forge field-test report --json  Summarize the machine-readable field-test report",
+    "  forge deploy init --target docker --json  Generate Docker production files, env template, and deploy README",
+    "  forge deploy readiness --production --json  Answer whether the app can publish, what blocks it, and the next command",
+    "  forge env doctor --target production --json  Show production env sources, missing keys, auth mode, database, and provider",
     "  forge seed status --json  Discover app seed commands from the generated runtime graph",
     "  forge seed dev --json     Run the app seed command against the local Forge dev runtime",
     "  forge seed dev --all-tenants --json  Seed every discovered local tenant/persona profile",
@@ -51,7 +54,7 @@ function formatHelp(): string {
     "  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 package --target 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 deploy verify --production --url https://app.example.com --json  Probe health, public auth metadata, and optional runtime endpoints",
     "  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/parse.ts

@@ -418,6 +418,7 @@ export type ForgeCommand =
       subcommand: EnvSubcommand;
       json: boolean;
       redacted: boolean;
+      target?: "local" | "staging" | "production";
       workspaceRoot: string;
     }
   | {
@@ -602,7 +603,7 @@ const BASELINE_SUBCOMMANDS: BaselineSubcommand[] = ["create", "status"];
 const AUTHMD_SUBCOMMANDS: AuthMdSubcommand[] = ["generate", "check"];
 const WORKOS_SUBCOMMANDS: WorkOSSubcommand[] = ["install", "doctor", "seed", "setup", "prove", "fga"];
 const WORKOS_FGA_ACTIONS: WorkOSFgaAction[] = ["plan", "sync", "prove", "doctor"];
-const DEPLOY_SUBCOMMANDS: DeploySubcommand[] = ["plan", "check", "render", "package", "verify"];
+const DEPLOY_SUBCOMMANDS: DeploySubcommand[] = ["plan", "init", "check", "readiness", "render", "package", "verify"];
 const FIELD_TEST_SUBCOMMANDS: FieldTestSubcommand[] = ["create", "run", "report"];
 const SECURITY_SUBCOMMANDS: SecuritySubcommand[] = ["prove"];
 const RLS_SUBCOMMANDS: RlsSubcommand[] = ["generate", "check", "apply", "test", "mutate-test"];
@@ -1484,10 +1485,10 @@ export function parseCli(argv: string[]): ParsedCli {
     case "deploy": {
       const subcommand = rest[0] as DeploySubcommand | undefined;
       if (!subcommand || !DEPLOY_SUBCOMMANDS.includes(subcommand)) {
-        errors.push("forge deploy requires subcommand: plan, check, render, package, or verify");
+        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 === "render" || subcommand === "package" ? rest[1] : undefined) ?? "docker";
+      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");
       }
@@ -2974,10 +2975,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: {
@@ -2985,6 +2990,7 @@ export function parseCli(argv: string[]): ParsedCli {
           subcommand,
           json: parseFlag(argv, "--json"),
           redacted: parseFlag(argv, "--redacted"),
+          target: targetRaw as "local" | "staging" | "production",
           workspaceRoot,
         },
         workspaceRoot,

package/src/forge/cli/secrets.ts

@@ -219,13 +219,141 @@ export function formatSecretsJson(result: SecretsCommandResult): string {
   return `${JSON.stringify(result, null, 2)}\n`;
 }
 
-export type EnvSubcommand = "list" | "check" | "print";
+export type EnvSubcommand = "list" | "check" | "print" | "doctor";
+export type EnvDoctorTarget = "local" | "staging" | "production";
 
 export interface EnvCommandOptions {
   subcommand: EnvSubcommand;
   workspaceRoot: string;
   json: boolean;
   redacted?: boolean;
+  target?: EnvDoctorTarget;
+}
+
+const ENV_DOCTOR_KEYS = [
+  "DATABASE_URL",
+  "FORGE_AUTH_MODE",
+  "FORGE_AUTH_ISSUER",
+  "FORGE_AUTH_AUDIENCE",
+  "FORGE_AUTH_JWKS_URI",
+  "FORGE_AUTH_DISCOVERY_URL",
+  "WORKOS_API_KEY",
+  "WORKOS_CLIENT_ID",
+  "WORKOS_COOKIE_PASSWORD",
+  "WORKOS_REDIRECT_URI",
+  "WORKOS_POST_LOGIN_REDIRECT_URI",
+  "WORKOS_POST_LOGOUT_REDIRECT_URI",
+  "WORKOS_WEBHOOK_SECRET",
+] as const;
+
+function parseEnvFile(workspaceRoot: string, relative: string): Record<string, string> {
+  const path = join(workspaceRoot, relative);
+  if (!nodeFileSystem.exists(path)) return {};
+  const values: Record<string, string> = {};
+  for (const rawLine of (nodeFileSystem.readText(path) ?? "").split(/\r?\n/)) {
+    const line = rawLine.trim();
+    if (!line || line.startsWith("#")) continue;
+    const eq = line.indexOf("=");
+    if (eq <= 0) continue;
+    const rawValue = line.slice(eq + 1).trim();
+    values[line.slice(0, eq).trim()] = rawValue.replace(/^["']|["']$/g, "");
+  }
+  return values;
+}
+
+function envDoctorFiles(target: EnvDoctorTarget): string[] {
+  if (target === "production") return ["deploy/.env.production"];
+  if (target === "staging") return ["deploy/.env.staging", ".env.staging"];
+  return [".env", ".env.local"];
+}
+
+function hasWorkOSAppArtifacts(workspaceRoot: string): boolean {
+  return nodeFileSystem.exists(join(workspaceRoot, "workos-seed.yml")) ||
+    nodeFileSystem.exists(join(workspaceRoot, "src/policies.workos.ts")) ||
+    nodeFileSystem.exists(join(workspaceRoot, "src/forge/_generated/integrations/workos/auth-routes.ts"));
+}
+
+function envDoctor(options: EnvCommandOptions): SecretsCommandResult {
+  const target = options.target ?? "local";
+  const files = envDoctorFiles(target).map((path) => {
+    const values = parseEnvFile(options.workspaceRoot, path);
+    return {
+      path,
+      present: nodeFileSystem.exists(join(options.workspaceRoot, path)),
+      keys: Object.keys(values).filter((key) => ENV_DOCTOR_KEYS.includes(key as (typeof ENV_DOCTOR_KEYS)[number])).sort(),
+      values,
+    };
+  });
+  const processValues = Object.fromEntries(
+    ENV_DOCTOR_KEYS.filter((key) => Boolean(process.env[key])).map((key) => [key, process.env[key]!]),
+  );
+  const effective = {
+    ...Object.assign({}, ...files.map((file) => file.values)),
+    ...processValues,
+  } as Record<string, string>;
+  const required = target === "production"
+    ? ["DATABASE_URL", "FORGE_AUTH_MODE", "FORGE_AUTH_ISSUER", "FORGE_AUTH_AUDIENCE"]
+    : ["FORGE_AUTH_MODE"];
+  const missing = required.filter((key) => !effective[key]);
+  const authMode = effective.FORGE_AUTH_MODE ?? "dev-headers";
+  const productionAuth = authMode === "jwt" || authMode === "oidc";
+  const database = effective.DATABASE_URL
+    ? "postgres"
+    : target === "production"
+      ? "missing"
+      : "local-dev";
+  const workosDetected = hasWorkOSAppArtifacts(options.workspaceRoot) ||
+    Boolean(effective.WORKOS_CLIENT_ID || effective.WORKOS_API_KEY);
+  const provider = workosDetected ? "workos" : "none";
+  const hasJwtSource = Boolean(effective.FORGE_AUTH_JWKS_URI || effective.FORGE_AUTH_DISCOVERY_URL);
+  const blockers = [
+    ...missing.filter((key) => key !== "DATABASE_URL").map((key) => `${key} missing`),
+    ...(target === "production" && !productionAuth ? [`FORGE_AUTH_MODE=${authMode} is not production auth`] : []),
+    ...(target === "production" && database === "missing" ? ["DATABASE_URL missing"] : []),
+    ...(target === "production" && productionAuth && !hasJwtSource
+      ? ["FORGE_AUTH_JWKS_URI or FORGE_AUTH_DISCOVERY_URL missing"]
+      : []),
+    ...(target === "production" && workosDetected && !effective.WORKOS_CLIENT_ID ? ["WORKOS_CLIENT_ID missing"] : []),
+    ...(target === "production" && workosDetected && !effective.WORKOS_API_KEY ? ["WORKOS_API_KEY missing"] : []),
+  ];
+  const warnings = [
+    ...(target === "production" && files.every((file) => !file.present)
+      ? ["deploy/.env.production not found; process.env alone may be fine in CI but is easy for agents to miss"]
+      : []),
+    ...(workosDetected && !effective.WORKOS_COOKIE_PASSWORD ? ["WORKOS_COOKIE_PASSWORD missing"] : []),
+    ...(workosDetected && !effective.WORKOS_REDIRECT_URI ? ["WORKOS_REDIRECT_URI missing"] : []),
+  ];
+  return {
+    exitCode: blockers.length === 0 ? 0 : 1,
+    data: {
+      schemaVersion: "0.1.0",
+      kind: "env-doctor",
+      ok: blockers.length === 0,
+      target,
+      authMode,
+      productionAuth,
+      database,
+      provider,
+      sources: [
+        {
+          path: "process.env",
+          present: Object.keys(processValues).length > 0,
+          keys: Object.keys(processValues).sort(),
+          values: undefined,
+        },
+        ...files.map(({ path, present, keys }) => ({ path, present, keys })),
+      ],
+      present: ENV_DOCTOR_KEYS.filter((key) => Boolean(effective[key])).sort(),
+      missing,
+      blockers,
+      warnings,
+      nextActions: blockers.length === 0
+        ? ["forge deploy readiness --production --json"]
+        : target === "production"
+          ? ["cp deploy/.env.production.example deploy/.env.production", "forge env doctor --target production --json"]
+          : ["forge env doctor --target local --json"],
+    },
+  };
 }
 
 export async function runEnvCommand(options: EnvCommandOptions): Promise<SecretsCommandResult> {
@@ -233,6 +361,8 @@ export async function runEnvCommand(options: EnvCommandOptions): Promise<Secrets
   const schema = loadEnvSchema(options.workspaceRoot);
 
   switch (options.subcommand) {
+    case "doctor":
+      return envDoctor(options);
     case "list":
       if (!schema) {
         return {

package/src/forge/version.ts

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