forgeos 0.1.0-alpha.54 → 0.1.0-alpha.56

package/AGENTS.md

@@ -1,4 +1,4 @@
-// @forge-generated generator=0.1.0-alpha.54 input=7577a1a1a717ae3776c6725b005a98a36c149041f62ef4e28e098baad0bd1fcc 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,48 @@
 # 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
+
+- Make WorkOS FGA opt-in instead of part of the default auth adapter path.
+
+  - `forge add auth workos` now generates the AuthKit/RBAC/permission-claims
+    adapter, seed, policies, tenant claim mapping, webhook helpers, and React
+    bridge without WorkOS FGA resource helpers by default.
+  - `forge add auth workos --with-fga` keeps generating the optional WorkOS
+    Authorization/FGA resource graph helpers, `resource_types` seed metadata,
+    cache/telemetry helpers, and cross-tenant resource guard.
+  - `forge workos doctor` and `forge workos seed` now treat `resource_types`
+    and FGA state as optional unless the app has opted into FGA artifacts.
+  - `forge deploy check --production` no longer blocks ordinary WorkOS apps on
+    `workos-fga-proof`; it still requires FGA sync/proof when FGA helpers or
+    FGA state are present.
+
 ## 0.1.0-alpha.54
 
 ### Patch Changes

package/docs/changelog.md

@@ -6,6 +6,35 @@ 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,
+  Forge policies, tenant claim mapping, seed, webhooks, and frontend bridge
+  without generating WorkOS FGA resource helpers.
+- `forge add auth workos --with-fga` enables the optional WorkOS FGA resource
+  graph helpers and `resource_types` seed metadata for apps that need
+  resource-level authorization.
+- WorkOS doctor/seed/deploy checks now treat FGA as optional unless the app has
+  FGA artifacts or FGA state, so normal WorkOS apps are gated by AuthKit, RBAC,
+  hosted seed evidence, policies, and tenant proof instead of mandatory FGA
+  proof.
+
 ## 0.1.0-alpha.54
 
 - WorkOS FGA setup writes now produce a paired machine-readable

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "forgeos",
-  "version": "0.1.0-alpha.54",
+  "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.54","releaseId":"forgeos@0.1.0-alpha.54+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.54 input=7577a1a1a717ae3776c6725b005a98a36c149041f62ef4e28e098baad0bd1fcc content=7078de03fb1c3ae829b803fdfd1e9320fa10b8c128e51d374d8afab09cdc3df5
+// @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.54",
-  "releaseId": "forgeos@0.1.0-alpha.54+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") ||
@@ -101,6 +193,12 @@ function hasWorkOSIntegration(workspaceRoot: string): boolean {
     nodeFileSystem.exists(join(workspaceRoot, "src/policies.workos.ts"));
 }
 
+function hasWorkOSFgaIntegration(workspaceRoot: string): boolean {
+  return nodeFileSystem.exists(join(workspaceRoot, `${GENERATED_DIR}/integrations/workos/fga.ts`)) ||
+    nodeFileSystem.exists(join(workspaceRoot, `${GENERATED_DIR}/integrations/workos/resource-map.ts`)) ||
+    nodeFileSystem.exists(join(workspaceRoot, ".workos-fga-state.json"));
+}
+
 function readJsonFile<T>(workspaceRoot: string, relative: string): T | null {
   const absolute = join(workspaceRoot, relative);
   if (!nodeFileSystem.exists(absolute)) return null;
@@ -590,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
 
@@ -613,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
 
@@ -627,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
 \`\`\`
 
@@ -648,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.
 `;
 }
 
@@ -663,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",
       ];
@@ -693,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.",
       ],
     },
