forgeos 0.1.0-alpha.28 → 0.1.0-alpha.29

package/AGENTS.md

@@ -1,4 +1,4 @@
-// @forge-generated generator=0.1.0-alpha.28 input=17144e8bdfd3e1024bc4ca6ec68a23a3b7c2fba75d3033853d2486fbc51db17f content=0d493cf0e41b71cb652d5e0e1b0c1f83d2a1281b748321f0b00f0773ba93074e
+// @forge-generated generator=0.1.0-alpha.29 input=25d84ce77a02f5c4ce49fa082fa968608c9859594d5876886344276ca0c27523 content=0d493cf0e41b71cb652d5e0e1b0c1f83d2a1281b748321f0b00f0773ba93074e
 # AGENTS.md
 
 <!-- forge-generated:start -->

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # forgeos
 
+## 0.1.0-alpha.29
+
+### Patch Changes
+
+- Add the first WorkOS/AuthKit adapter and local auth metadata tooling.
+
+  - Add `forge add auth workos`, generated WorkOS seed/config/docs, AuthKit routes, webhook handling, JWT/OIDC claim mapping, and permission-derived Forge policies.
+  - Add `forge authmd generate` and `forge authmd check`, including `/auth.md` and OAuth protected-resource metadata served by `forge dev`.
+  - Add a local WorkOS/FGA testkit, resource-graph helpers, cross-tenant guards, FGA cache/fallback telemetry, and mock multi-tenant regression coverage.
+  - Teach Forge auth and policies to understand permission claims alongside roles.
+  - Add `forge version --json` as a command alias and capture local helper table reads in the generated agent contract/capability map.
+
 ## 0.1.0-alpha.28
 
 ### Patch Changes

package/docs/changelog.md

@@ -6,6 +6,26 @@ The canonical source file in the repository is `CHANGELOG.md`.
 
 ## Unreleased
 
+## 0.1.0-alpha.29
+
+- Added the first WorkOS/AuthKit adapter surface: `forge add auth workos`
+  generates local AuthKit wiring, `.env.example`, `workos-seed.yml`, demo
+  organizations, roles, permissions, redirect/CORS/webhook hints, JWT/OIDC
+  claim mapping, and permission-derived Forge policies.
+- Added `forge authmd generate` and `forge authmd check`, including
+  `public/auth.md`, OAuth protected-resource metadata, command/policy/tenant
+  requirements, approval metadata, and `forge dev` serving for `/auth.md` and
+  `/.well-known/oauth-protected-resource`.
+- Added local WorkOS/FGA scaffolding without requiring real WorkOS credentials:
+  resource graph helpers, cross-tenant guards, FGA check cache/fallback
+  telemetry, a mock WorkOS testkit, and Acme/Globex multi-tenant regression
+  coverage.
+- Taught Forge auth and policies to evaluate permission claims alongside
+  roles, including dev-header permission simulation.
+- Added `forge version --json` as a command alias and improved the generated
+  agent contract/capability map so table reads performed by imported local
+  helpers are captured.
+
 ## 0.1.0-alpha.28
 
 - Accepted visible Codex hook canaries as sufficient for local editing while

package/package.json

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

package/src/forge/_generated/releaseManifest.ts

@@ -1,4 +1,4 @@
-// @forge-generated generator=0.1.0-alpha.28 input=17144e8bdfd3e1024bc4ca6ec68a23a3b7c2fba75d3033853d2486fbc51db17f content=232067bb5b77f562ad4aa2ddf44f9e3a796ef42205185a28d16ec1ff86cc40b0
+// @forge-generated generator=0.1.0-alpha.29 input=25d84ce77a02f5c4ce49fa082fa968608c9859594d5876886344276ca0c27523 content=ace6a64b0efd317e17fff6fb883bd20137bde066cbee7c2a304be18b90a20fd0
 export const releaseManifest = {
   "defaultProvider": "local",
   "diagnostics": [],
@@ -19,7 +19,7 @@ export const releaseManifest = {
     "custom"
   ],
   "packageName": "forgeos",
-  "packageVersion": "0.1.0-alpha.28",
-  "releaseId": "forgeos@0.1.0-alpha.28+unknown",
+  "packageVersion": "0.1.0-alpha.29",
+  "releaseId": "forgeos@0.1.0-alpha.29+unknown",
   "schemaVersion": "0.1.0"
 } as const;

