forgeos 0.1.0-alpha.60 → 0.1.0-alpha.61

package/AGENTS.md

@@ -1,4 +1,4 @@
-// @forge-generated generator=0.1.0-alpha.60 input=dd73ff0861775ded0c4b42b55e3261a44043d4c09aa3c9f5641d3c23b17e2e6c content=721818a6f9a664aa898092d4aa5cd68cbbd8ad6e150c7d3ad3ef785a2e3fcf53
+// @forge-generated generator=0.1.0-alpha.61 input=6dd290dbb57f6f75a802f741028ac6dbd672aa09d598ba2639ffcec7fa7feb7d content=721818a6f9a664aa898092d4aa5cd68cbbd8ad6e150c7d3ad3ef785a2e3fcf53
 # AGENTS.md
 
 <!-- forge-generated:start -->

package/CHANGELOG.md

@@ -1,5 +1,21 @@
 # forgeos
 
+## 0.1.0-alpha.61
+
+### Patch Changes
+
+- Harden the WorkOS golden path and production deploy gate.
+
+  - Add the ForgeOS golden path status/plan flow for the official
+    `create -> auth -> field-test -> deploy` path.
+  - Add WorkOS real-auth proof helpers and env synchronization for app and web
+    workspaces, including backend-owned AuthKit session bridge guidance.
+  - Block production readiness when `deploy/.env.production` still contains
+    placeholder or dummy values, preventing local/demo WorkOS and database
+    settings from being mistaken for publishable production evidence.
+  - Expand field-test, deploy, env doctor, WorkOS, and golden-path regression
+    coverage, plus docs for the production-shaped WorkOS vendor-access flow.
+
 ## 0.1.0-alpha.60
 
 ### Patch Changes

package/README.md

@@ -75,6 +75,53 @@ npm run dev -- --open
 Template apps ignore `src/forge/_generated/`, `forge.lock`, and operational `.forge/**` work dirs by default so a freshly created app does not flood git or the editor with generated files. Run `forge generate` after checkout or before verification to recreate the agent contract, client SDK, frontend graph, capability map, and runtime manifests.
 Templates also include workspace editor excludes for generated/runtime directories so source files stay visually prominent.
 
