forgeos 0.1.0-alpha.53 → 0.1.0-alpha.55

package/AGENTS.md

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

package/CHANGELOG.md

@@ -1,5 +1,39 @@
 # forgeos
 
+## 0.1.0-alpha.55
+
+### Patch Changes
+
+- Make WorkOS FGA opt-in instead of part of the default auth adapter path.
+
+  - `forge add auth workos` now generates the AuthKit/RBAC/permission-claims
+    adapter, seed, policies, tenant claim mapping, webhook helpers, and React
+    bridge without WorkOS FGA resource helpers by default.
+  - `forge add auth workos --with-fga` keeps generating the optional WorkOS
+    Authorization/FGA resource graph helpers, `resource_types` seed metadata,
+    cache/telemetry helpers, and cross-tenant resource guard.
+  - `forge workos doctor` and `forge workos seed` now treat `resource_types`
+    and FGA state as optional unless the app has opted into FGA artifacts.
+  - `forge deploy check --production` no longer blocks ordinary WorkOS apps on
+    `workos-fga-proof`; it still requires FGA sync/proof when FGA helpers or
+    FGA state are present.
+
+## 0.1.0-alpha.54
+
+### Patch Changes
+
+- Add a machine-readable WorkOS FGA hosted setup artifact.
+
+  - `forge workos fga plan --write --json` and real sync failures that write
+    `.forge/workos-fga-setup.md` now also write
+    `.forge/workos-fga-setup.json`.
+  - The JSON artifact includes the derived resource types, hosted setup
+    boundary, rerun commands, docs, unsupported automation notes, and paired
+    Markdown/JSON paths so agents and CI can consume the FGA handoff without
+    parsing Markdown.
+  - Human output now prints both the Markdown guide and JSON setup artifact
+    paths when they are written.
+
 ## 0.1.0-alpha.53
 
 ### Patch Changes

package/docs/changelog.md

@@ -6,6 +6,27 @@ The canonical source file in the repository is `CHANGELOG.md`.
 
 ## Unreleased
 
+## 0.1.0-alpha.55
+
+- `forge add auth workos` now defaults to AuthKit/RBAC, permission claims,
+  Forge policies, tenant claim mapping, seed, webhooks, and frontend bridge
+  without generating WorkOS FGA resource helpers.
+- `forge add auth workos --with-fga` enables the optional WorkOS FGA resource
+  graph helpers and `resource_types` seed metadata for apps that need
+  resource-level authorization.
+- WorkOS doctor/seed/deploy checks now treat FGA as optional unless the app has
+  FGA artifacts or FGA state, so normal WorkOS apps are gated by AuthKit, RBAC,
+  hosted seed evidence, policies, and tenant proof instead of mandatory FGA
+  proof.
+
+## 0.1.0-alpha.54
+
+- WorkOS FGA setup writes now produce a paired machine-readable
+  `.forge/workos-fga-setup.json` artifact alongside the Markdown guide.
+- The JSON artifact includes derived resource types, hosted setup boundary,
+  rerun commands, docs, unsupported automation notes, and paired artifact paths
+  for agents and CI.
+
 ## 0.1.0-alpha.53
 
 - `forge workos fga doctor --json` now distinguishes local FGA proof timestamps

package/package.json

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

package/src/forge/_generated/releaseManifest.ts

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

package/src/forge/cli/deploy.ts

@@ -101,6 +101,12 @@ function hasWorkOSIntegration(workspaceRoot: string): boolean {
     nodeFileSystem.exists(join(workspaceRoot, "src/policies.workos.ts"));
 }
 
