forgeos 0.1.0-alpha.39 → 0.1.0-alpha.40

package/AGENTS.md

@@ -1,4 +1,4 @@
-// @forge-generated generator=0.1.0-alpha.39 input=1c15364ea76cedba476c98d2f661e485cdee778fa10e7b06f7db1b6f23b1dc4a content=721818a6f9a664aa898092d4aa5cd68cbbd8ad6e150c7d3ad3ef785a2e3fcf53
+// @forge-generated generator=0.1.0-alpha.40 input=34767fc77e63b67b94ae661c501b2aa362dd8234ba16c12cf84a55da5e94de28 content=721818a6f9a664aa898092d4aa5cd68cbbd8ad6e150c7d3ad3ef785a2e3fcf53
 # AGENTS.md
 
 <!-- forge-generated:start -->

package/CHANGELOG.md

@@ -1,5 +1,30 @@
 # forgeos
 
+## 0.1.0-alpha.40
+
+### Patch Changes
+
+- Complete the WorkOS/AuthKit production-like app setup loop.
+
+  - Add `forge workos setup --real --file workos-seed.yml --json` as the
+    explicit no-dashboard apply path for WorkOS hosted redirect URI, CORS,
+    homepage, webhook, and seed configuration.
+  - Make `forge workos doctor` validate production OIDC/JWT readiness,
+    browser AuthKit environment variables, the frontend AuthKit package, and
+    actual AuthKit provider mounting in the web app shell.
+  - Generate a Vite React WorkOS bridge that wraps `AuthKitProvider`, forwards
+    `getAccessToken()` into `ForgeProvider`, preserves `forgeUrl`, and handles
+    the `/login` sign-in endpoint flow.
+  - Teach `forge add auth workos` to install `@workos-inc/authkit-react` in a
+    detected `web/` workspace and automatically rewrite the default Forge Vite
+    root from local `devAuth` to `ForgeWorkOSAuthProvider`.
+  - Keep custom web roots safe by leaving them unchanged and emitting actionable
+    doctor/UI-audit guidance when AuthKit still needs to be mounted manually.
+  - Expose production auth readiness in `/health` and make `authmd check` fail
+    when OIDC/JWT mode is enabled without issuer/JWKS configuration.
+  - Improve `forge dev` lifecycle diagnostics and port-busy recovery hints for
+    agent-run app previews.
+
 ## 0.1.0-alpha.39
 
 ### Patch Changes

package/package.json

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

package/src/forge/_generated/releaseManifest.ts

@@ -1,4 +1,4 @@
-// @forge-generated generator=0.1.0-alpha.39 input=1c15364ea76cedba476c98d2f661e485cdee778fa10e7b06f7db1b6f23b1dc4a content=d76bcca47149c3378aca45191d0df75cbc6c25b49548ba94b7e2ac4ecbaa91a8
+// @forge-generated generator=0.1.0-alpha.40 input=34767fc77e63b67b94ae661c501b2aa362dd8234ba16c12cf84a55da5e94de28 content=140291417df07bee6f2a7973ba1655fa53741dcb94b0447fc7e46d2a7a8f5d2b
 export const releaseManifest = {
   "defaultProvider": "local",
   "diagnostics": [],
@@ -19,7 +19,7 @@ export const releaseManifest = {
     "custom"
   ],
   "packageName": "forgeos",
-  "packageVersion": "0.1.0-alpha.39",
-  "releaseId": "forgeos@0.1.0-alpha.39+unknown",
+  "packageVersion": "0.1.0-alpha.40",
+  "releaseId": "forgeos@0.1.0-alpha.40+unknown",
   "schemaVersion": "0.1.0"
 } as const;

package/src/forge/cli/authmd.ts

@@ -167,6 +167,59 @@ function metadataPathFor(markdownPath: string): string {
     : `${dirname(markdownPath)}/.well-known/oauth-protected-resource`;
 }
 
