forgeos 0.1.0-alpha.50 → 0.1.0-alpha.52

package/AGENTS.md

@@ -1,4 +1,4 @@
-// @forge-generated generator=0.1.0-alpha.50 input=5f918b7dab43b47f2774c505897503c0b5ddc26d4022167410ed9f3b76190ee6 content=721818a6f9a664aa898092d4aa5cd68cbbd8ad6e150c7d3ad3ef785a2e3fcf53
+// @forge-generated generator=0.1.0-alpha.52 input=9a95853ed8e82db41be0b0cc4fc809e0b1c0c12fd1ac024d386bc651a70d965b content=721818a6f9a664aa898092d4aa5cd68cbbd8ad6e150c7d3ad3ef785a2e3fcf53
 # AGENTS.md
 
 <!-- forge-generated:start -->

package/CHANGELOG.md

@@ -1,5 +1,42 @@
 # forgeos
 
+## 0.1.0-alpha.52
+
+### Patch Changes
+
+- Make WorkOS FGA real-rollout failures produce a concrete operator artifact.
+
+  - Generated WorkOS FGA setup guides now include an explicit automation
+    boundary explaining that ForgeOS derives the graph, syncs resources, and
+    proves Authorization API checks, but does not invent unsupported WorkOS
+    resource-type creation commands.
+  - `forge workos fga sync --real --write --json` now remains useful when the
+    WorkOS Authorization API reports missing resource types: the JSON includes
+    `setupGuidePath` and the written guide lists the resource types, parents,
+    permissions, roles, example external IDs, membership env, and rerun
+    commands needed to finish the hosted setup.
+
+## 0.1.0-alpha.51
+
+### Patch Changes
+
+- Make the WorkOS FGA production doctor explicit enough for real P2 rollout.
+
+  - `forge workos fga doctor --real --json` now reports structured readiness
+    for the full hosted path: FGA plan, hosted seed evidence, hosted resource
+    type/resource sync, `organizationMembershipId` env, real proof state, and
+    production readiness.
+  - FGA JSON output now includes `membershipEnv`, `seedState`, and `readiness`
+    metadata so agents can choose the next command without scraping human text.
+  - Hosted FGA setup data now states that WorkOS resource type creation is not
+    automated by the WorkOS API/CLI path, while resource sync and authorization
+    checks remain ForgeOS-driven after those resource types exist.
+  - WorkOS real checks now read `deploy/.env.production` as an explicit deploy
+    evidence source, and `forge deploy check --production` runs WorkOS/FGA
+    doctors with those values in scope.
+  - Human output now distinguishes local FGA planning success from real
+    production-gate readiness.
+
 ## 0.1.0-alpha.50
 
 ### Patch Changes

package/docs/changelog.md

@@ -6,6 +6,33 @@ The canonical source file in the repository is `CHANGELOG.md`.
 
 ## Unreleased
 
+## 0.1.0-alpha.52
+
+- Generated WorkOS FGA setup guides now include an explicit automation boundary
+  describing what ForgeOS can automate versus the hosted WorkOS resource-type
+  configuration that must exist before real resource sync.
+- `forge workos fga sync --real --write --json` now provides a concrete
+  `setupGuidePath` even when real sync fails because hosted WorkOS resource
+  types are missing, so agents have a deterministic artifact for the remaining
+  setup and rerun commands.
+
+## 0.1.0-alpha.51
+
+- `forge workos fga doctor --real --json` now reports a structured readiness
+  object for the full hosted FGA path: app-derived plan, hosted seed state,
+  real resource sync, membership env for WorkOS access checks, proof state, and
+  production readiness.
+- FGA command JSON now includes `membershipEnv`, `seedState`, and `readiness`
+  metadata so agents can continue the no-dashboard WorkOS flow deterministically.
+- Hosted FGA setup output now explicitly states that WorkOS resource type
+  creation is hosted WorkOS configuration, while ForgeOS can still sync
+  resources and run Authorization API checks after those types exist.
+- WorkOS real checks now read `deploy/.env.production` as deploy evidence, and
+  `forge deploy check --production` runs WorkOS/FGA doctors with those values
+  in scope.
+- Human FGA output now separates local planning success from real production
+  gate readiness.
+
 ## 0.1.0-alpha.50
 
 - WorkOS hosted setup now includes explicit

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "forgeos",
-  "version": "0.1.0-alpha.50",
+  "version": "0.1.0-alpha.52",
   "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.50","releaseId":"forgeos@0.1.0-alpha.50+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.52","releaseId":"forgeos@0.1.0-alpha.52+unknown","schemaVersion":"0.1.0"}