@@ -821,6 +935,7 @@ async function buildChecks(options: DeployCommandOptions): Promise<DeployCommand
     },
   });
   if (hasWorkOSIntegration(options.workspaceRoot)) {
+    const workosFgaEnabled = hasWorkOSFgaIntegration(options.workspaceRoot);
     const workosDoctor = await withDeployEnv(options.workspaceRoot, async () =>
       runWorkOSCommand({
         subcommand: "doctor",
@@ -835,7 +950,7 @@ async function buildChecks(options: DeployCommandOptions): Promise<DeployCommand
       ok: workosDoctor.exitCode === 0,
       severity: options.production ? "error" : "warning",
       message: workosDoctor.exitCode === 0
-        ? "WorkOS adapter files, seed, claims, policies, and FGA bridge are app-aware"
+        ? `WorkOS adapter files, seed, claims, policies, and tenant guards are app-aware${workosFgaEnabled ? " with FGA enabled" : ""}`
         : "WorkOS adapter is incomplete for this app; run forge workos doctor --json",
       command: "forge workos doctor --json",
       details: workosDoctor.checks,
@@ -855,27 +970,37 @@ async function buildChecks(options: DeployCommandOptions): Promise<DeployCommand
       command: "forge workos prove --real --file workos-seed.yml --json",
       details: seedState,
     });
-    const workosFgaDoctor = await withDeployEnv(options.workspaceRoot, async () =>
-      runWorkOSCommand({
-        subcommand: "fga",
-        fgaAction: "doctor",
-        workspaceRoot: options.workspaceRoot,
-        json: true,
-        yes: false,
-        dryRun: true,
-        real: options.production,
-      })
-    );
-    checks.push({
-      name: "workos-fga-proof",
-      ok: !options.production || workosFgaDoctor.exitCode === 0,
-      severity: options.production ? "error" : "warning",
-      message: workosFgaDoctor.exitCode === 0
-        ? "WorkOS FGA resource graph state matches the current app contract and seed"
-        : "WorkOS production deploy requires FGA graph sync/proof evidence matching the current app",
-      command: "forge workos fga prove --real --file workos-seed.yml --json",
-      details: workosFgaDoctor.data,
-    });
+    if (workosFgaEnabled) {
+      const workosFgaDoctor = await withDeployEnv(options.workspaceRoot, async () =>
+        runWorkOSCommand({
+          subcommand: "fga",
+          fgaAction: "doctor",
+          workspaceRoot: options.workspaceRoot,
+          json: true,
+          yes: false,
+          dryRun: true,
+          real: options.production,
+        })
+      );
+      checks.push({
+        name: "workos-fga-proof",
+        ok: !options.production || workosFgaDoctor.exitCode === 0,
+        severity: options.production ? "error" : "warning",
+        message: workosFgaDoctor.exitCode === 0
+          ? "WorkOS FGA resource graph state matches the current app contract and seed"
+          : "WorkOS production deploy requires FGA graph sync/proof evidence matching the current app because FGA helpers are enabled",
+        command: "forge workos fga prove --real --file workos-seed.yml --json",
+        details: workosFgaDoctor.data,
+      });
+    } else {
+      checks.push({
+        name: "workos-fga-optional",
+        ok: true,
+        severity: "warning",
+        message: "WorkOS FGA is not enabled; production deploy is gated by AuthKit, RBAC permission claims, Forge policies, tenant proof, and hosted seed evidence",
+        command: "forge add auth workos --with-fga",
+      });
+    }
   }
   const tenantProofRequired = auth.requiresTenant || hasWorkOSIntegration(options.workspaceRoot);
   const tenantProof = tenantProofRequired
@@ -954,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,
@@ -962,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,
   });
 }
@@ -1003,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",
     ],
@@ -1070,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,
@@ -1094,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);
 }
 
@@ -1115,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",
@@ -38,11 +41,12 @@ function formatHelp(): string {
     "  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 --json  Check WorkOS AuthKit/RBAC 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 --dry-run --json  Validate WorkOS seed without hosted changes",
-    "  forge workos prove --file workos-seed.yml --json  Prove local WorkOS/AuthKit/FGA/seed readiness without dashboard changes",
+    "  forge workos prove --file workos-seed.yml --json  Prove local WorkOS/AuthKit/RBAC/seed readiness without dashboard changes",
     "  forge workos setup --real --file workos-seed.yml --json  Apply redirect/CORS/homepage config and seed WorkOS without dashboard",
+    "  forge add auth workos --with-fga  Add optional WorkOS FGA resource-level authorization helpers",
     "  forge workos fga plan --json  Derive the WorkOS FGA resource graph and proof scenarios from the app",
     "  forge workos fga plan --write --json  Write .forge/workos-fga-setup.md for hosted FGA resource type setup",
     "  forge workos fga sync --json  Record an idempotent local FGA graph state for deploy gates",
@@ -50,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"];
@@ -822,6 +823,7 @@ 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,
@@ -1483,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");
       }
