forgeos 0.1.0-alpha.55 → 0.1.0-alpha.57

package/AGENTS.md

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

package/CHANGELOG.md

@@ -1,5 +1,41 @@
 # forgeos
 
+## 0.1.0-alpha.57
+
+### Patch Changes
+
+- Fix the WorkOS AuthKit local and tunneled development flow.
+
+  - Add `response_type=code` to Forge-owned WorkOS authorization URLs and avoid sending a default `organization_id` during login so AuthKit can present normal sign-in and organization selection.
+  - Resolve WorkOS organization and membership claims during callback when AuthKit returns only the user/token, then expose Forge-normalized session claims through `/session`.
+  - Add `forge dev --public-api-url` for browser-facing API URLs behind tunnels and update the WorkOS React bridge to use backend-owned `/login`, `/session`, and `/logout` routes through same-origin/proxy-aware URL resolution.
+  - Sync public WorkOS browser env into `web/.env.local` during `forge add auth workos` and `forge workos setup --real`, and update WorkOS doctor/UI audit checks for the backend-owned AuthKit session flow.
+
+## 0.1.0-alpha.56
+
+### Patch Changes
+
+- Add the production deploy golden path as an explicit CLI workflow.
+
+  - `forge deploy init --target docker` now acts as the canonical Docker
+    production bootstrap command for runtime files, `deploy/.env.production`
+    guidance, and production handoff docs.
+  - `forge deploy readiness --production --json` now summarizes whether an app
+    can publish, grouped blockers/warnings, readiness score, and the next
+    command an agent should run.
+  - `forge env doctor --target local|staging|production --json` now reports the
+    effective auth mode, database posture, provider detection, missing env
+    names, and safe source metadata without printing secret values.
+  - `forge deploy check --production --json` now includes blocking/warning
+    summaries and the readiness object used by the deploy gate.
+  - `forge deploy verify --production --url ... --json` now validates required
+    public auth metadata and probes optional runtime endpoints such as
+    `/ready`, `/live/status`, `/outbox/status`, and `/webhooks/workos`.
+  - Production docs now present the canonical flow:
+    `deploy init -> env doctor -> auth/auth.md/WorkOS proof -> field-test ->
+readiness -> check -> package -> verify`, while keeping WorkOS FGA
+    explicitly optional unless the app opts into FGA artifacts.
+
 ## 0.1.0-alpha.55
 
 ### Patch Changes
@@ -90,7 +126,7 @@
 - Tighten the no-dashboard WorkOS real setup/proof handoff.
 
   - WorkOS hosted setup now records explicit `WORKOS_MODE=agent npx --yes
-    workos@latest auth login --json` shell guidance when CLI login is required.
+workos@latest auth login --json` shell guidance when CLI login is required.
   - Failed `forge workos setup --real` login attempts now tell the operator to
     rerun the same setup command after completing OAuth/device-code login,
     instead of pointing generically at `prove --real`.
@@ -251,7 +287,7 @@
     `forge dev --seed --all-tenants`, and seed readiness evidence in dev and
     field-test summaries.
   - Update templates, docs, and tests around the new `create app -> add auth ->
-    field-test -> deploy` path.
+field-test -> deploy` path.
 
 ## 0.1.0-alpha.41
 

package/docs/changelog.md

@@ -6,6 +6,38 @@ The canonical source file in the repository is `CHANGELOG.md`.
 
 ## Unreleased
 