+function hasWorkOSFgaIntegration(workspaceRoot: string): boolean {
+  return nodeFileSystem.exists(join(workspaceRoot, `${GENERATED_DIR}/integrations/workos/fga.ts`)) ||
+    nodeFileSystem.exists(join(workspaceRoot, `${GENERATED_DIR}/integrations/workos/resource-map.ts`)) ||
+    nodeFileSystem.exists(join(workspaceRoot, ".workos-fga-state.json"));
+}
+
 function readJsonFile<T>(workspaceRoot: string, relative: string): T | null {
   const absolute = join(workspaceRoot, relative);
   if (!nodeFileSystem.exists(absolute)) return null;
@@ -821,6 +827,7 @@ async function buildChecks(options: DeployCommandOptions): Promise<DeployCommand
     },
   });
   if (hasWorkOSIntegration(options.workspaceRoot)) {
+    const workosFgaEnabled = hasWorkOSFgaIntegration(options.workspaceRoot);
     const workosDoctor = await withDeployEnv(options.workspaceRoot, async () =>
       runWorkOSCommand({
         subcommand: "doctor",
@@ -835,7 +842,7 @@ async function buildChecks(options: DeployCommandOptions): Promise<DeployCommand
       ok: workosDoctor.exitCode === 0,
       severity: options.production ? "error" : "warning",
       message: workosDoctor.exitCode === 0
-        ? "WorkOS adapter files, seed, claims, policies, and FGA bridge are app-aware"
+        ? `WorkOS adapter files, seed, claims, policies, and tenant guards are app-aware${workosFgaEnabled ? " with FGA enabled" : ""}`
         : "WorkOS adapter is incomplete for this app; run forge workos doctor --json",
       command: "forge workos doctor --json",
       details: workosDoctor.checks,
@@ -855,27 +862,37 @@ async function buildChecks(options: DeployCommandOptions): Promise<DeployCommand
       command: "forge workos prove --real --file workos-seed.yml --json",
       details: seedState,
     });
-    const workosFgaDoctor = await withDeployEnv(options.workspaceRoot, async () =>
-      runWorkOSCommand({
-        subcommand: "fga",
-        fgaAction: "doctor",
-        workspaceRoot: options.workspaceRoot,
-        json: true,
-        yes: false,
-        dryRun: true,
-        real: options.production,
-      })
-    );
-    checks.push({
-      name: "workos-fga-proof",
-      ok: !options.production || workosFgaDoctor.exitCode === 0,
-      severity: options.production ? "error" : "warning",
-      message: workosFgaDoctor.exitCode === 0
-        ? "WorkOS FGA resource graph state matches the current app contract and seed"
-        : "WorkOS production deploy requires FGA graph sync/proof evidence matching the current app",
-      command: "forge workos fga prove --real --file workos-seed.yml --json",
-      details: workosFgaDoctor.data,
-    });
+    if (workosFgaEnabled) {
+      const workosFgaDoctor = await withDeployEnv(options.workspaceRoot, async () =>
+        runWorkOSCommand({
+          subcommand: "fga",
+          fgaAction: "doctor",
+          workspaceRoot: options.workspaceRoot,
+          json: true,
+          yes: false,
+          dryRun: true,
+          real: options.production,
+        })
+      );
+      checks.push({
+        name: "workos-fga-proof",
+        ok: !options.production || workosFgaDoctor.exitCode === 0,
+        severity: options.production ? "error" : "warning",
+        message: workosFgaDoctor.exitCode === 0
+          ? "WorkOS FGA resource graph state matches the current app contract and seed"
+          : "WorkOS production deploy requires FGA graph sync/proof evidence matching the current app because FGA helpers are enabled",
+        command: "forge workos fga prove --real --file workos-seed.yml --json",
+        details: workosFgaDoctor.data,
+      });
+    } else {
+      checks.push({
+        name: "workos-fga-optional",
+        ok: true,
+        severity: "warning",
+        message: "WorkOS FGA is not enabled; production deploy is gated by AuthKit, RBAC permission claims, Forge policies, tenant proof, and hosted seed evidence",
+        command: "forge add auth workos --with-fga",
+      });
+    }
   }
   const tenantProofRequired = auth.requiresTenant || hasWorkOSIntegration(options.workspaceRoot);
   const tenantProof = tenantProofRequired

package/src/forge/cli/main.ts

@@ -38,11 +38,12 @@ function formatHelp(): string {
     "  forge auth check --production --json  Fail unless auth is jwt/oidc production-ready",
     "  forge authmd check --json   Check public/auth.md drift for CI and agent-ready apps",
     "  forge workos install --yes --json  Delegate AuthKit setup to npx --yes workos@latest install",
-    "  forge workos doctor --json  Check WorkOS AuthKit/FGA files, claims, seed, webhook, and tenant guards",
+    "  forge workos doctor --json  Check WorkOS AuthKit/RBAC files, claims, seed, webhook, and tenant guards",
     "  forge workos doctor --yes --json  Run local checks, then delegate to npx --yes workos@latest doctor",
     "  forge workos seed --file workos-seed.yml --dry-run --json  Validate WorkOS seed without hosted changes",
-    "  forge workos prove --file workos-seed.yml --json  Prove local WorkOS/AuthKit/FGA/seed readiness without dashboard changes",
+    "  forge workos prove --file workos-seed.yml --json  Prove local WorkOS/AuthKit/RBAC/seed readiness without dashboard changes",
     "  forge workos setup --real --file workos-seed.yml --json  Apply redirect/CORS/homepage config and seed WorkOS without dashboard",
+    "  forge add auth workos --with-fga  Add optional WorkOS FGA resource-level authorization helpers",
     "  forge workos fga plan --json  Derive the WorkOS FGA resource graph and proof scenarios from the app",
     "  forge workos fga plan --write --json  Write .forge/workos-fga-setup.md for hosted FGA resource type setup",
     "  forge workos fga sync --json  Record an idempotent local FGA graph state for deploy gates",

package/src/forge/cli/parse.ts

@@ -822,6 +822,7 @@ function parseAddOptions(
       parseOptionValue(args, "--sandbox-backend"),
     ),
     allowScripts: parseFlag(args, "--allow-scripts"),
+    withFga: parseFlag(args, "--with-fga"),
     mode,
     installWorkspace: parseOptionValue(args, "--workspace"),
     packageTarget: frontend && !backend ? "frontend" : backend ? "backend" : undefined,
@@ -3117,6 +3118,7 @@ export function hasUnknownOption(argv: string[]): string | null {
     "--with-livequery",
     "--with-react",
     "--with-ui",
+    "--with-fga",
     "--with-tests",
     "--with-create-form",
     "--write",

package/src/forge/cli/workos.ts

@@ -57,6 +57,7 @@ const GENERATED_SEED_FILE = `${GENERATED_DIR}/integrations/workos/workos-seed.ym
 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";
+const WORKOS_FGA_SETUP_PLAN_FILE = ".forge/workos-fga-setup.json";
 
 function runExternalCommand(
   command: string[],
@@ -84,6 +85,12 @@ function exists(root: string, path: string): boolean {
   return existsSync(join(root, path));
 }
 
+function hasWorkOSFgaArtifacts(root: string): boolean {
+  return exists(root, `${GENERATED_DIR}/integrations/workos/fga.ts`) ||
+    exists(root, `${GENERATED_DIR}/integrations/workos/resource-map.ts`) ||
+    exists(root, WORKOS_FGA_STATE_FILE);
+}
+
 function readJson(root: string, path: string): unknown | null {
   const absolute = join(root, path);
   if (!existsSync(absolute)) {
@@ -287,7 +294,6 @@ export function parseSeedFile(workspaceRoot: string, preferredPath = DEFAULT_SEE
 
   if (permissions.size === 0) diagnostics.push("no permission slugs found");
   if (roles.size === 0) diagnostics.push("no role slugs found");
-  if (resourceTypes.size === 0) diagnostics.push("no resource_types slugs found");
   if (organizations.size === 0) diagnostics.push("no organizations found");
 
   return {
@@ -714,7 +720,16 @@ export interface WorkOSFgaResourceTypeSetup {
 }
 
 export interface WorkOSFgaSetupGuide {
+  schemaVersion: "0.1.0";
+  kind: "workos-fga-setup";
   resourceTypes: WorkOSFgaResourceTypeSetup[];
+  hostedSetup: WorkOSFgaHostedSetup;
+  commands: {
+    plan: string;
+    syncReal: string;
+    proveReal: string;
+    deployCheck: string;
+  };
   markdown: string;
   docs: string[];
   unsupportedAutomation: string[];
@@ -1196,7 +1211,16 @@ function workOSFgaSetupGuide(manifest: WorkOSFgaManifest, hostedSetup: WorkOSFga
     "",
   ].join("\n");
   return {
+    schemaVersion: "0.1.0",
+    kind: "workos-fga-setup",
     resourceTypes,
+    hostedSetup,
+    commands: {
+      plan: "forge workos fga plan --file workos-seed.yml --write --json",
+      syncReal: "forge workos fga sync --real --file workos-seed.yml --json",
+      proveReal: "forge workos fga prove --real --file workos-seed.yml --json",
+      deployCheck: "forge deploy check --production --json",
+    },
     markdown,
     docs: hostedSetup.docs,
     unsupportedAutomation: [
@@ -1214,16 +1238,34 @@ function resolveWorkOSFgaSetupGuidePath(options: WorkOSCommandOptions): string |
   return candidate && candidate !== "true" && !candidate.startsWith("--") ? candidate : WORKOS_FGA_SETUP_GUIDE_FILE;
 }
 
+function workOSFgaSetupPlanPath(markdownPath: string): string {
+  if (markdownPath === WORKOS_FGA_SETUP_GUIDE_FILE) {
+    return WORKOS_FGA_SETUP_PLAN_FILE;
+  }
+  return markdownPath.endsWith(".md")
+    ? `${markdownPath.slice(0, -3)}.json`
+    : `${markdownPath}.json`;
+}
+
 function writeWorkOSFgaSetupGuide(
   workspaceRoot: string,
   guide: WorkOSFgaSetupGuide,
   preferredPath = WORKOS_FGA_SETUP_GUIDE_FILE,
-): string {
+): { markdownPath: string; jsonPath: 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;
+  const jsonPath = workOSFgaSetupPlanPath(relativePath);
+  const absoluteJsonPath = join(workspaceRoot, jsonPath);
+  mkdirSync(dirname(absoluteJsonPath), { recursive: true });
+  const { markdown: _markdown, ...jsonGuide } = guide;
+  writeFileSync(absoluteJsonPath, `${JSON.stringify({
+    ...jsonGuide,
+    markdownPath: relativePath,
+    jsonPath,
+  }, null, 2)}\n`, "utf8");
+  return { markdownPath: relativePath, jsonPath };
 }
 
 function fgaData(input: {
@@ -1240,6 +1282,7 @@ function fgaData(input: {
   nextCommand?: string;
   nextActions?: string[];
   setupGuidePath?: string;
+  setupGuideJsonPath?: string;
 }): Record<string, unknown> {
   const hostedSetup = workOSFgaHostedSetup(input.manifest, input.workosSdk);
   const setupGuide = workOSFgaSetupGuide(input.manifest, hostedSetup);
@@ -1259,6 +1302,7 @@ function fgaData(input: {
     ...(input.workosSdk ? { workosSdk: input.workosSdk } : {}),
     ...(input.stateFile ? { stateFile: input.stateFile } : {}),
     ...(input.setupGuidePath ? { setupGuidePath: input.setupGuidePath } : {}),
+    ...(input.setupGuideJsonPath ? { setupGuideJsonPath: input.setupGuideJsonPath } : {}),
     nextCommand: input.nextCommand,
     nextActions: input.nextActions ?? hostedSetup.nextActions,
     notes: [
@@ -1703,6 +1747,7 @@ function collectWorkOSChecks(workspaceRoot: string, preferredSeedPath = DEFAULT_
   const authRoutes = readText(workspaceRoot, `${GENERATED_DIR}/integrations/workos/auth-routes.ts`);
   const fga = readText(workspaceRoot, `${GENERATED_DIR}/integrations/workos/fga.ts`);
   const resourceMap = readText(workspaceRoot, `${GENERATED_DIR}/integrations/workos/resource-map.ts`);
+  const fgaEnabled = hasWorkOSFgaArtifacts(workspaceRoot);
   const httpHandler = readText(workspaceRoot, `${GENERATED_DIR}/integrations/workos/http-handler.ts`);
   const policies = readText(workspaceRoot, "src/policies.workos.ts");
   const session = readText(workspaceRoot, `${GENERATED_DIR}/integrations/workos/session.ts`);
@@ -1803,7 +1848,7 @@ function collectWorkOSChecks(workspaceRoot: string, preferredSeedPath = DEFAULT_
       name: "seed-file",
       ok: seed.exists,
       detail: seed.exists
-        ? `${seed.path} exists with ${seed.permissions.length} permission(s), ${seed.roles.length} role(s), ${seed.resourceTypes.length} resource type(s)`
+        ? `${seed.path} exists with ${seed.permissions.length} permission(s), ${seed.roles.length} role(s), ${seed.resourceTypes.length} optional FGA resource type(s)`
         : `${DEFAULT_SEED_FILE} or ${GENERATED_SEED_FILE} is required`,
     },
     {
@@ -1832,11 +1877,13 @@ function collectWorkOSChecks(workspaceRoot: string, preferredSeedPath = DEFAULT_
     },
     {
       name: "seed-resource-types",
-      ok: seed.resourceTypes.length > 0 &&
-        (expectedResourceTypes.length === 0 || missingSeedResources.length === 0),
-      detail: missingSeedResources.length === 0
-        ? `seed resource_types cover app graph: ${expectedResourceTypes.length > 0 ? expectedResourceTypes.join(", ") : seed.resourceTypes.join(", ")}`
-        : `seed missing resource_type(s) for app graph: ${missingSeedResources.join(", ")}`,
+      ok: !fgaEnabled || (seed.resourceTypes.length > 0 &&
+        (expectedResourceTypes.length === 0 || missingSeedResources.length === 0)),
+      detail: !fgaEnabled
+        ? "FGA is not enabled; resource_types are optional for AuthKit/RBAC apps"
+        : missingSeedResources.length === 0
+          ? `seed resource_types cover app graph: ${expectedResourceTypes.length > 0 ? expectedResourceTypes.join(", ") : seed.resourceTypes.join(", ")}`
+          : `seed missing resource_type(s) for app graph: ${missingSeedResources.join(", ")}`,
     },
     {
       name: "seed-auth-config",
@@ -1858,21 +1905,25 @@ function collectWorkOSChecks(workspaceRoot: string, preferredSeedPath = DEFAULT_
     },
     {
       name: "fga-plan",
-      ok: fgaManifest.diagnostics.length === 0,
-      detail: fgaManifest.diagnostics.length === 0
-        ? `FGA plan covers ${fgaManifest.resourceTypes.length} resource type(s), ${fgaManifest.resources.length} resource(s), and ${fgaManifest.proofScenarios.length} proof scenario(s)`
-        : `FGA plan has gap(s): ${fgaManifest.diagnostics.join("; ")}`,
+      ok: !fgaEnabled || fgaManifest.diagnostics.length === 0,
+      detail: !fgaEnabled
+        ? "FGA is not enabled; run forge add auth workos --with-fga for resource-level WorkOS Authorization"
+        : fgaManifest.diagnostics.length === 0
+          ? `FGA plan covers ${fgaManifest.resourceTypes.length} resource type(s), ${fgaManifest.resources.length} resource(s), and ${fgaManifest.proofScenarios.length} proof scenario(s)`
+          : `FGA plan has gap(s): ${fgaManifest.diagnostics.join("; ")}`,
     },
     {
       name: "fga-state",
       ok: true,
-      detail: !fgaState.exists
-        ? `${WORKOS_FGA_STATE_FILE} not found; run forge workos fga sync --json before production deploy`
-        : fgaState.matchesManifestHash
-          ? `${WORKOS_FGA_STATE_FILE} matches current FGA manifest${fgaState.mode === "real" ? " in real mode" : ""}`
-          : fgaState.valid
-            ? `${WORKOS_FGA_STATE_FILE} exists but does not match current FGA manifest; rerun forge workos fga sync --json`
-            : `${WORKOS_FGA_STATE_FILE} exists but is invalid: ${fgaState.diagnostics.join("; ")}`,
+      detail: !fgaEnabled
+        ? "FGA is not enabled; no FGA state file is required"
+        : !fgaState.exists
+          ? `${WORKOS_FGA_STATE_FILE} not found; run forge workos fga sync --json before production deploy`
+          : fgaState.matchesManifestHash
+            ? `${WORKOS_FGA_STATE_FILE} matches current FGA manifest${fgaState.mode === "real" ? " in real mode" : ""}`
+            : fgaState.valid
+              ? `${WORKOS_FGA_STATE_FILE} exists but does not match current FGA manifest; rerun forge workos fga sync --json`
+              : `${WORKOS_FGA_STATE_FILE} exists but is invalid: ${fgaState.diagnostics.join("; ")}`,
     },
     {
       name: "authkit-routes",
@@ -1896,7 +1947,7 @@ function collectWorkOSChecks(workspaceRoot: string, preferredSeedPath = DEFAULT_
     },
     {
       name: "fga-bridge",
-      ok: includesAll(resourceMap, [
+      ok: !fgaEnabled || (includesAll(resourceMap, [
         "canWorkOS",
         "assertWorkOSResourceTenant",
         "FORGE_WORKOS_CROSS_TENANT_RESOURCE",
@@ -1906,8 +1957,10 @@ function collectWorkOSChecks(workspaceRoot: string, preferredSeedPath = DEFAULT_
         "permissionSlug",
         "resourceExternalId",
       ]) &&
-        includesAll(fga, ["forgeWorkOSResourceTypes"]),
-      detail: "WorkOS FGA resource-map bridge exists with sync, cache, telemetry, official check shape, and cross-tenant guard",
+        includesAll(fga, ["forgeWorkOSResourceTypes"])),
+      detail: fgaEnabled
+        ? "WorkOS FGA resource-map bridge exists with sync, cache, telemetry, official check shape, and cross-tenant guard"
+        : "FGA bridge is optional and not enabled for this WorkOS AuthKit/RBAC app",
     },
     {
       name: "policies",
@@ -2237,6 +2290,7 @@ export function runWorkOSSeedCommand(options: WorkOSCommandOptions): WorkOSComma
   const missingSeedPermissions = missingValues(activePermissions, seed.permissions);
   const missingSeedResources = missingValues(expectedResourceTypes, seed.resourceTypes);
   const unusedSeedPermissions = seed.permissions.filter((permission) => !activePermissions.includes(permission));
+  const fgaEnabled = hasWorkOSFgaArtifacts(options.workspaceRoot);
   const checks = [
     {
       name: "seed-file",
@@ -2246,7 +2300,9 @@ export function runWorkOSSeedCommand(options: WorkOSCommandOptions): WorkOSComma
     {
       name: "seed-yaml-shape",
       ok: seed.valid,
-      detail: seed.valid ? "seed contains permissions, roles, resource_types, and organizations" : seed.diagnostics.join("; "),
+      detail: seed.valid
+        ? `seed contains permissions, roles, organizations${seed.resourceTypes.length > 0 ? ", and optional FGA resource_types" : ""}`
+        : seed.diagnostics.join("; "),
     },
     {
       name: "seed-policy-coverage",
@@ -2266,10 +2322,12 @@ export function runWorkOSSeedCommand(options: WorkOSCommandOptions): WorkOSComma
     },
     {
       name: "seed-resource-coverage",
-      ok: missingSeedResources.length === 0,
-      detail: missingSeedResources.length === 0
-        ? `seed covers app resource type(s): ${expectedResourceTypes.join(", ") || "none required"}`
-        : `seed missing resource type(s): ${missingSeedResources.join(", ")}`,
+      ok: !fgaEnabled || missingSeedResources.length === 0,
+      detail: !fgaEnabled
+        ? "FGA is not enabled; seed resource type coverage is not required"
+        : missingSeedResources.length === 0
+          ? `seed covers app resource type(s): ${expectedResourceTypes.join(", ") || "none required"}`
+          : `seed missing resource type(s): ${missingSeedResources.join(", ")}`,
     },
     {
       name: "seed-hosted-config",
@@ -2764,9 +2822,12 @@ export function runWorkOSFgaCommand(options: WorkOSCommandOptions): WorkOSComman
   const manifest = collectWorkOSFgaManifest(options.workspaceRoot, file);
   const initialHostedSetup = workOSFgaHostedSetup(manifest);
   const setupGuidePath = resolveWorkOSFgaSetupGuidePath(options);
-  const writtenSetupGuidePath = setupGuidePath
+  const writtenSetupGuide = setupGuidePath
     ? writeWorkOSFgaSetupGuide(options.workspaceRoot, workOSFgaSetupGuide(manifest, initialHostedSetup), setupGuidePath)
     : undefined;
+  const writtenSetupGuideData = writtenSetupGuide
+    ? { setupGuidePath: writtenSetupGuide.markdownPath, setupGuideJsonPath: writtenSetupGuide.jsonPath }
+    : {};
   let state = readWorkOSFgaState(options.workspaceRoot, manifest);
   const command = ["forge", "workos", "fga", action, "--file", file];
   const real = options.real ?? false;
@@ -2798,7 +2859,7 @@ export function runWorkOSFgaCommand(options: WorkOSCommandOptions): WorkOSComman
         state,
         seedState,
         real,
-        ...(writtenSetupGuidePath ? { setupGuidePath: writtenSetupGuidePath } : {}),
+        ...writtenSetupGuideData,
         nextCommand: `forge workos fga sync --file ${file} --json`,
       }),
       exitCode: ok ? 0 : 1,
@@ -2835,7 +2896,7 @@ export function runWorkOSFgaCommand(options: WorkOSCommandOptions): WorkOSComman
           seedState,
           real,
           ...(cliAuth ? { cliAuth } : {}),
-          ...(writtenSetupGuidePath ? { setupGuidePath: writtenSetupGuidePath } : {}),
+          ...writtenSetupGuideData,
           nextCommand: real ? `forge workos fga sync --real --file ${file} --json` : `forge workos fga plan --file ${file} --json`,
         }),
         exitCode: 1,
@@ -2856,7 +2917,7 @@ export function runWorkOSFgaCommand(options: WorkOSCommandOptions): WorkOSComman
           seedState,
           real,
           ...(cliAuth ? { cliAuth } : {}),
-          ...(writtenSetupGuidePath ? { setupGuidePath: writtenSetupGuidePath } : {}),
+          ...writtenSetupGuideData,
           nextCommand: real ? `forge workos fga sync --real --file ${file} --json` : `forge workos fga sync --file ${file} --json`,
         }),
         exitCode: 0,
@@ -2886,7 +2947,7 @@ export function runWorkOSFgaCommand(options: WorkOSCommandOptions): WorkOSComman
           real,
           ...(cliAuth ? { cliAuth } : {}),
           workosSdk: sdk.data,
-          ...(writtenSetupGuidePath ? { setupGuidePath: writtenSetupGuidePath } : {}),
+          ...writtenSetupGuideData,
           nextCommand: `forge workos fga sync --real --file ${file} --json`,
           nextActions: workOSFgaHostedSetup(manifest, sdk.data).nextActions,
         }),
@@ -2919,7 +2980,7 @@ export function runWorkOSFgaCommand(options: WorkOSCommandOptions): WorkOSComman
         ...(cliAuth ? { cliAuth } : {}),
         ...(sdk ? { workosSdk: sdk.data } : {}),
         stateFile,
-        ...(writtenSetupGuidePath ? { setupGuidePath: writtenSetupGuidePath } : {}),
+        ...writtenSetupGuideData,
         nextCommand: real ? `forge workos fga prove --real --file ${file} --json` : `forge workos fga prove --file ${file} --json`,
       }),
       exitCode: 0,
@@ -2992,7 +3053,7 @@ export function runWorkOSFgaCommand(options: WorkOSCommandOptions): WorkOSComman
         ...(cliAuth ? { cliAuth } : {}),
         ...(sdk ? { workosSdk: sdk.data } : {}),
         ...(stateFile ? { stateFile } : {}),
-        ...(writtenSetupGuidePath ? { setupGuidePath: writtenSetupGuidePath } : {}),
+        ...writtenSetupGuideData,
         nextCommand: ok ? "forge deploy check --production --json" : `forge workos fga sync${real ? " --real" : ""} --file ${file} --json`,
       }),
       stdout: sdk?.stdout,
@@ -3032,7 +3093,7 @@ export function runWorkOSFgaCommand(options: WorkOSCommandOptions): WorkOSComman
       seedState,
       readiness,
       real,
-      ...(writtenSetupGuidePath ? { setupGuidePath: writtenSetupGuidePath } : {}),
+      ...writtenSetupGuideData,
       nextCommand: readiness.nextCommand,
       nextActions: readiness.nextActions,
     }),
@@ -3159,11 +3220,14 @@ export function formatWorkOSHuman(result: WorkOSCommandResult): string {
   }
   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[] }
+      ? result.data as { action?: string; real?: boolean; nextCommand?: string; stateFile?: string; setupGuidePath?: string; setupGuideJsonPath?: string; nextActions?: string[] }
       : {};
     if (data.setupGuidePath) {
       lines.push(`FGA setup guide: ${data.setupGuidePath}`);
     }
+    if (data.setupGuideJsonPath) {
+      lines.push(`FGA setup JSON: ${data.setupGuideJsonPath}`);
+    }
     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") {

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

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

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

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

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

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

package/src/forge/version.ts

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