forgeos 0.1.0-alpha.30 → 0.1.0-alpha.32

package/AGENTS.md

@@ -1,4 +1,4 @@
-// @forge-generated generator=0.1.0-alpha.30 input=5d12d4ad2a959d692b306eb18ba706c52f22f2d148c6e4ed541bd67fd8222c84 content=0d493cf0e41b71cb652d5e0e1b0c1f83d2a1281b748321f0b00f0773ba93074e
+// @forge-generated generator=0.1.0-alpha.32 input=26469f4d84697cd1397a4a6726dff71ec50e70270a82b3ea4c84c75f25ac5f58 content=721818a6f9a664aa898092d4aa5cd68cbbd8ad6e150c7d3ad3ef785a2e3fcf53
 # AGENTS.md
 
 <!-- forge-generated:start -->
@@ -205,8 +205,8 @@ node bin/forge.mjs do verify --json
 Use:
 
 ```bash
-node bin/forge.mjs make resource <name> --fields title:text,status:enum(open,closed) --dry-run --json
-node bin/forge.mjs make resource <name> --fields title:text,status:enum(open,closed) --with-ui --yes
+node bin/forge.mjs make resource <name> --fields title:text,status:enum=open+closed --dry-run --json
+node bin/forge.mjs make resource <name> --fields title:text,status:enum=open+closed --with-ui --yes
 node bin/forge.mjs make ui --framework vite --dry-run --json
 node bin/forge.mjs make ui --framework nuxt --dry-run --json
 node bin/forge.mjs make ai-chat support --dry-run --json

package/CHANGELOG.md

@@ -1,5 +1,35 @@
 # forgeos
 
+## 0.1.0-alpha.32
+
+### Patch Changes
+
+- Harden the alpha field-test loop after real Codex, WorkOS, PGlite, and app-server exercises.
+
+  - Accept `create-forgeos-app --git` as a supported/no-op compatibility flag when git initialization is already handled by the scaffold path, and keep `npm create forgeos-app@alpha .` working from empty current directories.
+  - Reject schema definitions that try to model `id` as a normal text field so generated SQL cannot silently create the wrong primary-key shape.
+  - Fix tenant-scoped updates in the in-memory database adapter and bring memory timestamp behavior closer to PGlite by rejecting empty timestamp strings and returning `Date` objects for timestamp columns.
+  - Improve smoke/generate drift diagnostics and keep `forge handoff` read-only with respect to generated artifacts.
+  - Copy generated WorkOS seed data to a root-level `workos-seed.yml` for app DX, serve `HEAD /auth.md` and `HEAD /.well-known/oauth-protected-resource`, and make local-vs-production auth posture more explicit.
+  - Normalize suggested Forge commands in framework checkouts so `agent`, `delta`, `studio`, `status`, `changed`, `handoff`, doctors, and WorkOS/auth helpers recommend `node bin/forge.mjs ...` instead of a possibly stale global `forge`.
+  - Return structured JSON diagnostics for Delta/PGlite export/open failures instead of leaking raw PGlite stack output, and improve Windows/PGlite repair guidance.
+  - Expand `forge ui audit` with static UX/auth-readiness warnings for missing semantic landmarks, unlabeled form controls, unnamed buttons, missing loading/error/empty states, and tenant/prod-auth apps that still only show local dev auth posture.
+
+## 0.1.0-alpha.31
+
+### Patch Changes
+
+- Smooth the ForgeOS field-demo DX after the alpha.30 app-server and WorkOS exercises.
+
+  - Add `forge baseline create` and `forge baseline status` so non-git template workspaces can establish a local baseline and get useful `forge changed` / `forge handoff` diffs instead of noisy filesystem inventories.
+  - Add `forge auth status` and production-focused `forge auth prove --prod` output so `dev-headers` is clearly labeled as local-only while JWT/OIDC proofs show production auth posture.
+  - Expand `forge doctor windows` with local PGlite store posture and cleanup guidance, including safer PGlite abort inspection that does not poison the surrounding process exit code.
+  - Add `forge ui audit` and run it during `forge verify --smoke` when a web app is present, catching missing UI scenarios, missing stable Forge test IDs, and missing policy-denied coverage for sensitive routes.
+  - Expand `forge ui audit` with static UX/auth-readiness warnings for missing semantic landmarks, unlabeled form controls, unnamed buttons, missing loading/error/empty states, and tenant/prod-auth apps that still only show local dev auth posture.
+  - Bring the in-memory DB adapter closer to PGlite for timestamp fields by rejecting empty timestamp values and returning `Date` objects for `timestamp`/`timestamptz` columns.
+  - Make `forge handoff` use a read-only generated-artifact check so preparing a handoff no longer rewrites `src/forge/_generated/**`, `forge.lock`, or generated `AGENTS.md` noise; `forge dev --once` still self-heals stale artifacts.
+  - Allow `forge new .` / `npm create forgeos-app@alpha .` from an empty current directory, while refusing non-empty directories to avoid overwriting existing apps.
+
 ## 0.1.0-alpha.30
 
 ### Patch Changes

package/docs/changelog.md

@@ -6,6 +6,61 @@ The canonical source file in the repository is `CHANGELOG.md`.
 
 ## Unreleased
 
+## 0.1.0-alpha.32
+
+- Accepted `create-forgeos-app --git` as a supported/no-op compatibility flag
+  when git initialization is already handled by the scaffold path, and kept
+  `npm create forgeos-app@alpha .` working from empty current directories.
+- Added stronger schema validation for `id` so apps cannot accidentally model
+  the primary key as a normal text field and generate incorrect SQL.
+- Fixed tenant-scoped updates in the in-memory database adapter and made memory
+  timestamp handling closer to PGlite by rejecting empty timestamp strings and
+  returning `Date` objects for timestamp columns.
+- Improved smoke/generate drift diagnostics and kept `forge handoff` read-only
+  with respect to generated artifacts.
+- Improved WorkOS/auth app DX: root-level `workos-seed.yml`, `HEAD /auth.md`,
+  `HEAD /.well-known/oauth-protected-resource`, and clearer local-vs-production
+  auth posture.
+- Normalized suggested Forge commands in framework checkouts so `agent`,
+  `delta`, `studio`, `status`, `changed`, `handoff`, doctors, and WorkOS/auth
+  helpers recommend `node bin/forge.mjs ...` instead of a possibly stale global
+  `forge`.
+- Returned structured JSON diagnostics for Delta/PGlite export/open failures
+  instead of raw PGlite stack output, and expanded Windows/PGlite repair hints.
+- Expanded `forge ui audit` with static UX/auth-readiness warnings for missing
+  semantic landmarks, unlabeled form controls, unnamed buttons, missing
+  loading/error/empty states, and tenant/prod-auth apps that still only expose
+  local dev auth posture.
+
+## 0.1.0-alpha.31
+
+- Added Forge workspace baselines for non-git app directories:
+  `forge baseline create` records a local baseline and `forge changed` /
+  `forge handoff` can now report baseline diffs instead of noisy full
+  filesystem inventories.
+- Added `forge auth status` and production-aware `forge auth prove --prod`
+  posture checks so local `dev-headers` auth is clearly distinguished from
+  JWT/OIDC production authentication.
+- Expanded `forge doctor windows` with local PGlite store posture and cleanup
+  guidance, and made PGlite abort inspection preserve the surrounding process
+  exit code.
+- Added `forge ui audit` and wired it into `forge verify --smoke` for web apps
+  to catch missing route scenarios, missing stable Forge test IDs, and missing
+  policy-denied coverage for sensitive flows. It now also reports static
+  UX/auth-readiness warnings for missing semantic landmarks, unlabeled form
+  controls, unnamed buttons, missing loading/error/empty states, and
+  tenant/prod-auth apps that still only expose local dev auth posture.
+- Brought the in-memory DB adapter closer to PGlite for timestamp fields by
+  rejecting empty timestamp values and returning `Date` objects for
+  `timestamp`/`timestamptz` columns.
+- Made `forge handoff` use a read-only generated-artifact check so preparing a
+  handoff no longer rewrites `src/forge/_generated/**`, `forge.lock`, or
+  generated `AGENTS.md` noise; `forge dev --once` still self-heals stale
+  artifacts.
+- Allowed `forge new .` / `npm create forgeos-app@alpha .` from an empty
+  current directory, while refusing non-empty directories to avoid overwriting
+  existing apps.
+
 ## 0.1.0-alpha.30
 
 - Hardened the WorkOS/AuthKit adapter and dev telemetry after the alpha.29

package/package.json

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

package/src/forge/_generated/releaseManifest.ts

@@ -1,4 +1,4 @@
-// @forge-generated generator=0.1.0-alpha.30 input=5d12d4ad2a959d692b306eb18ba706c52f22f2d148c6e4ed541bd67fd8222c84 content=065153708d210de0b5893a6e8c8ecbfc8bab3b011c8f1e576ae54d9c59bff838
+// @forge-generated generator=0.1.0-alpha.32 input=26469f4d84697cd1397a4a6726dff71ec50e70270a82b3ea4c84c75f25ac5f58 content=ba652b73917e09bcc803cfea91f38e1aa2563b17eacc60f6faaebdc949997e9a
 export const releaseManifest = {
   "defaultProvider": "local",
   "diagnostics": [],
@@ -19,7 +19,7 @@ export const releaseManifest = {
     "custom"
   ],
   "packageName": "forgeos",
-  "packageVersion": "0.1.0-alpha.30",
-  "releaseId": "forgeos@0.1.0-alpha.30+unknown",
+  "packageVersion": "0.1.0-alpha.32",
+  "releaseId": "forgeos@0.1.0-alpha.32+unknown",
   "schemaVersion": "0.1.0"
 } as const;

package/src/forge/agent-adapters/index.ts

@@ -56,6 +56,7 @@ import {
 } from "../agent-memory/hook-runner.ts";
 import { releaseManifest } from "../_generated/releaseManifest.ts";
 import { runDevConsoleCycle } from "../dev-console/cycle.ts";
+import { normalizeForgeCliCommandsInValue } from "../workspace/forge-cli.ts";
 
 export const AGENT_ADAPTER_VERSION = "agent-adapter-0.1.0";
 export const AGENT_FORMAT_VERSION = "2026-06";
@@ -77,6 +78,25 @@ function diagnostic(
   return createDiagnostic({ severity, code, message, ...(file ? { file } : {}) });
 }
 
+function normalizeAgentCliCommandHints<T>(workspaceRoot: string, result: T): T {
+  if (!result || typeof result !== "object") {
+    return result;
+  }
+  const value = result as Record<string, unknown>;
+  const normalized: Record<string, unknown> = { ...value };
+  for (const key of ["nextActions", "diagnostics", "commands", "checks", "steps"]) {
+    if (key in normalized) {
+      normalized[key] = normalizeForgeCliCommandsInValue(workspaceRoot, normalized[key], key);
+    }
+  }
+  for (const key of ["installResult", "ingestResult"]) {
+    if (key in normalized) {
+      normalized[key] = normalizeAgentCliCommandHints(workspaceRoot, normalized[key]);
+    }
+  }
+  return normalized as T;
+}
+
 function readText(workspaceRoot: string, relative: string): string | null {
   const path = join(workspaceRoot, relative);
   if (!nodeFileSystem.exists(path)) {
@@ -2222,9 +2242,11 @@ export async function runAgentHooksSmoke(options: AgentCommandOptions): Promise<
   };
 }
 
-export async function runAgentCommand(options: AgentCommandOptions): Promise<
+type AgentCommandResult =
   AgentExportResult | AgentCheckResult | AgentTargetsResult | AgentPrintContextResult | AgentDoctorResult | AgentPrepareResult | AgentOnboardResult | AgentHooksSmokeResult | AgentHooksStatusResult | AgentTimelineResult | AgentMemoryCommandResult
-> {
+;
+
+async function runAgentCommandRaw(options: AgentCommandOptions): Promise<AgentCommandResult> {
   if (options.subcommand === "list-targets") {
     return runAgentListTargets(options.workspaceRoot);
   }
@@ -2295,6 +2317,10 @@ export async function runAgentCommand(options: AgentCommandOptions): Promise<
   };
 }
 
+export async function runAgentCommand(options: AgentCommandOptions): Promise<AgentCommandResult> {
+  return normalizeAgentCliCommandHints(options.workspaceRoot, await runAgentCommandRaw(options));
+}
+
 export function formatAgentJson(result: Awaited<ReturnType<typeof runAgentCommand>>): string {
   if ("timeline" in result && result.timeline === "agent") {
     return `${JSON.stringify(result, null, 2)}\n`;

package/src/forge/cli/auth.ts

@@ -9,14 +9,19 @@ 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 { existsSync } from "node:fs";
+import { join } from "node:path";
+import { normalizeForgeCliCommandsInValue } from "../workspace/forge-cli.ts";
 
-export type AuthSubcommand = "check" | "config" | "decode" | "test-token" | "jwks" | "prove";
+export type AuthSubcommand = "check" | "config" | "decode" | "test-token" | "jwks" | "prove" | "status";
 
 export interface AuthCommandOptions {
   subcommand: AuthSubcommand;
   workspaceRoot: string;
   json: boolean;
   token?: string;
+  prod?: boolean;
+  scenario?: string;
 }
 
 export interface AuthCommandResult {
@@ -59,11 +64,8 @@ function detectWorkOS(workspaceRoot: string, claims: AuthClaimsMapping) {
   };
 }
 
-function validateConfig(workspaceRoot: string): AuthCommandResult {
-  const config = loadAuthConfigFromEnv(workspaceRoot);
+function configErrors(config: ReturnType<typeof loadAuthConfigFromEnv>): { code: string; message: string }[] {
   const errors: { code: string; message: string }[] = [];
-  const workos = detectWorkOS(workspaceRoot, config.claims);
-
   if ((config.mode === "jwt" || config.mode === "oidc") && !config.issuer) {
     errors.push({
       code: FORGE_AUTH_INVALID_ISSUER,
@@ -82,6 +84,99 @@ function validateConfig(workspaceRoot: string): AuthCommandResult {
       message: "FORGE_AUTH_JWKS_URI is required for jwt auth",
     });
   }
+  return errors;
+}
+
+function buildAuthPosture(workspaceRoot: string) {
+  const config = loadAuthConfigFromEnv(workspaceRoot);
+  const productionMode = config.mode === "jwt" || config.mode === "oidc";
+  const errors = configErrors(config);
+  const configReady = errors.length === 0;
+  return normalizeForgeCliCommandsInValue(workspaceRoot, {
+    schemaVersion: "0.1.0",
+    mode: config.mode,
+    localOnly: config.mode === "dev-headers",
+    productionReady: productionMode && configReady,
+    requiresTenant: config.requiresTenant,
+    bearerHeader: productionMode ? "Authorization: Bearer <token>" : null,
+    tenantClaim: config.claims.tenantId ?? "tenant_id",
+    productionChecklist: [
+      { item: "auth mode is jwt or oidc", ok: productionMode },
+      { item: "FORGE_AUTH_ISSUER configured", ok: Boolean(config.issuer) },
+      { item: "FORGE_AUTH_AUDIENCE configured", ok: Boolean(config.audience) },
+      { item: "FORGE_AUTH_JWKS_URI or OIDC discovery configured", ok: config.mode === "oidc" || Boolean(config.jwksUri) },
+      { item: "tenant claim mapped", ok: Boolean(config.claims.tenantId) },
+      { item: "permission claim mapped", ok: Boolean(config.claims.permissions) },
+      { item: "dev-headers disabled for public runtime", ok: config.mode !== "dev-headers" },
+    ],
+    reason: productionMode
+      ? configReady
+        ? "jwt/oidc production auth configuration is present"
+        : "jwt/oidc production auth is selected but required settings are missing"
+      : "dev-headers auth is local-only and is not real production authentication",
+    nextActions: productionMode
+      ? configReady
+        ? ["forge auth prove --prod --token <jwt> --json", "forge serve --json"]
+        : ["forge auth check --json", "configure FORGE_AUTH_ISSUER, FORGE_AUTH_AUDIENCE, and FORGE_AUTH_JWKS_URI or OIDC issuer"]
+      : ["set FORGE_AUTH_MODE=jwt or oidc for production", "forge auth prove --prod --token <jwt> --json"],
+  });
+}
+
+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 authMdPresent = existsSync(join(workspaceRoot, "public/auth.md"));
+  const metadataPresent = existsSync(join(workspaceRoot, "public/.well-known/oauth-protected-resource"));
+  const permissions = ["onboarding:read", "invitations:create", "tasks:update"];
+  const permissionVocabularyPresent = workos.detected && workos.claimStatus.some((claim) => claim.name === "permissions" && claim.ok);
+  const checks = [
+    {
+      id: "tenant-claim",
+      ok: requiresTenant && workos.claimStatus.some((claim) => claim.name === "tenantId" && claim.ok),
+      evidence: "Forge tenant claim maps to WorkOS organization_id and tenant auth is required.",
+    },
+    {
+      id: "permission-claim",
+      ok: permissionVocabularyPresent,
+      evidence: "Forge permissions claim maps to WorkOS permissions.",
+    },
+    {
+      id: "seed-organizations",
+      ok: rootSeedPresent || generatedSeedPresent,
+      evidence: rootSeedPresent ? "workos-seed.yml exists at app root." : "generated WorkOS seed exists.",
+    },
+    {
+      id: "agent-auth-metadata",
+      ok: authMdPresent && metadataPresent,
+      evidence: "public/auth.md and protected resource metadata are present.",
+    },
+  ];
+  return normalizeForgeCliCommandsInValue(workspaceRoot, {
+    scenario: "multi-tenant",
+    ok: checks.every((check) => check.ok),
+    claims: {
+      acme: { organization_id: "org_acme", role: "owner", permissions },
+      globex: { organization_id: "org_globex", role: "member", permissions: ["onboarding:read", "tasks:update"] },
+    },
+    invariants: [
+      "Acme and Globex must use different organization_id claim values.",
+      "Tenant-scoped reads must include the active organization_id.",
+      "Tenant-scoped writes must verify the resource tenant before mutation.",
+      "Role-only UI affordances are not sufficient; policies must use permissions/claims.",
+    ],
+    checks,
+    nextActions: [
+      "forge workos doctor --json",
+      "forge workos seed --file workos-seed.yml --dry-run --json",
+      "run an HTTP E2E with Acme and Globex tokens before production",
+    ],
+  });
+}
+
+function validateConfig(workspaceRoot: string): AuthCommandResult {
+  const config = loadAuthConfigFromEnv(workspaceRoot);
+  const errors = configErrors(config);
+  const workos = detectWorkOS(workspaceRoot, config.claims);
 
   return {
     ok: errors.length === 0,
@@ -94,6 +189,7 @@ function validateConfig(workspaceRoot: string): AuthCommandResult {
       algorithms: config.algorithms,
       claims: config.claims,
       requiresTenant: config.requiresTenant,
+      authPosture: buildAuthPosture(workspaceRoot),
       workos,
       errors,
     },
@@ -116,6 +212,7 @@ function publicConfig(workspaceRoot: string): AuthCommandResult {
       algorithms: config.algorithms,
       claims: config.claims,
       requiresTenant: config.requiresTenant,
+      authPosture: buildAuthPosture(workspaceRoot),
       workos,
     },
     exitCode: 0,
@@ -197,6 +294,15 @@ async function testToken(
 export async function runAuthCommand(
   options: AuthCommandOptions,
 ): Promise<AuthCommandResult> {
+  if (options.subcommand === "status") {
+    const posture = buildAuthPosture(options.workspaceRoot);
+    return {
+      ok: true,
+      mode: posture.mode,
+      data: posture,
+      exitCode: 0,
+    };
+  }
   if (options.subcommand === "check") {
     return validateConfig(options.workspaceRoot);
   }
@@ -206,15 +312,34 @@ export async function runAuthCommand(
     const workos = detectWorkOS(options.workspaceRoot, config.claims);
     const productionMode = config.mode === "jwt" || config.mode === "oidc";
     const workosClaimsOk = workos.claimStatus.every((claim) => claim.ok);
+    const posture = buildAuthPosture(options.workspaceRoot);
+    const tokenProof = options.token ? await testToken(options.workspaceRoot, options.token) : null;
+    const prodError = options.prod && !productionMode
+      ? { code: "FORGE_AUTH_MODE_INVALID", message: "forge auth prove --prod requires FORGE_AUTH_MODE=jwt or oidc" }
+      : options.prod && !options.token
+        ? { code: "FORGE_AUTH_MISSING_TOKEN", message: "forge auth prove --prod requires --token" }
+        : options.prod && tokenProof && !tokenProof.ok
+          ? tokenProof.error
+          : undefined;
+    const proofOk = checked.ok && (!options.prod || (productionMode && tokenProof?.ok === true));
+    const multiTenantProof = options.scenario === "multi-tenant"
+      ? buildMultiTenantProof(options.workspaceRoot, workos, config.requiresTenant)
+      : null;
+    const scenarioOk = !multiTenantProof || multiTenantProof.ok;
     return {
-      ok: checked.ok,
+      ok: proofOk && scenarioOk,
       mode: config.mode,
       data: {
         schemaVersion: "0.1.0",
         kind: "auth-proof",
-        ok: checked.ok,
+        ok: proofOk,
         mode: config.mode,
         productionReady: productionMode && checked.ok,
+        prod: options.prod === true,
+        scenario: options.scenario ?? null,
+        authPosture: posture,
+        ...(tokenProof ? { tokenProof: tokenProof.ok ? tokenProof.data : tokenProof.error } : {}),
+        ...(multiTenantProof ? { multiTenantProof } : {}),
         invariants: [
           {
             id: "INV-001",
@@ -249,8 +374,8 @@ export async function runAuthCommand(
         workos,
         checkedAt: "deterministic",
       },
-      error: checked.error,
-      exitCode: checked.exitCode,
+      error: prodError ?? checked.error,
+      exitCode: proofOk && scenarioOk ? 0 : 1,
     };
   }
   if (options.subcommand === "config") {

package/src/forge/cli/baseline.ts

@@ -0,0 +1,112 @@
+import { spawnSync } from "node:child_process";
+import { createWorkspaceBaseline, readWorkspaceBaseline, writeWorkspaceBaseline, WORKSPACE_BASELINE_PATH } from "../workspace/baseline.ts";
+import { listWorkspaceFiles } from "../workspace/git-summary.ts";
+
+export type BaselineSubcommand = "create" | "status";
+
+export interface BaselineCommandOptions {
+  subcommand: BaselineSubcommand;
+  workspaceRoot: string;
+  json: boolean;
+  reason?: string;
+}
+
+export interface BaselineCommandResult {
+  ok: boolean;
+  path: string;
+  required: boolean;
+  created?: boolean;
+  baseline?: ReturnType<typeof readWorkspaceBaseline>;
+  summary: {
+    files: number;
+    reason?: string;
+    tracking: "git" | "forge-baseline" | "missing";
+  };
+  nextActions: string[];
+  exitCode: 0 | 1;
+}
+
+function gitAvailable(workspaceRoot: string): boolean {
+  const result = spawnSync("git", ["rev-parse", "--show-toplevel"], {
+    cwd: workspaceRoot,
+    encoding: "utf8",
+    windowsHide: true,
+  });
+  return result.status === 0;
+}
+
+export function runBaselineCommand(options: BaselineCommandOptions): BaselineCommandResult {
+  if (options.subcommand === "create") {
+    const files = listWorkspaceFiles(options.workspaceRoot);
+    const baseline = createWorkspaceBaseline({
+      workspaceRoot: options.workspaceRoot,
+      files,
+      reason: options.reason,
+    });
+    writeWorkspaceBaseline(options.workspaceRoot, baseline);
+    return {
+      ok: true,
+      path: WORKSPACE_BASELINE_PATH,
+      required: false,
+      created: true,
+      baseline,
+      summary: {
+        files: Object.keys(baseline.files).length,
+        tracking: "forge-baseline",
+        ...(baseline.reason ? { reason: baseline.reason } : {}),
+      },
+      nextActions: ["forge changed --json", "forge handoff --json"],
+      exitCode: 0,
+    };
+  }
+
+  const baseline = readWorkspaceBaseline(options.workspaceRoot);
+  if (!baseline && gitAvailable(options.workspaceRoot)) {
+    return {
+      ok: true,
+      path: WORKSPACE_BASELINE_PATH,
+      required: false,
+      baseline: null,
+      summary: {
+        files: 0,
+        tracking: "git",
+      },
+      nextActions: ["forge changed --json", "git status --short"],
+      exitCode: 0,
+    };
+  }
+  return {
+    ok: baseline !== null,
+    path: WORKSPACE_BASELINE_PATH,
+    required: baseline === null,
+    baseline,
+    summary: {
+      files: baseline ? Object.keys(baseline.files).length : 0,
+      tracking: baseline ? "forge-baseline" : "missing",
+      ...(baseline?.reason ? { reason: baseline.reason } : {}),
+    },
+    nextActions: baseline
+      ? ["forge changed --json", "forge baseline create --reason refresh --json"]
+      : ["forge baseline create --reason initial-scaffold --json", "git init"],
+    exitCode: baseline ? 0 : 1,
+  };
+}
+
+export function formatBaselineJson(result: BaselineCommandResult): string {
+  return `${JSON.stringify(result, null, 2)}\n`;
+}
+
+export function formatBaselineHuman(result: BaselineCommandResult): string {
+  const label = result.required ? "missing" : result.summary.tracking === "git" ? "not required (git workspace)" : "ready";
+  const lines = [
+    `Forge baseline: ${label}`,
+    `Path: ${result.path}`,
+    `Tracking: ${result.summary.tracking}`,
+    `Files: ${result.summary.files}`,
+  ];
+  if (result.summary.reason) {
+    lines.push(`Reason: ${result.summary.reason}`);
+  }
+  lines.push("", "Next:", ...result.nextActions.map((action) => `  ${action}`));
+  return `${lines.join("\n")}\n`;
+}