forgeos 0.1.0-alpha.46 → 0.1.0-alpha.48

package/src/forge/cli/workos.ts

@@ -1,21 +1,25 @@
-import { existsSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
-import { basename, join } from "node:path";
+import { basename, dirname, join } from "node:path";
 import { spawnSync } from "node:child_process";
 import { createHash } from "node:crypto";
 import { GENERATED_DIR } from "../compiler/emitter/constants.ts";
 import { stripDeterministicHeader } from "../compiler/primitives/header.ts";
 
-export type WorkOSSubcommand = "install" | "doctor" | "seed" | "setup" | "prove";
+export type WorkOSSubcommand = "install" | "doctor" | "seed" | "setup" | "prove" | "fga";
+export type WorkOSFgaAction = "plan" | "sync" | "prove" | "doctor";
 
 export interface WorkOSCommandOptions {
   subcommand: WorkOSSubcommand;
+  fgaAction?: WorkOSFgaAction;
   workspaceRoot: string;
   json: boolean;
   file?: string;
   yes: boolean;
   dryRun: boolean;
   real?: boolean;
+  write?: boolean;
+  writePath?: string;
   commandRunner?: WorkOSCommandRunner;
 }
 
@@ -27,7 +31,7 @@ export interface WorkOSCheck {
 
 export interface WorkOSCommandResult {
   ok: boolean;
-  kind: "workos-install" | "workos-doctor" | "workos-seed" | "workos-setup" | "workos-prove";
+  kind: "workos-install" | "workos-doctor" | "workos-seed" | "workos-setup" | "workos-prove" | "workos-fga";
   checks: WorkOSCheck[];
   command?: string[];
   applied?: boolean;
@@ -44,12 +48,15 @@ export type WorkOSCommandRunner = (
     cwd: string;
     encoding: "utf8";
     stdio: ["ignore", "pipe", "pipe"];
+    env?: Record<string, string | undefined>;
   },
 ) => { status: number | null; stdout: string; stderr: string };
 
 const DEFAULT_SEED_FILE = "workos-seed.yml";
 const GENERATED_SEED_FILE = `${GENERATED_DIR}/integrations/workos/workos-seed.yml`;
 const WORKOS_SEED_STATE_FILE = ".workos-seed-state.json";
+const WORKOS_FGA_STATE_FILE = ".workos-fga-state.json";
+const WORKOS_FGA_SETUP_GUIDE_FILE = ".forge/workos-fga-setup.md";
 
 function runExternalCommand(
   command: string[],
@@ -60,6 +67,11 @@ function runExternalCommand(
     cwd: options.workspaceRoot,
     encoding: "utf8",
     stdio: ["ignore", "pipe", "pipe"],
+    env: {
+      ...process.env,
+      ...readRealEnv(options.workspaceRoot),
+      WORKOS_MODE: process.env.WORKOS_MODE || "agent",
+    },
   });
   return {
     status: result.status,
@@ -329,6 +341,207 @@ function workosJwksUri(clientId: string | undefined): string {
   return clientId ? `https://api.workos.com/sso/jwks/${clientId}` : "https://api.workos.com/sso/jwks/<WORKOS_CLIENT_ID>";
 }
 
+export interface WorkOSCliAuthSummary {
+  required: boolean;
+  ok: boolean;
+  method: "api-key" | "cli";
+  skippedReason?: string;
+  statusCommand: string[];
+  loginCommand?: string[];
+  loginAttempted: boolean;
+  authenticated?: boolean;
+  email?: string;
+  userId?: string;
+  tokenExpired?: boolean;
+  hasRefreshToken?: boolean;
+  activeEnvironment?: unknown;
+  status?: number | null;
+  loginStatus?: number | null;
+  detail: string;
+  loginInstructions?: {
+    url?: string;
+    code?: string;
+    message?: string;
+  };
+  nextActions: string[];
+}
+
+function parseJsonObject(text: string): Record<string, unknown> | null {
+  try {
+    const parsed = JSON.parse(text);
+    return parsed && typeof parsed === "object" && !Array.isArray(parsed)
+      ? parsed as Record<string, unknown>
+      : null;
+  } catch {
+    return null;
+  }
+}
+
+function stringField(value: unknown): string | undefined {
+  return typeof value === "string" && value.trim() ? value : undefined;
+}
+
+function booleanField(value: unknown): boolean | undefined {
+  return typeof value === "boolean" ? value : undefined;
+}
+
+function extractWorkOSLoginInstructions(stdout: string, stderr: string): WorkOSCliAuthSummary["loginInstructions"] | undefined {
+  const output = `${stdout}\n${stderr}`.trim();
+  if (!output) {
+    return undefined;
+  }
+  const url = output.match(/https?:\/\/[^\s"'<>]+/)?.[0];
+  const code = output.match(/(?:code|verification code|user code)[^\w]*([A-Z0-9-]{4,})/i)?.[1]
+    ?? output.match(/\b([A-Z0-9]{4}-[A-Z0-9]{4}|[A-Z0-9]{6,12})\b/)?.[1];
+  const message = output
+    .split(/\r?\n/)
+    .map((line) => line.trim())
+    .filter(Boolean)
+    .slice(0, 12)
+    .join("\n");
+  return {
+    ...(url ? { url } : {}),
+    ...(code ? { code } : {}),
+    ...(message ? { message } : {}),
+  };
+}
+
+function workOSCliAuthCheck(auth: WorkOSCliAuthSummary): WorkOSCheck {
+  return {
+    name: "workos-cli-auth",
+    ok: auth.ok,
+    detail: auth.detail,
+  };
+}
+
+function ensureWorkOSCliAuthForHosted(options: WorkOSCommandOptions): WorkOSCliAuthSummary {
+  const env = readRealEnv(options.workspaceRoot);
+  const statusCommand = ["npx", "--yes", "workos@latest", "auth", "status", "--json"];
+  if (hasValue(env, "WORKOS_API_KEY")) {
+    return {
+      required: false,
+      ok: true,
+      method: "api-key",
+      skippedReason: "WORKOS_API_KEY is present; WorkOS CLI browser login is optional for hosted setup",
+      statusCommand,
+      loginAttempted: false,
+      detail: "WORKOS_API_KEY is present; hosted WorkOS setup can use API key authentication",
+      nextActions: [],
+    };
+  }
+
+  const status = runExternalCommand(statusCommand, options);
+  const parsed = parseJsonObject(status.stdout);
+  const authenticated = booleanField(parsed?.authenticated) ?? false;
+  const tokenExpired = booleanField(parsed?.tokenExpired) ?? false;
+  const hasRefreshToken = booleanField(parsed?.hasRefreshToken) ?? false;
+  const email = stringField(parsed?.email);
+  const userId = stringField(parsed?.userId);
+  const activeEnvironment = parsed?.activeEnvironment;
+  if (status.status === 0 && authenticated && (!tokenExpired || hasRefreshToken)) {
+    return {
+      required: true,
+      ok: true,
+      method: "cli",
+      statusCommand,
+      loginAttempted: false,
+      authenticated,
+      ...(email ? { email } : {}),
+      ...(userId ? { userId } : {}),
+      tokenExpired,
+      hasRefreshToken,
+      ...(activeEnvironment ? { activeEnvironment } : {}),
+      status: status.status,
+      detail: tokenExpired && hasRefreshToken
+        ? `WorkOS CLI is authenticated${email ? ` as ${email}` : ""}; token is expired but a refresh token is available`
+        : `WorkOS CLI is authenticated${email ? ` as ${email}` : ""}`,
+      nextActions: [],
+    };
+  }
+
+  const loginCommand = ["npx", "--yes", "workos@latest", "auth", "login", "--json"];
+  const login = runExternalCommand(loginCommand, options);
+  const instructions = extractWorkOSLoginInstructions(login.stdout, login.stderr);
+  if (login.status === 0) {
+    return {
+      required: true,
+      ok: true,
+      method: "cli",
+      statusCommand,
+      loginCommand,
+      loginAttempted: true,
+      authenticated: true,
+      status: status.status,
+      loginStatus: login.status,
+      detail: "WorkOS CLI login completed or was already authenticated",
+      ...(instructions ? { loginInstructions: instructions } : {}),
+      nextActions: [],
+    };
+  }
+
+  const nextActions = [
+    "complete the WorkOS CLI OAuth/device-code login shown in loginInstructions",
+    "rerun forge workos prove --real --file workos-seed.yml --json",
+  ];
+  return {
+    required: true,
+    ok: false,
+    method: "cli",
+    statusCommand,
+    loginCommand,
+    loginAttempted: true,
+    authenticated,
+    ...(email ? { email } : {}),
+    ...(userId ? { userId } : {}),
+    tokenExpired,
+    hasRefreshToken,
+    ...(activeEnvironment ? { activeEnvironment } : {}),
+    status: status.status,
+    loginStatus: login.status,
+    detail: instructions?.url || instructions?.code
+      ? "WorkOS CLI login is required; open the URL and enter the code from loginInstructions, then rerun the command"
+      : "WorkOS CLI login is required; run WORKOS_MODE=agent npx --yes workos@latest auth login --json and rerun the Forge command",
+    ...(instructions ? { loginInstructions: instructions } : {}),
+    nextActions,
+  };
+}
+
+function collectWorkOSRealEnvChecks(workspaceRoot: string, cliAuth?: WorkOSCliAuthSummary): WorkOSCheck[] {
+  const env = readRealEnv(workspaceRoot);
+  const authMode = env.FORGE_AUTH_MODE;
+  const clientId = env.WORKOS_CLIENT_ID || env.VITE_WORKOS_CLIENT_ID;
+  const required = [
+    ["WORKOS_CLIENT_ID", "WorkOS client ID is required for AuthKit and JWKS discovery"],
+    ["WORKOS_COOKIE_PASSWORD", "cookie password is required for AuthKit session signing"],
+    ["FORGE_AUTH_ISSUER", "Forge OIDC issuer must be https://api.workos.com"],
+    ["FORGE_AUTH_AUDIENCE", "Forge OIDC audience must match the WorkOS client/application audience"],
+    ["FORGE_AUTH_JWKS_URI", `Forge JWKS URI must be configured, usually ${workosJwksUri(clientId)}`],
+  ] as const;
+  return [
+    {
+      name: "real-env-auth-mode",
+      ok: authMode === "oidc" || authMode === "jwt",
+      detail: authMode === "oidc" || authMode === "jwt"
+        ? `FORGE_AUTH_MODE=${authMode} is production-capable`
+        : "FORGE_AUTH_MODE must be oidc or jwt before running hosted WorkOS proof",
+    },
+    {
+      name: "real-env-workos_api_key-or-cli-auth",
+      ok: hasValue(env, "WORKOS_API_KEY") || cliAuth?.ok === true,
+      detail: hasValue(env, "WORKOS_API_KEY")
+        ? "WORKOS_API_KEY is present"
+        : cliAuth?.ok
+          ? "WORKOS_API_KEY is missing, but WorkOS CLI authentication is available for no-dashboard hosted setup"
+          : "WORKOS_API_KEY is missing and WorkOS CLI authentication is not complete; run WorkOS CLI login",
+    },
+    ...required.map(([name, detail]) => ({
+      name: `real-env-${name.toLowerCase()}`,
+      ok: hasValue(env, name),
+      detail: hasValue(env, name) ? `${name} is present` : `${name} is missing: ${detail}`,
+    })),
+  ];
+}
+
 export function collectPolicyPermissions(workspaceRoot: string): string[] {
   const registry = readJson(workspaceRoot, `${GENERATED_DIR}/policyRegistry.json`) as {
     policies?: Array<{ permissions?: string[] }>;
@@ -391,9 +604,945 @@ export function missingValues(expected: string[], actual: string[]): string[] {
   return expected.filter((value) => !actualSet.has(value));
 }
 
+export interface WorkOSFgaResource {
+  externalId: string;
+  type: string;
+  tenant: string;
+  name: string;
+  parentExternalId?: string;
+  parentType?: string;
+}
+
+export interface WorkOSFgaProofScenario {
+  name: string;
+  expected: "allow" | "deny";
+  permission: string;
+  resourceExternalId: string;
+  resourceTypeSlug: string;
+  organization: string;
+  reason: string;
+}
+
+export interface WorkOSFgaManifest {
+  schemaVersion: "0.1.0";
+  provider: "workos";
+  kind: "fga-manifest";
+  seedFile: string;
+  seedHash?: string;
+  manifestHash: string;
+  permissions: string[];
+  roles: string[];
+  resourceTypes: string[];
+  organizations: string[];
+  resources: WorkOSFgaResource[];
+  proofScenarios: WorkOSFgaProofScenario[];
+  diagnostics: string[];
+}
+
+export interface WorkOSFgaStateSummary {
+  exists: boolean;
+  valid: boolean;
+  path: string;
+  matchesManifestHash: boolean | null;
+  manifestHash?: string;
+  currentManifestHash?: string;
+  syncedAt?: string;
+  provedAt?: string;
+  mode?: "local" | "real";
+  sdkOk?: boolean;
+  diagnostics: string[];
+}
+
+export interface WorkOSFgaHostedSetup {
+  requiredResourceTypes: string[];
+  rootResourceType: "organization";
+  missingResourceTypes: string[];
+  requiredMembershipEnv: string[];
+  managedBy: "hosted-workos";
+  cliSupport: "resources-and-checks";
+  sdkSupport: "resources-and-checks";
+  docs: string[];
+  nextActions: string[];
+}
+
+export interface WorkOSFgaResourceTypeSetup {
+  slug: string;
+  displayName: string;
+  hostedAction: "none" | "configure-resource-type";
+  requiredBeforeRealSync: boolean;
+  permissions: string[];
+  roles: string[];
+  parentTypes: string[];
+  childTypes: string[];
+  exampleExternalIds: string[];
+  proofScenarios: string[];
+  notes: string[];
+}
+
+export interface WorkOSFgaSetupGuide {
+  resourceTypes: WorkOSFgaResourceTypeSetup[];
+  markdown: string;
+  docs: string[];
+  unsupportedAutomation: string[];
+}
+
+function slugifyExternalIdPart(value: string): string {
+  return value
+    .trim()
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-+|-+$/g, "") || "demo";
+}
+
+function preferredParentType(resourceType: string, resourceTypes: string[]): string | undefined {
+  const has = (value: string) => resourceTypes.includes(value);
+  if (resourceType === "organization") return undefined;
+  if (["access_request", "accessRequest", "evidence_document", "evidenceDocument"].includes(resourceType)) {
+    if (has("vendor")) return "vendor";
+  }
+  if (["task", "taskGroup"].includes(resourceType)) {
+    if (has("team")) return "team";
+    if (has("project")) return "project";
+  }
+  if (resourceType === "team" && has("project")) return "project";
+  return has("organization") ? "organization" : undefined;
+}
+
+function stableJson(value: unknown): string {
+  if (Array.isArray(value)) {
+    return `[${value.map(stableJson).join(",")}]`;
+  }
+  if (value && typeof value === "object") {
+    return `{${Object.entries(value as Record<string, unknown>)
+      .sort(([a], [b]) => a.localeCompare(b))
+      .map(([key, child]) => `${JSON.stringify(key)}:${stableJson(child)}`)
+      .join(",")}}`;
+  }
+  return JSON.stringify(value);
+}
+
+function hashObject(value: unknown): string {
+  return createHash("sha256").update(stableJson(value)).digest("hex");
+}
+
+export function collectWorkOSFgaManifest(
+  workspaceRoot: string,
+  preferredSeedPath = DEFAULT_SEED_FILE,
+): WorkOSFgaManifest {
+  const seed = parseSeedFile(workspaceRoot, preferredSeedPath);
+  const activePermissions = collectPolicyPermissions(workspaceRoot);
+  const expectedResourceTypes = collectExpectedResourceTypes(workspaceRoot);
+  const permissions = uniqueSorted([...seed.permissions, ...activePermissions]);
+  const resourceTypes = uniqueSorted([...seed.resourceTypes, ...expectedResourceTypes]);
+  const organizations = seed.organizations.length > 0 ? seed.organizations : ["Demo Organization"];
+  const diagnostics: string[] = [];
+  const missingSeedPermissions = missingValues(activePermissions, seed.permissions);
+  const missingSeedResources = missingValues(expectedResourceTypes, seed.resourceTypes);
+  if (!seed.exists) diagnostics.push(`${preferredSeedPath} is missing; run forge add auth workos or forge workos seed --dry-run first`);
+  if (missingSeedPermissions.length > 0) diagnostics.push(`seed missing active policy permission(s): ${missingSeedPermissions.join(", ")}`);
+  if (missingSeedResources.length > 0) diagnostics.push(`seed missing app resource type(s): ${missingSeedResources.join(", ")}`);
+  if (!resourceTypes.includes("organization")) diagnostics.push("FGA graph should include an organization resource type for tenant roots");
+  if (permissions.length === 0) diagnostics.push("no WorkOS permission slugs were discovered");
+  if (seed.roles.length === 0) diagnostics.push("no WorkOS roles were discovered");
+
+  const resources: WorkOSFgaResource[] = [];
+  for (const organization of organizations) {
+    const orgSlug = slugifyExternalIdPart(organization);
+    const orgExternalId = `organization:${orgSlug}`;
+    if (resourceTypes.includes("organization")) {
+      resources.push({
+        externalId: orgExternalId,
+        type: "organization",
+        tenant: organization,
+        name: organization,
+      });
+    }
+    for (const resourceType of resourceTypes.filter((type) => type !== "organization")) {
+      const parentType = preferredParentType(resourceType, resourceTypes);
+      const parentExternalId = parentType
+        ? parentType === "organization"
+          ? orgExternalId
+          : `${parentType}:${orgSlug}:demo`
+        : undefined;
+      resources.push({
+        externalId: `${resourceType}:${orgSlug}:demo`,
+        type: resourceType,
+        tenant: organization,
+        name: `${organization} ${resourceType}`,
+        ...(parentType ? { parentType } : {}),
+        ...(parentExternalId ? { parentExternalId } : {}),
+      });
+    }
+  }
+
+  const firstOrg = organizations[0] ?? "Demo Organization";
+  const secondOrg = organizations[1] ?? `${firstOrg} Other`;
+  const firstResource = resources.find((resource) => resource.type !== "organization") ?? resources[0];
+  const firstPermission = permissions[0] ?? "app:read";
+  const proofScenarios: WorkOSFgaProofScenario[] = firstResource
+    ? [
+        {
+          name: "allowed-same-tenant",
+          expected: "allow",
+          permission: firstPermission,
+          resourceExternalId: firstResource.externalId,
+          resourceTypeSlug: firstResource.type,
+          organization: firstOrg,
+          reason: "membership, permission, and resource tenant match",
+        },
+        {
+          name: "cross-tenant-read-denied",
+          expected: "deny",
+          permission: firstPermission,
+          resourceExternalId: firstResource.externalId,
+          resourceTypeSlug: firstResource.type,
+          organization: secondOrg,
+          reason: "resource belongs to a different organization tenant",
+        },
+      ]
+    : [];
+
+  const hashInput = {
+    seedFile: seed.path,
+    seedHash: seed.exists ? hashSeedFile(workspaceRoot, seed.path) : undefined,
+    permissions,
+    roles: seed.roles,
+    resourceTypes,
+    organizations,
+    resources,
+    proofScenarios,
+  };
+  return {
+    schemaVersion: "0.1.0",
+    provider: "workos",
+    kind: "fga-manifest",
+    seedFile: seed.path,
+    ...(seed.exists ? { seedHash: hashSeedFile(workspaceRoot, seed.path) } : {}),
+    manifestHash: hashObject(hashInput),
+    permissions,
+    roles: seed.roles,
+    resourceTypes,
+    organizations,
+    resources,
+    proofScenarios,
+    diagnostics,
+  };
+}
+
+export function readWorkOSFgaState(
+  workspaceRoot: string,
+  manifest: WorkOSFgaManifest,
+): WorkOSFgaStateSummary {
+  const path = WORKOS_FGA_STATE_FILE;
+  const absolute = join(workspaceRoot, path);
+  if (!existsSync(absolute)) {
+    return {
+      exists: false,
+      valid: false,
+      path,
+      matchesManifestHash: null,
+      currentManifestHash: manifest.manifestHash,
+      diagnostics: [`${path} is missing; run forge workos fga sync --json`],
+    };
+  }
+  try {
+    const parsed = JSON.parse(readFileSync(absolute, "utf8")) as {
+      manifestHash?: unknown;
+      syncedAt?: unknown;
+      provedAt?: unknown;
+      mode?: unknown;
+      sdkOk?: unknown;
+    };
+    const diagnostics: string[] = [];
+    const manifestHash = typeof parsed.manifestHash === "string" ? parsed.manifestHash : undefined;
+    const mode = parsed.mode === "real" ? "real" : parsed.mode === "local" ? "local" : undefined;
+    const sdkOk = typeof parsed.sdkOk === "boolean" ? parsed.sdkOk : undefined;
+    if (!manifestHash) diagnostics.push("FGA state is missing manifestHash");
+    if (typeof parsed.syncedAt !== "string") diagnostics.push("FGA state is missing syncedAt");
+    if (!mode) diagnostics.push("FGA state is missing mode");
+    if (mode === "real" && sdkOk !== true) diagnostics.push("real FGA state is missing sdkOk:true from WorkOS Authorization API sync/proof");
+    return {
+      exists: true,
+      valid: diagnostics.length === 0,
+      path,
+      matchesManifestHash: manifestHash ? manifestHash === manifest.manifestHash : null,
+      ...(manifestHash ? { manifestHash } : {}),
+      currentManifestHash: manifest.manifestHash,
+      ...(typeof parsed.syncedAt === "string" ? { syncedAt: parsed.syncedAt } : {}),
+      ...(typeof parsed.provedAt === "string" ? { provedAt: parsed.provedAt } : {}),
+      ...(mode ? { mode } : {}),
+      ...(sdkOk !== undefined ? { sdkOk } : {}),
+      diagnostics,
+    };
+  } catch (error) {
+    return {
+      exists: true,
+      valid: false,
+      path,
+      matchesManifestHash: null,
+      currentManifestHash: manifest.manifestHash,
+      diagnostics: [`failed to parse ${path}: ${error instanceof Error ? error.message : String(error)}`],
+    };
+  }
+}
+
+function writeWorkOSFgaState(input: {
+  workspaceRoot: string;
+  manifest: WorkOSFgaManifest;
+  mode: "local" | "real";
+  proved: boolean;
+  sdkOk?: boolean;
+  sdk?: unknown;
+}): string {
+  const now = new Date().toISOString();
+  const payload = {
+    schemaVersion: "0.1.0",
+    provider: "workos",
+    kind: "fga-state",
+    mode: input.mode,
+    seedFile: input.manifest.seedFile,
+    seedHash: input.manifest.seedHash,
+    manifestHash: input.manifest.manifestHash,
+    syncedAt: now,
+    ...(input.proved ? { provedAt: now } : {}),
+    ...(input.sdkOk !== undefined ? { sdkOk: input.sdkOk } : {}),
+    ...(input.sdk ? { sdk: input.sdk } : {}),
+    permissions: input.manifest.permissions,
+    roles: input.manifest.roles,
+    resourceTypes: input.manifest.resourceTypes,
+    organizations: input.manifest.organizations,
+    resources: input.manifest.resources,
+    proofScenarios: input.manifest.proofScenarios,
+  };
+  writeFileSync(join(input.workspaceRoot, WORKOS_FGA_STATE_FILE), `${JSON.stringify(payload, null, 2)}\n`, "utf8");
+  return WORKOS_FGA_STATE_FILE;
+}
+
+function hostedFgaResourceTypes(manifest: WorkOSFgaManifest): string[] {
+  return manifest.resourceTypes.filter((resourceType) => resourceType !== "organization");
+}
+
+function fgaMembershipEnvKey(organization: string): string {
+  const suffix = slugifyExternalIdPart(organization).replace(/-/g, "_").toUpperCase();
+  return `WORKOS_FGA_MEMBERSHIP_${suffix}`;
+}
+
+function extractMissingWorkOSFgaResourceTypes(data: unknown, manifest?: WorkOSFgaManifest): string[] {
+  const missing = new Set<string>();
+  const add = (value: unknown) => {
+    if (typeof value === "string" && value && value !== "organization") {
+      missing.add(value);
+    }
+  };
+  if (data && typeof data === "object") {
+    const errors = (data as { errors?: unknown }).errors;
+    if (Array.isArray(errors)) {
+      for (const error of errors) {
+        if (!error || typeof error !== "object") continue;
+        const record = error as Record<string, unknown>;
+        const message = typeof record.message === "string" ? record.message : "";
+        const status = String(record.status ?? "");
+        if (message.includes("AuthorizationResourceType not found") || status === "404") {
+          add(record.resourceTypeSlug);
+        }
+        const match = /AuthorizationResourceType not found:\s*['"]([^'"]+)['"]/.exec(message);
+        add(match?.[1]);
+      }
+    }
+  }
+  const text = JSON.stringify(data) ?? "";
+  const missingTypePattern = /AuthorizationResourceType not found:\s*['"]([^'"]+)['"]/g;
+  let match: RegExpExecArray | null;
+  while ((match = missingTypePattern.exec(text))) {
+    add(match[1]);
+  }
+  if (missing.size === 0 && text.includes("AuthorizationResourceType not found") && manifest) {
+    for (const resourceType of hostedFgaResourceTypes(manifest)) {
+      missing.add(resourceType);
+    }
+  }
+  return uniqueSorted(missing);
+}
+
+function workOSFgaHostedSetup(manifest: WorkOSFgaManifest, sdkData?: unknown): WorkOSFgaHostedSetup {
+  const requiredResourceTypes = hostedFgaResourceTypes(manifest);
+  const missingResourceTypes = extractMissingWorkOSFgaResourceTypes(sdkData, manifest);
+  const resourceList = (missingResourceTypes.length > 0 ? missingResourceTypes : requiredResourceTypes).join(", ") || "none";
+  const requiredMembershipEnv = manifest.organizations.map(fgaMembershipEnvKey);
+  return {
+    requiredResourceTypes,
+    rootResourceType: "organization",
+    missingResourceTypes,
+    requiredMembershipEnv,
+    managedBy: "hosted-workos",
+    cliSupport: "resources-and-checks",
+    sdkSupport: "resources-and-checks",
+    docs: [
+      "https://workos.com/docs/fga/resource-types",
+      "https://workos.com/docs/fga/resources",
+      "https://workos.com/docs/fga/access-checks",
+    ],
+    nextActions: [
+      missingResourceTypes.length > 0
+        ? `configure missing WorkOS FGA resource type(s): ${resourceList}`
+        : `confirm WorkOS FGA resource type(s) exist: ${resourceList}`,
+      "treat organization as the WorkOS tenant root; ForgeOS does not create it as an authorization resource",
+      `set WorkOS FGA membership env for real access checks: WORKOS_FGA_MEMBERSHIPS_JSON or ${requiredMembershipEnv.join(", ") || "WORKOS_FGA_MEMBERSHIP_<ORG>"}`,
+      "rerun forge workos fga sync --real --file workos-seed.yml --json",
+      "rerun forge workos fga prove --real --file workos-seed.yml --json",
+      "rerun forge deploy check --production --json",
+    ],
+  };
+}
+
+function displayResourceType(slug: string): string {
+  return slug
+    .replace(/[_-]+/g, " ")
+    .replace(/\b\w/g, (letter) => letter.toUpperCase());
+}
+
+function permissionResourcePart(permission: string): string {
+  return permission.split(":")[0] ?? permission;
+}
+
+function permissionMatchesResourceType(permission: string, resourceType: string): boolean {
+  const part = permissionResourcePart(permission);
+  const normalizedPart = singularResourceName(part.replace(/[-_]/g, ""));
+  const normalizedType = singularResourceName(resourceType.replace(/[-_]/g, ""));
+  return part === resourceType ||
+    singularResourceName(part) === resourceType ||
+    normalizedPart === normalizedType ||
+    normalizedType.startsWith(normalizedPart) ||
+    normalizedPart === `${normalizedType}request`;
+}
+
+function permissionsForResourceType(manifest: WorkOSFgaManifest, resourceType: string): string[] {
+  if (resourceType === "organization") {
+    return manifest.permissions.filter((permission) => permissionResourcePart(permission) === "organization");
+  }
+  return manifest.permissions.filter((permission) => permissionMatchesResourceType(permission, resourceType));
+}
+
+function roleLooksRelevantToResourceType(role: string, resourceType: string): boolean {
+  const normalizedRole = role.replace(/[-_]/g, "");
+  const normalizedType = resourceType.replace(/[-_]/g, "");
+  return normalizedRole.includes(normalizedType) ||
+    normalizedRole.includes(singularResourceName(normalizedType)) ||
+    ["owner", "admin", "manager", "member", "auditor", "reviewer", "requester", "security"].some((shared) => normalizedRole.includes(shared));
+}
+
+function rolesForResourceType(manifest: WorkOSFgaManifest, resourceType: string): string[] {
+  const relevant = manifest.roles.filter((role) => roleLooksRelevantToResourceType(role, resourceType));
+  return relevant.length > 0 ? relevant : manifest.roles;
+}
+
+function workOSFgaSetupGuide(manifest: WorkOSFgaManifest, hostedSetup: WorkOSFgaHostedSetup): WorkOSFgaSetupGuide {
+  const resourcesByType = new Map<string, WorkOSFgaResource[]>();
+  for (const resource of manifest.resources) {
+    resourcesByType.set(resource.type, [...resourcesByType.get(resource.type) ?? [], resource]);
+  }
+  const resourceTypes = manifest.resourceTypes.map((slug): WorkOSFgaResourceTypeSetup => {
+    const resources = resourcesByType.get(slug) ?? [];
+    const parentTypes = uniqueSorted(resources.map((resource) => resource.parentType ?? "").filter(Boolean));
+    const childTypes = uniqueSorted(manifest.resources
+      .filter((resource) => resource.parentType === slug)
+      .map((resource) => resource.type));
+    const proofScenarios = manifest.proofScenarios
+      .filter((scenario) => scenario.resourceTypeSlug === slug)
+      .map((scenario) => `${scenario.name}:${scenario.expected}`);
+    const permissions = permissionsForResourceType(manifest, slug);
+    const roles = rolesForResourceType(manifest, slug);
+    const isRoot = slug === hostedSetup.rootResourceType;
+    return {
+      slug,
+      displayName: displayResourceType(slug),
+      hostedAction: isRoot ? "none" : "configure-resource-type",
+      requiredBeforeRealSync: !isRoot,
+      permissions,
+      roles,
+      parentTypes,
+      childTypes,
+      exampleExternalIds: resources.map((resource) => resource.externalId).slice(0, 4),
+      proofScenarios,
+      notes: isRoot
+        ? [
+            "Treat WorkOS organization as the tenant root.",
+            "ForgeOS keeps organization in the graph for parent/tenant reasoning, but real sync does not create it as an authorization resource.",
+          ]
+        : [
+            "Create/configure this resource type in hosted WorkOS before real sync.",
+            parentTypes.length > 0
+              ? `Expected parent type(s): ${parentTypes.join(", ")}.`
+              : "No parent type inferred from the app graph.",
+          ],
+    };
+  });
+  const markdown = [
+    "# WorkOS FGA Setup",
+    "",
+    "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.",
+    "",
+    "## Resource Types",
+    "",
+    ...resourceTypes.flatMap((resourceType) => [
+      `### ${resourceType.slug}`,
+      "",
+      `- Display name: ${resourceType.displayName}`,
+      `- Hosted action: ${resourceType.hostedAction}`,
+      `- Required before real sync: ${resourceType.requiredBeforeRealSync ? "yes" : "no"}`,
+      `- Parent types: ${resourceType.parentTypes.join(", ") || "none"}`,
+      `- Child types: ${resourceType.childTypes.join(", ") || "none"}`,
+      `- Permissions to attach/model: ${resourceType.permissions.join(", ") || "none inferred"}`,
+      `- Roles to review for this type: ${resourceType.roles.join(", ") || "none inferred"}`,
+      `- Example external IDs: ${resourceType.exampleExternalIds.join(", ") || "none"}`,
+      `- Proof scenarios: ${resourceType.proofScenarios.join(", ") || "none"}`,
+      ...resourceType.notes.map((note) => `- Note: ${note}`),
+      "",
+    ]),
+    "## Permission And Role Coverage",
+    "",
+    `- Permissions discovered: ${manifest.permissions.join(", ") || "none"}`,
+    `- Roles discovered: ${manifest.roles.join(", ") || "none"}`,
+    "- In hosted WorkOS, ensure each permission is scoped to the intended resource type and each role includes the permissions needed by your Forge policies.",
+    "- ForgeOS will not claim production readiness until real Authorization API checks pass for the generated proof scenarios.",
+    "",
+    "## Required Membership Environment",
+    "",
+    "- WORKOS_FGA_MEMBERSHIPS_JSON: JSON object mapping organization name to organizationMembershipId",
+    ...hostedSetup.requiredMembershipEnv.map((env) => `- ${env}: organizationMembershipId for that organization`),
+    "",
+    "## Commands",
+    "",
+    "```bash",
+    "forge workos fga plan --file workos-seed.yml --write --json",
+    "forge workos fga sync --real --file workos-seed.yml --json",
+    "forge workos fga prove --real --file workos-seed.yml --json",
+    "forge deploy check --production --json",
+    "```",
+    "",
+  ].join("\n");
+  return {
+    resourceTypes,
+    markdown,
+    docs: hostedSetup.docs,
+    unsupportedAutomation: [
+      "ForgeOS does not invent WorkOS CLI/API calls for resource type creation.",
+      "ForgeOS can create/read FGA resources and run authorization checks through the WorkOS CLI/API or SDK after resource types exist.",
+    ],
+  };
+}
+
+function resolveWorkOSFgaSetupGuidePath(options: WorkOSCommandOptions): string | undefined {
+  if (!options.write && !options.writePath) {
+    return undefined;
+  }
+  const candidate = options.writePath?.trim();
+  return candidate && candidate !== "true" && !candidate.startsWith("--") ? candidate : WORKOS_FGA_SETUP_GUIDE_FILE;
+}
+
+function writeWorkOSFgaSetupGuide(
+  workspaceRoot: string,
+  guide: WorkOSFgaSetupGuide,
+  preferredPath = WORKOS_FGA_SETUP_GUIDE_FILE,
+): string {
+  const relativePath = preferredPath.startsWith("/") ? preferredPath.slice(1) : preferredPath;
+  const absolutePath = join(workspaceRoot, relativePath);
+  mkdirSync(dirname(absolutePath), { recursive: true });
+  writeFileSync(absolutePath, guide.markdown, "utf8");
+  return relativePath;
+}
+
+function fgaData(input: {
+  action: WorkOSFgaAction;
+  manifest: WorkOSFgaManifest;
+  state: WorkOSFgaStateSummary;
+  real?: boolean;
+  cliAuth?: WorkOSCliAuthSummary;
+  workosSdk?: unknown;
+  stateFile?: string;
+  nextCommand?: string;
+  nextActions?: string[];
+  setupGuidePath?: string;
+}): Record<string, unknown> {
+  const hostedSetup = workOSFgaHostedSetup(input.manifest, input.workosSdk);
+  const setupGuide = workOSFgaSetupGuide(input.manifest, hostedSetup);
+  return {
+    action: input.action,
+    real: input.real ?? false,
+    manifest: input.manifest,
+    state: input.state,
+    hostedSetup,
+    resourceTypeSetup: setupGuide.resourceTypes,
+    setupGuide,
+    ...(input.cliAuth ? { cliAuth: input.cliAuth } : {}),
+    ...(input.workosSdk ? { workosSdk: input.workosSdk } : {}),
+    ...(input.stateFile ? { stateFile: input.stateFile } : {}),
+    ...(input.setupGuidePath ? { setupGuidePath: input.setupGuidePath } : {}),
+    nextCommand: input.nextCommand,
+    nextActions: input.nextActions ?? hostedSetup.nextActions,
+    notes: [
+      "ForgeOS derives resource graph and proof scenarios from app contract, policies, and workos-seed.yml.",
+      "WorkOS FGA resource types are hosted WorkOS configuration; ForgeOS syncs/proves resources and gates production deploys through .workos-fga-state.json.",
+    ],
+  };
+}
+
+function runWorkOSFgaSdk(
+  options: WorkOSCommandOptions,
+  manifest: WorkOSFgaManifest,
+  action: "sync" | "prove",
+): { ok: boolean; command: string[]; data: Record<string, unknown>; status: number | null; stdout?: string; stderr?: string } {
+const script = String.raw`
+const { spawnSync } = await import("node:child_process");
+const payload = JSON.parse(process.env.FORGE_WORKOS_FGA_PAYLOAD || "{}");
+const out = { ok: true, action: payload.action, resources: [], checks: [], skipped: [], errors: [] };
+function message(error) {
+  return error && typeof error === "object" && "message" in error ? String(error.message) : String(error);
+}
+function status(error) {
+  return error && typeof error === "object" && "status" in error ? error.status : error && typeof error === "object" && "statusCode" in error ? error.statusCode : undefined;
+}
+async function listAll(page) {
+  if (!page) return [];
+  if (Array.isArray(page.data)) return page.data;
+  if (Symbol.asyncIterator in Object(page)) {
+    const values = [];
+    for await (const item of page) values.push(item);
+    return values;
+  }
+  return [];
+}
+function slugify(value) {
+  return String(value || "")
+    .trim()
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-+|-+$/g, "") || "demo";
+}
+function membershipEnvKey(organization) {
+  return "WORKOS_FGA_MEMBERSHIP_" + slugify(organization).replace(/-/g, "_").toUpperCase();
+}
+function readMembershipMap(organizations) {
+  const memberships = new Map();
+  for (const name of ["WORKOS_FGA_MEMBERSHIPS_JSON", "WORKOS_FGA_TEST_MEMBERSHIPS"]) {
+    const raw = process.env[name];
+    if (!raw) continue;
+    try {
+      const parsed = JSON.parse(raw);
+      if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
+        for (const [organization, membershipId] of Object.entries(parsed)) {
+          if (typeof membershipId === "string" && membershipId.trim()) {
+            memberships.set(organization, membershipId.trim());
+            memberships.set(slugify(organization), membershipId.trim());
+          }
+        }
+      }
+    } catch (error) {
+      out.ok = false;
+      out.errors.push({ operation: "membership.env", env: name, message: "failed to parse JSON membership map: " + message(error) });
+    }
+  }
+  for (const organization of organizations || []) {
+    const envKey = membershipEnvKey(organization);
+    const membershipId = process.env[envKey];
+    if (membershipId && membershipId.trim()) {
+      memberships.set(organization, membershipId.trim());
+      memberships.set(slugify(organization), membershipId.trim());
+    }
+  }
+  const legacy = process.env.WORKOS_FGA_TEST_MEMBERSHIP_ID || process.env.WORKOS_FGA_ORGANIZATION_MEMBERSHIP_ID;
+  if (legacy && legacy.trim() && organizations && organizations.length === 1) {
+    memberships.set(organizations[0], legacy.trim());
+    memberships.set(slugify(organizations[0]), legacy.trim());
+  }
+  return memberships;
+}
+function parseCliJson(text) {
+  try {
+    const parsed = JSON.parse(text || "{}");
+    return parsed && typeof parsed === "object" ? parsed : {};
+  } catch (error) {
+    return { parseError: message(error), raw: text };
+  }
+}
+function cliApi(path, options = {}) {
+  const args = ["--yes", "workos@latest", "api", path, "--method", options.method || "GET", "--json"];
+  if (options.data) args.push("--data", JSON.stringify(options.data));
+  if (options.yes) args.push("--yes");
+  const child = spawnSync("npx", args, {
+    encoding: "utf8",
+    env: { ...process.env, WORKOS_MODE: process.env.WORKOS_MODE || "agent" },
+  });
+  const parsed = parseCliJson(child.stdout);
+  return {
+    ok: child.status === 0,
+    status: child.status,
+    data: parsed,
+    stdout: child.stdout,
+    stderr: child.stderr,
+  };
+}
+function dataList(payload) {
+  if (Array.isArray(payload)) return payload;
+  if (Array.isArray(payload?.data)) return payload.data;
+  if (Array.isArray(payload?.list)) return payload.list;
+  return [];
+}
+function encodePathPart(value) {
+  return encodeURIComponent(String(value));
+}
+async function runWithWorkOSCli() {
+  const orgResponse = cliApi("/organizations", { method: "GET" });
+  if (!orgResponse.ok) {
+    out.ok = false;
+    out.errors.push({ operation: "cli.organizations.list", status: orgResponse.status, message: orgResponse.stderr || JSON.stringify(orgResponse.data) });
+    return;
+  }
+  const orgs = dataList(orgResponse.data);
+  const orgByName = new Map(orgs.map((org) => [org.name, org]));
+  const sortedResources = [...payload.manifest.resources].sort((a, b) => {
+    if (a.type === "organization") return -1;
+    if (b.type === "organization") return 1;
+    if (!a.parentExternalId && b.parentExternalId) return -1;
+    if (a.parentExternalId && !b.parentExternalId) return 1;
+    return a.externalId.localeCompare(b.externalId);
+  });
+  for (const resource of sortedResources) {
+    if (resource.type === "organization") {
+      out.resources.push({ externalId: resource.externalId, resourceTypeSlug: resource.type, organizationName: resource.tenant, status: "root-organization" });
+      continue;
+    }
+    const org = orgByName.get(resource.tenant);
+    if (!org?.id) {
+      out.ok = false;
+      out.errors.push({ operation: "organization.lookup", organization: resource.tenant, message: "organization not found in WorkOS environment" });
+      continue;
+    }
+    const getPath = "/authorization/organizations/" + encodePathPart(org.id) + "/resources/" + encodePathPart(resource.type) + "/" + encodePathPart(resource.externalId);
+    const existing = cliApi(getPath, { method: "GET" });
+    if (existing.ok) {
+      out.resources.push({ externalId: resource.externalId, resourceTypeSlug: resource.type, organizationId: org.id, status: "existing", id: existing.data?.id });
+      continue;
+    }
+    const created = cliApi("/authorization/resources", {
+      method: "POST",
+      yes: true,
+      data: {
+        organization_id: org.id,
+        resource_type_slug: resource.type,
+        external_id: resource.externalId,
+        name: resource.name,
+        ...(resource.parentExternalId && resource.parentType !== "organization" ? { parent_resource_external_id: resource.parentExternalId, parent_resource_type_slug: resource.parentType } : {}),
+      },
+    });
+    if (!created.ok) {
+      out.ok = false;
+      out.errors.push({ operation: "resource.create", externalId: resource.externalId, resourceTypeSlug: resource.type, status: created.status, message: created.stderr || JSON.stringify(created.data) });
+      continue;
+    }
+    out.resources.push({ externalId: resource.externalId, resourceTypeSlug: resource.type, organizationId: org.id, status: "created", id: created.data?.id });
+  }
+  if (payload.action === "prove") {
+    const memberships = readMembershipMap(payload.manifest.organizations);
+    for (const scenario of payload.manifest.proofScenarios) {
+      const membershipId = memberships.get(scenario.organization) || memberships.get(slugify(scenario.organization));
+      if (!membershipId) {
+        out.ok = false;
+        out.errors.push({
+          operation: "authorization.check",
+          scenario: scenario.name,
+          organization: scenario.organization,
+          expected: scenario.expected,
+          message: "missing organizationMembershipId for WorkOS FGA proof scenario",
+          env: ["WORKOS_FGA_MEMBERSHIPS_JSON", membershipEnvKey(scenario.organization)],
+        });
+        continue;
+      }
+      const checked = cliApi("/authorization/organization_memberships/" + encodePathPart(membershipId) + "/check", {
+        method: "POST",
+        yes: true,
+        data: {
+          permission_slug: scenario.permission,
+          resource_external_id: scenario.resourceExternalId,
+          resource_type_slug: scenario.resourceTypeSlug,
+        },
+      });
+      if (!checked.ok) {
+        out.ok = false;
+        out.errors.push({ operation: "authorization.check", scenario: scenario.name, status: checked.status, message: checked.stderr || JSON.stringify(checked.data) });
+        continue;
+      }
+      const expectedAuthorized = scenario.expected === "allow";
+      const passed = Boolean(checked.data?.authorized) === expectedAuthorized;
+      if (!passed) out.ok = false;
+      out.checks.push({ name: scenario.name, organization: scenario.organization, expected: scenario.expected, authorized: Boolean(checked.data?.authorized), ok: passed });
+    }
+  }
+}
+try {
+  if (!process.env.WORKOS_API_KEY) {
+    await runWithWorkOSCli();
+    console.log(JSON.stringify(out));
+    process.exit(out.ok ? 0 : 1);
+  }
+  const mod = await import("@workos-inc/node");
+  const WorkOS = mod.WorkOS || mod.default?.WorkOS;
+  if (!WorkOS) throw new Error("@workos-inc/node did not export WorkOS");
+  const workos = new WorkOS(process.env.WORKOS_API_KEY);
+  const orgs = await listAll(await workos.organizations.listOrganizations());
+  const orgByName = new Map(orgs.map((org) => [org.name, org]));
+  const sortedResources = [...payload.manifest.resources].sort((a, b) => {
+    if (a.type === "organization") return -1;
+    if (b.type === "organization") return 1;
+    if (!a.parentExternalId && b.parentExternalId) return -1;
+    if (a.parentExternalId && !b.parentExternalId) return 1;
+    return a.externalId.localeCompare(b.externalId);
+  });
+  for (const resource of sortedResources) {
+    if (resource.type === "organization") {
+      out.resources.push({ externalId: resource.externalId, resourceTypeSlug: resource.type, organizationName: resource.tenant, status: "root-organization" });
+      continue;
+    }
+    const org = orgByName.get(resource.tenant);
+    if (!org) {
+      out.ok = false;
+      out.errors.push({ operation: "organization.lookup", organization: resource.tenant, message: "organization not found in WorkOS environment" });
+      continue;
+    }
+    try {
+      const existing = await workos.authorization.getResourceByExternalId({
+        organizationId: org.id,
+        resourceTypeSlug: resource.type,
+        externalId: resource.externalId,
+      });
+      out.resources.push({ externalId: resource.externalId, resourceTypeSlug: resource.type, organizationId: org.id, status: "existing", id: existing.id });
+    } catch (error) {
+      if (![404, "404"].includes(status(error))) {
+        out.ok = false;
+        out.errors.push({ operation: "resource.get", externalId: resource.externalId, resourceTypeSlug: resource.type, status: status(error), message: message(error) });
+        continue;
+      }
+      try {
+        const created = await workos.authorization.createResource({
+          organizationId: org.id,
+          resourceTypeSlug: resource.type,
+          externalId: resource.externalId,
+          name: resource.name,
+          ...(resource.parentExternalId && resource.parentType !== "organization" ? { parentResourceExternalId: resource.parentExternalId, parentResourceTypeSlug: resource.parentType } : {}),
+        });
+        out.resources.push({ externalId: resource.externalId, resourceTypeSlug: resource.type, organizationId: org.id, status: "created", id: created.id });
+      } catch (createError) {
+        out.ok = false;
+        out.errors.push({ operation: "resource.create", externalId: resource.externalId, resourceTypeSlug: resource.type, status: status(createError), message: message(createError) });
+      }
+    }
+  }
+  if (payload.action === "prove") {
+    const memberships = readMembershipMap(payload.manifest.organizations);
+    for (const scenario of payload.manifest.proofScenarios) {
+      const membershipId = memberships.get(scenario.organization) || memberships.get(slugify(scenario.organization));
+      if (!membershipId) {
+        out.ok = false;
+        out.errors.push({
+          operation: "authorization.check",
+          scenario: scenario.name,
+          organization: scenario.organization,
+          expected: scenario.expected,
+          message: "missing organizationMembershipId for WorkOS FGA proof scenario",
+          env: ["WORKOS_FGA_MEMBERSHIPS_JSON", membershipEnvKey(scenario.organization)],
+        });
+        continue;
+      }
+      try {
+        const check = await workos.authorization.check({
+          organizationMembershipId: membershipId,
+          permissionSlug: scenario.permission,
+          resourceExternalId: scenario.resourceExternalId,
+          resourceTypeSlug: scenario.resourceTypeSlug,
+        });
+        const expectedAuthorized = scenario.expected === "allow";
+        const passed = Boolean(check.authorized) === expectedAuthorized;
+        if (!passed) out.ok = false;
+        out.checks.push({ name: scenario.name, organization: scenario.organization, expected: scenario.expected, authorized: Boolean(check.authorized), ok: passed });
+      } catch (checkError) {
+        out.ok = false;
+        out.errors.push({ operation: "authorization.check", scenario: scenario.name, status: status(checkError), message: message(checkError) });
+      }
+    }
+  }
+} catch (error) {
+  out.ok = false;
+  out.errors.push({ operation: "sdk", message: message(error), status: status(error) });
+}
+console.log(JSON.stringify(out));
+process.exit(out.ok ? 0 : 1);
+`;
+  const command = ["node", "--input-type=module", "-e", script];
+  const displayCommand = ["node", "--input-type=module", "-e", "<forge-workos-fga-sdk>"];
+  const previousPayload = process.env.FORGE_WORKOS_FGA_PAYLOAD;
+  let child: { status: number | null; stdout: string; stderr: string };
+  try {
+    process.env.FORGE_WORKOS_FGA_PAYLOAD = JSON.stringify({ action, manifest });
+    child = runExternalCommand(command, {
+      ...options,
+      commandRunner: options.commandRunner ?? spawnSync,
+    });
+  } finally {
+    if (previousPayload === undefined) {
+      delete process.env.FORGE_WORKOS_FGA_PAYLOAD;
+    } else {
+      process.env.FORGE_WORKOS_FGA_PAYLOAD = previousPayload;
+    }
+  }
+  const parsed = parseJsonObject(child.stdout);
+  return {
+    ok: child.status === 0 && parsed?.ok === true,
+    command: displayCommand,
+    data: parsed ?? {
+      ok: false,
+      errors: [{ operation: "sdk.parse", message: "failed to parse WorkOS FGA SDK output" }],
+    },
+    status: child.status,
+    stdout: child.stdout,
+    stderr: child.stderr,
+  };
+}
+
+function workOSFgaSdkFailureDetail(data: unknown, manifest?: WorkOSFgaManifest): string {
+  const text = JSON.stringify(data);
+  if (text.includes("AuthorizationResourceType not found")) {
+    const missing = extractMissingWorkOSFgaResourceTypes(data, manifest);
+    const suffix = missing.length > 0 ? `: ${missing.join(", ")}` : "";
+    return `WorkOS Authorization API returned missing FGA resource type(s)${suffix}; configure them in hosted WorkOS, then rerun forge workos fga sync --real --json`;
+  }
+  if (text.includes("Cannot add resource to organization resource type")) {
+    return "WorkOS treats organizations as tenant roots, not creatable authorization resources; Forge will keep organization in the graph and skip resource creation for it";
+  }
+  if (text.includes("missing organizationMembershipId") || text.includes("WORKOS_FGA_MEMBERSHIPS_JSON")) {
+    const env = manifest?.organizations.map(fgaMembershipEnvKey).join(", ") || "WORKOS_FGA_MEMBERSHIP_<ORG>";
+    return `WorkOS FGA real proof requires organizationMembershipId values per organization; set WORKOS_FGA_MEMBERSHIPS_JSON or ${env}`;
+  }
+  return "WorkOS Authorization API resource sync failed; inspect workosSdk.errors";
+}
+
+function workOSFgaSdkProofComplete(data: unknown, manifest: WorkOSFgaManifest): boolean {
+  if (!data || typeof data !== "object") return false;
+  const record = data as { ok?: unknown; checks?: unknown; skipped?: unknown; errors?: unknown };
+  if (record.ok !== true) return false;
+  if (Array.isArray(record.errors) && record.errors.length > 0) return false;
+  if (Array.isArray(record.skipped) && record.skipped.length > 0) return false;
+  if (!Array.isArray(record.checks)) return false;
+  const checks = record.checks as Array<{ name?: unknown; ok?: unknown }>;
+  const checkByName = new Map(checks.map((check) => [String(check.name ?? ""), check]));
+  return manifest.proofScenarios.every((scenario) => checkByName.get(scenario.name)?.ok === true);
+}
+
 export interface WorkOSDoctorData {
   seed: WorkOSSeedSummary;
   seedState: WorkOSSeedStateSummary;
+  fgaManifest: WorkOSFgaManifest;
+  fgaState: WorkOSFgaStateSummary;
   activePermissions: string[];
   expectedResourceTypes: string[];
   missingSeedPermissions: string[];
@@ -407,6 +1556,8 @@ function collectWorkOSDoctorData(
 ): WorkOSDoctorData {
   const seed = parseSeedFile(workspaceRoot, preferredSeedPath);
   const seedState = readWorkOSSeedState(workspaceRoot, seed);
+  const fgaManifest = collectWorkOSFgaManifest(workspaceRoot, preferredSeedPath);
+  const fgaState = readWorkOSFgaState(workspaceRoot, fgaManifest);
   const activePermissions = collectPolicyPermissions(workspaceRoot);
   const expectedResourceTypes = collectExpectedResourceTypes(workspaceRoot);
   const missingSeedPermissions = missingValues(activePermissions, seed.permissions);
@@ -417,6 +1568,8 @@ function collectWorkOSDoctorData(
   return {
     seed,
     seedState,
+    fgaManifest,
+    fgaState,
     activePermissions,
     expectedResourceTypes,
     missingSeedPermissions,
@@ -453,6 +1606,8 @@ function collectWorkOSChecks(workspaceRoot: string, preferredSeedPath = DEFAULT_
   const {
     seed,
     seedState,
+    fgaManifest,
+    fgaState,
     activePermissions,
     expectedResourceTypes,
     missingSeedPermissions,
@@ -621,6 +1776,24 @@ function collectWorkOSChecks(workspaceRoot: string, preferredSeedPath = DEFAULT_
             ? `${WORKOS_SEED_STATE_FILE} exists but does not match current ${seed.path}; rerun forge workos seed --file ${seed.path} --json after reviewing seed changes`
             : `${WORKOS_SEED_STATE_FILE} exists but is invalid: ${seedState.diagnostics.join("; ")}`,
     },
+    {
+      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("; ")}`,
+    },
+    {
+      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("; ")}`,
+    },
     {
       name: "authkit-routes",
       ok: includesAll(authRoutes, ["handleWorkOSAuthRequest", "/login", "/callback", "/logout", "/session"]),
@@ -705,6 +1878,7 @@ function seedData(input: {
   seedAlreadyApplied?: boolean;
   seedAlreadyAppliedReason?: string;
   seedStateFile?: string;
+  cliAuth?: WorkOSCliAuthSummary;
   workosCli?: Record<string, unknown>;
   configActions?: WorkOSConfigActionResult[];
   nextCommand?: string;
@@ -720,6 +1894,7 @@ function seedData(input: {
     seedAlreadyApplied: input.seedAlreadyApplied ?? false,
     ...(input.seedAlreadyAppliedReason ? { seedAlreadyAppliedReason: input.seedAlreadyAppliedReason } : {}),
     ...(input.seedStateFile ? { seedStateFile: input.seedStateFile } : {}),
+    ...(input.cliAuth ? { cliAuth: input.cliAuth } : {}),
     ...(input.workosCli ? { workosCli: input.workosCli } : {}),
     configActions: input.configActions ?? [],
     ...(input.nextCommand ? { nextCommand: input.nextCommand } : {}),
@@ -1057,6 +2232,26 @@ export function runWorkOSSeedCommand(options: WorkOSCommandOptions): WorkOSComma
       exitCode: 0,
     };
   }
+  const cliAuth = ensureWorkOSCliAuthForHosted(options);
+  if (!cliAuth.ok) {
+    return {
+      ok: false,
+      kind: "workos-seed",
+      checks: [...checks, workOSCliAuthCheck(cliAuth)],
+      command: cliAuth.loginCommand ?? cliAuth.statusCommand ?? command,
+      applied: false,
+      data: seedData({
+        seed,
+        activePermissions,
+        expectedResourceTypes,
+        unusedSeedPermissions,
+        seedState,
+        cliAuth,
+        nextCommand: `forge workos seed --file ${file} --json`,
+      }),
+      exitCode: 1,
+    };
+  }
   const preparedSeed = prepareSeedFileForWorkOSCli(options.workspaceRoot, seed.path);
   const delegatedCommand = [
     "npx",
@@ -1080,11 +2275,12 @@ export function runWorkOSSeedCommand(options: WorkOSCommandOptions): WorkOSComma
           seed,
           activePermissions,
           expectedResourceTypes,
-          unusedSeedPermissions,
-          seedState,
-          seedFileSanitized: preparedSeed.sanitized,
-          configActions,
-        }),
+        unusedSeedPermissions,
+        seedState,
+        cliAuth,
+        seedFileSanitized: preparedSeed.sanitized,
+        configActions,
+      }),
         exitCode: 1,
       };
     }
@@ -1118,6 +2314,7 @@ export function runWorkOSSeedCommand(options: WorkOSCommandOptions): WorkOSComma
         expectedResourceTypes,
         unusedSeedPermissions,
         seedState: latestSeedState,
+        cliAuth,
         seedFileSanitized: preparedSeed.sanitized,
         seedAlreadyApplied,
         seedAlreadyAppliedReason,
@@ -1141,7 +2338,13 @@ export function runWorkOSSeedCommand(options: WorkOSCommandOptions): WorkOSComma
 export function runWorkOSSetupCommand(options: WorkOSCommandOptions): WorkOSCommandResult {
   const file = options.file ?? DEFAULT_SEED_FILE;
   const checks = collectWorkOSChecks(options.workspaceRoot);
-  const localOk = checks.every((check) => check.ok);
+  const cliAuth = options.real ? ensureWorkOSCliAuthForHosted(options) : undefined;
+  const realEnvChecks = options.real ? collectWorkOSRealEnvChecks(options.workspaceRoot, cliAuth) : [];
+  const allChecks = [...checks, ...realEnvChecks];
+  if (options.real && cliAuth && !cliAuth.ok) {
+    allChecks.push(workOSCliAuthCheck(cliAuth));
+  }
+  const localOk = allChecks.every((check) => check.ok);
   const seed = parseSeedFile(options.workspaceRoot, file);
   const seedState = readWorkOSSeedState(options.workspaceRoot, seed);
   const setupDryRun = options.dryRun || !options.real;
@@ -1151,7 +2354,7 @@ export function runWorkOSSetupCommand(options: WorkOSCommandOptions): WorkOSComm
     return {
       ok: false,
       kind: "workos-setup",
-      checks,
+      checks: allChecks,
       command,
       applied: false,
       data: {
@@ -1159,8 +2362,11 @@ export function runWorkOSSetupCommand(options: WorkOSCommandOptions): WorkOSComm
         real: options.real ?? false,
         seed,
         seedState,
+        ...(cliAuth ? { cliAuth } : {}),
         configActions,
-        nextCommand: "forge workos doctor --json",
+        nextCommand: cliAuth && !cliAuth.ok
+          ? `forge workos setup --real --file ${file} --json`
+          : "forge workos doctor --json",
       },
       exitCode: 1,
     };
@@ -1177,6 +2383,7 @@ export function runWorkOSSetupCommand(options: WorkOSCommandOptions): WorkOSComm
         real: false,
         seed,
         seedState,
+        ...(cliAuth ? { cliAuth } : {}),
         configActions,
         nextCommand: `forge workos setup --real --file ${file} --json`,
       },
@@ -1195,12 +2402,13 @@ export function runWorkOSSetupCommand(options: WorkOSCommandOptions): WorkOSComm
   return {
     ok: seedResult.ok,
     kind: "workos-setup",
-    checks: seedResult.checks,
+    checks: [...seedResult.checks, ...realEnvChecks],
     command: seedResult.command,
     applied: seedResult.ok,
     data: {
       real: true,
       seed,
+      ...(cliAuth ? { cliAuth } : {}),
       seedState: seedResultData.seedState ?? readWorkOSSeedState(options.workspaceRoot, seed),
       seedResult: seedResult.data,
       nextCommand: "forge workos doctor --json",
@@ -1233,6 +2441,9 @@ export function runWorkOSProveCommand(options: WorkOSCommandOptions): WorkOSComm
     real: options.real ?? false,
     file,
   });
+  const setupBlockingChecks = setup.checks
+    .filter((check) => !check.ok)
+    .map((check) => ({ ...check, name: `setup:${check.name}` }));
   const checks: WorkOSCheck[] = [
     ...doctor.checks.map((check) => ({ ...check, name: `doctor:${check.name}` })),
     {
@@ -1242,6 +2453,7 @@ export function runWorkOSProveCommand(options: WorkOSCommandOptions): WorkOSComm
         ? `${file} is valid, app-aware, and ready for hosted application`
         : `${file} failed seed validation before hosted application`,
     },
+    ...setupBlockingChecks,
     {
       name: options.real ? "setup:real" : "setup:dry-run",
       ok: setup.ok,
@@ -1277,7 +2489,320 @@ export function runWorkOSProveCommand(options: WorkOSCommandOptions): WorkOSComm
   };
 }
 
+function collectWorkOSFgaChecks(input: {
+  manifest: WorkOSFgaManifest;
+  state: WorkOSFgaStateSummary;
+  requireState?: boolean;
+  requireRealState?: boolean;
+  requireProof?: boolean;
+}): WorkOSCheck[] {
+  return [
+    {
+      name: "fga-manifest",
+      ok: input.manifest.diagnostics.length === 0,
+      detail: input.manifest.diagnostics.length === 0
+        ? `manifest ${input.manifest.manifestHash.slice(0, 12)} covers ${input.manifest.resourceTypes.length} resource type(s) and ${input.manifest.resources.length} resource(s)`
+        : input.manifest.diagnostics.join("; "),
+    },
+    {
+      name: "fga-resource-types",
+      ok: input.manifest.resourceTypes.length > 0 && input.manifest.resourceTypes.includes("organization"),
+      detail: input.manifest.resourceTypes.length > 0
+        ? `resource types: ${input.manifest.resourceTypes.join(", ")}`
+        : "at least organization plus app resource types are required",
+    },
+    {
+      name: "fga-proof-scenarios",
+      ok: input.manifest.proofScenarios.some((scenario) => scenario.expected === "allow") &&
+        input.manifest.proofScenarios.some((scenario) => scenario.expected === "deny"),
+      detail: `proof scenarios: ${input.manifest.proofScenarios.map((scenario) => `${scenario.name}:${scenario.expected}`).join(", ") || "none"}`,
+    },
+    {
+      name: "fga-state",
+      ok: !input.requireState || Boolean(input.state.exists && input.state.valid && input.state.matchesManifestHash === true),
+      detail: !input.state.exists
+        ? `${WORKOS_FGA_STATE_FILE} is missing`
+        : !input.state.valid
+          ? `${WORKOS_FGA_STATE_FILE} is invalid: ${input.state.diagnostics.join("; ")}`
+        : input.state.matchesManifestHash
+          ? `${WORKOS_FGA_STATE_FILE} matches current manifest`
+          : `${WORKOS_FGA_STATE_FILE} is stale or invalid: ${input.state.diagnostics.join("; ") || "manifest hash mismatch"}`,
+    },
+    {
+      name: "fga-real-state",
+      ok: !input.requireRealState || input.state.mode === "real",
+      detail: input.state.mode === "real"
+        ? `${WORKOS_FGA_STATE_FILE} records real sync/proof mode`
+        : input.requireRealState
+          ? `${WORKOS_FGA_STATE_FILE} must be produced by forge workos fga sync --real --json`
+          : `${WORKOS_FGA_STATE_FILE} real mode not required for this command`,
+    },
+    {
+      name: "fga-proof-state",
+      ok: !input.requireProof || Boolean(input.state.provedAt),
+      detail: input.state.provedAt
+        ? `${WORKOS_FGA_STATE_FILE} records real proof at ${input.state.provedAt}`
+        : input.requireProof
+          ? `${WORKOS_FGA_STATE_FILE} must be produced by forge workos fga prove --real --json`
+          : `${WORKOS_FGA_STATE_FILE} proof timestamp not required for this command`,
+    },
+  ];
+}
+
+export function runWorkOSFgaCommand(options: WorkOSCommandOptions): WorkOSCommandResult {
+  const action = options.fgaAction ?? "doctor";
+  const file = options.file ?? DEFAULT_SEED_FILE;
+  const manifest = collectWorkOSFgaManifest(options.workspaceRoot, file);
+  const initialHostedSetup = workOSFgaHostedSetup(manifest);
+  const setupGuidePath = resolveWorkOSFgaSetupGuidePath(options);
+  const writtenSetupGuidePath = setupGuidePath
+    ? writeWorkOSFgaSetupGuide(options.workspaceRoot, workOSFgaSetupGuide(manifest, initialHostedSetup), setupGuidePath)
+    : undefined;
+  let state = readWorkOSFgaState(options.workspaceRoot, manifest);
+  const command = ["forge", "workos", "fga", action, "--file", file];
+  const real = options.real ?? false;
+  const requireState = action === "prove" || action === "doctor";
+  const requireRealState = real && action !== "plan";
+  const requireProof = real && action === "doctor";
+  const seed = parseSeedFile(options.workspaceRoot, file);
+  const seedState = readWorkOSSeedState(options.workspaceRoot, seed);
+  const checks: WorkOSCheck[] = collectWorkOSFgaChecks({
+    manifest,
+    state,
+    requireState,
+    requireRealState,
+    requireProof,
+  });
+
+  if (action === "plan") {
+    const ok = checks.filter((check) => check.name !== "fga-state" && check.name !== "fga-real-state" && check.name !== "fga-proof-state").every((check) => check.ok);
+    return {
+      ok,
+      kind: "workos-fga",
+      checks,
+      command,
+      applied: false,
+      data: fgaData({
+        action,
+        manifest,
+        state,
+        real,
+        ...(writtenSetupGuidePath ? { setupGuidePath: writtenSetupGuidePath } : {}),
+        nextCommand: `forge workos fga sync --file ${file} --json`,
+      }),
+      exitCode: ok ? 0 : 1,
+    };
+  }
+
+  if (action === "sync") {
+    const cliAuth = real ? ensureWorkOSCliAuthForHosted(options) : undefined;
+    const realChecks: WorkOSCheck[] = real
+      ? [
+          ...(cliAuth && !cliAuth.ok ? [workOSCliAuthCheck(cliAuth)] : []),
+          {
+            name: "fga-seed-state",
+            ok: Boolean(seedState.exists && seedState.valid && seedState.matchesSeedHash === true),
+            detail: seedState.matchesSeedHash
+              ? `${WORKOS_SEED_STATE_FILE} matches ${seed.path}`
+              : `real FGA sync requires hosted seed evidence; run forge workos prove --real --file ${file} --json first`,
+          },
+        ]
+      : [];
+    const allChecks = [...checks.filter((check) => check.name !== "fga-state" && check.name !== "fga-real-state" && check.name !== "fga-proof-state"), ...realChecks];
+    if (!allChecks.every((check) => check.ok)) {
+      return {
+        ok: false,
+        kind: "workos-fga",
+        checks: allChecks,
+        command: cliAuth && !cliAuth.ok ? cliAuth.loginCommand ?? cliAuth.statusCommand : command,
+        applied: false,
+        data: fgaData({
+          action,
+          manifest,
+          state,
+          real,
+          ...(cliAuth ? { cliAuth } : {}),
+          ...(writtenSetupGuidePath ? { setupGuidePath: writtenSetupGuidePath } : {}),
+          nextCommand: real ? `forge workos fga sync --real --file ${file} --json` : `forge workos fga plan --file ${file} --json`,
+        }),
+        exitCode: 1,
+      };
+    }
+    if (options.dryRun) {
+      return {
+        ok: true,
+        kind: "workos-fga",
+        checks: allChecks,
+        command,
+        applied: false,
+        data: fgaData({
+          action,
+          manifest,
+          state,
+          real,
+          ...(cliAuth ? { cliAuth } : {}),
+          ...(writtenSetupGuidePath ? { setupGuidePath: writtenSetupGuidePath } : {}),
+          nextCommand: real ? `forge workos fga sync --real --file ${file} --json` : `forge workos fga sync --file ${file} --json`,
+        }),
+        exitCode: 0,
+      };
+    }
+    const sdk = real ? runWorkOSFgaSdk(options, manifest, "sync") : undefined;
+    if (sdk && !sdk.ok) {
+      return {
+        ok: false,
+        kind: "workos-fga",
+        checks: [
+          ...allChecks,
+          {
+            name: "fga-real-sdk-sync",
+            ok: false,
+            detail: workOSFgaSdkFailureDetail(sdk.data, manifest),
+          },
+        ],
+        command: sdk.command,
+        applied: false,
+        data: fgaData({
+          action,
+          manifest,
+          state,
+          real,
+          ...(cliAuth ? { cliAuth } : {}),
+          workosSdk: sdk.data,
+          ...(writtenSetupGuidePath ? { setupGuidePath: writtenSetupGuidePath } : {}),
+          nextCommand: `forge workos fga sync --real --file ${file} --json`,
+          nextActions: workOSFgaHostedSetup(manifest, sdk.data).nextActions,
+        }),
+        stdout: sdk.stdout,
+        stderr: sdk.stderr,
+        exitCode: 1,
+      };
+    }
+    const stateFile = writeWorkOSFgaState({
+      workspaceRoot: options.workspaceRoot,
+      manifest,
+      mode: real ? "real" : "local",
+      proved: false,
+      ...(sdk ? { sdkOk: sdk.ok, sdk: sdk.data } : {}),
+    });
+    state = readWorkOSFgaState(options.workspaceRoot, manifest);
+    return {
+      ok: true,
+      kind: "workos-fga",
+      checks: collectWorkOSFgaChecks({ manifest, state, requireState: true, requireRealState: real }),
+      command,
+      applied: true,
+      data: fgaData({
+        action,
+        manifest,
+        state,
+        real,
+        ...(cliAuth ? { cliAuth } : {}),
+        ...(sdk ? { workosSdk: sdk.data } : {}),
+        stateFile,
+        ...(writtenSetupGuidePath ? { setupGuidePath: writtenSetupGuidePath } : {}),
+        nextCommand: real ? `forge workos fga prove --real --file ${file} --json` : `forge workos fga prove --file ${file} --json`,
+      }),
+      exitCode: 0,
+    };
+  }
+
+  if (action === "prove") {
+    const cliAuth = real ? ensureWorkOSCliAuthForHosted(options) : undefined;
+    const sdk = real && state.exists && state.valid && state.matchesManifestHash === true && state.mode === "real"
+      ? runWorkOSFgaSdk(options, manifest, "prove")
+      : undefined;
+    const sdkProofComplete = sdk ? workOSFgaSdkProofComplete(sdk.data, manifest) : false;
+    const proofChecks: WorkOSCheck[] = [
+      ...checks,
+      ...(cliAuth && !cliAuth.ok ? [workOSCliAuthCheck(cliAuth)] : []),
+      ...(sdk
+        ? [
+            {
+              name: "fga-real-sdk-proof",
+              ok: sdk.ok && sdkProofComplete,
+              detail: sdk.ok && sdkProofComplete
+                ? "WorkOS Authorization API resource sync/check proof completed for every scenario"
+                : workOSFgaSdkFailureDetail(sdk.data, manifest),
+            },
+          ]
+        : real
+          ? [
+              {
+                name: "fga-real-sdk-proof",
+                ok: false,
+                detail: "real FGA proof requires a fresh real FGA state from forge workos fga sync --real --json",
+              },
+            ]
+          : []),
+      {
+        name: "fga-cross-tenant-proof",
+        ok: manifest.proofScenarios.some((scenario) => scenario.name.includes("cross-tenant") && scenario.expected === "deny"),
+        detail: "FGA proof includes cross-tenant denial scenario using resourceExternalId and resourceTypeSlug",
+      },
+      {
+        name: "fga-authorization-api-shape",
+        ok: true,
+        detail: "proof contract uses organizationMembershipId, resourceExternalId, resourceTypeSlug, and permission slugs",
+      },
+    ];
+    const ok = proofChecks.every((check) => check.ok);
+    const stateFile = ok && !options.dryRun
+      ? writeWorkOSFgaState({
+        workspaceRoot: options.workspaceRoot,
+        manifest,
+        mode: real ? "real" : "local",
+        proved: true,
+        ...(sdk ? { sdkOk: sdk.ok, sdk: sdk.data } : {}),
+      })
+      : undefined;
+    state = stateFile ? readWorkOSFgaState(options.workspaceRoot, manifest) : state;
+    return {
+      ok,
+      kind: "workos-fga",
+      checks: proofChecks,
+      command: cliAuth && !cliAuth.ok ? cliAuth.loginCommand ?? cliAuth.statusCommand : command,
+      applied: Boolean(ok && !options.dryRun),
+      data: fgaData({
+        action,
+        manifest,
+        state,
+        real,
+        ...(cliAuth ? { cliAuth } : {}),
+        ...(sdk ? { workosSdk: sdk.data } : {}),
+        ...(stateFile ? { stateFile } : {}),
+        ...(writtenSetupGuidePath ? { setupGuidePath: writtenSetupGuidePath } : {}),
+        nextCommand: ok ? "forge deploy check --production --json" : `forge workos fga sync${real ? " --real" : ""} --file ${file} --json`,
+      }),
+      stdout: sdk?.stdout,
+      stderr: sdk?.stderr,
+      exitCode: ok ? 0 : 1,
+    };
+  }
+
+  const ok = checks.every((check) => check.ok);
+  return {
+    ok,
+    kind: "workos-fga",
+    checks,
+    command,
+    applied: false,
+    data: fgaData({
+      action,
+      manifest,
+      state,
+      real,
+      ...(writtenSetupGuidePath ? { setupGuidePath: writtenSetupGuidePath } : {}),
+      nextCommand: state.exists ? `forge workos fga prove --file ${file} --json` : `forge workos fga sync --file ${file} --json`,
+    }),
+    exitCode: ok ? 0 : 1,
+  };
+}
+
 export function runWorkOSCommand(options: WorkOSCommandOptions): WorkOSCommandResult {
+  if (options.subcommand === "fga") {
+    return runWorkOSFgaCommand(options);
+  }
   if (options.subcommand === "install") {
     return runWorkOSInstallCommand(options);
   }
@@ -1301,6 +2826,29 @@ export function formatWorkOSHuman(result: WorkOSCommandResult): string {
     result.ok ? "WorkOS: ok" : "WorkOS: needs attention",
     ...result.checks.map((check) => `${check.ok ? "ok" : "fail"} ${check.name}: ${check.detail}`),
   ];
+  const dataObject = result.data && typeof result.data === "object"
+    ? result.data as {
+      cliAuth?: WorkOSCliAuthSummary;
+      seedResult?: { cliAuth?: WorkOSCliAuthSummary };
+      setup?: { cliAuth?: WorkOSCliAuthSummary; seedResult?: { cliAuth?: WorkOSCliAuthSummary } };
+    }
+    : {};
+  const cliAuth = dataObject.cliAuth ?? dataObject.seedResult?.cliAuth ?? dataObject.setup?.cliAuth ?? dataObject.setup?.seedResult?.cliAuth;
+  if (cliAuth) {
+    if (cliAuth.ok && cliAuth.method === "cli") {
+      lines.push(`WorkOS CLI authenticated${cliAuth.email ? ` as ${cliAuth.email}` : ""}; hosted setup can proceed without opening the dashboard.`);
+    } else if (!cliAuth.ok && cliAuth.loginInstructions) {
+      lines.push("WorkOS CLI login required before hosted setup can proceed.");
+      if (cliAuth.loginInstructions.url) {
+        lines.push(`open: ${cliAuth.loginInstructions.url}`);
+      }
+      if (cliAuth.loginInstructions.code) {
+        lines.push(`code: ${cliAuth.loginInstructions.code}`);
+      }
+    } else if (cliAuth.method === "api-key") {
+      lines.push("WorkOS hosted setup will use WORKOS_API_KEY; CLI browser login is optional.");
+    }
+  }
   if (result.command) {
     lines.push(`command: ${result.command.join(" ")}`);
   }
@@ -1362,5 +2910,25 @@ export function formatWorkOSHuman(result: WorkOSCommandResult): string {
       lines.push("WorkOS proof failed; inspect doctor, seed, and setup details.");
     }
   }
+  if (result.kind === "workos-fga") {
+    const data = result.data && typeof result.data === "object"
+      ? result.data as { action?: string; real?: boolean; nextCommand?: string; stateFile?: string; setupGuidePath?: string; nextActions?: string[] }
+      : {};
+    if (data.setupGuidePath) {
+      lines.push(`FGA setup guide: ${data.setupGuidePath}`);
+    }
+    if (result.ok && data.action === "plan") {
+      lines.push(`WorkOS FGA plan passed; run ${data.nextCommand ?? "forge workos fga sync --json"}.`);
+    } else if (result.ok && data.action === "sync") {
+      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) {
+      lines.push("WorkOS FGA check failed; inspect manifest diagnostics, seed coverage, and FGA state.");
+      for (const action of data.nextActions ?? []) {
+        lines.push(`  - ${action}`);
+      }
+    }
+  }
   return `${lines.join("\n")}\n`;
 }