+function parseEnvText(text: string): Record<string, string> {
+  const values: Record<string, string> = {};
+  for (const line of text.split(/\r?\n/)) {
+    const match = /^\s*([A-Za-z_][A-Za-z0-9_]*)\s*=\s*(.*)\s*$/.exec(line);
+    if (!match) continue;
+    values[match[1]!] = (match[2] ?? "").trim().replace(/^["']|["']$/g, "");
+  }
+  return values;
+}
+
+function readRuntimeEnv(workspaceRoot: string): Record<string, string> {
+  const read = (path: string) => {
+    const absolute = join(workspaceRoot, path);
+    return existsSync(absolute) ? parseEnvText(readFileSync(absolute, "utf8")) : {};
+  };
+  return {
+    ...read(".env"),
+    ...read(".env.local"),
+    ...Object.fromEntries(
+      Object.entries(process.env)
+        .filter(([key]) => key.startsWith("FORGE_") || key.startsWith("WORKOS_") || key.startsWith("VITE_WORKOS_"))
+        .filter((entry): entry is [string, string] => typeof entry[1] === "string"),
+    ),
+  };
+}
+
+function valuePresent(env: Record<string, string>, name: string): boolean {
+  return typeof env[name] === "string" && env[name]!.trim().length > 0;
+}
+
+function authEnvDiagnostics(workspaceRoot: string): AuthMdCommandResult["diagnostics"] {
+  const env = readRuntimeEnv(workspaceRoot);
+  const mode = env.FORGE_AUTH_MODE;
+  if (mode !== "oidc" && mode !== "jwt") {
+    return [];
+  }
+  const diagnostics: AuthMdCommandResult["diagnostics"] = [];
+  if (!valuePresent(env, "FORGE_AUTH_ISSUER")) {
+    diagnostics.push({
+      code: "FORGE_AUTHMD_AUTH_ENV_MISSING",
+      message: "FORGE_AUTH_MODE uses production auth, but FORGE_AUTH_ISSUER is missing; for hosted WorkOS use https://api.workos.com",
+    });
+  }
+  if (!valuePresent(env, "FORGE_AUTH_JWKS_URI")) {
+    const clientId = env.WORKOS_CLIENT_ID || env.VITE_WORKOS_CLIENT_ID || "<WORKOS_CLIENT_ID>";
+    diagnostics.push({
+      code: "FORGE_AUTHMD_AUTH_ENV_MISSING",
+      message: `FORGE_AUTH_MODE uses production auth, but FORGE_AUTH_JWKS_URI is missing; for hosted WorkOS use https://api.workos.com/sso/jwks/${clientId}`,
+    });
+  }
+  return diagnostics;
+}
+
 function renderAuthMd(workspaceRoot: string): AuthMdCommandResult & { content: string; metadataContent: string } {
   const contract = readGeneratedJson<AgentContractLike>(
     workspaceRoot,
@@ -340,6 +393,15 @@ export function runAuthMdCommand(options: AuthMdCommandOptions): AuthMdCommandRe
   }
 
   if (options.subcommand === "check") {
+    const envDiagnostics = authEnvDiagnostics(options.workspaceRoot);
+    if (envDiagnostics.length > 0) {
+      return {
+        ...result,
+        ok: false,
+        diagnostics: envDiagnostics,
+        exitCode: 1,
+      };
+    }
     return {
       ...result,
       ok: !changed,

package/src/forge/cli/dev.ts

@@ -1,5 +1,5 @@
 import { spawn } from "node:child_process";
-import { closeSync, openSync } from "node:fs";
+import { closeSync, readFileSync, readlinkSync, openSync } from "node:fs";
 import { createServer as createNetServer } from "node:net";
 import { run } from "../compiler/orchestrator/run.ts";
 import { basename, join } from "node:path";
@@ -213,12 +213,30 @@ function removeDevPidFile(workspaceRoot: string): void {
   }
 }
 
+function processDetails(pid: number): { pid: number; cwd?: string; command?: string } {
+  const details: { pid: number; cwd?: string; command?: string } = { pid };
+  try {
+    details.cwd = readlinkSync(`/proc/${pid}/cwd`);
+  } catch {
+    // /proc is Linux-only; process metadata is best-effort.
+  }
+  try {
+    const raw = readFileSync(`/proc/${pid}/cmdline`, "utf8");
+    const command = raw.split("\0").filter(Boolean).join(" ");
+    if (command) details.command = command;
+  } catch {
+    // /proc is Linux-only; process metadata is best-effort.
+  }
+  return details;
+}
+
 function printDevLifecycleResult(input: {
   options: DevCommandOptions;
   ok: boolean;
   action: "detach" | "status" | "stop";
   running: boolean;
   pid?: number;
+  process?: { pid: number; cwd?: string; command?: string };
   logFile: string;
   message: string;
   exitCode: 0 | 1;
@@ -228,6 +246,7 @@ function printDevLifecycleResult(input: {
     action: input.action,
     running: input.running,
     ...(input.pid !== undefined ? { pid: input.pid } : {}),
+    ...(input.process ? { process: input.process } : {}),
     logFile: input.logFile,
     message: input.message,
     nextActions: input.running
@@ -240,6 +259,8 @@ function printDevLifecycleResult(input: {
   } else {
     process.stdout.write(`${input.message}\n`);
     if (input.pid !== undefined) process.stdout.write(`pid: ${input.pid}\n`);
+    if (input.process?.cwd) process.stdout.write(`cwd: ${input.process.cwd}\n`);
+    if (input.process?.command) process.stdout.write(`command: ${input.process.command}\n`);
     process.stdout.write(`log: ${input.logFile}\n`);
   }
   return { exitCode: input.exitCode };
@@ -278,6 +299,7 @@ function runDevStatus(options: DevCommandOptions): DevCommandResult {
     action: "status",
     running,
     ...(pid !== null ? { pid } : {}),
+    ...(pid !== null && running ? { process: processDetails(pid) } : {}),
     logFile: paths.logFile,
     message: running ? "forge dev detached server is running" : "forge dev detached server is not running",
     exitCode: 0,
@@ -295,6 +317,7 @@ function runDevStop(options: DevCommandOptions): DevCommandResult {
       action: "stop",
       running: false,
       ...(pid !== null ? { pid } : {}),
+      ...(pid !== null ? { process: processDetails(pid) } : {}),
       logFile: paths.logFile,
       message: "no detached forge dev server was running",
       exitCode: 0,
@@ -308,6 +331,7 @@ function runDevStop(options: DevCommandOptions): DevCommandResult {
     action: "stop",
     running: false,
     pid,
+    process: processDetails(pid),
     logFile: paths.logFile,
     message: "stopped detached forge dev server",
     exitCode: 0,
@@ -336,6 +360,7 @@ function runDevDetach(options: DevCommandOptions): DevCommandResult {
       action: "detach",
       running: true,
       pid: existingPid,
+      process: processDetails(existingPid),
       logFile: paths.logFile,
       message: "forge dev detached server is already running",
       exitCode: 0,
@@ -382,6 +407,7 @@ function runDevDetach(options: DevCommandOptions): DevCommandResult {
       action: "detach",
       running: true,
       pid: child.pid,
+      process: processDetails(child.pid),
       logFile: paths.logFile,
       message: "started detached forge dev server",
       exitCode: 0,
@@ -474,6 +500,8 @@ function classifyDevStartFailure(input: {
     /port\s+\d+\s+.*in use/i.test(input.rawMessage);
   if (busy) {
     const suggestedCommands = [
+      "forge dev status --json",
+      "forge dev stop --json",
       `forge dev --port 0${input.webPort ? ` --web-port ${input.webPort}` : ""} --json`,
       "forge doctor windows --json",
     ];

package/src/forge/cli/field-test.ts

@@ -198,6 +198,7 @@ async function createFieldTestApp(options: FieldTestCommandOptions): Promise<Fie
             `${options.packageManager} run forge -- authmd check --json`,
             `${options.packageManager} run forge -- workos doctor --json`,
             `${options.packageManager} run forge -- workos seed --file workos-seed.yml --dry-run --json`,
+            `${options.packageManager} run forge -- workos setup --file workos-seed.yml --json`,
           ]
         : []),
       `${options.packageManager} run forge -- dev --once --json`,

package/src/forge/cli/main.ts

@@ -37,6 +37,7 @@ function formatHelp(): string {
     "  forge workos doctor --json  Check WorkOS AuthKit/FGA 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 setup --real --file workos-seed.yml --json  Apply redirect/CORS/homepage config and seed WorkOS without dashboard",
     "  forge deploy plan --target docker --json  Explain production deploy gates and commands",
     "  forge deploy check --production --json  Gate auth, DB, metadata, generated artifacts, and liveQuery readiness",
     "  forge deploy render docker  Write Docker production deploy files under deploy/",

package/src/forge/cli/parse.ts

@@ -155,6 +155,7 @@ export type ForgeCommand =
       file?: string;
       yes: boolean;
       dryRun: boolean;
+      real?: boolean;
       workspaceRoot: string;
     }
   | {
@@ -575,7 +576,7 @@ const AUTH_SUBCOMMANDS: AuthSubcommand[] = [
 ];
 const BASELINE_SUBCOMMANDS: BaselineSubcommand[] = ["create", "status"];
 const AUTHMD_SUBCOMMANDS: AuthMdSubcommand[] = ["generate", "check"];
-const WORKOS_SUBCOMMANDS: WorkOSSubcommand[] = ["install", "doctor", "seed"];
+const WORKOS_SUBCOMMANDS: WorkOSSubcommand[] = ["install", "doctor", "seed", "setup"];
 const DEPLOY_SUBCOMMANDS: DeploySubcommand[] = ["plan", "check", "render", "verify"];
 const FIELD_TEST_SUBCOMMANDS: FieldTestSubcommand[] = ["create", "run", "report"];
 const SECURITY_SUBCOMMANDS: SecuritySubcommand[] = ["prove"];
@@ -1422,7 +1423,7 @@ export function parseCli(argv: string[]): ParsedCli {
     case "workos": {
       const subcommand = rest[0] as WorkOSSubcommand | undefined;
       if (!subcommand || !WORKOS_SUBCOMMANDS.includes(subcommand)) {
-        errors.push("forge workos requires subcommand: install, doctor, or seed");
+        errors.push("forge workos requires subcommand: install, doctor, seed, or setup");
         return { command: null, workspaceRoot, errors };
       }
       return {
@@ -1433,6 +1434,7 @@ export function parseCli(argv: string[]): ParsedCli {
           file: parseOptionValue(argv, "--file"),
           yes: parseFlag(argv, "--yes"),
           dryRun: parseFlag(argv, "--dry-run"),
+          real: parseFlag(argv, "--real"),
           workspaceRoot,
         },
         workspaceRoot,

package/src/forge/cli/workos.ts

@@ -5,7 +5,7 @@ import { spawnSync } from "node:child_process";
 import { GENERATED_DIR } from "../compiler/emitter/constants.ts";
 import { stripDeterministicHeader } from "../compiler/primitives/header.ts";
 
-export type WorkOSSubcommand = "install" | "doctor" | "seed";
+export type WorkOSSubcommand = "install" | "doctor" | "seed" | "setup";
 
 export interface WorkOSCommandOptions {
   subcommand: WorkOSSubcommand;
@@ -14,6 +14,7 @@ export interface WorkOSCommandOptions {
   file?: string;
   yes: boolean;
   dryRun: boolean;
+  real?: boolean;
   commandRunner?: WorkOSCommandRunner;
 }
 
@@ -25,7 +26,7 @@ export interface WorkOSCheck {
 
 export interface WorkOSCommandResult {
   ok: boolean;
-  kind: "workos-install" | "workos-doctor" | "workos-seed";
+  kind: "workos-install" | "workos-doctor" | "workos-seed" | "workos-setup";
   checks: WorkOSCheck[];
   command?: string[];
   applied?: boolean;
@@ -114,6 +115,10 @@ export interface WorkOSSeedSummary {
   resourceTypes: string[];
   organizations: string[];
   domains: string[];
+  redirectUris: string[];
+  corsOrigins: string[];
+  homepageUrl?: string;
+  webhookEndpoints: Array<{ url: string; events: string[] }>;
   diagnostics: string[];
 }
 
@@ -139,8 +144,14 @@ export function parseSeedFile(workspaceRoot: string, preferredPath = DEFAULT_SEE
   const resourceTypes = new Set<string>();
   const organizations = new Set<string>();
   const domains = new Set<string>();
+  const redirectUris = new Set<string>();
+  const corsOrigins = new Set<string>();
+  let homepageUrl: string | undefined;
+  const webhookEndpoints: Array<{ url: string; events: string[] }> = [];
   const diagnostics: string[] = [];
   let section = "";
+  let configKey = "";
+  let currentWebhook: { url: string; events: string[] } | undefined;
 
   if (!raw.trim()) {
     return {
@@ -152,6 +163,9 @@ export function parseSeedFile(workspaceRoot: string, preferredPath = DEFAULT_SEE
       resourceTypes: [],
       organizations: [],
       domains: [],
+      redirectUris: [],
+      corsOrigins: [],
+      webhookEndpoints: [],
       diagnostics: [`${seedPath} is missing or empty`],
     };
   }
@@ -160,9 +174,47 @@ export function parseSeedFile(workspaceRoot: string, preferredPath = DEFAULT_SEE
     const rootSection = /^([a-zA-Z_][\w-]*):\s*$/.exec(line);
     if (rootSection) {
       section = rootSection[1]!;
+      configKey = "";
+      currentWebhook = undefined;
       continue;
     }
 
+    if (section === "config") {
+      const configEntry = /^\s{2}([a-zA-Z_][\w-]*):\s*(.*)$/.exec(line);
+      if (configEntry) {
+        configKey = configEntry[1]!;
+        const rest = configEntry[2] ?? "";
+        if (configKey === "redirect_uris") {
+          for (const value of quotedValues(rest)) redirectUris.add(value);
+        } else if (configKey === "cors_origins") {
+          for (const value of quotedValues(rest)) corsOrigins.add(value);
+        } else if (configKey === "homepage_url") {
+          homepageUrl = quotedValues(rest)[0] ?? (rest.trim().replace(/^["']|["']$/g, "") || homepageUrl);
+        } else if (configKey === "webhook_endpoints") {
+          currentWebhook = undefined;
+        }
+      }
+      const bulletValue = /^\s*-\s*["']?([^"'\]\s]+)["']?\s*$/.exec(line)?.[1];
+      if (bulletValue && configKey === "redirect_uris") {
+        redirectUris.add(bulletValue);
+      } else if (bulletValue && configKey === "cors_origins") {
+        corsOrigins.add(bulletValue);
+      } else if (bulletValue && configKey === "webhook_events" && currentWebhook) {
+        currentWebhook.events.push(bulletValue);
+      }
+      const webhookUrl = /^\s*-\s*url:\s*["']?([^"']+)["']?\s*$/.exec(line)?.[1] ??
+        /^\s{4}url:\s*["']?([^"']+)["']?\s*$/.exec(line)?.[1];
+      if (webhookUrl) {
+        currentWebhook = { url: webhookUrl.trim(), events: [] };
+        webhookEndpoints.push(currentWebhook);
+        configKey = "webhook_endpoints";
+      }
+      if (/^\s{4}events:\s*/.test(line) && currentWebhook) {
+        configKey = "webhook_events";
+        for (const value of quotedValues(line)) currentWebhook.events.push(value);
+      }
+    }
+
     const slug = parseSlug(line);
     if (slug) {
       if (section === "permissions") {
@@ -205,10 +257,48 @@ export function parseSeedFile(workspaceRoot: string, preferredPath = DEFAULT_SEE
     resourceTypes: uniqueSorted(resourceTypes),
     organizations: uniqueSorted(organizations),
     domains: uniqueSorted(domains),
+    redirectUris: uniqueSorted(redirectUris),
+    corsOrigins: uniqueSorted(corsOrigins),
+    ...(homepageUrl ? { homepageUrl } : {}),
+    webhookEndpoints: webhookEndpoints.map((endpoint) => ({
+      url: endpoint.url,
+      events: uniqueSorted(endpoint.events),
+    })),
     diagnostics,
   };
 }
 
+function parseEnvText(text: string): Record<string, string> {
+  const values: Record<string, string> = {};
+  for (const line of text.split(/\r?\n/)) {
+    const match = /^\s*([A-Za-z_][A-Za-z0-9_]*)\s*=\s*(.*)\s*$/.exec(line);
+    if (!match) continue;
+    const raw = match[2] ?? "";
+    values[match[1]!] = raw.trim().replace(/^["']|["']$/g, "");
+  }
+  return values;
+}
+
+function readRealEnv(workspaceRoot: string): Record<string, string> {
+  return {
+    ...parseEnvText(readRawText(workspaceRoot, ".env")),
+    ...parseEnvText(readRawText(workspaceRoot, ".env.local")),
+    ...Object.fromEntries(
+      Object.entries(process.env)
+        .filter(([key]) => key.startsWith("FORGE_") || key.startsWith("WORKOS_") || key.startsWith("VITE_WORKOS_"))
+        .filter((entry): entry is [string, string] => typeof entry[1] === "string"),
+    ),
+  };
+}
+
+function hasValue(env: Record<string, string>, name: string): boolean {
+  return typeof env[name] === "string" && env[name]!.trim().length > 0;
+}
+
+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 function collectPolicyPermissions(workspaceRoot: string): string[] {
   const registry = readJson(workspaceRoot, `${GENERATED_DIR}/policyRegistry.json`) as {
     policies?: Array<{ permissions?: string[] }>;
@@ -287,11 +377,26 @@ function collectWorkOSChecks(workspaceRoot: string): WorkOSCheck[] {
     ...(packageJson?.dependencies ?? {}),
     ...(packageJson?.devDependencies ?? {}),
   };
+  const webPackageJson = readJson(workspaceRoot, "web/package.json") as {
+    dependencies?: Record<string, string>;
+    devDependencies?: Record<string, string>;
+  } | null;
+  const webDeps = {
+    ...(webPackageJson?.dependencies ?? {}),
+    ...(webPackageJson?.devDependencies ?? {}),
+  };
+  const hasWeb = webPackageJson !== null;
   const seed = parseSeedFile(workspaceRoot);
   const activePermissions = collectPolicyPermissions(workspaceRoot);
   const expectedResourceTypes = collectExpectedResourceTypes(workspaceRoot);
   const missingSeedPermissions = missingValues(activePermissions, seed.permissions);
   const missingSeedResources = missingValues(expectedResourceTypes, seed.resourceTypes);
+  const realEnv = readRealEnv(workspaceRoot);
+  const authMode = realEnv.FORGE_AUTH_MODE;
+  const productionAuthEnabled = authMode === "oidc" || authMode === "jwt";
+  const issuerConfigured = hasValue(realEnv, "FORGE_AUTH_ISSUER");
+  const jwksConfigured = hasValue(realEnv, "FORGE_AUTH_JWKS_URI");
+  const clientId = realEnv.WORKOS_CLIENT_ID || realEnv.VITE_WORKOS_CLIENT_ID;
   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`);
@@ -299,6 +404,11 @@ function collectWorkOSChecks(workspaceRoot: string): WorkOSCheck[] {
   const policies = readText(workspaceRoot, "src/policies.workos.ts");
   const session = readText(workspaceRoot, `${GENERATED_DIR}/integrations/workos/session.ts`);
   const webhook = readText(workspaceRoot, `${GENERATED_DIR}/integrations/workos/webhook.ts`);
+  const generatedFrontendAuthBridge = readText(workspaceRoot, "web/src/lib/workos-auth.tsx");
+  const frontendAppShell = [
+    readText(workspaceRoot, "web/src/main.tsx"),
+    readText(workspaceRoot, "web/src/App.tsx"),
+  ].join("\n");
 
   return [
     {
@@ -318,8 +428,53 @@ function collectWorkOSChecks(workspaceRoot: string): WorkOSCheck[] {
     },
     {
       name: "env-example",
-      ok: exists(workspaceRoot, ".env.example"),
-      detail: ".env.example exists",
+      ok: exists(workspaceRoot, ".env.example") &&
+        includesAll(readRawText(workspaceRoot, ".env.example"), [
+          "FORGE_AUTH_MODE=oidc",
+          "FORGE_AUTH_ISSUER=https://api.workos.com",
+          "FORGE_AUTH_JWKS_URI=",
+          "VITE_WORKOS_CLIENT_ID=",
+          "VITE_WORKOS_REDIRECT_URI=",
+        ]),
+      detail: ".env.example exists with Forge OIDC and browser AuthKit variables",
+    },
+    {
+      name: "production-auth-readiness",
+      ok: !productionAuthEnabled || (issuerConfigured && jwksConfigured),
+      detail: !productionAuthEnabled
+        ? "production OIDC/JWT env not enabled in .env/.env.local"
+        : issuerConfigured && jwksConfigured
+          ? "FORGE_AUTH_MODE uses production auth and issuer/JWKS are configured"
+          : `FORGE_AUTH_MODE=${authMode} requires FORGE_AUTH_ISSUER=https://api.workos.com and FORGE_AUTH_JWKS_URI=${workosJwksUri(clientId)}`,
+    },
+    {
+      name: "browser-authkit-env",
+      ok: !hasWeb || (hasValue(realEnv, "VITE_WORKOS_CLIENT_ID") || readRawText(workspaceRoot, ".env.example").includes("VITE_WORKOS_CLIENT_ID=")) &&
+        (hasValue(realEnv, "VITE_WORKOS_REDIRECT_URI") || readRawText(workspaceRoot, ".env.example").includes("VITE_WORKOS_REDIRECT_URI=")),
+      detail: hasWeb
+        ? "web workspace has VITE_WORKOS_CLIENT_ID and VITE_WORKOS_REDIRECT_URI guidance for AuthKit React"
+        : "no web workspace detected",
+    },
+    {
+      name: "browser-authkit-package",
+      ok: !hasWeb || "@workos-inc/authkit-react" in webDeps,
+      detail: hasWeb
+        ? "@workos-inc/authkit-react is present in web/package.json"
+        : "no web workspace detected",
+    },
+    {
+      name: "browser-authkit-bridge",
+      ok: !hasWeb || includesAll(generatedFrontendAuthBridge, ["AuthKitProvider", "getAccessToken", "ForgeProvider"]),
+      detail: hasWeb
+        ? "generated web/src/lib/workos-auth.tsx bridge provides AuthKitProvider and ForgeProvider token wiring"
+        : "no web workspace detected",
+    },
+    {
+      name: "browser-authkit-provider",
+      ok: !hasWeb || includesAll(frontendAppShell, ["AuthKitProvider", "getAccessToken", "ForgeProvider"]),
+      detail: hasWeb
+        ? "web app shell mounts AuthKitProvider and forwards getAccessToken to ForgeProvider"
+        : "no web workspace detected",
     },
     {
       name: "seed-file",
@@ -351,6 +506,13 @@ function collectWorkOSChecks(workspaceRoot: string): WorkOSCheck[] {
         ? `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",
+      ok: seed.redirectUris.length > 0 && seed.corsOrigins.length > 0 && Boolean(seed.homepageUrl),
+      detail: seed.redirectUris.length > 0 && seed.corsOrigins.length > 0 && Boolean(seed.homepageUrl)
+        ? `seed config contains ${seed.redirectUris.length} redirect URI(s), ${seed.corsOrigins.length} CORS origin(s), and homepage URL`
+        : "seed config should include redirect_uris, cors_origins, and homepage_url for no-dashboard setup",
+    },
     {
       name: "authkit-routes",
       ok: includesAll(authRoutes, ["handleWorkOSAuthRequest", "/login", "/callback", "/logout", "/session"]),
@@ -432,6 +594,7 @@ function seedData(input: {
   dryRun?: boolean;
   seedFileSanitized?: boolean;
   seedAlreadyApplied?: boolean;
+  configActions?: WorkOSConfigActionResult[];
   nextCommand?: string;
 }): Record<string, unknown> {
   return {
@@ -442,10 +605,95 @@ function seedData(input: {
     dryRun: input.dryRun ?? false,
     seedFileSanitized: input.seedFileSanitized ?? false,
     seedAlreadyApplied: input.seedAlreadyApplied ?? false,
+    configActions: input.configActions ?? [],
     ...(input.nextCommand ? { nextCommand: input.nextCommand } : {}),
   };
 }
 
+export interface WorkOSConfigActionResult {
+  name: string;
+  command?: string[];
+  ok: boolean;
+  skipped: boolean;
+  reason?: string;
+  stdout?: string;
+  stderr?: string;
+  status?: number | null;
+}
+
+function configActionsForSeed(seed: WorkOSSeedSummary): Array<{ name: string; command: string[]; skipReason?: string }> {
+  const actions: Array<{ name: string; command: string[]; skipReason?: string }> = [];
+  for (const uri of seed.redirectUris) {
+    actions.push({
+      name: "redirect-uri",
+      command: ["npx", "--yes", "workos@latest", "config", "redirect", "add", uri],
+    });
+  }
+  for (const origin of seed.corsOrigins) {
+    actions.push({
+      name: "cors-origin",
+      command: ["npx", "--yes", "workos@latest", "config", "cors", "add", origin],
+    });
+  }
+  if (seed.homepageUrl) {
+    actions.push({
+      name: "homepage-url",
+      command: ["npx", "--yes", "workos@latest", "config", "homepage-url", "set", seed.homepageUrl],
+    });
+  }
+  for (const endpoint of seed.webhookEndpoints) {
+    const events = endpoint.events.length > 0 ? endpoint.events.join(",") : "user.created,organization_membership.updated";
+    actions.push({
+      name: "webhook",
+      command: ["npx", "--yes", "workos@latest", "webhook", "create", "--url", endpoint.url, "--events", events],
+      skipReason: endpoint.url.startsWith("https://")
+        ? undefined
+        : "WorkOS hosted webhook endpoints require HTTPS; use a tunnel or production URL for this endpoint.",
+    });
+  }
+  return actions;
+}
+
+function runWorkOSConfigActions(
+  seed: WorkOSSeedSummary,
+  options: WorkOSCommandOptions,
+  dryRun: boolean,
+): WorkOSConfigActionResult[] {
+  return configActionsForSeed(seed).map((action) => {
+    if (action.skipReason) {
+      return {
+        name: action.name,
+        command: action.command,
+        ok: true,
+        skipped: true,
+        reason: action.skipReason,
+      };
+    }
+    if (dryRun) {
+      return {
+        name: action.name,
+        command: action.command,
+        ok: true,
+        skipped: true,
+        reason: "dry-run",
+      };
+    }
+    const child = runExternalCommand(action.command, options);
+    return {
+      name: action.name,
+      command: action.command,
+      ok: child.status === 0 || isWorkOSSeedAlreadyApplied(child.stdout, child.stderr),
+      skipped: false,
+      stdout: child.stdout,
+      stderr: child.stderr,
+      status: child.status,
+      ...(child.status !== 0 && isWorkOSSeedAlreadyApplied(child.stdout, child.stderr)
+        ? { reason: "already-applied" }
+        : {}),
+    };
+  });
+}
+
 export function runWorkOSDoctorCommand(options: WorkOSCommandOptions): WorkOSCommandResult {
   const checks = collectWorkOSChecks(options.workspaceRoot);
   const ok = checks.every((check) => check.ok);
@@ -553,6 +801,13 @@ export function runWorkOSSeedCommand(options: WorkOSCommandOptions): WorkOSComma
         ? `seed covers app resource type(s): ${expectedResourceTypes.join(", ") || "none required"}`
         : `seed missing resource type(s): ${missingSeedResources.join(", ")}`,
     },
+    {
+      name: "seed-hosted-config",
+      ok: seed.redirectUris.length > 0 && seed.corsOrigins.length > 0 && Boolean(seed.homepageUrl),
+      detail: seed.redirectUris.length > 0 && seed.corsOrigins.length > 0 && Boolean(seed.homepageUrl)
+        ? `seed includes hosted config: ${seed.redirectUris.length} redirect URI(s), ${seed.corsOrigins.length} CORS origin(s), homepage ${seed.homepageUrl}`
+        : "seed should include config.redirect_uris, config.cors_origins, and config.homepage_url",
+    },
   ];
   const command = ["npx", "--yes", "workos@latest", "seed", "--file", file];
   if (!checks.every((check) => check.ok)) {
@@ -567,6 +822,7 @@ export function runWorkOSSeedCommand(options: WorkOSCommandOptions): WorkOSComma
     };
   }
   if (options.dryRun) {
+    const configActions = runWorkOSConfigActions(seed, options, true);
     return {
       ok: true,
       kind: "workos-seed",
@@ -579,6 +835,7 @@ export function runWorkOSSeedCommand(options: WorkOSCommandOptions): WorkOSComma
         expectedResourceTypes,
         unusedSeedPermissions,
         dryRun: true,
+        configActions,
         nextCommand: `forge workos seed --file ${file} --json`,
       }),
       exitCode: 0,
@@ -594,6 +851,26 @@ export function runWorkOSSeedCommand(options: WorkOSCommandOptions): WorkOSComma
     preparedSeed.file,
   ];
   try {
+    const configActions = runWorkOSConfigActions(seed, options, false);
+    const configOk = configActions.every((action) => action.ok);
+    if (!configOk) {
+      return {
+        ok: false,
+        kind: "workos-seed",
+        checks,
+        command: configActions.find((action) => !action.ok)?.command ?? delegatedCommand,
+        applied: false,
+        data: seedData({
+          seed,
+          activePermissions,
+          expectedResourceTypes,
+          unusedSeedPermissions,
+          seedFileSanitized: preparedSeed.sanitized,
+          configActions,
+        }),
+        exitCode: 1,
+      };
+    }
     const child = runExternalCommand(delegatedCommand, options);
     const seedAlreadyApplied =
       child.status !== 0 && isWorkOSSeedAlreadyApplied(child.stdout, child.stderr);
@@ -610,6 +887,7 @@ export function runWorkOSSeedCommand(options: WorkOSCommandOptions): WorkOSComma
         unusedSeedPermissions,
         seedFileSanitized: preparedSeed.sanitized,
         seedAlreadyApplied,
+        configActions,
       }),
       stdout: child.stdout,
       stderr: child.stderr,
@@ -620,10 +898,79 @@ 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 seed = parseSeedFile(options.workspaceRoot, file);
+  const setupDryRun = options.dryRun || !options.real;
+  const configActions = runWorkOSConfigActions(seed, options, true);
+  const command = ["npx", "--yes", "workos@latest", "seed", "--file", file];
+  if (!localOk) {
+    return {
+      ok: false,
+      kind: "workos-setup",
+      checks,
+      command,
+      applied: false,
+      data: {
+        dryRun: setupDryRun,
+        real: options.real ?? false,
+        seed,
+        configActions,
+        nextCommand: "forge workos doctor --json",
+      },
+      exitCode: 1,
+    };
+  }
+  if (setupDryRun) {
+    return {
+      ok: true,
+      kind: "workos-setup",
+      checks,
+      command,
+      applied: false,
+      data: {
+        dryRun: true,
+        real: false,
+        seed,
+        configActions,
+        nextCommand: `forge workos setup --real --file ${file} --json`,
+      },
+      exitCode: 0,
+    };
+  }
+  const seedResult = runWorkOSSeedCommand({
+    ...options,
+    subcommand: "seed",
+    dryRun: false,
+    file,
+  });
+  return {
+    ok: seedResult.ok,
+    kind: "workos-setup",
+    checks: seedResult.checks,
+    command: seedResult.command,
+    applied: seedResult.ok,
+    data: {
+      real: true,
+      seed,
+      seedResult: seedResult.data,
+      nextCommand: "forge workos doctor --json",
+    },
+    stdout: seedResult.stdout,
+    stderr: seedResult.stderr,
+    exitCode: seedResult.exitCode,
+  };
+}
+
 export function runWorkOSCommand(options: WorkOSCommandOptions): WorkOSCommandResult {
   if (options.subcommand === "install") {
     return runWorkOSInstallCommand(options);
   }
+  if (options.subcommand === "setup") {
+    return runWorkOSSetupCommand(options);
+  }
   return options.subcommand === "doctor"
     ? runWorkOSDoctorCommand(options)
     : runWorkOSSeedCommand(options);
@@ -659,5 +1006,15 @@ export function formatWorkOSHuman(result: WorkOSCommandResult): string {
       lines.push("seed not applied; inspect stdout/stderr from the WorkOS CLI command");
     }
   }
+  if (result.kind === "workos-setup" && !result.applied) {
+    const data = result.data && typeof result.data === "object"
+      ? result.data as { dryRun?: boolean; nextCommand?: string }
+      : {};
+    if (data.dryRun) {
+      lines.push(`setup dry-run only; run ${data.nextCommand ?? "forge workos setup --real --file workos-seed.yml --json"} to apply hosted config`);
+    } else {
+      lines.push("setup not applied; inspect WorkOS checks and seed/config action output");
+    }
+  }
   return `${lines.join("\n")}\n`;
 }

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

@@ -354,8 +354,9 @@ function fileHashOrNull(path: string): string | null {
 function snapshotPackageManagerFiles(
   workspaceRoot: string,
   pm: PackageManagerAdapter,
+  extraPaths: string[] = [],
 ): Map<string, string | null> {
-  const paths = ["package.json", pm.lockfile];
+  const paths = [...new Set(["package.json", pm.lockfile, ...extraPaths])];
   return new Map(
     paths.map((path) => [
       path,
@@ -377,6 +378,70 @@ function changedPackageManagerFiles(
   return changed.sort();
 }
 
+function workosFrontendWorkspace(workspaceRoot: string): string | undefined {
+  return findFrontendWorkspace(workspaceRoot);
+}
+
+function connectWorkOSReactRoot(workspaceRoot: string, frontendWorkspace: string): {
+  changed: string[];
+  warnings: Diagnostic[];
+} {
+  const mainRel = `${frontendWorkspace}/src/main.tsx`;
+  const mainPath = join(workspaceRoot, mainRel);
+  const current = nodeFileSystem.readText(mainPath);
+  if (current === null) {
+    return {
+      changed: [],
+      warnings: [
+        createDiagnostic({
+          severity: "warning",
+          code: "FORGE_WORKOS_AUTHKIT_ROOT_NOT_FOUND",
+          message: `generated WorkOS AuthKit bridge, but ${mainRel} was not found`,
+          fixHint: "Wrap the web app root with ForgeWorkOSAuthProvider from ./lib/workos-auth.",
+          suggestedCommands: ["forge workos doctor --json", "forge inspect ui --json"],
+        }),
+      ],
+    };
+  }
+  if (current.includes("ForgeWorkOSAuthProvider")) {
+    return { changed: [], warnings: [] };
+  }
+
+  const canRewriteDefaultViteRoot =
+    current.includes('import { ForgeProvider, forgeUrl } from "./lib/forge";') &&
+    current.includes("<ForgeProvider url={forgeUrl} devAuth>") &&
+    current.includes("</ForgeProvider>");
+
+  if (!canRewriteDefaultViteRoot) {
+    return {
+      changed: [],
+      warnings: [
+        createDiagnostic({
+          severity: "warning",
+          code: "FORGE_WORKOS_AUTHKIT_ROOT_CUSTOM",
+          message: `generated WorkOS AuthKit bridge, but ${mainRel} is custom and was not rewritten automatically`,
+          fixHint: "Import ForgeWorkOSAuthProvider from ./lib/workos-auth and wrap the app root with it so AuthKit tokens are passed to ForgeProvider.",
+          suggestedCommands: ["forge workos doctor --json", "forge inspect ui --json"],
+        }),
+      ],
+    };
+  }
+
+  const next = current
+    .replace(
+      'import { ForgeProvider, forgeUrl } from "./lib/forge";',
+      'import { ForgeWorkOSAuthProvider } from "./lib/workos-auth";',
+    )
+    .replace("<ForgeProvider url={forgeUrl} devAuth>", "<ForgeWorkOSAuthProvider>")
+    .replace("</ForgeProvider>", "</ForgeWorkOSAuthProvider>");
+
+  if (next !== current) {
+    nodeFileSystem.writeText(mainPath, next);
+    return { changed: [mainRel], warnings: [] };
+  }
+  return { changed: [], warnings: [] };
+}
+
 async function analyzeRecipePackages(
   recipe: NonNullable<ReturnType<typeof resolveRecipe>>,
   ctx: ReturnType<typeof discover>,
@@ -668,13 +733,24 @@ export async function forgeAdd(
   const snapshot = snapshotVersionControlled(options.workspaceRoot);
 
   try {
-    const packageManagerBefore = snapshotPackageManagerFiles(options.workspaceRoot, pm);
+    const frontendWorkspace = normalized === "workos" ? workosFrontendWorkspace(options.workspaceRoot) : undefined;
+    const packageManagerBefore = snapshotPackageManagerFiles(
+      options.workspaceRoot,
+      pm,
+      frontendWorkspace ? [packageJsonRelativeFor(frontendWorkspace)] : [],
+    );
     for (const pkg of recipe.packages) {
       await pm.add(pkg.packageName, {
         cwd: options.workspaceRoot,
         ignoreScripts: !options.allowScripts,
       });
     }
+    if (frontendWorkspace) {
+      await pm.add("@workos-inc/authkit-react", {
+        cwd: join(options.workspaceRoot, frontendWorkspace),
+        ignoreScripts: !options.allowScripts,
+      });
+    }
 
     const ctx = discover({ workspaceRoot: options.workspaceRoot });
     const { emitPlan, warnings, errors: analyzeErrors } = await buildAddPlan(
@@ -705,7 +781,11 @@ export async function forgeAdd(
       mode: "write",
     });
 
-    const warningsCombined = [...warnings, ...emitResult.warnings];
+    const workosWeb = normalized === "workos" && frontendWorkspace
+      ? connectWorkOSReactRoot(options.workspaceRoot, frontendWorkspace)
+      : { changed: [] as string[], warnings: [] as Diagnostic[] };
+
+    const warningsCombined = [...warnings, ...emitResult.warnings, ...workosWeb.warnings];
     const errors = [...analyzeErrors, ...emitResult.errors];
 
     if (errors.length > 0) {
@@ -772,6 +852,7 @@ export async function forgeAdd(
       changed: [
         ...changedPackageManagerFiles(options.workspaceRoot, packageManagerBefore),
         ...emitResult.changed,
+        ...workosWeb.changed,
       ],
       unchanged: emitResult.unchanged,
       warnings: warningsCombined,

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

@@ -97,6 +97,7 @@ function shouldEmitAdapter(
 function buildGeneratedPaths(
   recipe: IntegrationRecipe,
   compatible: RuntimeContext[],
+  workspaceRoot: string,
 ): string[] {
   const paths: string[] = [];
 
@@ -120,6 +121,9 @@ function buildGeneratedPaths(
   }
 
   for (const rootFile of recipe.rootFiles ?? []) {
+    if (rootFile.startsWith("web/") && !nodeFileSystem.exists(join(workspaceRoot, "web", "package.json"))) {
+      continue;
+    }
     paths.push(rootFile);
   }
 
@@ -243,6 +247,9 @@ export function buildIntegrationEmitPlan(input: IntegrationPlanInput): EmitPlan
   }
 
   for (const rootFile of recipe.rootFiles ?? []) {
+    if (rootFile.startsWith("web/") && !nodeFileSystem.exists(join(ctx.workspaceRoot, "web", "package.json"))) {
+      continue;
+    }
     const content = renderRootFile(rootFile, templateCtx);
     files.push({
       path: rootFile,
@@ -282,7 +289,7 @@ export function buildIntegrationEmitPlan(input: IntegrationPlanInput): EmitPlan
   const matrix = buildRuntimeMatrix(allClassified);
   files.push(...buildGuardArtifactEmitFiles(matrix, appGraph.moduleGraph));
 
-  const generatedFiles = buildGeneratedPaths(recipe, compatible);
+  const generatedFiles = buildGeneratedPaths(recipe, compatible, ctx.workspaceRoot);
   const lockEntry = buildLockEntry(recipe, classified, generatedFiles);
   const lock = mergeLockPackages(input.existingLock, lockEntry, ctx);
 

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

@@ -87,6 +87,7 @@ const ROOT_FILE_RENDERERS: Record<string, Record<string, TemplateRenderer>> = {
   workos: {
     ".env.example": workos.renderWorkosEnvExample,
     "src/policies.workos.ts": workos.renderWorkosPolicies,
+    "web/src/lib/workos-auth.tsx": workos.renderWorkosReactBridge,
     "workos-seed.yml": workos.renderWorkosSeedYaml,
   },
 };

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

@@ -186,6 +186,7 @@ export function renderWorkosAuthkit(_input: IntegrationTemplateInput): string {
     '  "forge workos doctor --yes --json",',
     '  "forge workos seed --file workos-seed.yml --dry-run --json",',
     '  "forge workos seed --file workos-seed.yml --json",',
+    '  "forge workos setup --real --file workos-seed.yml --json",',
     '  "forge auth check --json",',
     '  "forge auth prove --json",',
     "] as const;",
@@ -238,8 +239,9 @@ export function renderWorkosEnvExample(_input: IntegrationTemplateInput): string
     "# Forge WorkOS/AuthKit production auth example.",
     "# Secret values are intentionally blank. Keep real values in .env.local, your host secrets, or WorkOS/Vercel integration env.",
     "FORGE_AUTH_MODE=oidc",
-    "FORGE_AUTH_ISSUER=",
+    "FORGE_AUTH_ISSUER=https://api.workos.com",
     "FORGE_AUTH_AUDIENCE=",
+    "# Set to https://api.workos.com/sso/jwks/<WORKOS_CLIENT_ID> after filling WORKOS_CLIENT_ID.",
     "FORGE_AUTH_JWKS_URI=",
     "FORGE_AUTH_ALGORITHMS=RS256",
     "",
@@ -252,12 +254,90 @@ export function renderWorkosEnvExample(_input: IntegrationTemplateInput): string
     "WORKOS_POST_LOGOUT_REDIRECT_URI=http://localhost:5173/",
     "WORKOS_WEBHOOK_SECRET=",
     "",
+    "# Browser AuthKit settings for Vite/React. These are public client identifiers, not secrets.",
+    "VITE_WORKOS_CLIENT_ID=",
+    "VITE_WORKOS_REDIRECT_URI=http://localhost:5173/callback",
+    "",
     "# WorkOS token claims expected by ForgeOS after forge add auth workos:",
     "# sub, email, organization_id, role, roles, permissions, organization_membership_id",
     "",
   ].join("\n");
 }
 
+export function renderWorkosReactBridge(_input: IntegrationTemplateInput): string {
+  return [
+    "/** Forge generated WorkOS/AuthKit React bridge.",
+    " * Import ForgeWorkOSAuthProvider from web/src/main.tsx, or copy the pattern into your app shell.",
+    " */",
+    'import { AuthKitProvider, useAuth as useWorkOSAuth } from "@workos-inc/authkit-react";',
+    'import { useEffect, type ReactNode } from "react";',
+    'import { ForgeProvider, forgeUrl } from "./forge";',
+    "",
+    "const clientId = import.meta.env.VITE_WORKOS_CLIENT_ID as string | undefined;",
+    "const redirectUri = import.meta.env.VITE_WORKOS_REDIRECT_URI as string | undefined;",
+    "",
+    "export function hasWorkOSBrowserConfig(): boolean {",
+    "  return Boolean(clientId && redirectUri);",
+    "}",
+    "",
+    "export function ForgeWorkOSAuthProvider({ children }: { children: ReactNode }) {",
+    "  if (!clientId || !redirectUri) {",
+    "    throw new Error(\"WorkOS AuthKit requires VITE_WORKOS_CLIENT_ID and VITE_WORKOS_REDIRECT_URI\");",
+    "  }",
+    "  return (",
+    "    <AuthKitProvider clientId={clientId} redirectUri={redirectUri}>",
+    "      <ForgeWorkOSBearerProvider>{children}</ForgeWorkOSBearerProvider>",
+    "    </AuthKitProvider>",
+    "  );",
+    "}",
+    "",
+    "function ForgeWorkOSBearerProvider({ children }: { children: ReactNode }) {",
+    "  const auth = useWorkOSAuth();",
+    "  return (",
+    "    <ForgeProvider",
+    "      url={forgeUrl}",
+    "      auth={{",
+    "        getAccessToken: async () => {",
+    "          const token = await auth.getAccessToken();",
+    "          return token ?? null;",
+    "        },",
+    "      }}",
+    "    >",
+    "      {children}",
+    "    </ForgeProvider>",
+    "  );",
+    "}",
+    "",
+    "export function WorkOSLoginPanel() {",
+    "  const { isLoading, user, signIn, signUp, signOut } = useWorkOSAuth();",
+    "  useEffect(() => {",
+    "    if (!isLoading && !user && window.location.pathname === \"/login\") {",
+    "      void signIn();",
+    "    }",
+    "  }, [isLoading, signIn, user]);",
+    "  if (isLoading) return <p>Loading authentication...</p>;",
+    "  if (!user && window.location.pathname === \"/login\") return <p>Redirecting...</p>;",
+    "  if (!user) {",
+    "    return (",
+    "      <div>",
+    "        <button type=\"button\" onClick={() => void signIn()}>Sign in</button>",
+    "        <button type=\"button\" onClick={() => void signUp()}>Sign up</button>",
+    "      </div>",
+    "    );",
+    "  }",
+    "  return (",
+    "    <div>",
+    "      <span>{user.email}</span>",
+    "      <button type=\"button\" onClick={() => signOut({ returnTo: window.location.origin })}>Sign out</button>",
+    "    </div>",
+    "  );",
+    "}",
+    "",
+    "export { useWorkOSAuth };",
+    "",
+  ].join("\n");
+}
+
 export function renderWorkosFga(input: IntegrationTemplateInput): string {
   const permissions = permissionsFromApp(input);
   const roles = rolePermissions(permissions);
@@ -941,8 +1021,14 @@ export function renderWorkosSeedYaml(input: IntegrationTemplateInput): string {
     "    domains: ['globex.test']",
     "",
     "config:",
-    "  redirect_uris: ['http://localhost:5173/callback']",
-    "  cors_origins: ['http://localhost:5173']",
+    "  redirect_uris:",
+    "    - 'http://localhost:5173'",
+    "    - 'http://localhost:5173/callback'",
+    "    - 'http://127.0.0.1:5173'",
+    "    - 'http://127.0.0.1:5173/callback'",
+    "  cors_origins:",
+    "    - 'http://localhost:5173'",
+    "    - 'http://127.0.0.1:5173'",
     "  homepage_url: 'http://localhost:5173'",
     "  webhook_endpoints:",
     "    - url: 'http://localhost:3765/webhooks/workos'",
@@ -1064,6 +1150,7 @@ export function renderWorkosDoc(input: IntegrationTemplateInput): string {
     "## What this recipe does",
     "",
     "- 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 framework-agnostic AuthKit route/session helpers for `/login`, `/callback`, `/logout`, and `/session`.",
@@ -1079,6 +1166,7 @@ export function renderWorkosDoc(input: IntegrationTemplateInput): string {
     "forge workos doctor --yes --json",
     "forge workos seed --file workos-seed.yml --dry-run --json",
     "forge workos seed --file workos-seed.yml --json",
+    "forge workos setup --real --file workos-seed.yml --json",
     "forge auth check --json",
     "forge auth prove --json",
     "forge check --json",
@@ -1099,11 +1187,13 @@ export function renderWorkosDoc(input: IntegrationTemplateInput): string {
     "## Production auth mapping",
     "",
     "- `FORGE_AUTH_MODE=oidc` or `jwt`",
-    "- `FORGE_AUTH_ISSUER` points at the WorkOS/AuthKit issuer for the environment.",
+    "- `FORGE_AUTH_ISSUER=https://api.workos.com` for hosted WorkOS AuthKit.",
+    "- `FORGE_AUTH_JWKS_URI=https://api.workos.com/sso/jwks/<WORKOS_CLIENT_ID>` for hosted WorkOS AuthKit.",
     "- `FORGE_AUTH_AUDIENCE` matches the API audience configured for the app.",
     "- Tenant claim should map to WorkOS `org_id` or a normalized `tenant_id` claim.",
     "- Role and permissions should come from WorkOS organization roles/permissions, not from dev headers.",
     "- Use generated `src/policies.workos.ts` as a permission-first policy template; it uses `canPermission(...)` rather than role-only checks.",
+    "- `dev-headers` and frontend `devAuth` are local-only simulation paths. Real WorkOS production-like tests should use AuthKit and Bearer tokens.",
     "",
     "## AuthKit routes",
     "",

package/src/forge/compiler/recipes/definitions.ts

@@ -246,7 +246,7 @@ export const WORKOS_RECIPE: IntegrationRecipe = {
     "workos/webhook.ts",
     "workos/workos-seed.yml",
   ],
-  rootFiles: [".env.example", "src/policies.workos.ts", "workos-seed.yml"],
+  rootFiles: [".env.example", "src/policies.workos.ts", "web/src/lib/workos-auth.tsx", "workos-seed.yml"],
   testkits: ["workos.mock.ts"],
   docs: ["workos.md"],
 };

package/src/forge/dev/server.ts

@@ -1318,6 +1318,16 @@ export async function startDevServer(
           const aiRegistry = loadAiRegistry(workspaceRoot);
           const aiCheck = checkAiProviders(envStore, aiRegistry, secretRegistry);
           const mockAi = isMockAiEnabled({ mockAi: options.mockAi });
+          const productionAuthMode = authConfig.mode === "oidc" || authConfig.mode === "jwt";
+          const missingAuthConfig = [
+            ...(productionAuthMode && !authConfig.issuer ? ["FORGE_AUTH_ISSUER"] : []),
+            ...(productionAuthMode && !authConfig.jwksUri ? ["FORGE_AUTH_JWKS_URI"] : []),
+          ];
+          const workosClientId = envStore.resolve("WORKOS_CLIENT_ID") || envStore.resolve("VITE_WORKOS_CLIENT_ID");
+          const suggestedWorkOSJwksUri = workosClientId
+            ? `https://api.workos.com/sso/jwks/${workosClientId}`
+            : "https://api.workos.com/sso/jwks/<WORKOS_CLIENT_ID>";
+          const authProductionReady = !productionAuthMode || missingAuthConfig.length === 0;
 
           return jsonResponse({
             ok: true,
@@ -1346,6 +1356,12 @@ export async function startDevServer(
               audienceConfigured: Boolean(authConfig.audience),
               jwksConfigured: Boolean(authConfig.jwksUri),
               requiresTenant: authConfig.requiresTenant,
+              ready: authProductionReady,
+              productionReady: authProductionReady,
+              missing: missingAuthConfig,
+              ...(missingAuthConfig.includes("FORGE_AUTH_JWKS_URI")
+                ? { suggestedWorkOSJwksUri }
+                : {}),
             },
             env: {
               loadedFiles: envStore.loadedFiles,

package/src/forge/ui/index.ts

@@ -117,6 +117,25 @@ function looksLikeAuthFlow(text: string): boolean {
   return /sign\s*in|signin|login|logout|authkit|organization|tenant|session|workos|clerk|auth0/i.test(text);
 }
 
+function hasWorkOSIntegration(workspaceRoot: string): boolean {
+  return nodeFileSystem.exists(join(workspaceRoot, `${GENERATED}/integrations/workos/authkit.ts`)) ||
+    nodeFileSystem.exists(join(workspaceRoot, `${GENERATED}/integrations/workos/auth-routes.ts`));
+}
+
+function webPackageHasAuthKit(workspaceRoot: string): boolean {
+  const path = join(workspaceRoot, "web/package.json");
+  if (!nodeFileSystem.exists(path)) return false;
+  try {
+    const packageJson = JSON.parse(nodeFileSystem.readText(path) ?? "{}") as {
+      dependencies?: Record<string, string>;
+      devDependencies?: Record<string, string>;
+    };
+    return Boolean(packageJson.dependencies?.["@workos-inc/authkit-react"] ?? packageJson.devDependencies?.["@workos-inc/authkit-react"]);
+  } catch {
+    return false;
+  }
+}
+
 function hasMainLandmark(text: string): boolean {
   return /<main[\s>]|role=["']main["']|<header[\s>]|<nav[\s>]/i.test(text);
 }
@@ -775,6 +794,10 @@ function runUiAudit(options: UiCommandOptions): UiCommandResult {
   const diagnostics: Diagnostic[] = [];
   const webSources = listWebSourceFiles(options.workspaceRoot, manifest.webRoot);
   const webText = webSources.map((source) => source.text).join("\n");
+  const appShellText = webSources
+    .filter((source) => !source.path.endsWith("/lib/workos-auth.tsx"))
+    .map((source) => source.text)
+    .join("\n");
   const scenarioRoutes = new Set(scenarios.map((scenario) => scenario.route));
   const scenarioNames = scenarios.map((scenario) => scenario.name);
   const selectorSet = new Set(manifest.selectors);
@@ -835,6 +858,18 @@ function runUiAudit(options: UiCommandOptions): UiCommandResult {
       "Tenant-scoped or production-auth app has no obvious sign-in/session/organization UI; local devAuth is not a production auth flow.",
     ));
   }
+  if (
+    hasWorkOSIntegration(options.workspaceRoot) &&
+    manifest.webRoot &&
+    webSources.length > 0 &&
+    (!webPackageHasAuthKit(options.workspaceRoot) || !/AuthKitProvider/.test(appShellText) || !/getAccessToken/.test(appShellText))
+  ) {
+    diagnostics.push(diagnostic(
+      "warning",
+      "FORGE_UI_WORKOS_AUTHKIT_MISSING",
+      "WorkOS integration is present, but the web app does not appear to mount AuthKitProvider and pass getAccessToken into ForgeProvider.",
+    ));
+  }
 
   return {
     ok: diagnostics.every((item) => item.severity !== "error"),

package/src/forge/version.ts

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