+## Production-Shaped Golden Path
+
+For a real multi-tenant app with WorkOS/AuthKit, start with the golden-path
+planner instead of piecing together commands from docs:
+
+```bash
+forge golden-path plan --auth workos --target docker --real --production --json
+```
+
+The canonical path is:
+
+```bash
+forge field-test create vendor-access --auth workos --template vendor-access --package-manager npm --install --git --json
+cd vendor-access
+npm run forge -- workos env --client-id client_... --write --json
+npm run forge -- workos setup --real --file workos-seed.yml --json
+npm run forge -- auth prove --provider workos --real --client-id client_... --file workos-seed.yml --json
+npm run forge -- field-test run --realistic --json
+npm run forge -- deploy readiness --production --json
+npm run forge -- deploy package --target docker
+```
+
+For an existing app, ask ForgeOS for the current blocking stage:
+
+```bash
+forge golden-path status --real --production --json
+```
+
+It reports whether the app can publish, which stage blocks publication, and the
+next command to run. WorkOS FGA is optional; ordinary B2B apps can ship with
+AuthKit, RBAC permission claims, Forge policies, and tenant isolation.
+
+If the AuthKit client id is already known, pass it to the status command so the
+next action is copy/paste exact instead of using `client_...` placeholders:
+
+```bash
+forge golden-path status --real --production --client-id client_... --json
+```
+
+When the WorkOS CLI can confirm a client id exists but cannot expose the value,
+`golden-path status` asks for `forge workos env --client-id client_... --write
+--json`; ForgeOS then writes the OIDC/JWKS and web public env values without
+dashboard clicks or shell-specific env syntax. The higher-level
+`forge auth prove --provider workos --real --client-id client_... --file
+workos-seed.yml --json` wrapper performs the same env preparation before it
+proves hosted WorkOS setup.
+
 For release or external smoke testing, choose the Forge package source explicitly:
 
 ```bash

package/docs/changelog.md

@@ -4,7 +4,63 @@ Release history for the `forgeos` npm package.
 
 The canonical source file in the repository is `CHANGELOG.md`.
 
-## Unreleased
+## 0.1.0-alpha.61
+
+- Added `forge golden-path plan/status` as the canonical
+  create -> WorkOS auth -> field-test -> Docker deploy production path for
+  agents and users.
+- `forge golden-path plan/status` now accepts `--forge-spec`, so maintainers can
+  run the same P0 path against `npm:forgeos@alpha`, a packed tarball, or a local
+  checkout before publishing.
+- `forge golden-path status --real --production --json` now wraps WorkOS
+  posture, field-test evidence, and deploy readiness into one answer with the
+  current stage, blockers, and next command.
+- `forge golden-path plan/status` now accepts `--client-id client_...`, so
+  agents that already know the AuthKit client id get exact WorkOS env/proof
+  commands instead of placeholder next actions.
+- `forge golden-path status` now includes the first blocking stage in
+  `summary.blockers` (for example `workos-real-seed` or `workos-doctor`) before
+  lower-level deploy readiness blockers, so agents do not have to infer the
+  real next action.
+- Added `forge auth prove --provider workos --real --client-id client_...
+  --file workos-seed.yml --json` as the provider-aware auth proof wrapper
+  around hosted WorkOS setup, seed evidence, public AuthKit env preparation, and
+  CLI login instructions.
+- `forge auth prove --provider workos --real --client-id ...` now reads the
+  `.env.local` values it just prepared, so a successful real WorkOS proof reports
+  `mode: "oidc"`/`productionReady: true` instead of falling back to local
+  `dev-headers` in the same process.
+- Added `forge workos env --client-id client_... --write --json` to prepare `.env.local` and
+  `web/.env.local` for real WorkOS/AuthKit proof, including audience/JWKS values
+  when `WORKOS_CLIENT_ID` is supplied and an explicit next action when the CLI
+  reports a client id exists but cannot expose the value.
+- `forge golden-path plan/status --real` now includes the WorkOS env preparation
+  gate before hosted setup/seed proof, so agents fix missing client/JWKS envs
+  before retrying AuthKit login or deploy readiness.
+- In `--real` mode, `forge golden-path status` now treats missing or stale
+  `.workos-seed-state.json` evidence as an auth-stage blocker and points agents
+  to `forge auth prove --provider workos --real --file workos-seed.yml --json`
+  after env is ready, or the `--client-id client_...` form when agents need the
+  proof command to prepare WorkOS env in the same step.
+- `forge golden-path status` now returns compact field-test/deploy summaries
+  instead of embedding full command stdout, keeping the JSON safe for agents to
+  parse after realistic field-test runs.
+- `forge deploy plan` and generated Docker production README output now point
+  back to `forge golden-path status --real --production --json` as the first
+  app-to-production triage command.
+- `forge deploy readiness/check` now prioritizes the deploy env action that
+  actually unblocks production, such as copying
+  `deploy/.env.production.example` to `deploy/.env.production` before rerunning
+  auth diagnostics.
+- `forge env doctor --target production` and `forge deploy check --production`
+  now reject known placeholder/dummy production env values without printing the
+  secret value, preventing copied examples like `client_test_local` or
+  `sk_test_dummy_do_not_use` from being treated as deploy-ready evidence.
+- Docs now surface the WorkOS real + Docker deploy golden path from the CLI,
+  golden-path, field-testing, production-readiness pages, and README.
+- Added a redacted WorkOS real vendor-access field report documenting hosted
+  setup, idempotent seed, AuthKit session bridge, tenant normalization,
+  policy denial, field-test evidence, and production deploy blockers.
 
 ## 0.1.0-alpha.60
 

package/package.json

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

package/src/forge/_generated/releaseManifest.ts

@@ -1,4 +1,4 @@
-// @forge-generated generator=0.1.0-alpha.60 input=dd73ff0861775ded0c4b42b55e3261a44043d4c09aa3c9f5641d3c23b17e2e6c content=185c42e22dbf3b1cc6e329af86d71f513f19cde067ec0e4ea0a228df020c30f9
+// @forge-generated generator=0.1.0-alpha.61 input=6dd290dbb57f6f75a802f741028ac6dbd672aa09d598ba2639ffcec7fa7feb7d content=82fdee65e1219bbb3fa9572a4c904c7e1e4061b00430769528426ece3b3a4067
 export const releaseManifest = {
   "defaultProvider": "local",
   "diagnostics": [],
@@ -19,7 +19,7 @@ export const releaseManifest = {
     "custom"
   ],
   "packageName": "forgeos",
-  "packageVersion": "0.1.0-alpha.60",
-  "releaseId": "forgeos@0.1.0-alpha.60+unknown",
+  "packageVersion": "0.1.0-alpha.61",
+  "releaseId": "forgeos@0.1.0-alpha.61+unknown",
   "schemaVersion": "0.1.0"
 } as const;

package/src/forge/cli/auth.ts

@@ -4,11 +4,12 @@ import {
   FORGE_AUTH_INVALID_AUDIENCE,
   FORGE_AUTH_JWKS_FAILED,
 } from "../compiler/diagnostics/codes.ts";
-import { loadAuthConfigFromEnv, type AuthClaimsMapping } from "../runtime/auth/config.ts";
+import { AUTH_ENV, 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";
+import { loadEnvFiles } from "../runtime/secrets/env-loader.ts";
 import { existsSync } from "node:fs";
 import { join } from "node:path";
 import { normalizeForgeCliCommandsInValue } from "../workspace/forge-cli.ts";
@@ -17,6 +18,9 @@ import {
   collectPolicyPermissions,
   missingValues,
   parseSeedFile,
+  runWorkOSCommand,
+  type WorkOSCommandResult,
+  type WorkOSCommandRunner,
 } from "./workos.ts";
 
 export type AuthSubcommand = "check" | "config" | "decode" | "test-token" | "jwks" | "prove" | "status";
@@ -28,6 +32,11 @@ export interface AuthCommandOptions {
   token?: string;
   prod?: boolean;
   scenario?: string;
+  provider?: "workos";
+  real?: boolean;
+  file?: string;
+  clientId?: string;
+  commandRunner?: WorkOSCommandRunner;
 }
 
 export interface AuthCommandResult {
@@ -38,6 +47,42 @@ export interface AuthCommandResult {
   exitCode: 0 | 1;
 }
 
+const AUTH_CLI_ENV_KEYS = Object.values(AUTH_ENV);
+
+function withCliAuthEnv<T>(workspaceRoot: string, fn: () => T): T {
+  const { store } = loadEnvFiles({ workspaceRoot });
+  const previous = AUTH_CLI_ENV_KEYS.map((key) => ({
+    key,
+    had: Object.prototype.hasOwnProperty.call(process.env, key),
+    value: process.env[key],
+  }));
+
+  for (const key of AUTH_CLI_ENV_KEYS) {
+    if (process.env[key] === undefined) {
+      const value = store.resolve(key);
+      if (value !== undefined) {
+        process.env[key] = value;
+      }
+    }
+  }
+
+  try {
+    return fn();
+  } finally {
+    for (const entry of previous) {
+      if (entry.had) {
+        process.env[entry.key] = entry.value;
+      } else {
+        delete process.env[entry.key];
+      }
+    }
+  }
+}
+
+function loadAuthConfigForCli(workspaceRoot: string) {
+  return withCliAuthEnv(workspaceRoot, () => loadAuthConfigFromEnv(workspaceRoot));
+}
+
 function detectWorkOS(workspaceRoot: string, claims: AuthClaimsMapping) {
   const secretRegistry = loadSecretRegistry(workspaceRoot);
   const secretNames = new Set((secretRegistry?.secrets ?? []).map((secret) => secret.name));
@@ -94,7 +139,7 @@ function configErrors(config: ReturnType<typeof loadAuthConfigFromEnv>): { code:
 }
 
 function buildAuthPosture(workspaceRoot: string) {
-  const config = loadAuthConfigFromEnv(workspaceRoot);
+  const config = loadAuthConfigForCli(workspaceRoot);
   const productionMode = config.mode === "jwt" || config.mode === "oidc";
   const errors = configErrors(config);
   const configReady = errors.length === 0;
@@ -272,8 +317,41 @@ function buildMultiTenantProof(workspaceRoot: string, workos: ReturnType<typeof
   });
 }
 
+function runProviderProof(options: AuthCommandOptions): WorkOSCommandResult | null {
+  if (options.provider !== "workos") return null;
+  const file = options.file ?? "workos-seed.yml";
+  if (options.real && options.clientId) {
+    const env = runWorkOSCommand({
+      subcommand: "env",
+      workspaceRoot: options.workspaceRoot,
+      json: true,
+      file,
+      yes: false,
+      dryRun: false,
+      real: true,
+      write: true,
+      clientId: options.clientId,
+      commandRunner: options.commandRunner,
+    });
+    if (!env.ok) {
+      return env;
+    }
+  }
+  return runWorkOSCommand({
+    subcommand: "prove",
+    workspaceRoot: options.workspaceRoot,
+    json: true,
+    file,
+    yes: false,
+    dryRun: !options.real,
+    real: options.real ?? false,
+    clientId: options.clientId,
+    commandRunner: options.commandRunner,
+  });
+}
+
 function validateConfig(workspaceRoot: string): AuthCommandResult {
-  const config = loadAuthConfigFromEnv(workspaceRoot);
+  const config = loadAuthConfigForCli(workspaceRoot);
   const errors = configErrors(config);
   const workos = detectWorkOS(workspaceRoot, config.claims);
 
@@ -298,7 +376,7 @@ function validateConfig(workspaceRoot: string): AuthCommandResult {
 }
 
 function publicConfig(workspaceRoot: string): AuthCommandResult {
-  const config = loadAuthConfigFromEnv(workspaceRoot);
+  const config = loadAuthConfigForCli(workspaceRoot);
   const workos = detectWorkOS(workspaceRoot, config.claims);
   return {
     ok: true,
@@ -319,7 +397,7 @@ function publicConfig(workspaceRoot: string): AuthCommandResult {
 }
 
 function decodeToken(workspaceRoot: string, token: string | undefined): AuthCommandResult {
-  const config = loadAuthConfigFromEnv(workspaceRoot);
+  const config = loadAuthConfigForCli(workspaceRoot);
   if (!token) {
     return {
       ok: false,
@@ -354,7 +432,7 @@ async function testToken(
   workspaceRoot: string,
   token: string | undefined,
 ): Promise<AuthCommandResult> {
-  const config = loadAuthConfigFromEnv(workspaceRoot);
+  const config = loadAuthConfigForCli(workspaceRoot);
   if (!token) {
     return {
       ok: false,
@@ -430,8 +508,9 @@ export async function runAuthCommand(
     };
   }
   if (options.subcommand === "prove") {
+    const providerProof = runProviderProof(options);
     const checked = validateConfig(options.workspaceRoot);
-    const config = loadAuthConfigFromEnv(options.workspaceRoot);
+    const config = loadAuthConfigForCli(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);
@@ -444,7 +523,9 @@ export async function runAuthCommand(
         : options.prod && tokenProof && !tokenProof.ok
           ? tokenProof.error
           : undefined;
-    const proofOk = checked.ok && (!options.prod || (productionMode && tokenProof?.ok === true));
+    const proofOk = checked.ok &&
+      (!options.prod || (productionMode && tokenProof?.ok === true)) &&
+      (!providerProof || providerProof.ok);
     const multiTenantProof = options.scenario === "multi-tenant"
       ? buildMultiTenantProof(options.workspaceRoot, workos, config.requiresTenant)
       : null;
@@ -460,8 +541,11 @@ export async function runAuthCommand(
         productionReady: productionMode && checked.ok,
         prod: options.prod === true,
         scenario: options.scenario ?? null,
+        provider: options.provider ?? null,
+        real: options.real === true,
         authPosture: posture,
         ...(tokenProof ? { tokenProof: tokenProof.ok ? tokenProof.data : tokenProof.error } : {}),
+        ...(providerProof ? { providerProof } : {}),
         ...(multiTenantProof ? { multiTenantProof } : {}),
         invariants: [
           {
@@ -495,9 +579,19 @@ export async function runAuthCommand(
           },
         ],
         workos,
+        nextActions: [
+          ...(providerProof && !providerProof.ok
+            ? providerProof.data && typeof providerProof.data === "object" && "nextCommand" in providerProof.data
+              ? [String((providerProof.data as { nextCommand?: unknown }).nextCommand)]
+              : ["forge workos prove --real --file workos-seed.yml --json"]
+            : []),
+          ...(options.provider === "workos" && providerProof?.ok
+            ? ["forge auth prove --scenario multi-tenant --json", "forge deploy readiness --production --json"]
+            : []),
+        ],
         checkedAt: "deterministic",
       },
-      error: prodError ?? checked.error,
+      error: prodError ?? (!providerProof || providerProof.ok ? checked.error : { code: "FORGE_AUTH_PROVIDER_PROOF_FAILED", message: "WorkOS provider proof failed" }),
       exitCode: proofOk && scenarioOk ? 0 : 1,
     };
   }
@@ -511,7 +605,7 @@ export async function runAuthCommand(
     return testToken(options.workspaceRoot, options.token);
   }
 
-  const config = loadAuthConfigFromEnv(options.workspaceRoot);
+  const config = loadAuthConfigForCli(options.workspaceRoot);
   return {
     ok: true,
     mode: config.mode,
@@ -540,9 +634,12 @@ function authPostureFromResult(result: AuthCommandResult): Record<string, unknow
 export function formatAuthHuman(result: AuthCommandResult): string {
   const posture = authPostureFromResult(result);
   if (posture) {
+    const data = result.data && typeof result.data === "object" ? result.data as Record<string, unknown> : {};
     const classification = typeof posture.classification === "string" ? posture.classification : result.mode;
     const reason = typeof posture.reason === "string" ? posture.reason : result.error?.message;
-    const nextActions = Array.isArray(posture.nextActions) ? posture.nextActions.filter((item): item is string => typeof item === "string") : [];
+    const postureNextActions = Array.isArray(posture.nextActions) ? posture.nextActions.filter((item): item is string => typeof item === "string") : [];
+    const proofNextActions = Array.isArray(data.nextActions) ? data.nextActions.filter((item): item is string => typeof item === "string") : [];
+    const nextActions = Array.from(new Set([...proofNextActions, ...postureNextActions]));
     const lines = [
       `Auth ${result.mode}: ${result.ok ? "ok" : "failed"} (${classification})`,
       `Production ready: ${posture.productionReady === true ? "yes" : "no"}`,

package/src/forge/cli/commands.ts

@@ -226,6 +226,11 @@ import {
   formatFieldTestJson,
   runFieldTestCommand,
 } from "./field-test.ts";
+import {
+  formatGoldenPathHuman,
+  formatGoldenPathJson,
+  runGoldenPathCommand,
+} from "./golden-path.ts";
 import {
   formatSeedHuman,
   formatSeedJson,
@@ -2144,6 +2149,11 @@ export async function executeCommand(command: ForgeCommand): Promise<number> {
       process.stdout.write(command.json ? formatDeployJson(result) : formatDeployHuman(result));
       return result.exitCode;
     }
+    case "golden-path": {
+      const result = await runGoldenPathCommand(command);
+      process.stdout.write(command.json ? formatGoldenPathJson(result) : formatGoldenPathHuman(result));
+      return result.exitCode;
+    }
     case "field-test": {
       const result = await runFieldTestCommand(command);
       process.stdout.write(command.json ? formatFieldTestJson(result) : formatFieldTestHuman(result));

package/src/forge/cli/deploy.ts

@@ -12,6 +12,7 @@ import { join } from "node:path";
 import { runAuthCommand } from "./auth.ts";
 import { runAuthMdCommand } from "./authmd.ts";
 import { runWorkOSCommand } from "./workos.ts";
+import { productionPlaceholderEnvProblems } from "./env-placeholders.ts";
 
 export type DeploySubcommand = "plan" | "init" | "check" | "readiness" | "render" | "package" | "verify";
 export type DeployTarget = "docker" | "forge-cloud";
@@ -125,7 +126,7 @@ function deployStageForCheck(name: string): string {
   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";
+  if (name === "deploy-env-sources" || name === "production-env-values") return "environment";
   return "production";
 }
 
@@ -588,6 +589,13 @@ function processDeployEnv(): Record<string, string> {
   );
 }
 
+function productionEnvValues(workspaceRoot: string): Record<string, string> {
+  return {
+    ...readDeployEnvFile(workspaceRoot),
+    ...processDeployEnv(),
+  };
+}
+
 function deployEnvSources(workspaceRoot: string): Record<string, unknown> {
   const processEnv = processDeployEnv();
   const deployEnv = readDeployEnvFile(workspaceRoot);
@@ -601,10 +609,7 @@ function deployEnvSources(workspaceRoot: string): Record<string, unknown> {
       keys: envKeys(values),
     };
   });
-  const productionEvidence = {
-    ...deployEnv,
-    ...processEnv,
-  };
+  const productionEvidence = productionEnvValues(workspaceRoot);
   return {
     readOrder: ["process.env", DEPLOY_ENV_FILE],
     note: `${DEPLOY_ENV_FILE} and current process env are production deploy evidence; .env/.env.local are reported only as local guidance and are not used to pass production gates.`,
@@ -690,6 +695,16 @@ function renderProductionReadme(): string {
 
 This directory is generated by \`forge deploy init --target docker\` or \`forge deploy package --target docker\`.
 
+Start with the golden-path status gate when you are unsure what comes next:
+
+\`\`\`bash
+forge golden-path status --real --production --json
+\`\`\`
+
+It reads WorkOS hosted setup evidence, field-test evidence, and deploy readiness
+without hiding the lower-level commands. If it cannot publish, it returns the
+current blocking stage and the next command to run.
+
 ## 1. Prepare production env
 
 \`\`\`bash
@@ -760,6 +775,7 @@ forge deploy verify --production --url https://app.example.com --json
 function buildPlan(options: DeployCommandOptions): DeployCommandResult {
   const commands = options.target === "forge-cloud"
     ? [
+        "forge golden-path status --real --production --json",
         "forge deploy check --production --json",
         "forge auth check --production --json",
         "forge authmd check --json",
@@ -768,6 +784,7 @@ function buildPlan(options: DeployCommandOptions): DeployCommandResult {
         "forge deploy verify --production --url https://<your-forge-cloud-app> --json",
       ]
     : [
+        "forge golden-path status --real --production --json",
         "forge deploy init --target docker",
         "cp deploy/.env.production.example deploy/.env.production",
         "forge authmd generate --json",
@@ -810,6 +827,7 @@ function buildPlan(options: DeployCommandOptions): DeployCommandResult {
       notes: [
         "dev-headers auth is local-only and must not be enabled for public runtime.",
         "Use forge workos doctor/seed when WorkOS is configured.",
+        "Use forge golden-path status --real --production --json when the next blocking stage is unclear.",
         "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.",
       ],
@@ -858,6 +876,22 @@ async function buildChecks(options: DeployCommandOptions): Promise<DeployCommand
     message: `${DEPLOY_ENV_FILE} and process.env are production deploy evidence; .env/.env.local are local guidance only`,
     details: deployEnvSources(options.workspaceRoot),
   });
+  const placeholderEnvProblems = options.production
+    ? productionPlaceholderEnvProblems(productionEnvValues(options.workspaceRoot), DEPLOY_ENV_KEYS as unknown as string[])
+    : [];
+  checks.push({
+    name: "production-env-values",
+    ok: placeholderEnvProblems.length === 0,
+    severity: "error",
+    message: placeholderEnvProblems.length === 0
+      ? "production env values do not contain known placeholders"
+      : `production env contains placeholder value(s): ${placeholderEnvProblems.map((problem) => problem.key).join(", ")}`,
+    command: "edit deploy/.env.production with real production values",
+    details: {
+      placeholders: placeholderEnvProblems,
+      valuesRedacted: true,
+    },
+  });
 
   const auth = await withDeployEnv(options.workspaceRoot, async () => loadAuthConfigFromEnv(options.workspaceRoot));
   const productionAuth = auth.mode === "jwt" || auth.mode === "oidc";
@@ -1076,9 +1110,10 @@ async function buildChecks(options: DeployCommandOptions): Promise<DeployCommand
   });
 
   const errorFree = checks.every((check) => check.ok || check.severity === "warning");
-  const failureActions = unique(checks.flatMap((check) =>
+  const rawFailureActions = unique(checks.flatMap((check) =>
     !check.ok && check.command ? expandDeployFailureCommand(check.command) : []
   ));
+  const failureActions = prioritizeDeployFailureActions(options, checks, rawFailureActions);
   const nextActions = errorFree
     ? ["forge deploy verify --production --url https://app.example.com --json"]
     : failureActions;
@@ -1110,6 +1145,22 @@ function expandDeployFailureCommand(command: string): string[] {
   return [command];
 }
 
+function prioritizeDeployFailureActions(
+  options: DeployCommandOptions,
+  checks: DeployCheck[],
+  actions: string[],
+): string[] {
+  const database = checks.find((check) => check.name === "database-url");
+  if (!database || database.ok || !database.command) {
+    return actions;
+  }
+  const deployEnvMissing = !nodeFileSystem.exists(join(options.workspaceRoot, DEPLOY_ENV_FILE));
+  if (deployEnvMissing && database.command === "cp deploy/.env.production.example deploy/.env.production") {
+    return unique([database.command, ...actions.filter((action) => action !== database.command)]);
+  }
+  return actions;
+}
+
 function renderDocker(options: DeployCommandOptions): DeployCommandResult {
   const dir = join(options.workspaceRoot, "deploy");
   nodeFileSystem.mkdirp(dir);

package/src/forge/cli/env-placeholders.ts

@@ -0,0 +1,62 @@
+export interface PlaceholderEnvProblem {
+  key: string;
+  reason: string;
+}
+
+const GENERIC_PLACEHOLDER_PATTERNS: Array<{ pattern: RegExp; reason: string }> = [
+  { pattern: /\bexample\.(com|test|org|net)\b/, reason: "example domain" },
+  { pattern: /\bdummy\b/, reason: "dummy marker" },
+  { pattern: /\bplaceholder\b/, reason: "placeholder marker" },
+  { pattern: /\bchange[-_]?me\b/, reason: "change-me marker" },
+  { pattern: /\bdo[-_]?not[-_]?use\b/, reason: "do-not-use marker" },
+  { pattern: /^<.*>$/, reason: "angle-bracket placeholder" },
+  { pattern: /^your[-_]/, reason: "your-value placeholder" },
+];
+
+const KEY_PLACEHOLDER_PATTERNS: Record<string, Array<{ pattern: RegExp; reason: string }>> = {
+  DATABASE_URL: [
+    { pattern: /^postgres:\/\/forge:forge@postgres:5432\/forge_app$/i, reason: "generated Docker example database URL" },
+    { pattern: /^postgres:\/\/forge:forge@db:5432\/forge$/i, reason: "local dummy database URL" },
+    { pattern: /^postgres:\/\/local-only\b/i, reason: "local-only database URL" },
+  ],
+  WORKOS_API_KEY: [
+    { pattern: /^sk_test_dummy/i, reason: "dummy WorkOS API key" },
+    { pattern: /^sk_test_?\.\.\.$/i, reason: "placeholder WorkOS API key" },
+  ],
+  WORKOS_CLIENT_ID: [
+    { pattern: /^client_?\.\.\.$/i, reason: "placeholder WorkOS client id" },
+    { pattern: /^client_test_local$/i, reason: "local fake WorkOS client id" },
+  ],
+  WORKOS_COOKIE_PASSWORD: [
+    { pattern: /dummy/i, reason: "dummy cookie password" },
+    { pattern: /change[-_]?me/i, reason: "change-me cookie password" },
+  ],
+  FORGE_AUTH_AUDIENCE: [
+    { pattern: /^client_test_local$/i, reason: "local fake auth audience" },
+  ],
+  FORGE_AUTH_JWKS_URI: [
+    { pattern: /\/client_test_local$/i, reason: "local fake JWKS client id" },
+  ],
+};
+
+export function placeholderEnvProblem(key: string, value: string | undefined): PlaceholderEnvProblem | null {
+  const trimmed = value?.trim() ?? "";
+  if (!trimmed) return null;
+  const normalized = trimmed.toLowerCase();
+  for (const { pattern, reason } of KEY_PLACEHOLDER_PATTERNS[key] ?? []) {
+    if (pattern.test(trimmed)) return { key, reason };
+  }
+  for (const { pattern, reason } of GENERIC_PLACEHOLDER_PATTERNS) {
+    if (pattern.test(normalized)) return { key, reason };
+  }
+  return null;
+}
+
+export function productionPlaceholderEnvProblems(
+  values: Record<string, string>,
+  keys = Object.keys(values),
+): PlaceholderEnvProblem[] {
+  return keys
+    .map((key) => placeholderEnvProblem(key, values[key]))
+    .filter((problem): problem is PlaceholderEnvProblem => Boolean(problem));
+}

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

@@ -317,6 +317,7 @@ async function createFieldTestApp(options: FieldTestCommandOptions): Promise<Fie
     };
   }
   if (options.dryRun) {
+    const forgeSpecFlag = options.forgeSpec ? ` --forge-spec ${options.forgeSpec}` : "";
     return normalizeForgeCliCommandsInValue(options.workspaceRoot, {
       schemaVersion: "0.1.0",
       ok: true,
@@ -328,11 +329,12 @@ async function createFieldTestApp(options: FieldTestCommandOptions): Promise<Fie
         template: options.template,
         packageManager: options.packageManager,
         auth: options.auth,
+        forgeSpec: options.forgeSpec,
         install: true,
         git: true,
-        command: `forge new ${options.name} --template ${options.template} --package-manager ${options.packageManager} --field-test --install`,
+        command: `forge new ${options.name} --template ${options.template} --package-manager ${options.packageManager}${forgeSpecFlag} --field-test --install`,
         goldenPath: [
-          `forge field-test create ${options.name} --auth ${options.auth ?? "none"} --template ${options.template} --package-manager ${options.packageManager} --install --git --json`,
+          `forge field-test create ${options.name} --auth ${options.auth ?? "none"} --template ${options.template} --package-manager ${options.packageManager}${forgeSpecFlag} --install --git --json`,
           `cd ${options.name}`,
           "forge field-test run --realistic --json",
           "forge field-test report --json",
@@ -341,7 +343,7 @@ async function createFieldTestApp(options: FieldTestCommandOptions): Promise<Fie
         ],
       },
       nextActions: [
-        `forge field-test create ${options.name} --auth ${options.auth ?? "none"} --template ${options.template} --package-manager ${options.packageManager} --install --git --json`,
+        `forge field-test create ${options.name} --auth ${options.auth ?? "none"} --template ${options.template} --package-manager ${options.packageManager}${forgeSpecFlag} --install --git --json`,
       ],
       exitCode: 0,
     });