package/src/forge/cli/auth.ts

@@ -4,10 +4,11 @@ import {
   FORGE_AUTH_INVALID_AUDIENCE,
   FORGE_AUTH_JWKS_FAILED,
 } from "../compiler/diagnostics/codes.ts";
-import { loadAuthConfigFromEnv } from "../runtime/auth/config.ts";
+import { loadAuthConfigFromEnv, type AuthClaimsMapping } from "../runtime/auth/config.ts";
 import { mapClaimsToAuthContext } from "../runtime/auth/claims.ts";
 import { ForgeAuthError } from "../runtime/auth/errors.ts";
 import { verifyJwtToken } from "../runtime/auth/verifier.ts";
+import { loadSecretRegistry } from "../runtime/secrets/check.ts";
 
 export type AuthSubcommand = "check" | "config" | "decode" | "test-token" | "jwks" | "prove";
 
@@ -26,9 +27,42 @@ export interface AuthCommandResult {
   exitCode: 0 | 1;
 }
 
+function detectWorkOS(workspaceRoot: string, claims: AuthClaimsMapping) {
+  const secretRegistry = loadSecretRegistry(workspaceRoot);
+  const secretNames = new Set((secretRegistry?.secrets ?? []).map((secret) => secret.name));
+  const detected =
+    secretNames.has("WORKOS_API_KEY") ||
+    secretNames.has("WORKOS_CLIENT_ID") ||
+    claims.tenantId === "organization_id";
+  const expectedClaims = {
+    userId: "sub",
+    email: "email",
+    tenantId: "organization_id",
+    role: "role",
+    roles: "roles",
+    permissions: "permissions",
+  };
+  const claimStatus = Object.entries(expectedClaims).map(([name, expected]) => ({
+    name,
+    expected,
+    actual: claims[name as keyof AuthClaimsMapping],
+    ok: claims[name as keyof AuthClaimsMapping] === expected,
+  }));
+  return {
+    detected,
+    requiredSecretsRegistered: ["WORKOS_API_KEY", "WORKOS_CLIENT_ID", "WORKOS_COOKIE_PASSWORD"].every((name) =>
+      secretNames.has(name)
+    ),
+    webhookSecretRegistered: secretNames.has("WORKOS_WEBHOOK_SECRET"),
+    expectedClaims,
+    claimStatus,
+  };
+}
+
 function validateConfig(workspaceRoot: string): AuthCommandResult {
   const config = loadAuthConfigFromEnv(workspaceRoot);
   const errors: { code: string; message: string }[] = [];
+  const workos = detectWorkOS(workspaceRoot, config.claims);
 
   if ((config.mode === "jwt" || config.mode === "oidc") && !config.issuer) {
     errors.push({
@@ -60,6 +94,7 @@ function validateConfig(workspaceRoot: string): AuthCommandResult {
       algorithms: config.algorithms,
       claims: config.claims,
       requiresTenant: config.requiresTenant,
+      workos,
       errors,
     },
     error: errors[0],
@@ -69,6 +104,7 @@ function validateConfig(workspaceRoot: string): AuthCommandResult {
 
 function publicConfig(workspaceRoot: string): AuthCommandResult {
   const config = loadAuthConfigFromEnv(workspaceRoot);
+  const workos = detectWorkOS(workspaceRoot, config.claims);
   return {
     ok: true,
     mode: config.mode,
@@ -80,6 +116,7 @@ function publicConfig(workspaceRoot: string): AuthCommandResult {
       algorithms: config.algorithms,
       claims: config.claims,
       requiresTenant: config.requiresTenant,
+      workos,
     },
     exitCode: 0,
   };
@@ -166,7 +203,9 @@ export async function runAuthCommand(
   if (options.subcommand === "prove") {
     const checked = validateConfig(options.workspaceRoot);
     const config = loadAuthConfigFromEnv(options.workspaceRoot);
+    const workos = detectWorkOS(options.workspaceRoot, config.claims);
     const productionMode = config.mode === "jwt" || config.mode === "oidc";
+    const workosClaimsOk = workos.claimStatus.every((claim) => claim.ok);
     return {
       ok: checked.ok,
       mode: config.mode,
@@ -191,7 +230,23 @@ export async function runAuthCommand(
             status: checked.ok ? "passed" : "failed",
             evidence: checked.data,
           },
+          {
+            id: "INV-WORKOS-001",
+            name: "WorkOS adapter claim mapping is explicit when WorkOS is present",
+            status: !workos.detected ? "not-applicable" : workosClaimsOk ? "passed" : "failed",
+            evidence: workos.claimStatus,
+          },
+          {
+            id: "INV-WORKOS-002",
+            name: "WorkOS required secret names are registered without values",
+            status: !workos.detected ? "not-applicable" : workos.requiredSecretsRegistered ? "passed" : "failed",
+            evidence: {
+              required: ["WORKOS_API_KEY", "WORKOS_CLIENT_ID", "WORKOS_COOKIE_PASSWORD"],
+              webhookSecretRegistered: workos.webhookSecretRegistered,
+            },
+          },
         ],
+        workos,
         checkedAt: "deterministic",
       },
       error: checked.error,

package/src/forge/cli/authmd.ts

@@ -0,0 +1,356 @@
+import { existsSync, mkdirSync, readFileSync, readdirSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { GENERATED_DIR } from "../compiler/emitter/constants.ts";
+import { nodeFileSystem } from "../compiler/fs/index.ts";
+import { stripDeterministicHeader } from "../compiler/primitives/header.ts";
+
+export type AuthMdSubcommand = "generate" | "check";
+
+export interface AuthMdCommandOptions {
+  subcommand: AuthMdSubcommand;
+  workspaceRoot: string;
+  json: boolean;
+  output?: string;
+}
+
+export interface AuthMdCommandResult {
+  ok: boolean;
+  path: string;
+  metadataPath: string;
+  changed: boolean;
+  diagnostics: Array<{ code: string; message: string }>;
+  data: {
+    commands: number;
+    queries: number;
+    liveQueries: number;
+    actions: number;
+    policies: number;
+    aiTools: number;
+    requiresTenant: boolean;
+  };
+  exitCode: 0 | 1;
+}
+
+interface RuntimeEntry {
+  name: string;
+  policy?: string;
+  requiresAuth?: boolean;
+  risk?: string;
+  needsApproval?: boolean;
+}
+
+interface AgentContractLike {
+  project?: { name?: string };
+  commands?: RuntimeEntry[];
+  queries?: RuntimeEntry[];
+  liveQueries?: RuntimeEntry[];
+  actions?: RuntimeEntry[];
+  policies?: Array<{ name: string; kind?: string; roles?: string[]; permissions?: string[] }>;
+  auth?: {
+    defaultMode?: string;
+    bearerTokenHeader?: string;
+    env?: Record<string, string>;
+    claims?: Record<string, string | undefined>;
+    requiresTenant?: boolean;
+  };
+}
+
+interface AgentToolsLike {
+  tools?: Array<{
+    name: string;
+    description?: string;
+    risk?: string;
+    needsApproval?: boolean | "dynamic";
+  }>;
+}
+
+function readGeneratedJson<T>(workspaceRoot: string, relativePath: string): T | null {
+  const absolute = join(workspaceRoot, relativePath);
+  if (!nodeFileSystem.exists(absolute)) {
+    return null;
+  }
+  return JSON.parse(stripDeterministicHeader(readFileSync(absolute, "utf8"))) as T;
+}
+
+function outputPath(options: AuthMdCommandOptions): string {
+  return options.output?.trim() || "public/auth.md";
+}
+
+function listRuntimeEntries(title: string, entries: RuntimeEntry[] | undefined): string[] {
+  const rows = (entries ?? []).map((entry) =>
+    `| \`${entry.name}\` | ${entry.policy ? `\`${entry.policy}\`` : "none"} | ${
+      entry.requiresAuth === false ? "no" : "yes"
+    } | ${entry.risk ?? "read"} | ${String(entry.needsApproval ?? false)} |`
+  );
+  return [
+    `## ${title}`,
+    "",
+    "| Name | Policy | Requires auth | Risk | Needs approval |",
+    "|------|--------|---------------|------|----------------|",
+    ...(rows.length > 0 ? rows : ["| none | none | no | none | false |"]),
+    "",
+  ];
+}
+
+function existingDocLinks(workspaceRoot: string): string[] {
+  const candidates = [
+    "README.md",
+    "docs/index.md",
+    "docs/security-and-data.md",
+    "docs/forge-add.md",
+    `${GENERATED_DIR}/capabilityMap.md`,
+    `${GENERATED_DIR}/operationPlaybooks.md`,
+    `${GENERATED_DIR}/docs/workos.md`,
+  ];
+  const docsDir = join(workspaceRoot, "docs");
+  if (existsSync(docsDir)) {
+    for (const entry of readdirSync(docsDir).slice(0, 20)) {
+      if (entry.endsWith(".md")) {
+        candidates.push(`docs/${entry}`);
+      }
+    }
+  }
+  return [...new Set(candidates)].filter((path) => existsSync(join(workspaceRoot, path)));
+}
+
+function riskMetadata(contract: AgentContractLike | null, tools: AgentToolsLike | null) {
+  const runtime = [
+    ...(contract?.commands ?? []).map((entry) => ({ kind: "command", ...entry, risk: entry.risk ?? "write" })),
+    ...(contract?.queries ?? []).map((entry) => ({ kind: "query", ...entry, risk: entry.risk ?? "read" })),
+    ...(contract?.liveQueries ?? []).map((entry) => ({ kind: "liveQuery", ...entry, risk: entry.risk ?? "read" })),
+    ...(contract?.actions ?? []).map((entry) => ({ kind: "action", ...entry, risk: entry.risk ?? "external" })),
+  ].map((entry) => ({
+    kind: entry.kind,
+    name: entry.name,
+    policy: entry.policy ?? null,
+    risk: entry.risk ?? "read",
+    needs_approval: entry.needsApproval ?? (entry.kind === "action"),
+    requires_auth: entry.requiresAuth !== false,
+  }));
+  const aiTools = (tools?.tools ?? []).map((tool) => ({
+    kind: "aiTool",
+    name: tool.name,
+    risk: tool.risk ?? "read",
+    needs_approval: tool.needsApproval ?? false,
+    policy: null,
+  }));
+  return [...runtime, ...aiTools];
+}
+
+function metadataPathFor(markdownPath: string): string {
+  const publicPrefix = "public/";
+  return markdownPath.startsWith(publicPrefix)
+    ? "public/.well-known/oauth-protected-resource"
+    : `${dirname(markdownPath)}/.well-known/oauth-protected-resource`;
+}
+
+function renderAuthMd(workspaceRoot: string): AuthMdCommandResult & { content: string; metadataContent: string } {
+  const contract = readGeneratedJson<AgentContractLike>(
+    workspaceRoot,
+    `${GENERATED_DIR}/agentContract.json`,
+  );
+  const tools = readGeneratedJson<AgentToolsLike>(
+    workspaceRoot,
+    `${GENERATED_DIR}/agentTools.json`,
+  );
+  const diagnostics: AuthMdCommandResult["diagnostics"] = [];
+  if (!contract) {
+    diagnostics.push({
+      code: "FORGE_AUTHMD_MISSING_AGENT_CONTRACT",
+      message: "missing src/forge/_generated/agentContract.json; run forge generate first",
+    });
+  }
+
+  const auth = contract?.auth;
+  const docLinks = existingDocLinks(workspaceRoot);
+  const riskRows = riskMetadata(contract, tools);
+  const toolRows = (tools?.tools ?? []).map((tool) =>
+    `| \`${tool.name}\` | ${tool.description ?? ""} | ${tool.risk ?? "read"} | ${
+      String(tool.needsApproval ?? false)
+    } |`
+  );
+  const policyRows = (contract?.policies ?? []).map((policy) =>
+    `| \`${policy.name}\` | ${policy.kind ?? "roles"} | ${
+      (policy.roles ?? []).map((role) => `\`${role}\``).join(", ") || "none"
+    } | ${(policy.permissions ?? []).map((permission) => `\`${permission}\``).join(", ") || "none"} |`
+  );
+  const scopes = (contract?.policies ?? []).map((policy) => policy.name).sort();
+  const actionNames = (contract?.actions ?? []).map((entry) => entry.name).sort();
+  const protectedResourceMetadata = {
+    resource: "/",
+    authorization_servers: ["configured via FORGE_AUTH_ISSUER"],
+    bearer_methods_supported: ["header"],
+    resource_documentation: "/auth.md",
+    scopes_supported: scopes,
+    resource_signing_alg_values_supported: auth?.env?.algorithms ? ["RS256"] : undefined,
+    forge: {
+      app: contract?.project?.name ?? "unknown",
+      tenant_required: auth?.requiresTenant ?? false,
+      commands: (contract?.commands ?? []).map((entry) => entry.name).sort(),
+      queries: (contract?.queries ?? []).map((entry) => entry.name).sort(),
+      live_queries: (contract?.liveQueries ?? []).map((entry) => entry.name).sort(),
+      actions: actionNames,
+      policies: scopes,
+      risks: riskRows,
+      docs: docLinks.map((path) => `/${path}`),
+      ai_tools: (tools?.tools ?? []).map((tool) => ({
+        name: tool.name,
+        risk: tool.risk ?? "read",
+        needs_approval: tool.needsApproval ?? false,
+      })),
+    },
+  };
+
+  const content = [
+    "# auth.md",
+    "",
+    `App: ${contract?.project?.name ?? "unknown"}`,
+    "",
+    "This file is generated by ForgeOS for agents and authorization-aware clients. It describes protected resource metadata, runtime capabilities, policy names, tenant requirements, and approval expectations without exposing secrets.",
+    "",
+    "## Protected Resource Metadata",
+    "",
+    `- Auth mode: \`${auth?.defaultMode ?? "dev-headers"}\` locally; production should use \`jwt\` or \`oidc\`.`,
+    `- Bearer header: \`${auth?.bearerTokenHeader ?? "Authorization"}\`.`,
+    `- Issuer env: \`${auth?.env?.issuer ?? "FORGE_AUTH_ISSUER"}\`.`,
+    `- Audience env: \`${auth?.env?.audience ?? "FORGE_AUTH_AUDIENCE"}\`.`,
+    `- JWKS env: \`${auth?.env?.jwksUri ?? "FORGE_AUTH_JWKS_URI"}\`.`,
+    `- Tenant required: \`${String(auth?.requiresTenant ?? false)}\`.`,
+    "",
+    "## OAuth 2.0 Protected Resource Metadata",
+    "",
+    "```json",
+    JSON.stringify(protectedResourceMetadata, null, 2),
+    "```",
+    "",
+    "## Claim Mapping",
+    "",
+    `- User: \`${auth?.claims?.userId ?? "sub"}\``,
+    `- Email: \`${auth?.claims?.email ?? "email"}\``,
+    `- Tenant/organization: \`${auth?.claims?.tenantId ?? "tenant_id"}\``,
+    `- Role: \`${auth?.claims?.role ?? "role"}\``,
+    `- Roles: \`${auth?.claims?.roles ?? "roles"}\``,
+    `- Permissions: \`${auth?.claims?.permissions ?? "permissions"}\``,
+    "",
+    ...listRuntimeEntries("Commands", contract?.commands),
+    ...listRuntimeEntries("Queries", contract?.queries),
+    ...listRuntimeEntries("Live Queries", contract?.liveQueries),
+    ...listRuntimeEntries("Actions", contract?.actions),
+    "## Policies",
+    "",
+    "| Policy | Kind | Roles | Permissions |",
+    "|--------|------|-------|-------------|",
+    ...(policyRows.length > 0 ? policyRows : ["| none | none | none | none |"]),
+    "",
+    "## Risk And Approval Metadata",
+    "",
+    "| Kind | Name | Risk | Needs approval | Policy |",
+    "|------|------|------|----------------|--------|",
+    ...(riskRows.length > 0
+      ? riskRows.map((entry) => `| ${entry.kind} | \`${entry.name}\` | ${entry.risk} | ${String(entry.needs_approval)} | ${entry.policy ? `\`${entry.policy}\`` : "none"} |`)
+      : ["| none | none | read | false | none |"]),
+    "",
+    "## Agent Tools",
+    "",
+    "| Tool | Description | Risk | Needs approval |",
+    "|------|-------------|------|----------------|",
+    ...(toolRows.length > 0 ? toolRows : ["| none | none | read | false |"]),
+    "",
+    "## Verification",
+    "",
+    "- Run `forge auth check --json` before production.",
+    "- Run `forge auth prove --json` before exposing tenant-scoped data.",
+    "- Run `forge authmd check --json` before publishing this file.",
+    "",
+    "## App Docs",
+    "",
+    "- `/auth.md` should be served as this public authorization summary when the web app has a public directory.",
+    "- `src/forge/_generated/agentContract.json` is the private source contract.",
+    "- `src/forge/_generated/capabilityMap.json` maps frontend/backend capabilities.",
+    "- `src/forge/_generated/policyRegistry.json` is the policy source of truth.",
+    ...docLinks.map((path) => `- \`${path}\``),
+    "",
+  ].join("\n");
+
+  return {
+    ok: diagnostics.length === 0,
+    path: "public/auth.md",
+    metadataPath: "public/.well-known/oauth-protected-resource",
+    changed: false,
+    diagnostics,
+    data: {
+      commands: contract?.commands?.length ?? 0,
+      queries: contract?.queries?.length ?? 0,
+      liveQueries: contract?.liveQueries?.length ?? 0,
+      actions: contract?.actions?.length ?? 0,
+      policies: contract?.policies?.length ?? 0,
+      aiTools: tools?.tools?.length ?? 0,
+      requiresTenant: auth?.requiresTenant ?? false,
+    },
+    content,
+    metadataContent: `${JSON.stringify(protectedResourceMetadata, null, 2)}\n`,
+    exitCode: diagnostics.length === 0 ? 0 : 1,
+  };
+}
+
+export function runAuthMdCommand(options: AuthMdCommandOptions): AuthMdCommandResult {
+  const rendered = renderAuthMd(options.workspaceRoot);
+  const path = outputPath(options);
+  const metadataPath = metadataPathFor(path);
+  const absolute = join(options.workspaceRoot, path);
+  const metadataAbsolute = join(options.workspaceRoot, metadataPath);
+  const current = nodeFileSystem.exists(absolute) ? readFileSync(absolute, "utf8") : null;
+  const currentMetadata = nodeFileSystem.exists(metadataAbsolute) ? readFileSync(metadataAbsolute, "utf8") : null;
+  const changed = current !== rendered.content || currentMetadata !== rendered.metadataContent;
+  const result = {
+    ...rendered,
+    path,
+    metadataPath,
+    changed,
+    exitCode: rendered.exitCode,
+  };
+  delete (result as { content?: string }).content;
+  delete (result as { metadataContent?: string }).metadataContent;
+
+  if (rendered.exitCode !== 0) {
+    return result;
+  }
+
+  if (options.subcommand === "check") {
+    return {
+      ...result,
+      ok: !changed,
+      diagnostics: changed
+        ? [
+            {
+              code: "FORGE_AUTHMD_DRIFT",
+              message: `${path} is missing or stale; run forge authmd generate`,
+            },
+          ]
+        : [],
+      exitCode: changed ? 1 : 0,
+    };
+  }
+
+  mkdirSync(dirname(absolute), { recursive: true });
+  mkdirSync(dirname(metadataAbsolute), { recursive: true });
+  writeFileSync(absolute, rendered.content, "utf8");
+  writeFileSync(metadataAbsolute, rendered.metadataContent, "utf8");
+  return {
+    ...result,
+    ok: true,
+    changed,
+    exitCode: 0,
+  };
+}
+
+export function formatAuthMdJson(result: AuthMdCommandResult): string {
+  return `${JSON.stringify(result, null, 2)}\n`;
+}
+
+export function formatAuthMdHuman(result: AuthMdCommandResult): string {
+  const status = result.ok ? "ok" : "failed";
+  const drift = result.changed ? "changed" : "unchanged";
+  const diagnostics = result.diagnostics.map((item) => `${item.code}: ${item.message}`).join("\n");
+  return `auth.md ${status}: ${result.path} (${drift})\n${diagnostics ? `${diagnostics}\n` : ""}`;
+}

package/src/forge/cli/commands.ts

@@ -192,6 +192,16 @@ import {
   runWindowsSetupCommand,
 } from "./windows.ts";
 import { formatAuthHuman, formatAuthJson, runAuthCommand } from "./auth.ts";
+import {
+  formatAuthMdHuman,
+  formatAuthMdJson,
+  runAuthMdCommand,
+} from "./authmd.ts";
+import {
+  formatWorkOSHuman,
+  formatWorkOSJson,
+  runWorkOSCommand,
+} from "./workos.ts";
 import { formatRlsHuman, formatRlsJson, runRlsCommand } from "./rls.ts";
 import {
   formatSecurityHuman,
@@ -1696,6 +1706,24 @@ export async function executeCommand(command: ForgeCommand): Promise<number> {
       }
       return result.exitCode;
     }
+    case "authmd": {
+      const result = runAuthMdCommand(command);
+      if (command.json) {
+        process.stdout.write(formatAuthMdJson(result));
+      } else {
+        process.stdout.write(formatAuthMdHuman(result));
+      }
+      return result.exitCode;
+    }
+    case "workos": {
+      const result = runWorkOSCommand(command);
+      if (command.json) {
+        process.stdout.write(formatWorkOSJson(result));
+      } else {
+        process.stdout.write(formatWorkOSHuman(result));
+      }
+      return result.exitCode;
+    }
     case "rls": {
       const result = await runRlsCommand(command);
       if (command.json) {

package/src/forge/cli/main.ts

@@ -23,6 +23,12 @@ function formatHelp(): string {
     "  forge docs check --json  Check public docs, ReadTheDocs config, links, and local MkDocs tooling",
     "  forge docs check --build --install-venv --json  Build docs strictly in a local RTD-style venv",
     "  forge release doctor --json  Aggregate release, sourcemaps, self-host, and docs readiness",
+    "  forge authmd generate       Write public/auth.md from the generated agent/auth contract",
+    "  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 --yes --json  Run local checks, then delegate to npx --yes workos@latest doctor",
+    "  forge workos seed --file src/forge/_generated/integrations/workos/workos-seed.yml --json  Plan WorkOS CLI seed",
     "  forge release check --allow-missing-local-release --json  Gate release readiness without failing on unprepared local artifacts",
     "  forge self-host check --prepared-only --json  Report compose readiness without creating deploy files",
     "  forge delta status --verbose --json  Include Delta schema, lock, and aggregate count details",

package/src/forge/cli/output.ts

@@ -162,6 +162,18 @@ export function buildAddJson(result: ForgeAddResult): Record<string, unknown> {
           ...((result.requiredSecrets?.length ?? 0) > 0 || (result.optionalSecrets?.length ?? 0) > 0
             ? ["forge secrets check --json", "forge inspect secrets --json"]
             : []),
+          ...(result.alias === "workos"
+            ? [
+                "forge workos install --json",
+                "forge workos install --yes --json",
+                "forge workos doctor --json",
+                "forge workos doctor --yes --json",
+                "forge workos seed --file src/forge/_generated/integrations/workos/workos-seed.yml --json",
+                "forge workos seed --file src/forge/_generated/integrations/workos/workos-seed.yml --yes --json",
+                "forge auth check --json",
+                "forge auth prove --json",
+              ]
+            : []),
           "forge check --json",
           "forge verify --smoke",
         ]