@@ -2973,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: {
@@ -2984,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,
@@ -3117,6 +3124,7 @@ export function hasUnknownOption(argv: string[]): string | null {
     "--with-livequery",
     "--with-react",
     "--with-ui",
+    "--with-fga",
     "--with-tests",
     "--with-create-form",
     "--write",

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/cli/workos.ts

@@ -85,6 +85,12 @@ function exists(root: string, path: string): boolean {
   return existsSync(join(root, path));
 }
 
+function hasWorkOSFgaArtifacts(root: string): boolean {
+  return exists(root, `${GENERATED_DIR}/integrations/workos/fga.ts`) ||
+    exists(root, `${GENERATED_DIR}/integrations/workos/resource-map.ts`) ||
+    exists(root, WORKOS_FGA_STATE_FILE);
+}
+
 function readJson(root: string, path: string): unknown | null {
   const absolute = join(root, path);
   if (!existsSync(absolute)) {
@@ -288,7 +294,6 @@ export function parseSeedFile(workspaceRoot: string, preferredPath = DEFAULT_SEE
 
   if (permissions.size === 0) diagnostics.push("no permission slugs found");
   if (roles.size === 0) diagnostics.push("no role slugs found");
-  if (resourceTypes.size === 0) diagnostics.push("no resource_types slugs found");
   if (organizations.size === 0) diagnostics.push("no organizations found");
 
   return {
@@ -1742,6 +1747,7 @@ function collectWorkOSChecks(workspaceRoot: string, preferredSeedPath = DEFAULT_
   const authRoutes = readText(workspaceRoot, `${GENERATED_DIR}/integrations/workos/auth-routes.ts`);
   const fga = readText(workspaceRoot, `${GENERATED_DIR}/integrations/workos/fga.ts`);
   const resourceMap = readText(workspaceRoot, `${GENERATED_DIR}/integrations/workos/resource-map.ts`);
+  const fgaEnabled = hasWorkOSFgaArtifacts(workspaceRoot);
   const httpHandler = readText(workspaceRoot, `${GENERATED_DIR}/integrations/workos/http-handler.ts`);
   const policies = readText(workspaceRoot, "src/policies.workos.ts");
   const session = readText(workspaceRoot, `${GENERATED_DIR}/integrations/workos/session.ts`);
@@ -1842,7 +1848,7 @@ function collectWorkOSChecks(workspaceRoot: string, preferredSeedPath = DEFAULT_
       name: "seed-file",
       ok: seed.exists,
       detail: seed.exists
-        ? `${seed.path} exists with ${seed.permissions.length} permission(s), ${seed.roles.length} role(s), ${seed.resourceTypes.length} resource type(s)`
+        ? `${seed.path} exists with ${seed.permissions.length} permission(s), ${seed.roles.length} role(s), ${seed.resourceTypes.length} optional FGA resource type(s)`
         : `${DEFAULT_SEED_FILE} or ${GENERATED_SEED_FILE} is required`,
     },
     {
@@ -1871,11 +1877,13 @@ function collectWorkOSChecks(workspaceRoot: string, preferredSeedPath = DEFAULT_
     },
     {
       name: "seed-resource-types",
-      ok: seed.resourceTypes.length > 0 &&
-        (expectedResourceTypes.length === 0 || missingSeedResources.length === 0),
-      detail: missingSeedResources.length === 0
-        ? `seed resource_types cover app graph: ${expectedResourceTypes.length > 0 ? expectedResourceTypes.join(", ") : seed.resourceTypes.join(", ")}`
-        : `seed missing resource_type(s) for app graph: ${missingSeedResources.join(", ")}`,
+      ok: !fgaEnabled || (seed.resourceTypes.length > 0 &&
+        (expectedResourceTypes.length === 0 || missingSeedResources.length === 0)),
+      detail: !fgaEnabled
+        ? "FGA is not enabled; resource_types are optional for AuthKit/RBAC apps"
+        : missingSeedResources.length === 0
+          ? `seed resource_types cover app graph: ${expectedResourceTypes.length > 0 ? expectedResourceTypes.join(", ") : seed.resourceTypes.join(", ")}`
+          : `seed missing resource_type(s) for app graph: ${missingSeedResources.join(", ")}`,
     },
     {
       name: "seed-auth-config",
@@ -1897,21 +1905,25 @@ function collectWorkOSChecks(workspaceRoot: string, preferredSeedPath = DEFAULT_
     },
     {
       name: "fga-plan",
-      ok: fgaManifest.diagnostics.length === 0,
-      detail: fgaManifest.diagnostics.length === 0
-        ? `FGA plan covers ${fgaManifest.resourceTypes.length} resource type(s), ${fgaManifest.resources.length} resource(s), and ${fgaManifest.proofScenarios.length} proof scenario(s)`
-        : `FGA plan has gap(s): ${fgaManifest.diagnostics.join("; ")}`,
+      ok: !fgaEnabled || fgaManifest.diagnostics.length === 0,
+      detail: !fgaEnabled
+        ? "FGA is not enabled; run forge add auth workos --with-fga for resource-level WorkOS Authorization"
+        : fgaManifest.diagnostics.length === 0
+          ? `FGA plan covers ${fgaManifest.resourceTypes.length} resource type(s), ${fgaManifest.resources.length} resource(s), and ${fgaManifest.proofScenarios.length} proof scenario(s)`
+          : `FGA plan has gap(s): ${fgaManifest.diagnostics.join("; ")}`,
     },
     {
       name: "fga-state",
       ok: true,
-      detail: !fgaState.exists
-        ? `${WORKOS_FGA_STATE_FILE} not found; run forge workos fga sync --json before production deploy`
-        : fgaState.matchesManifestHash
-          ? `${WORKOS_FGA_STATE_FILE} matches current FGA manifest${fgaState.mode === "real" ? " in real mode" : ""}`
-          : fgaState.valid
-            ? `${WORKOS_FGA_STATE_FILE} exists but does not match current FGA manifest; rerun forge workos fga sync --json`
-            : `${WORKOS_FGA_STATE_FILE} exists but is invalid: ${fgaState.diagnostics.join("; ")}`,
+      detail: !fgaEnabled
+        ? "FGA is not enabled; no FGA state file is required"
+        : !fgaState.exists
+          ? `${WORKOS_FGA_STATE_FILE} not found; run forge workos fga sync --json before production deploy`
+          : fgaState.matchesManifestHash
+            ? `${WORKOS_FGA_STATE_FILE} matches current FGA manifest${fgaState.mode === "real" ? " in real mode" : ""}`
+            : fgaState.valid
+              ? `${WORKOS_FGA_STATE_FILE} exists but does not match current FGA manifest; rerun forge workos fga sync --json`
+              : `${WORKOS_FGA_STATE_FILE} exists but is invalid: ${fgaState.diagnostics.join("; ")}`,
     },
     {
       name: "authkit-routes",
@@ -1935,7 +1947,7 @@ function collectWorkOSChecks(workspaceRoot: string, preferredSeedPath = DEFAULT_
     },
     {
       name: "fga-bridge",
-      ok: includesAll(resourceMap, [
+      ok: !fgaEnabled || (includesAll(resourceMap, [
         "canWorkOS",
         "assertWorkOSResourceTenant",
         "FORGE_WORKOS_CROSS_TENANT_RESOURCE",
@@ -1945,8 +1957,10 @@ function collectWorkOSChecks(workspaceRoot: string, preferredSeedPath = DEFAULT_
         "permissionSlug",
         "resourceExternalId",
       ]) &&
-        includesAll(fga, ["forgeWorkOSResourceTypes"]),
-      detail: "WorkOS FGA resource-map bridge exists with sync, cache, telemetry, official check shape, and cross-tenant guard",
+        includesAll(fga, ["forgeWorkOSResourceTypes"])),
+      detail: fgaEnabled
+        ? "WorkOS FGA resource-map bridge exists with sync, cache, telemetry, official check shape, and cross-tenant guard"
+        : "FGA bridge is optional and not enabled for this WorkOS AuthKit/RBAC app",
     },
     {
       name: "policies",
@@ -2276,6 +2290,7 @@ export function runWorkOSSeedCommand(options: WorkOSCommandOptions): WorkOSComma
   const missingSeedPermissions = missingValues(activePermissions, seed.permissions);
   const missingSeedResources = missingValues(expectedResourceTypes, seed.resourceTypes);
   const unusedSeedPermissions = seed.permissions.filter((permission) => !activePermissions.includes(permission));
+  const fgaEnabled = hasWorkOSFgaArtifacts(options.workspaceRoot);
   const checks = [
     {
       name: "seed-file",
@@ -2285,7 +2300,9 @@ export function runWorkOSSeedCommand(options: WorkOSCommandOptions): WorkOSComma
     {
       name: "seed-yaml-shape",
       ok: seed.valid,
-      detail: seed.valid ? "seed contains permissions, roles, resource_types, and organizations" : seed.diagnostics.join("; "),
+      detail: seed.valid
+        ? `seed contains permissions, roles, organizations${seed.resourceTypes.length > 0 ? ", and optional FGA resource_types" : ""}`
+        : seed.diagnostics.join("; "),
     },
     {
       name: "seed-policy-coverage",
@@ -2305,10 +2322,12 @@ export function runWorkOSSeedCommand(options: WorkOSCommandOptions): WorkOSComma
     },
     {
       name: "seed-resource-coverage",
-      ok: missingSeedResources.length === 0,
-      detail: missingSeedResources.length === 0
-        ? `seed covers app resource type(s): ${expectedResourceTypes.join(", ") || "none required"}`
-        : `seed missing resource type(s): ${missingSeedResources.join(", ")}`,
+      ok: !fgaEnabled || missingSeedResources.length === 0,
+      detail: !fgaEnabled
+        ? "FGA is not enabled; seed resource type coverage is not required"
+        : missingSeedResources.length === 0
+          ? `seed covers app resource type(s): ${expectedResourceTypes.join(", ") || "none required"}`
+          : `seed missing resource type(s): ${missingSeedResources.join(", ")}`,
     },
     {
       name: "seed-hosted-config",

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

@@ -3,6 +3,7 @@ import { nodeFileSystem } from "../fs/index.ts";
 import type { AddOptions } from "../types/cli.ts";
 import type { Diagnostic } from "../types/diagnostic.ts";
 import type { Dependency } from "../types/package-graph.ts";
+import type { IntegrationRecipe } from "../types/integration.ts";
 import type { ClassifiedPackage } from "../classifier/runtime-matrix.ts";
 import { buildAppGraph } from "../app-graph/build.ts";
 import { classify } from "../classifier/classify.ts";
@@ -79,7 +80,7 @@ export interface ForgeAddResult {
   failureKind?: string;
 }
 
-function recipeResultMetadata(recipe: NonNullable<ReturnType<typeof resolveRecipe>>): Pick<
+function recipeResultMetadata(recipe: IntegrationRecipe): Pick<
   ForgeAddResult,
   "recipeVersion" | "recipePackages" | "requiredSecrets" | "optionalSecrets"
 > {
@@ -91,6 +92,24 @@ function recipeResultMetadata(recipe: NonNullable<ReturnType<typeof resolveRecip
   };
 }
 
+const WORKOS_FGA_INTEGRATION_FILES = new Set([
+  "workos/fga.ts",
+  "workos/resource-map.ts",
+]);
+
+function applyWorkOSRecipeProfile(
+  recipe: NonNullable<ReturnType<typeof resolveRecipe>>,
+  options: Pick<ForgeAddOptions, "withFga">,
+): IntegrationRecipe {
+  if (recipe.alias !== "workos" || options.withFga) {
+    return recipe;
+  }
+  return {
+    ...recipe,
+    integrations: recipe.integrations?.filter((file) => !WORKOS_FGA_INTEGRATION_FILES.has(file)),
+  };
+}
+
 function addExplanation(result: ForgeAddResult): string {
   if (result.mode === "package") {
     const location = result.target && result.target !== "root" ? `${result.target}/package.json` : "package.json";
@@ -726,7 +745,7 @@ function connectWorkOSReactRoot(workspaceRoot: string, frontendWorkspace: string
 }
 
 async function analyzeRecipePackages(
-  recipe: NonNullable<ReturnType<typeof resolveRecipe>>,
+  recipe: IntegrationRecipe,
   ctx: ReturnType<typeof discover>,
   installRoot: string,
   options: ForgeAddOptions,
@@ -783,7 +802,7 @@ async function analyzeRecipePackages(
 
 async function buildAddPlan(
   alias: string,
-  recipe: NonNullable<ReturnType<typeof resolveRecipe>>,
+  recipe: IntegrationRecipe,
   ctx: ReturnType<typeof discover>,
   installRoot: string,
   options: ForgeAddOptions,
@@ -945,6 +964,8 @@ export async function forgeAdd(
     });
   }
 
+  const effectiveRecipe = applyWorkOSRecipeProfile(recipe, effectiveOptions);
+
   const pm =
     options.pmAdapter ??
     detectAndCreatePackageManagerAdapter(options.workspaceRoot);
@@ -955,7 +976,7 @@ export async function forgeAdd(
 
     try {
       const dryRun = await pm.dryRunAddWithPath(
-        recipe.packages.map((pkg) => pkg.packageName).join(" "),
+        effectiveRecipe.packages.map((pkg) => pkg.packageName).join(" "),
         {
           cwd: options.workspaceRoot,
           ignoreScripts: !options.allowScripts,
@@ -966,7 +987,7 @@ export async function forgeAdd(
       const fallback = dryRunRecipeFallbackMessage(normalized);
       const { emitPlan, warnings, errors } = await buildAddPlan(
         normalized,
-        recipe,
+        effectiveRecipe,
         ctx,
         installRoot,
         effectiveOptions,
@@ -982,7 +1003,7 @@ export async function forgeAdd(
       return finalizeAddResult({
         alias: normalized,
         mode: "integration",
-        ...recipeResultMetadata(recipe),
+        ...recipeResultMetadata(effectiveRecipe),
         changed: [...emitPlan.files.map((file) => file.path), "forge.lock"],
         unchanged: [],
         warnings,
@@ -994,7 +1015,7 @@ export async function forgeAdd(
 
     const { emitPlan, warnings, errors } = await buildAddPlan(
       normalized,
-      recipe,
+      effectiveRecipe,
       ctx,
       installRoot,
       effectiveOptions,
@@ -1003,7 +1024,7 @@ export async function forgeAdd(
     return finalizeAddResult({
       alias: normalized,
       mode: "integration",
-      ...recipeResultMetadata(recipe),
+      ...recipeResultMetadata(effectiveRecipe),
       changed: [...emitPlan.files.map((file) => file.path), "forge.lock"],
       unchanged: [],
       warnings,
@@ -1023,7 +1044,7 @@ export async function forgeAdd(
       frontendWorkspace ? [packageJsonRelativeFor(frontendWorkspace)] : [],
     );
     const preinstalledWarnings: Diagnostic[] = [];
-    for (const pkg of recipe.packages) {
+    for (const pkg of effectiveRecipe.packages) {
       const rootPackageJson = join(options.workspaceRoot, "package.json");
       await addPackageOrContinueIfInstalled({
         pm,
@@ -1055,7 +1076,7 @@ export async function forgeAdd(
     const ctx = discover({ workspaceRoot: options.workspaceRoot });
     const { emitPlan, warnings, errors: analyzeErrors } = await buildAddPlan(
       normalized,
-      recipe,
+      effectiveRecipe,
       ctx,
       options.workspaceRoot,
       options,
@@ -1066,7 +1087,7 @@ export async function forgeAdd(
       return finalizeAddResult({
         alias: normalized,
         mode: "integration",
-        ...recipeResultMetadata(recipe),
+        ...recipeResultMetadata(effectiveRecipe),
         changed: [],
         unchanged: [],
         warnings,
@@ -1093,7 +1114,7 @@ export async function forgeAdd(
       return finalizeAddResult({
         alias: normalized,
         mode: "integration",
-        ...recipeResultMetadata(recipe),
+        ...recipeResultMetadata(effectiveRecipe),
         changed: [],
         unchanged: [],
         warnings: warningsCombined,
@@ -1112,7 +1133,7 @@ export async function forgeAdd(
       return finalizeAddResult({
         alias: normalized,
         mode: "integration",
-        ...recipeResultMetadata(recipe),
+        ...recipeResultMetadata(effectiveRecipe),
         changed: [],
         unchanged: [],
         warnings: warningsCombined,
@@ -1148,7 +1169,7 @@ export async function forgeAdd(
     return finalizeAddResult({
       alias: normalized,
       mode: "integration",
-      ...recipeResultMetadata(recipe),
+      ...recipeResultMetadata(effectiveRecipe),
       changed: [
         ...changedPackageManagerFiles(options.workspaceRoot, packageManagerBefore),
         ...emitResult.changed,
@@ -1178,7 +1199,7 @@ export async function forgeAdd(
     return finalizeAddResult({
       alias: normalized,
       mode: "integration",
-      ...recipeResultMetadata(recipe),
+      ...recipeResultMetadata(effectiveRecipe),
       changed: [],
       unchanged: [],
       warnings: [],

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

@@ -125,6 +125,13 @@ function rolePermissions(permissions: string[]): Record<string, string[]> {
   };
 }
 
+function workosFgaEnabled(input: IntegrationTemplateInput): boolean {
+  return Boolean(
+    input.recipe.integrations?.includes("workos/fga.ts") ||
+      input.recipe.integrations?.includes("workos/resource-map.ts"),
+  );
+}
+
 export function renderWorkosServerAdapter(_input: IntegrationTemplateInput): string {
   return [
     "/** Forge generated WorkOS server adapter — action/workflow/endpoint/server contexts only. */",
@@ -1059,7 +1066,18 @@ export function renderWorkosSeed(_input: IntegrationTemplateInput): string {
 export function renderWorkosSeedYaml(input: IntegrationTemplateInput): string {
   const permissions = permissionsFromApp(input);
   const roles = rolePermissions(permissions);
-  const resourceTypes = resourceTypesFromApp(input);
+  const resourceTypes = workosFgaEnabled(input) ? resourceTypesFromApp(input) : [];
+  const resourceTypeSection = resourceTypes.length > 0
+    ? [
+        "",
+        "resource_types:",
+        ...resourceTypes.flatMap((resource) => [
+          `  - slug: '${resource.slug}'`,
+          `    name: '${resource.name}'`,
+          ...(resource.parent ? [`    parent: '${resource.parent}'`] : []),
+        ]),
+      ]
+    : [];
   return [
     "# Forge generated WorkOS seed file.",
     "# Review names, domains, redirect URIs, and origins before applying to a real WorkOS environment.",
@@ -1068,13 +1086,7 @@ export function renderWorkosSeedYaml(input: IntegrationTemplateInput): string {
       `  - name: '${toTitle(permission)}'`,
       `    slug: '${permission}'`,
     ]),
-    "",
-    "resource_types:",
-    ...resourceTypes.flatMap((resource) => [
-      `  - slug: '${resource.slug}'`,
-      `    name: '${resource.name}'`,
-      ...(resource.parent ? [`    parent: '${resource.parent}'`] : []),
-    ]),
+    ...resourceTypeSection,
     "",
     "roles:",
     ...Object.entries(roles).flatMap(([role, rolePermissions]) => [
@@ -1210,6 +1222,34 @@ export function renderWorkosTestkit(input: IntegrationTemplateInput): string {
 }
 
 export function renderWorkosDoc(input: IntegrationTemplateInput): string {
+  const fgaEnabled = workosFgaEnabled(input);
+  const fgaCommandLines = fgaEnabled
+    ? [
+        "forge workos fga plan --file workos-seed.yml --write --json",
+        "forge workos fga sync --file workos-seed.yml --json",
+        "forge workos fga prove --file workos-seed.yml --json",
+      ]
+    : [
+        "# Optional when resource-level WorkOS Authorization is required:",
+        "forge add auth workos --with-fga",
+      ];
+  const fgaSection = fgaEnabled
+    ? [
+        "## FGA strategy",
+        "",
+        "Use JWT permissions for organization-wide checks. Use the WorkOS Authorization API for resource-level checks such as project, workspace, or task access. Keep those API calls in actions, workflows, endpoints, or server code; commands and queries should consume validated auth/policy context rather than importing the WorkOS SDK.",
+        "",
+        "Use `syncWorkOSResourceGraph(...)` after app resources are created or renamed to mirror the Forge resource graph into WorkOS FGA resources. Use `canWorkOS(...)` with `ForgeWorkOSFgaDecisionCache` for resource-level checks; it calls WorkOS `authorization.check` with `organizationMembershipId`, `permissionSlug`, `resourceTypeSlug`, and `resourceExternalId`, emits optional telemetry, and denies by default on provider errors unless `fallback: \"throw\"` is set.",
+        "",
+        "Use `assertWorkOSResourceTenant(...)` before resource-level FGA checks whenever the resource came from user input or an external id. This keeps Acme resources from being checked under Globex membership context.",
+      ]
+    : [
+        "## Authorization strategy",
+        "",
+        "The default WorkOS recipe uses AuthKit, organization claims, roles, permissions, Forge policies, and tenant isolation. That is enough for most SaaS apps.",
+        "",
+        "FGA is optional. Add it only when your app needs resource-level authorization beyond organization roles and permission claims, for example per-project, per-document, or inherited resource access.",
+      ];
   return [
     "# WorkOS integration",
     "",
@@ -1222,7 +1262,8 @@ export function renderWorkosDoc(input: IntegrationTemplateInput): string {
     "- Installs `@workos-inc/node` for server/action/workflow/endpoint code.",
     "- Installs `@workos-inc/authkit-react` and generates a Vite React bridge when a `web/package.json` workspace exists.",
     "- Registers WorkOS secret names without storing values.",
-    "- Generates an AuthKit/FGA checklist and a `workos-seed.yml` for roles, permissions, organizations, redirect URIs, and CORS origins.",
+    "- Generates an AuthKit/RBAC checklist and a `workos-seed.yml` for roles, permissions, organizations, redirect URIs, and CORS origins.",
+    ...(fgaEnabled ? ["- Generates optional WorkOS FGA resource graph helpers and resource type seed metadata."] : []),
     "- Generates framework-agnostic AuthKit route/session helpers for `/login`, `/callback`, `/logout`, and `/session`.",
     "- Generates a framework-agnostic `Request -> Response` webhook handler for `POST /webhooks/workos`.",
     "- Marks WorkOS SDK imports as forbidden from commands, queries, liveQueries, client, shared, and edge code.",
@@ -1238,6 +1279,7 @@ export function renderWorkosDoc(input: IntegrationTemplateInput): string {
     "forge workos seed --file workos-seed.yml --json",
     "forge workos prove --file workos-seed.yml --json",
     "forge workos setup --real --file workos-seed.yml --json",
+    ...fgaCommandLines,
     "forge auth check --json",
     "forge auth prove --json",
     "forge check --json",
@@ -1270,13 +1312,7 @@ export function renderWorkosDoc(input: IntegrationTemplateInput): string {
     "",
     "Mount `handleWorkOSAuthRequest(request, { workos, config, resolveOrganization })` for `/login`, `/callback`, `/logout`, and `/session`. The callback exchanges the AuthKit authorization code, signs an HttpOnly session cookie, and exposes Forge-normalized claims through `/session`.",
     "",
-    "## FGA strategy",
-    "",
-    "Use JWT permissions for organization-wide checks. Use the WorkOS Authorization API for resource-level checks such as project, workspace, or task access. Keep those API calls in actions, workflows, endpoints, or server code; commands and queries should consume validated auth/policy context rather than importing the WorkOS SDK.",
-    "",
-    "Use `syncWorkOSResourceGraph(...)` after app resources are created or renamed to mirror the Forge resource graph into WorkOS FGA resources. Use `canWorkOS(...)` with `ForgeWorkOSFgaDecisionCache` for resource-level checks; it calls WorkOS `authorization.check` with `organizationMembershipId`, `permissionSlug`, `resourceTypeSlug`, and `resourceExternalId`, emits optional telemetry, and denies by default on provider errors unless `fallback: \"throw\"` is set.",
-    "",
-    "Use `assertWorkOSResourceTenant(...)` before resource-level FGA checks whenever the resource came from user input or an external id. This keeps Acme resources from being checked under Globex membership context.",
+    ...fgaSection,
     "",
     "## Webhook route",
     "",

package/src/forge/compiler/types/cli.ts

@@ -63,6 +63,7 @@ export interface AddOptions extends CliCommonOptions {
   runtimeInspect: boolean;
   sandboxBackend: SandboxBackend;
   allowScripts: boolean;
+  withFga?: boolean;
   mode?: "auto" | "integration" | "package";
   installWorkspace?: string;
   packageTarget?: "frontend" | "backend";

package/src/forge/version.ts

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