+## 0.1.0-alpha.57
+
+- Fixed the WorkOS/AuthKit login path used by local and tunneled development:
+  Forge-owned authorization URLs now include `response_type=code` and no longer
+  send a default `organization_id` unless explicitly requested.
+- The WorkOS callback now resolves organization and membership claims when
+  AuthKit returns only the user/token, then exposes Forge-normalized session
+  claims through `/session`.
+- Added `forge dev --public-api-url` so browser-facing API URLs can be injected
+  cleanly for SSH tunnels, Docker Desktop, and remote dev hosts.
+- The generated WorkOS React bridge now uses backend-owned `/login`, `/session`,
+  and `/logout` routes through same-origin/proxy-aware URL resolution.
+- `forge add auth workos`, `forge workos setup --real`, `workos doctor`, and
+  `inspect ui --ergonomics` now understand the backend-owned AuthKit session
+  flow and sync public browser env into `web/.env.local`.
+
+## 0.1.0-alpha.56
+
+- Added `forge deploy init --target docker` as the canonical production Docker
+  bootstrap command.
+- Added `forge deploy readiness --production --json` to answer whether an app
+  can publish, what blocks production, and which command should run next.
+- Added `forge env doctor --target local|staging|production --json` for safe,
+  target-specific env source reporting without exposing secret values.
+- `forge deploy check --production --json` now includes grouped
+  blockers/warnings and a readiness summary for agent handoffs.
+- `forge deploy verify --production --url ... --json` now validates required
+  public auth metadata and optional operational endpoints.
+- Production docs now describe the canonical flow from deploy init through
+  field-test, readiness, package, and verify, with WorkOS FGA kept optional
+  unless the app opts into FGA artifacts.
+
 ## 0.1.0-alpha.55
 
 - `forge add auth workos` now defaults to AuthKit/RBAC, permission claims,

package/package.json

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

package/src/forge/_generated/releaseManifest.ts

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

package/src/forge/cli/auth.ts