package/src/forge/_generated/releaseManifest.ts

@@ -1,4 +1,4 @@
-// @forge-generated generator=0.1.0-alpha.50 input=5f918b7dab43b47f2774c505897503c0b5ddc26d4022167410ed9f3b76190ee6 content=5bb2a5849e690e58325fbd495bd3b1ad63a42f77c8c1d06464b64c27f9192c6c
+// @forge-generated generator=0.1.0-alpha.52 input=9a95853ed8e82db41be0b0cc4fc809e0b1c0c12fd1ac024d386bc651a70d965b content=d4d4c9fd5f2fe5a5d3fa127d43487901cf1e68875b7ac99abdfe9a9cc90265ee
 export const releaseManifest = {
   "defaultProvider": "local",
   "diagnostics": [],
@@ -19,7 +19,7 @@ export const releaseManifest = {
     "custom"
   ],
   "packageName": "forgeos",
-  "packageVersion": "0.1.0-alpha.50",
-  "releaseId": "forgeos@0.1.0-alpha.50+unknown",
+  "packageVersion": "0.1.0-alpha.52",
+  "releaseId": "forgeos@0.1.0-alpha.52+unknown",
   "schemaVersion": "0.1.0"
 } as const;

package/src/forge/cli/deploy.ts

@@ -821,13 +821,15 @@ async function buildChecks(options: DeployCommandOptions): Promise<DeployCommand
     },
   });
   if (hasWorkOSIntegration(options.workspaceRoot)) {
-    const workosDoctor = runWorkOSCommand({
-      subcommand: "doctor",
-      workspaceRoot: options.workspaceRoot,
-      json: true,
-      yes: false,
-      dryRun: true,
-    });
+    const workosDoctor = await withDeployEnv(options.workspaceRoot, async () =>
+      runWorkOSCommand({
+        subcommand: "doctor",
+        workspaceRoot: options.workspaceRoot,
+        json: true,
+        yes: false,
+        dryRun: true,
+      })
+    );
     checks.push({
       name: "workos-doctor",
       ok: workosDoctor.exitCode === 0,
@@ -853,15 +855,17 @@ async function buildChecks(options: DeployCommandOptions): Promise<DeployCommand
       command: "forge workos prove --real --file workos-seed.yml --json",
       details: seedState,
     });
-    const workosFgaDoctor = runWorkOSCommand({
-      subcommand: "fga",
-      fgaAction: "doctor",
-      workspaceRoot: options.workspaceRoot,
-      json: true,
-      yes: false,
-      dryRun: true,
-      real: options.production,
-    });
+    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,

package/src/forge/cli/workos.ts

@@ -324,6 +324,7 @@ function parseEnvText(text: string): Record<string, string> {
 function readRealEnv(workspaceRoot: string): Record<string, string> {
   return {
     ...parseEnvText(readRawText(workspaceRoot, ".env")),
+    ...parseEnvText(readRawText(workspaceRoot, "deploy/.env.production")),
     ...parseEnvText(readRawText(workspaceRoot, ".env.local")),
     ...Object.fromEntries(
       Object.entries(process.env)
@@ -677,12 +678,21 @@ export interface WorkOSFgaStateSummary {
   diagnostics: string[];
 }
 
+export interface WorkOSFgaMembershipEnvSummary {
+  requiredEnv: string[];
+  presentEnv: string[];
+  missingEnv: string[];
+  jsonEnvPresent: boolean;
+  complete: boolean;
+}
+
 export interface WorkOSFgaHostedSetup {
   requiredResourceTypes: string[];
   rootResourceType: "organization";
   missingResourceTypes: string[];
   requiredMembershipEnv: string[];
   managedBy: "hosted-workos";
+  resourceTypeAutomation: "not-supported-by-workos-api" | "not-needed";
   cliSupport: "resources-and-checks";
   sdkSupport: "resources-and-checks";
   docs: string[];
@@ -710,6 +720,19 @@ export interface WorkOSFgaSetupGuide {
   unsupportedAutomation: string[];
 }
 
+export interface WorkOSFgaReadiness {
+  real: boolean;
+  planReady: boolean;
+  seedReady: boolean;
+  resourceTypesConfigured: boolean;
+  membershipEnvReady: boolean;
+  synced: boolean;
+  proved: boolean;
+  productionReady: boolean;
+  nextCommand: string;
+  nextActions: string[];
+}
+
 function slugifyExternalIdPart(value: string): string {
   return value
     .trim()
@@ -951,6 +974,24 @@ function fgaMembershipEnvKey(organization: string): string {
   return `WORKOS_FGA_MEMBERSHIP_${suffix}`;
 }
 
+function workOSFgaMembershipEnvSummary(
+  workspaceRoot: string,
+  organizations: string[],
+): WorkOSFgaMembershipEnvSummary {
+  const env = readRealEnv(workspaceRoot);
+  const requiredEnv = organizations.map(fgaMembershipEnvKey);
+  const jsonEnvPresent = hasValue(env, "WORKOS_FGA_MEMBERSHIPS_JSON") || hasValue(env, "WORKOS_FGA_TEST_MEMBERSHIPS");
+  const presentEnv = requiredEnv.filter((name) => hasValue(env, name));
+  const missingEnv = jsonEnvPresent ? [] : requiredEnv.filter((name) => !presentEnv.includes(name));
+  return {
+    requiredEnv,
+    presentEnv,
+    missingEnv,
+    jsonEnvPresent,
+    complete: jsonEnvPresent || missingEnv.length === 0,
+  };
+}
+
 function extractMissingWorkOSFgaResourceTypes(data: unknown, manifest?: WorkOSFgaManifest): string[] {
   const missing = new Set<string>();
   const add = (value: unknown) => {
@@ -999,6 +1040,7 @@ function workOSFgaHostedSetup(manifest: WorkOSFgaManifest, sdkData?: unknown): W
     missingResourceTypes,
     requiredMembershipEnv,
     managedBy: "hosted-workos",
+    resourceTypeAutomation: requiredResourceTypes.length > 0 ? "not-supported-by-workos-api" : "not-needed",
     cliSupport: "resources-and-checks",
     sdkSupport: "resources-and-checks",
     docs: [
@@ -1107,6 +1149,13 @@ function workOSFgaSetupGuide(manifest: WorkOSFgaManifest, hostedSetup: WorkOSFga
     "ForgeOS derived this resource graph from the app contract, policies, and workos-seed.yml.",
     "WorkOS resource type configuration is hosted WorkOS configuration. ForgeOS uses the WorkOS CLI/API or SDK to sync resources and prove authorization checks after those resource types exist.",
     "",
+    "## Automation Boundary",
+    "",
+    "- ForgeOS can derive the FGA graph, generate this setup guide, sync WorkOS FGA resources, and run Authorization API access checks.",
+    "- ForgeOS does not invent WorkOS CLI/API calls for resource type creation. The current public WorkOS automation surface supports resources and checks after resource types exist.",
+    "- Configure each non-organization resource type below in hosted WorkOS, then rerun the real sync/proof commands.",
+    "- The `organization` node is treated as the WorkOS tenant root and is not created as an authorization resource.",
+    "",
     "## Resource Types",
     "",
     ...resourceTypes.flatMap((resourceType) => [
@@ -1179,11 +1228,14 @@ function writeWorkOSFgaSetupGuide(
 
 function fgaData(input: {
   action: WorkOSFgaAction;
+  workspaceRoot: string;
   manifest: WorkOSFgaManifest;
   state: WorkOSFgaStateSummary;
+  seedState?: WorkOSSeedStateSummary;
   real?: boolean;
   cliAuth?: WorkOSCliAuthSummary;
   workosSdk?: unknown;
+  readiness?: WorkOSFgaReadiness;
   stateFile?: string;
   nextCommand?: string;
   nextActions?: string[];
@@ -1191,12 +1243,16 @@ function fgaData(input: {
 }): Record<string, unknown> {
   const hostedSetup = workOSFgaHostedSetup(input.manifest, input.workosSdk);
   const setupGuide = workOSFgaSetupGuide(input.manifest, hostedSetup);
+  const membershipEnv = workOSFgaMembershipEnvSummary(input.workspaceRoot, input.manifest.organizations);
   return {
     action: input.action,
     real: input.real ?? false,
     manifest: input.manifest,
     state: input.state,
+    ...(input.seedState ? { seedState: input.seedState } : {}),
+    ...(input.readiness ? { readiness: input.readiness } : {}),
     hostedSetup,
+    membershipEnv,
     resourceTypeSetup: setupGuide.resourceTypes,
     setupGuide,
     ...(input.cliAuth ? { cliAuth: input.cliAuth } : {}),
@@ -2573,6 +2629,133 @@ function collectWorkOSFgaChecks(input: {
   ];
 }
 
+function workOSFgaReadiness(input: {
+  workspaceRoot: string;
+  file: string;
+  manifest: WorkOSFgaManifest;
+  state: WorkOSFgaStateSummary;
+  seedState: WorkOSSeedStateSummary;
+  real: boolean;
+}): WorkOSFgaReadiness {
+  const membershipEnv = workOSFgaMembershipEnvSummary(input.workspaceRoot, input.manifest.organizations);
+  const planReady = input.manifest.diagnostics.length === 0 &&
+    input.manifest.resourceTypes.includes("organization") &&
+    input.manifest.proofScenarios.some((scenario) => scenario.expected === "allow") &&
+    input.manifest.proofScenarios.some((scenario) => scenario.expected === "deny");
+  const seedReady = !input.real || Boolean(input.seedState.exists && input.seedState.valid && input.seedState.matchesSeedHash === true);
+  const synced = Boolean(input.state.exists && input.state.valid && input.state.matchesManifestHash === true);
+  const resourceTypesConfigured = !input.real || Boolean(synced && input.state.mode === "real" && input.state.sdkOk === true);
+  const membershipEnvReady = !input.real || membershipEnv.complete;
+  const proved = !input.real
+    ? Boolean(input.state.provedAt)
+    : Boolean(synced && input.state.mode === "real" && input.state.sdkOk === true && input.state.provedAt);
+  const productionReady = Boolean(planReady && seedReady && resourceTypesConfigured && membershipEnvReady && proved);
+  let nextCommand = `forge workos fga plan --file ${input.file} --write --json`;
+  if (planReady && input.real && !seedReady) {
+    nextCommand = `forge workos prove --real --file ${input.file} --json`;
+  } else if (planReady && input.real && !resourceTypesConfigured) {
+    nextCommand = `forge workos fga sync --real --file ${input.file} --write --json`;
+  } else if (planReady && input.real && !membershipEnvReady) {
+    nextCommand = `forge workos fga prove --real --file ${input.file} --json`;
+  } else if (planReady && input.real && !proved) {
+    nextCommand = `forge workos fga prove --real --file ${input.file} --json`;
+  } else if (planReady && !input.real && !synced) {
+    nextCommand = `forge workos fga sync --file ${input.file} --json`;
+  } else if (planReady && !input.real && !proved) {
+    nextCommand = `forge workos fga prove --file ${input.file} --json`;
+  } else if (productionReady || (planReady && !input.real)) {
+    nextCommand = "forge deploy check --production --json";
+  }
+  const nextActions = [
+    ...(planReady ? [] : [`repair FGA manifest gaps, then run forge workos fga plan --file ${input.file} --write --json`]),
+    ...(input.real && !seedReady ? [`apply/prove hosted WorkOS seed: forge workos prove --real --file ${input.file} --json`] : []),
+    ...(input.real && !resourceTypesConfigured
+      ? [
+          "configure hosted WorkOS FGA resource types listed in resourceTypeSetup",
+          `sync real WorkOS FGA resources: forge workos fga sync --real --file ${input.file} --write --json`,
+        ]
+      : []),
+    ...(input.real && !membershipEnvReady
+      ? [`set WORKOS_FGA_MEMBERSHIPS_JSON or ${membershipEnv.missingEnv.join(", ") || "WORKOS_FGA_MEMBERSHIP_<ORG>"} before real access checks`]
+      : []),
+    ...(input.real && membershipEnvReady && resourceTypesConfigured && !proved
+      ? [`prove real WorkOS FGA access checks: forge workos fga prove --real --file ${input.file} --json`]
+      : []),
+    ...(productionReady ? ["rerun forge deploy check --production --json"] : []),
+    ...(!input.real && planReady && !synced ? [`run forge workos fga sync --file ${input.file} --json`] : []),
+    ...(!input.real && planReady && synced && !proved ? [`run forge workos fga prove --file ${input.file} --json`] : []),
+  ];
+  return {
+    real: input.real,
+    planReady,
+    seedReady,
+    resourceTypesConfigured,
+    membershipEnvReady,
+    synced,
+    proved,
+    productionReady,
+    nextCommand,
+    nextActions,
+  };
+}
+
+function collectWorkOSFgaDoctorChecks(input: {
+  workspaceRoot: string;
+  file: string;
+  manifest: WorkOSFgaManifest;
+  state: WorkOSFgaStateSummary;
+  seedState: WorkOSSeedStateSummary;
+  real: boolean;
+}): WorkOSCheck[] {
+  const readiness = workOSFgaReadiness(input);
+  const membershipEnv = workOSFgaMembershipEnvSummary(input.workspaceRoot, input.manifest.organizations);
+  return [
+    ...collectWorkOSFgaChecks({
+      manifest: input.manifest,
+      state: input.state,
+      requireState: input.real,
+      requireRealState: input.real,
+      requireProof: input.real,
+    }),
+    {
+      name: "fga-seed-state",
+      ok: !input.real || readiness.seedReady,
+      detail: !input.real
+        ? "hosted seed evidence is only required for --real doctor"
+        : readiness.seedReady
+          ? `${WORKOS_SEED_STATE_FILE} matches ${input.file}`
+          : `real FGA proof requires hosted seed evidence matching ${input.file}; run forge workos prove --real --file ${input.file} --json`,
+    },
+    {
+      name: "fga-hosted-resource-types",
+      ok: !input.real || readiness.resourceTypesConfigured,
+      detail: !input.real
+        ? "hosted WorkOS resource type existence is only verified by --real sync/prove"
+        : readiness.resourceTypesConfigured
+          ? `${WORKOS_FGA_STATE_FILE} records successful real Authorization API resource sync`
+          : "real FGA requires hosted WorkOS resource types for every non-organization resource; run forge workos fga plan --write and configure any listed resource types before sync",
+    },
+    {
+      name: "fga-membership-env",
+      ok: !input.real || readiness.membershipEnvReady,
+      detail: !input.real
+        ? "organizationMembershipId env is only required for real WorkOS access checks"
+        : readiness.membershipEnvReady
+          ? `membership env is present${membershipEnv.jsonEnvPresent ? " through WORKOS_FGA_MEMBERSHIPS_JSON" : ` through ${membershipEnv.presentEnv.join(", ")}`}`
+          : `missing organizationMembershipId env for real checks: WORKOS_FGA_MEMBERSHIPS_JSON or ${membershipEnv.missingEnv.join(", ")}`,
+    },
+    {
+      name: "fga-production-readiness",
+      ok: !input.real || readiness.productionReady,
+      detail: !input.real
+        ? "run forge workos fga doctor --real --json for production FGA gates"
+        : readiness.productionReady
+          ? "real WorkOS FGA seed, resource sync, membership env, and proof are current"
+          : `real WorkOS FGA is not production-ready; next command: ${readiness.nextCommand}`,
+    },
+  ];
+}
+
 export function runWorkOSFgaCommand(options: WorkOSCommandOptions): WorkOSCommandResult {
   const action = options.fgaAction ?? "doctor";
   const file = options.file ?? DEFAULT_SEED_FILE;
@@ -2608,8 +2791,10 @@ export function runWorkOSFgaCommand(options: WorkOSCommandOptions): WorkOSComman
       applied: false,
       data: fgaData({
         action,
+        workspaceRoot: options.workspaceRoot,
         manifest,
         state,
+        seedState,
         real,
         ...(writtenSetupGuidePath ? { setupGuidePath: writtenSetupGuidePath } : {}),
         nextCommand: `forge workos fga sync --file ${file} --json`,
@@ -2642,8 +2827,10 @@ export function runWorkOSFgaCommand(options: WorkOSCommandOptions): WorkOSComman
         applied: false,
         data: fgaData({
           action,
+          workspaceRoot: options.workspaceRoot,
           manifest,
           state,
+          seedState,
           real,
           ...(cliAuth ? { cliAuth } : {}),
           ...(writtenSetupGuidePath ? { setupGuidePath: writtenSetupGuidePath } : {}),
@@ -2661,8 +2848,10 @@ export function runWorkOSFgaCommand(options: WorkOSCommandOptions): WorkOSComman
         applied: false,
         data: fgaData({
           action,
+          workspaceRoot: options.workspaceRoot,
           manifest,
           state,
+          seedState,
           real,
           ...(cliAuth ? { cliAuth } : {}),
           ...(writtenSetupGuidePath ? { setupGuidePath: writtenSetupGuidePath } : {}),
@@ -2688,8 +2877,10 @@ export function runWorkOSFgaCommand(options: WorkOSCommandOptions): WorkOSComman
         applied: false,
         data: fgaData({
           action,
+          workspaceRoot: options.workspaceRoot,
           manifest,
           state,
+          seedState,
           real,
           ...(cliAuth ? { cliAuth } : {}),
           workosSdk: sdk.data,
@@ -2718,8 +2909,10 @@ export function runWorkOSFgaCommand(options: WorkOSCommandOptions): WorkOSComman
       applied: true,
       data: fgaData({
         action,
+        workspaceRoot: options.workspaceRoot,
         manifest,
         state,
+        seedState,
         real,
         ...(cliAuth ? { cliAuth } : {}),
         ...(sdk ? { workosSdk: sdk.data } : {}),
@@ -2789,8 +2982,10 @@ export function runWorkOSFgaCommand(options: WorkOSCommandOptions): WorkOSComman
       applied: Boolean(ok && !options.dryRun),
       data: fgaData({
         action,
+        workspaceRoot: options.workspaceRoot,
         manifest,
         state,
+        seedState,
         real,
         ...(cliAuth ? { cliAuth } : {}),
         ...(sdk ? { workosSdk: sdk.data } : {}),
@@ -2804,20 +2999,40 @@ export function runWorkOSFgaCommand(options: WorkOSCommandOptions): WorkOSComman
     };
   }
 
-  const ok = checks.every((check) => check.ok);
+  const doctorChecks = collectWorkOSFgaDoctorChecks({
+    workspaceRoot: options.workspaceRoot,
+    file,
+    manifest,
+    state,
+    seedState,
+    real,
+  });
+  const readiness = workOSFgaReadiness({
+    workspaceRoot: options.workspaceRoot,
+    file,
+    manifest,
+    state,
+    seedState,
+    real,
+  });
+  const ok = doctorChecks.every((check) => check.ok);
   return {
     ok,
     kind: "workos-fga",
-    checks,
+    checks: doctorChecks,
     command,
     applied: false,
     data: fgaData({
       action,
+      workspaceRoot: options.workspaceRoot,
       manifest,
       state,
+      seedState,
+      readiness,
       real,
       ...(writtenSetupGuidePath ? { setupGuidePath: writtenSetupGuidePath } : {}),
-      nextCommand: state.exists ? `forge workos fga prove --file ${file} --json` : `forge workos fga sync --file ${file} --json`,
+      nextCommand: readiness.nextCommand,
+      nextActions: readiness.nextActions,
     }),
     exitCode: ok ? 0 : 1,
   };
@@ -2953,6 +3168,8 @@ export function formatWorkOSHuman(result: WorkOSCommandResult): string {
       lines.push(`WorkOS FGA sync recorded${data.stateFile ? ` in ${data.stateFile}` : ""}; run ${data.nextCommand ?? "forge workos fga prove --json"}.`);
     } else if (result.ok && data.action === "prove") {
       lines.push(`WorkOS FGA proof passed${data.real ? " for real-mode state" : " locally"}; production deploy gates can inspect the FGA state.`);
+    } else if (result.ok && data.action === "doctor") {
+      lines.push(`WorkOS FGA doctor passed${data.real ? " for real production gates" : " for local planning"}; run ${data.nextCommand ?? "forge workos fga sync --json"} if you need the next proof step.`);
     } else if (!result.ok) {
       lines.push("WorkOS FGA check failed; inspect manifest diagnostics, seed coverage, and FGA state.");
       for (const action of data.nextActions ?? []) {

package/src/forge/version.ts

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