@@ -180,11 +180,16 @@ function permissionSubsetForRestrictedTenant(permissions: string[]): string[] {
 function buildMultiTenantProof(workspaceRoot: string, workos: ReturnType<typeof detectWorkOS>, requiresTenant: boolean) {
   const rootSeedPresent = existsSync(join(workspaceRoot, "workos-seed.yml"));
   const generatedSeedPresent = existsSync(join(workspaceRoot, "src/forge/_generated/integrations/workos/workos-seed.yml"));
+  const fgaArtifactsPresent =
+    existsSync(join(workspaceRoot, "src/forge/_generated/integrations/workos/fga.ts")) ||
+    existsSync(join(workspaceRoot, "src/forge/_generated/integrations/workos/resource-map.ts")) ||
+    existsSync(join(workspaceRoot, ".workos-fga-state.json"));
   const authMdPresent = existsSync(join(workspaceRoot, "public/auth.md"));
   const metadataPresent = existsSync(join(workspaceRoot, "public/.well-known/oauth-protected-resource"));
   const activePermissions = collectPolicyPermissions(workspaceRoot);
   const expectedResourceTypes = collectExpectedResourceTypes(workspaceRoot);
   const seed = parseSeedFile(workspaceRoot);
+  const fgaEnabled = fgaArtifactsPresent || seed.resourceTypes.length > 0;
   const missingSeedPermissions = missingValues(activePermissions, seed.permissions);
   const missingSeedResources = missingValues(expectedResourceTypes, seed.resourceTypes);
   const acmePermissions = activePermissions;
@@ -223,8 +228,10 @@ function buildMultiTenantProof(workspaceRoot: string, workos: ReturnType<typeof
     },
     {
       id: "seed-resource-coverage",
-      ok: missingSeedResources.length === 0,
-      evidence: missingSeedResources.length === 0
+      ok: !fgaEnabled || missingSeedResources.length === 0,
+      evidence: !fgaEnabled
+        ? "FGA is not enabled; seed resource type coverage is not required for AuthKit/RBAC tenant isolation."
+        : missingSeedResources.length === 0
         ? `seed covers expected app resource type(s): ${expectedResourceTypes.join(", ") || "none required"}`
         : `seed missing expected app resource type(s): ${missingSeedResources.join(", ")}`,
     },
@@ -244,6 +251,7 @@ function buildMultiTenantProof(workspaceRoot: string, workos: ReturnType<typeof
     appContract: {
       activePermissions,
       expectedResourceTypes,
+      fgaEnabled,
       seedPath: seed.path,
       seedPermissions: seed.permissions,
       seedResourceTypes: seed.resourceTypes,

package/src/forge/cli/commands.ts

@@ -2709,6 +2709,7 @@ export async function executeCommand(command: ForgeCommand): Promise<number> {
         webOnly: command.webOnly,
         open: command.open,
         webPort: command.webPort,
+        publicApiUrl: command.publicApiUrl,
         telemetry: command.telemetry,
         envFile: command.envFile,
         skipStartupConsole: command.skipStartupConsole,
@@ -2863,6 +2864,7 @@ export async function executeCommand(command: ForgeCommand): Promise<number> {
         workspaceRoot: command.workspaceRoot,
         json: command.json,
         redacted: command.redacted,
+        target: command.target,
       });
 
       if (command.json) {

package/src/forge/cli/deploy.ts

@@ -13,7 +13,7 @@ import { runAuthCommand } from "./auth.ts";
 import { runAuthMdCommand } from "./authmd.ts";
 import { runWorkOSCommand } from "./workos.ts";
 
-export type DeploySubcommand = "plan" | "check" | "render" | "package" | "verify";
+export type DeploySubcommand = "plan" | "init" | "check" | "readiness" | "render" | "package" | "verify";
 export type DeployTarget = "docker" | "forge-cloud";
 
 export interface DeployCommandOptions {
@@ -42,6 +42,8 @@ export interface DeployCommandResult {
   target: DeployTarget;
   production: boolean;
   checks: DeployCheck[];
+  blocking?: string[];
+  warnings?: string[];
   files?: string[];
   plan?: {
     summary: string;
@@ -50,6 +52,7 @@ export interface DeployCommandResult {
     notes: string[];
   };
   probes?: Array<{ method: string; url: string; ok: boolean; status?: number; contentType?: string; error?: string; jsonValid?: boolean }>;
+  readiness?: DeployReadinessSummary;
   nextActions: string[];
   exitCode: 0 | 1;
 }
@@ -57,6 +60,27 @@ export interface DeployCommandResult {
 interface DeployProbeExpectation {
   contentTypeIncludes?: string;
   json?: boolean;
+  required?: boolean;
+}
+
+export interface DeployReadinessSummary {
+  score: number;
+  status: "ready" | "blocked" | "warning";
+  blocking: string[];
+  warnings: string[];
+  stages: Array<{
+    name: string;
+    ok: boolean;
+    score: number;
+    checks: string[];
+    blocking: string[];
+    warnings: string[];
+  }>;
+  answers: {
+    canPublish: boolean;
+    ifNotWhatIsMissing: string[];
+    nextCommand: string | null;
+  };
 }
 
 function readGeneratedJson<T>(workspaceRoot: string, relative: string): T | null {
@@ -93,6 +117,74 @@ function unique(values: string[]): string[] {
   return [...new Set(values)];
 }
 
+function deployStageForCheck(name: string): string {
+  if (["generated", "package-lockfile", "frontend-build-script"].includes(name)) return "build";
+  if (["database-url"].includes(name)) return "database";
+  if (name.startsWith("auth-") || ["production-auth-mode", "auth-issuer", "auth-audience", "auth-jwks", "tenant-claim"].includes(name)) return "auth";
+  if (name.startsWith("workos")) return "workos";
+  if (name.startsWith("auth-md") || name === "oauth-protected-resource") return "auth metadata";
+  if (name.startsWith("field-test")) return "field test";
+  if (name === "live-production") return "live/runtime";
+  if (name === "deploy-env-sources") return "environment";
+  return "production";
+}
+
+function summarizeDeployReadiness(checks: DeployCheck[], nextActions: string[]): DeployReadinessSummary {
+  const blocking = checks
+    .filter((check) => !check.ok && check.severity === "error")
+    .map((check) => `${check.name}: ${check.message}`);
+  const warnings = checks
+    .filter((check) => !check.ok && check.severity === "warning")
+    .map((check) => `${check.name}: ${check.message}`);
+  const stageNames = [
+    "build",
+    "environment",
+    "database",
+    "auth",
+    "workos",
+    "auth metadata",
+    "field test",
+    "live/runtime",
+    "production",
+  ];
+  const stages = stageNames
+    .map((stage) => {
+      const stageChecks = checks.filter((check) => deployStageForCheck(check.name) === stage);
+      const stageBlocking = stageChecks
+        .filter((check) => !check.ok && check.severity === "error")
+        .map((check) => `${check.name}: ${check.message}`);
+      const stageWarnings = stageChecks
+        .filter((check) => !check.ok && check.severity === "warning")
+        .map((check) => `${check.name}: ${check.message}`);
+      const passed = stageChecks.filter((check) => check.ok || check.severity === "warning").length;
+      const score = stageChecks.length === 0 ? 100 : Math.round((passed / stageChecks.length) * 100);
+      return {
+        name: stage,
+        ok: stageBlocking.length === 0,
+        score,
+        checks: stageChecks.map((check) => check.name),
+        blocking: stageBlocking,
+        warnings: stageWarnings,
+      };
+    })
+    .filter((stage) => stage.checks.length > 0);
+  const passed = checks.filter((check) => check.ok || check.severity === "warning").length;
+  const score = checks.length === 0 ? 100 : Math.round((passed / checks.length) * 100);
+  const canPublish = blocking.length === 0;
+  return {
+    score,
+    status: blocking.length > 0 ? "blocked" : warnings.length > 0 ? "warning" : "ready",
+    blocking,
+    warnings,
+    stages,
+    answers: {
+      canPublish,
+      ifNotWhatIsMissing: blocking,
+      nextCommand: canPublish ? "forge deploy verify --production --url https://app.example.com --json" : nextActions[0] ?? null,
+    },
+  };
+}
+
 function hasWorkOSIntegration(workspaceRoot: string): boolean {
   const secrets = new Set(requiredSecretNames(workspaceRoot));
   return secrets.has("WORKOS_API_KEY") ||
@@ -596,7 +688,7 @@ function databaseReadyCommand(options: DeployCommandOptions): string {
 function renderProductionReadme(): string {
   return `# ForgeOS Production Deploy
 
-This directory is generated by \`forge deploy package --target docker\`.
+This directory is generated by \`forge deploy init --target docker\` or \`forge deploy package --target docker\`.
 
 ## 1. Prepare production env
 
@@ -619,13 +711,17 @@ For WorkOS-backed apps, local dry-runs are not enough for production deploy
 readiness. Run:
 
 \`\`\`bash
+forge workos setup --real --file workos-seed.yml --json
 forge workos prove --real --file workos-seed.yml --json
 \`\`\`
 
-This applies or confirms hosted WorkOS config/seed through the WorkOS CLI and
-writes \`.workos-seed-state.json\`. \`forge deploy check --production\` requires
-that state to match the current \`workos-seed.yml\` before treating WorkOS
-posture as production evidence.
+This applies or confirms hosted redirect/CORS/webhook config and seed data
+through the WorkOS CLI and writes \`.workos-seed-state.json\`. \`forge deploy
+check --production\` requires that state to match the current \`workos-seed.yml\`
+before treating WorkOS posture as production evidence. WorkOS FGA is optional:
+most apps can ship with AuthKit, RBAC permission claims, Forge policies, and
+tenant isolation; use \`forge add auth workos --with-fga\` only when the app needs
+resource-level authorization outside normal role/permission checks.
 
 ## 2. Prove the app before traffic
 
@@ -633,9 +729,12 @@ posture as production evidence.
 forge generate --check --json
 forge check --json
 forge authmd generate --json
+forge env doctor --target production --json
 forge auth prove --scenario multi-tenant --json
+forge workos setup --real --file workos-seed.yml --json
 forge workos prove --real --file workos-seed.yml --json
 forge field-test run --realistic --json
+forge deploy readiness --production --json
 forge deploy check --production --json
 \`\`\`
 
@@ -654,7 +753,7 @@ forge auth prove --prod --token <jwt> --json
 forge deploy verify --production --url https://app.example.com --json
 \`\`\`
 
-\`forge auth prove --prod\` verifies a real JWT/OIDC token against the configured issuer/audience/JWKS. \`forge deploy verify --production\` probes \`GET /health\`, \`HEAD /auth.md\`, \`GET /auth.md\`, \`HEAD /.well-known/oauth-protected-resource\`, and \`GET /.well-known/oauth-protected-resource\`; it also validates auth metadata content-types and requires the OAuth protected-resource metadata body to be valid JSON.
+\`forge auth prove --prod\` verifies a real JWT/OIDC token against the configured issuer/audience/JWKS. \`forge deploy verify --production\` probes required endpoints \`GET /health\`, \`HEAD /auth.md\`, \`GET /auth.md\`, \`HEAD /.well-known/oauth-protected-resource\`, and \`GET /.well-known/oauth-protected-resource\`; it also validates auth metadata content-types and requires the OAuth protected-resource metadata body to be valid JSON. Optional probes check \`GET /ready\`, \`GET /live/status\`, \`GET /outbox/status\`, and \`HEAD /webhooks/workos\` when the app exposes those operational endpoints.
 `;
 }
 
@@ -669,10 +768,17 @@ function buildPlan(options: DeployCommandOptions): DeployCommandResult {
         "forge deploy verify --production --url https://<your-forge-cloud-app> --json",
       ]
     : [
-        "forge deploy package --target docker",
+        "forge deploy init --target docker",
         "cp deploy/.env.production.example deploy/.env.production",
-        "forge deploy check --production --json",
+        "forge authmd generate --json",
+        "forge env doctor --target production --json",
+        "forge auth prove --scenario multi-tenant --json",
+        "forge workos setup --real --file workos-seed.yml --json",
+        "forge workos prove --real --file workos-seed.yml --json",
         FIELD_TEST_PRODUCTION_COMMAND,
+        "forge deploy readiness --production --json",
+        "forge deploy check --production --json",
+        "forge deploy package --target docker",
         "docker compose -f deploy/docker-compose.yml up --build",
         "forge deploy verify --production --url https://app.example.com --json",
       ];
@@ -699,10 +805,12 @@ function buildPlan(options: DeployCommandOptions): DeployCommandResult {
         "field-test report exists with runtime/auth/UI probes",
         "runtime /health responds",
         "tenant and policy proof is run before public traffic",
+        "readiness score has no blocking items",
       ],
       notes: [
         "dev-headers auth is local-only and must not be enabled for public runtime.",
         "Use forge workos doctor/seed when WorkOS is configured.",
+        "WorkOS FGA is optional; ordinary WorkOS apps can be production-ready with AuthKit/RBAC permission claims, Forge policies, and tenant isolation.",
         "Use forge test authz or HTTP probes to prove cross-tenant denial.",
       ],
     },
@@ -971,6 +1079,10 @@ async function buildChecks(options: DeployCommandOptions): Promise<DeployCommand
   const failureActions = unique(checks.flatMap((check) =>
     !check.ok && check.command ? expandDeployFailureCommand(check.command) : []
   ));
+  const nextActions = errorFree
+    ? ["forge deploy verify --production --url https://app.example.com --json"]
+    : failureActions;
+  const readiness = summarizeDeployReadiness(checks, nextActions);
   return normalizeForgeCliCommandsInValue(options.workspaceRoot, {
     schemaVersion: "0.1.0",
     ok: errorFree,
@@ -979,9 +1091,10 @@ async function buildChecks(options: DeployCommandOptions): Promise<DeployCommand
     target: options.target,
     production: options.production,
     checks,
-    nextActions: errorFree
-      ? ["forge deploy verify --production --url https://app.example.com --json"]
-      : failureActions,
+    blocking: readiness.blocking,
+    warnings: readiness.warnings,
+    readiness,
+    nextActions,
     exitCode: errorFree ? 0 : 1,
   });
 }
@@ -1020,6 +1133,7 @@ function renderDocker(options: DeployCommandOptions): DeployCommandResult {
     files: files.map(([file]) => file),
     nextActions: [
       "cp deploy/.env.production.example deploy/.env.production",
+      "forge deploy readiness --production --json",
       "forge deploy check --production --json",
       "docker compose -f deploy/docker-compose.yml up --build",
     ],
@@ -1087,22 +1201,32 @@ async function verifyUrl(options: DeployCommandOptions): Promise<DeployCommandRe
       exitCode: 1,
     };
   }
-  const probes = await Promise.all([
-    probe("GET", `${base}/health`),
-    probe("HEAD", `${base}/auth.md`, { contentTypeIncludes: "text/markdown" }),
-    probe("GET", `${base}/auth.md`, { contentTypeIncludes: "text/markdown" }),
-    probe("HEAD", `${base}/.well-known/oauth-protected-resource`, { contentTypeIncludes: "application/json" }),
-    probe("GET", `${base}/.well-known/oauth-protected-resource`, { contentTypeIncludes: "application/json", json: true }),
-  ]);
+  const probeSpecs: Array<{ method: "GET" | "HEAD"; path: string; expectation?: DeployProbeExpectation }> = [
+    { method: "GET", path: "/health", expectation: { required: true } },
+    { method: "HEAD", path: "/auth.md", expectation: { contentTypeIncludes: "text/markdown", required: true } },
+    { method: "GET", path: "/auth.md", expectation: { contentTypeIncludes: "text/markdown", required: true } },
+    { method: "HEAD", path: "/.well-known/oauth-protected-resource", expectation: { contentTypeIncludes: "application/json", required: true } },
+    { method: "GET", path: "/.well-known/oauth-protected-resource", expectation: { contentTypeIncludes: "application/json", json: true, required: true } },
+    { method: "GET", path: "/ready", expectation: { contentTypeIncludes: "application/json" } },
+    { method: "GET", path: "/live/status", expectation: { contentTypeIncludes: "application/json" } },
+    { method: "GET", path: "/outbox/status", expectation: { contentTypeIncludes: "application/json" } },
+    { method: "HEAD", path: "/webhooks/workos" },
+  ];
+  const probes = await Promise.all(probeSpecs.map((item) =>
+    probe(item.method, `${base}${item.path}`, item.expectation ?? {})
+  ));
   const checks = probes.map((item): DeployCheck => ({
     name: `${item.method} ${item.url.replace(base, "") || "/"}`,
     ok: item.ok,
-    severity: item.url.endsWith("/health") || options.production ? "error" : "warning",
+    severity: probeSpecs.find((spec) => `${base}${spec.path}` === item.url && spec.method === item.method)?.expectation?.required || item.url.endsWith("/health")
+      ? "error"
+      : "warning",
     message: item.ok
       ? `HTTP ${item.status}${item.contentType ? ` ${item.contentType}` : ""}`
       : item.error ?? `HTTP ${item.status ?? "failed"}`,
   }));
   const ok = checks.every((check) => check.ok || check.severity === "warning");
+  const readiness = summarizeDeployReadiness(checks, ok ? [] : ["check runtime logs", "forge deploy check --production --json"]);
   return {
     schemaVersion: "0.1.0",
     ok,
@@ -1111,16 +1235,33 @@ async function verifyUrl(options: DeployCommandOptions): Promise<DeployCommandRe
     target: options.target,
     production: options.production,
     checks,
+    blocking: readiness.blocking,
+    warnings: readiness.warnings,
     probes,
-    nextActions: ok ? ["forge handoff --json"] : ["check runtime logs", "forge deploy check --production --json"],
+    readiness,
+    nextActions: ok
+      ? [
+          "forge auth prove --prod --token <jwt> --json",
+          "forge auth prove --scenario multi-tenant --json",
+          "forge handoff --json",
+        ]
+      : ["check runtime logs", "forge deploy check --production --json"],
     exitCode: ok ? 0 : 1,
   };
 }
 
 export async function runDeployCommand(options: DeployCommandOptions): Promise<DeployCommandResult> {
   if (options.subcommand === "plan") return buildPlan(options);
+  if (options.subcommand === "readiness") {
+    const result = await buildChecks({ ...options, subcommand: "check", production: true });
+    return {
+      ...result,
+      action: "readiness",
+      nextActions: result.readiness?.answers.nextCommand ? [result.readiness.answers.nextCommand] : result.nextActions,
+    };
+  }
   if (options.subcommand === "check") return buildChecks(options);
-  if (options.subcommand === "render" || options.subcommand === "package") return renderDocker(options);
+  if (options.subcommand === "init" || options.subcommand === "render" || options.subcommand === "package") return renderDocker(options);
   return verifyUrl(options);
 }
 
@@ -1132,7 +1273,13 @@ export function formatDeployHuman(result: DeployCommandResult): string {
   const lines = [
     `deploy ${result.action} ${result.ok ? "ok" : "failed"}`,
     `target: ${result.target}`,
+    ...(result.readiness ? [
+      `readiness: ${result.readiness.status} (${result.readiness.score}/100)`,
+      `can publish: ${result.readiness.answers.canPublish ? "yes" : "no"}`,
+    ] : []),
     ...result.checks.map((check) => `${check.ok ? "ok" : check.severity === "warning" ? "warn" : "fail"} ${check.name}: ${check.message}`),
+    ...(result.blocking?.length ? ["", "Blocking:", ...result.blocking.map((item) => `  ${item}`)] : []),
+    ...(result.warnings?.length ? ["", "Warnings:", ...result.warnings.map((item) => `  ${item}`)] : []),
     ...(result.files?.length ? ["", "Files:", ...result.files.map((file) => `  ${file}`)] : []),
     ...(result.plan ? ["", result.plan.summary, "", "Commands:", ...result.plan.commands.map((command) => `  ${command}`)] : []),
     ...(result.nextActions.length ? ["", "Next:", ...result.nextActions.map((action) => `  ${action}`)] : []),

package/src/forge/cli/dev.ts

@@ -53,6 +53,7 @@ export interface DevCommandOptions {
   webOnly?: boolean;
   open?: boolean;
   webPort?: number;
+  publicApiUrl?: string;
   telemetry: string[];
   envFile?: string;
   mode?: "dev" | "serve";
@@ -305,6 +306,7 @@ function buildDetachedDevArgs(options: DevCommandOptions): string[] {
   if (options.webOnly) args.push("--web-only");
   if (options.open) args.push("--open");
   if (options.webPort !== undefined) args.push("--web-port", String(options.webPort));
+  if (options.publicApiUrl) args.push("--public-api-url", options.publicApiUrl);
   if (options.telemetry.length > 0) args.push("--telemetry", options.telemetry.join(","));
   if (options.envFile) args.push("--env-file", options.envFile);
   if (options.seed) args.push("--seed");
@@ -1343,13 +1345,14 @@ export async function runDevCommand(
 
   if (options.webOnly) {
     const apiUrl = `http://${host}:${port}`;
+    const publicApiUrl = options.publicApiUrl ?? apiUrl;
     const webHandle = startWebDevServer({
       workspaceRoot,
       host,
       port: webPort,
       requestedPort: webPortSelection.requestedPort,
       autoPortSelected: webPortSelection.autoPortSelected,
-      apiUrl,
+      apiUrl: publicApiUrl,
       json: options.json,
     });
     if (!webHandle) {
@@ -1451,7 +1454,7 @@ export async function runDevCommand(
         port: webPort,
         requestedPort: webPortSelection.requestedPort,
         autoPortSelected: webPortSelection.autoPortSelected,
-        apiUrl: handle.url,
+        apiUrl: options.publicApiUrl ?? handle.url,
         json: options.json,
       });
 

package/src/forge/cli/main.ts

@@ -20,6 +20,9 @@ function formatHelp(): string {
     "  forge field-test create vendor-access --auth workos --install --git --json  Create a real field-test app",
     "  forge field-test run --realistic --templates vendor-access --package-managers npm --json",
     "  forge field-test report --json  Summarize the machine-readable field-test report",
+    "  forge deploy init --target docker --json  Generate Docker production files, env template, and deploy README",
+    "  forge deploy readiness --production --json  Answer whether the app can publish, what blocks it, and the next command",
+    "  forge env doctor --target production --json  Show production env sources, missing keys, auth mode, database, and provider",
     "  forge seed status --json  Discover app seed commands from the generated runtime graph",
     "  forge seed dev --json     Run the app seed command against the local Forge dev runtime",
     "  forge seed dev --all-tenants --json  Seed every discovered local tenant/persona profile",
@@ -51,7 +54,7 @@ function formatHelp(): string {
     "  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 package --target docker  Write Docker production deploy files under deploy/",
-    "  forge deploy verify --production --url https://app.example.com --json  Probe /health and validate public auth metadata",
+    "  forge deploy verify --production --url https://app.example.com --json  Probe health, public auth metadata, and optional runtime endpoints",
     "  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",
@@ -107,6 +110,7 @@ function formatDevHelp(): string {
     "  --db memory|pglite|postgres|none  Choose the development database adapter",
     "  --port <port>                     API runtime port; use 0 for an ephemeral port",
     "  --web-port <port>                 Web dev server port; use 0 for an ephemeral port",
+    "  --public-api-url <url>            Browser-facing API URL injected into web env, useful for tunnels",
     "  --host <host>                     Bind host, default 127.0.0.1",
     "  --no-web                          Start API/runtime only",
     "  --api-only                        Start API/runtime only",
@@ -121,6 +125,7 @@ function formatDevHelp(): string {
     "",
     "Examples:",
     "  forge dev --db memory --port 3777 --web-port 5174",
+    "  forge dev --public-api-url http://localhost:3765",
     "  forge dev --db memory --port 0 --web-port 0",
     "  forge dev --seed --db pglite",
     "  forge dev --seed --all-tenants --db pglite",