forgeos 0.1.0-alpha.7 → 0.1.0-alpha.71

package/src/forge/cli/handoff.ts

@@ -0,0 +1,336 @@
+import { join } from "node:path";
+import { nodeFileSystem } from "../compiler/fs/index.ts";
+import type { Diagnostic } from "../compiler/types/diagnostic.ts";
+import { runDevConsoleCycle } from "../dev-console/cycle.ts";
+import type { DevConsoleCycle, DevConsolePhase } from "../dev-console/types.ts";
+import type { TestRunRecord } from "../impact/types.ts";
+import type { UiRunReport } from "../ui/types.ts";
+import { summarizeChangeTypes, type CategorizedFileSummary } from "../workspace/change-summary.ts";
+import { forgeCliCommandsForWorkspace } from "../workspace/forge-cli.ts";
+import { buildWorkspaceGitSummary } from "../workspace/git-summary.ts";
+import { runChangedCommand } from "./changed.ts";
+
+export interface HandoffCommandOptions {
+  workspaceRoot: string;
+  json: boolean;
+  commitReady?: boolean;
+}
+
+export interface HandoffCommandResult {
+  schemaVersion: "0.1.0";
+  ok: boolean;
+  summary: {
+    projectRoot: string;
+    safeToEdit: boolean;
+    generatedFresh: boolean;
+    generatedChanged: boolean;
+    generatedChangedFiles: number;
+    frontendReady: boolean;
+    changedFiles: number;
+    commitReadyFiles: number;
+    stagedFiles: number;
+    unstagedFiles: number;
+    untrackedFiles: number;
+    lastTestRun: "passed" | "failed" | "missing";
+    lastUiRun: "passed" | "failed" | "missing";
+    workspaceMode: "git" | "nonGit";
+    tracking: string;
+  };
+  dev: {
+    ok: boolean;
+    primaryAction?: DevConsoleCycle["summary"]["primaryAction"];
+    agentContext: DevConsoleCycle["summary"]["agentContext"];
+    phases: Array<Pick<DevConsolePhase, "name" | "status" | "message">>;
+  };
+  git: {
+    available: boolean;
+    branch?: string;
+    commit?: string;
+    changed: {
+      count: number;
+      sample: string[];
+      hidden: number;
+    };
+    staged: {
+      count: number;
+      sample: string[];
+      hidden: number;
+    };
+    unstaged: {
+      count: number;
+      sample: string[];
+      hidden: number;
+    };
+    untracked: {
+      count: number;
+      sample: string[];
+      hidden: number;
+    };
+    changeSummary: {
+      changed: CategorizedFileSummary;
+      staged: CategorizedFileSummary;
+      unstaged: CategorizedFileSummary;
+      untracked: CategorizedFileSummary;
+    };
+    workspaceMode?: string;
+    tracking?: string;
+    baseline?: unknown;
+    error?: string;
+  };
+  recentRuns: {
+    test?: {
+      id?: string;
+      ok: boolean;
+      failed: string[];
+      durationMs?: number;
+    };
+    ui?: {
+      id?: string;
+      ok: boolean;
+      failedScenarios: string[];
+    };
+  };
+  nextAgent: {
+    openingBrief: string;
+    recommendedReadFiles: string[];
+    recommendedCommands: string[];
+    risks: string[];
+  };
+  commitReady?: {
+    count: number;
+    files: string[];
+  };
+  diagnosticSummary: {
+    total: number;
+    sample: Diagnostic[];
+    hidden: number;
+    bySeverity: Record<string, number>;
+    byCode: Record<string, number>;
+    fullDiagnosticsCommands: string[];
+  };
+  diagnostics: Diagnostic[];
+  nextActions: string[];
+  exitCode: 0 | 1;
+}
+
+function readJson<T>(workspaceRoot: string, relativePath: string): T | null {
+  const absolute = join(workspaceRoot, relativePath);
+  if (!nodeFileSystem.exists(absolute)) {
+    return null;
+  }
+  try {
+    return JSON.parse(nodeFileSystem.readText(absolute) ?? "null") as T;
+  } catch {
+    return null;
+  }
+}
+
+function summarizeRecentRuns(workspaceRoot: string): HandoffCommandResult["recentRuns"] {
+  const test = readJson<TestRunRecord>(workspaceRoot, ".forge/test-runs/last.json");
+  const ui = readJson<UiRunReport>(workspaceRoot, ".forge/ui-runs/last.json");
+  const failedScenarios = (ui?.scenarios ?? [])
+    .filter((scenario) => !scenario.ok)
+    .map((scenario) => scenario.name);
+  return {
+    ...(test
+      ? {
+          test: {
+            id: test.id,
+            ok: test.failed.length === 0,
+            failed: test.failed,
+            durationMs: test.durationMs,
+          },
+        }
+      : {}),
+    ...(ui
+      ? {
+          ui: {
+            id: ui.id,
+            ok: failedScenarios.length === 0 && ui.diagnostics.every((diagnostic) => diagnostic.severity !== "error"),
+            failedScenarios,
+          },
+        }
+      : {}),
+  };
+}
+
+function buildOpeningBrief(input: {
+  dev: DevConsoleCycle;
+  git: HandoffCommandResult["git"];
+  recentRuns: HandoffCommandResult["recentRuns"];
+  commitReady?: HandoffCommandResult["commitReady"];
+}): string {
+  const agent = input.dev.summary.agentContext;
+  const changedByType = summarizeChangeTypes(input.git.changeSummary.changed);
+  const changedFiles = Math.max(agent.changedFiles, input.git.changed.count);
+  const commitReadyNote = input.commitReady && input.commitReady.count !== changedFiles
+    ? `; ${input.commitReady.count} commit-ready file(s) after excluding generated/operational artifacts`
+    : "";
+  const tests = input.recentRuns.test
+    ? input.recentRuns.test.ok
+      ? "last test run passed"
+      : "last test run failed"
+    : "no last test run";
+  const blockers = agent.blockingIssues.length > 0
+    ? `${agent.blockingIssues.length} blocking issue(s)`
+    : "no blocking issues";
+  return [
+    `ForgeOS handoff: ${input.dev.ok ? "dev diagnostics are clean" : "dev diagnostics need attention"}.`,
+    `${changedFiles} changed file(s)${changedByType ? `: ${changedByType}` : ""}${commitReadyNote}; ${input.git.staged.count} staged, ${input.git.untracked.count} untracked.`,
+    `${tests}; ${blockers}.`,
+    `Next command: ${input.dev.summary.primaryAction?.command ?? input.dev.nextActions[0]?.command ?? "forge dev"}.`,
+  ].join(" ");
+}
+
+function compactDiagnostics(
+  workspaceRoot: string,
+  diagnostics: Diagnostic[],
+  sampleSize = 8,
+): HandoffCommandResult["diagnosticSummary"] {
+  const bySeverity: Record<string, number> = {};
+  const byCode: Record<string, number> = {};
+  for (const diagnostic of diagnostics) {
+    bySeverity[diagnostic.severity] = (bySeverity[diagnostic.severity] ?? 0) + 1;
+    byCode[diagnostic.code] = (byCode[diagnostic.code] ?? 0) + 1;
+  }
+  return {
+    total: diagnostics.length,
+    sample: diagnostics.slice(0, sampleSize),
+    hidden: Math.max(0, diagnostics.length - sampleSize),
+    bySeverity,
+    byCode,
+    fullDiagnosticsCommands: forgeCliCommandsForWorkspace(workspaceRoot, [
+      "forge dev --once --json",
+      "forge inspect all --full --json",
+      "forge generate --check --json",
+    ]),
+  };
+}
+
+export async function runHandoffCommand(options: HandoffCommandOptions): Promise<HandoffCommandResult> {
+  const workspaceRoot = options.workspaceRoot.replace(/\\/g, "/");
+  const dev = await runDevConsoleCycle({
+    workspaceRoot,
+    mode: "once",
+    generatedMode: "check",
+    includeImpact: true,
+  });
+  const git = buildWorkspaceGitSummary(workspaceRoot);
+  const commitReady = runChangedCommand(workspaceRoot, { commitReady: true }).data.commitReady as { count: number; files: string[] } | undefined;
+  const recentRuns = summarizeRecentRuns(workspaceRoot);
+  const agent = dev.summary.agentContext;
+  const risks = [
+    ...agent.blockingIssues,
+    ...(!git.available && git.source === "forge-baseline"
+      ? ["git status is unavailable; using Forge workspace baseline for non-git change tracking"]
+      : !git.available
+        ? ["git status is unavailable; using filesystem inventory as untracked-file analysis"]
+        : []),
+    ...(git.untracked.count > 0 && git.source !== "forge-baseline" ? [`${git.untracked.count} untracked file(s) are not in git history`] : []),
+    ...(commitReady && git.changed.count > commitReady.count
+      ? [`${git.changed.count - commitReady.count} generated or operational file(s) are excluded from the commit-ready view`]
+      : []),
+    ...(recentRuns.test && !recentRuns.test.ok ? ["last test run failed"] : []),
+    ...(recentRuns.ui && !recentRuns.ui.ok ? ["last UI run failed"] : []),
+  ];
+  const nextActions = [
+    ...agent.recommendedCommands,
+    ...forgeCliCommandsForWorkspace(workspaceRoot, [
+      ...(git.changed.count > 0 ? ["forge review run --changed --json"] : []),
+      ...(git.changed.count > 0 ? ["forge changed --commit-ready --json"] : []),
+      "forge handoff --json",
+    ]),
+  ];
+  const ok = dev.ok &&
+    agent.blockingIssues.length === 0 &&
+    (!recentRuns.test || recentRuns.test.ok) &&
+    (!recentRuns.ui || recentRuns.ui.ok);
+  const changedFiles = Math.max(agent.changedFiles, git.changed.count);
+  const diagnosticSummary = compactDiagnostics(workspaceRoot, dev.diagnostics);
+
+  return {
+    schemaVersion: "0.1.0",
+    ok,
+    summary: {
+      projectRoot: workspaceRoot,
+      safeToEdit: agent.safeToEdit,
+      generatedFresh: agent.generatedFresh,
+      generatedChanged: agent.generatedChanged,
+      generatedChangedFiles: agent.generatedChangedFiles,
+      frontendReady: agent.frontendReady,
+      changedFiles,
+      commitReadyFiles: commitReady?.count ?? changedFiles,
+      stagedFiles: git.staged.count,
+      unstagedFiles: git.unstaged.count,
+      untrackedFiles: git.untracked.count,
+      lastTestRun: recentRuns.test ? (recentRuns.test.ok ? "passed" : "failed") : "missing",
+      lastUiRun: recentRuns.ui ? (recentRuns.ui.ok ? "passed" : "failed") : "missing",
+      workspaceMode: git.workspaceMode ?? (git.available ? "git" : "nonGit"),
+      tracking: git.tracking ?? git.source ?? "git",
+    },
+    dev: {
+      ok: dev.ok,
+      ...(dev.summary.primaryAction ? { primaryAction: dev.summary.primaryAction } : {}),
+      agentContext: agent,
+      phases: dev.phases.map((phase) => ({
+        name: phase.name,
+        status: phase.status,
+        ...(phase.message ? { message: phase.message } : {}),
+      })),
+    },
+    git,
+    recentRuns,
+    nextAgent: {
+      openingBrief: buildOpeningBrief({ dev, git, recentRuns, commitReady }),
+      recommendedReadFiles: agent.recommendedReadFiles,
+      recommendedCommands: [...new Set(nextActions)].slice(0, 10),
+      risks,
+    },
+    ...(commitReady ? { commitReady } : {}),
+    diagnosticSummary,
+    diagnostics: diagnosticSummary.sample,
+    nextActions: [...new Set(nextActions)].slice(0, 10),
+    exitCode: ok ? 0 : 1,
+  };
+}
+
+export function formatHandoffJson(result: HandoffCommandResult): string {
+  return `${JSON.stringify(result, null, 2)}\n`;
+}
+
+export function formatHandoffHuman(result: HandoffCommandResult): string {
+  const lines = [
+    `Forge handoff: ${result.ok ? "ready" : "needs attention"}`,
+    result.nextAgent.openingBrief,
+    "",
+    "Read first:",
+    ...result.nextAgent.recommendedReadFiles.slice(0, 6).map((file) => `  ${file}`),
+    "",
+    "Next commands:",
+    ...result.nextActions.slice(0, 6).map((command) => `  ${command}`),
+  ];
+  if (result.nextAgent.risks.length > 0) {
+    lines.push("", "Risks:");
+    lines.push(...result.nextAgent.risks.slice(0, 6).map((risk) => `  ${risk}`));
+  }
+  if (result.diagnosticSummary.total > 0) {
+    lines.push(
+      "",
+      "Diagnostics:",
+      `  ${result.diagnosticSummary.total} total` +
+        (result.diagnosticSummary.hidden > 0 ? ` (${result.diagnosticSummary.hidden} hidden in compact handoff)` : ""),
+    );
+  }
+  if (result.commitReady) {
+    lines.push("", "Commit-ready files:", `  ${result.commitReady.count}`);
+    lines.push(...result.commitReady.files.slice(0, 8).map((file) => `  ${file}`));
+    if (result.commitReady.files.length > 8) {
+      lines.push(`  ... ${result.commitReady.files.length - 8} more`);
+    }
+  }
+  const changedTypes = summarizeChangeTypes(result.git.changeSummary.changed);
+  if (changedTypes) {
+    lines.push("", "Change types:", `  ${changedTypes}`);
+  }
+  return `${lines.join("\n")}\n`;
+}

package/src/forge/cli/index.ts

@@ -2,6 +2,7 @@ export { CLI_VERSION } from "./version.ts";
 export { parseCli, hasUnknownOption, type ParsedCli, type ForgeCommand } from "./parse.ts";
 export { runNewCommand, type NewCommandOptions, type NewCommandResult } from "./new.ts";
 export { runSelfHostCommand, type SelfHostCommandOptions } from "./self-host.ts";
+export { runDocsCheckCommand, type DocsCheckResult } from "./docs.ts";
 export { runBuildCommand, type BuildCommandOptions } from "./build.ts";
 export { runServeCommand, type ServeCommandOptions } from "./serve.ts";
 export { runWorkerCommand, type WorkerCommandOptions } from "./worker.ts";

package/src/forge/cli/last-run.ts

@@ -0,0 +1,84 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+
+export interface LastRunRecord {
+  schemaVersion: "0.1.0";
+  command: string;
+  ok: boolean;
+  startedAt: string;
+  finishedAt: string;
+  durationMs: number;
+  code?: string;
+  failureKind?: string;
+  message?: string;
+  nextActions: string[];
+  details?: Record<string, unknown>;
+}
+
+export interface LastRunCommandResult {
+  ok: boolean;
+  record: LastRunRecord | null;
+  path: string;
+  exitCode: 0 | 1;
+}
+
+function lastRunPath(workspaceRoot: string): string {
+  return join(workspaceRoot, ".forge", "last-run.json");
+}
+
+export function writeLastRunRecord(workspaceRoot: string, record: LastRunRecord): void {
+  const file = lastRunPath(workspaceRoot);
+  mkdirSync(join(workspaceRoot, ".forge"), { recursive: true });
+  writeFileSync(file, `${JSON.stringify(record, null, 2)}\n`, "utf8");
+}
+
+export function readLastRunRecord(workspaceRoot: string): LastRunRecord | null {
+  const file = lastRunPath(workspaceRoot);
+  if (!existsSync(file)) {
+    return null;
+  }
+  return JSON.parse(readFileSync(file, "utf8")) as LastRunRecord;
+}
+
+export function runLastCommand(options: { workspaceRoot: string }): LastRunCommandResult {
+  const path = lastRunPath(options.workspaceRoot);
+  const record = readLastRunRecord(options.workspaceRoot);
+  return {
+    ok: record !== null,
+    record,
+    path,
+    exitCode: record ? 0 : 1,
+  };
+}
+
+export function formatLastJson(result: LastRunCommandResult): string {
+  return `${JSON.stringify(result, null, 2)}\n`;
+}
+
+export function formatLastHuman(result: LastRunCommandResult): string {
+  if (!result.record) {
+    return `No last run record found at ${result.path}\n`;
+  }
+  const lines = [
+    `Last Forge run: ${result.record.command}`,
+    `OK: ${result.record.ok}`,
+    `Finished: ${result.record.finishedAt}`,
+    `Duration: ${result.record.durationMs}ms`,
+  ];
+  if (result.record.code) {
+    lines.push(`Code: ${result.record.code}`);
+  }
+  if (result.record.failureKind) {
+    lines.push(`Failure: ${result.record.failureKind}`);
+  }
+  if (result.record.message) {
+    lines.push(`Message: ${result.record.message}`);
+  }
+  if (result.record.nextActions.length > 0) {
+    lines.push("Next actions:");
+    for (const action of result.record.nextActions) {
+      lines.push(`  ${action}`);
+    }
+  }
+  return `${lines.join("\n")}\n`;
+}

package/src/forge/cli/main.ts

@@ -4,28 +4,209 @@ import { isMainModule } from "../platform/module.ts";
 import { executeCommand } from "./commands.ts";
 import { hasUnknownOption, parseCli } from "./parse.ts";
 import { formatJsonResult } from "./output.ts";
+import { recordParsedCliCommand } from "../delta/index.ts";
+import { readRepositoryManifest } from "../repository-manifest/index.ts";
 
 function formatHelp(): string {
   return [
     "ForgeOS",
+    "  forge manifest discover --root <path> --json  Propose a repository manifest without writing",
+    "  forge repository analyze --write --json  Analyze Vue/Java/Docker and save a coherent local map",
+    "  forge repository context --query routes --json  Read snapshot-bound repository context",
+    "  forge repository quality --cases tasks.json --json  Evaluate reviewed static task fixtures without running a model",
+    "  forge repository cache-gc --json  Preview cache cleanup; --write applies after retention",
+    "  forge repository benchmark-plan --cases tasks.json --model-config model.json --json  Prepare paired agent experiment",
+    "  forge repository benchmark-report --plan plan.json --observations observations.json --json  Compare supplied evidence",
+    "  forge repository runtime-plan --environment-id local --json  Review declared runtime commands without executing",
+    "  forge repository runtime-observe --environment-id local --execute --write --json  Execute in a temporary source copy and save observations",
+    "  forge repository runtime-context --environment-id local --query checkout --json  Read current, bounded runtime evidence",
     "",
     "Start with one of these:",
+    "  forge status --json       Compact project health, handoff state, and next actions",
+    "  forge changed --json      Group changed files into human, generated, and risk buckets",
+    "  forge changed --authored --json  Show only authored changed files, excluding generated artifacts",
+    "  forge changed --review --json  Show review-focused app/config/docs changes, excluding local agent/browser artifacts",
+    "  forge changed --commit-ready --json  Show files suitable for git add, excluding generated and operational artifacts",
+    "  forge new my-app --template vendor-access --field-test  Create an installed WorkOS/auth.md field-test app",
+    "  forge golden-path plan --auth workos --target docker --forge-spec npm:forgeos@alpha --json  Print the official create -> auth -> field-test -> deploy path",
+    "  forge golden-path status --real --production --client-id client_... --json  Read current app evidence and return the next blocking command",
+    "  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",
+    "  forge seed reset --json   Run the seed command with args.reset=true against the local dev runtime",
+    "  forge diff authored       Run the authored-only git diff pathspec",
+    "  forge handoff --json      Compact work handoff for the next external code agent",
+    "  forge agent onboard --target codex --json  Prepare adapter, hooks, memory, and dev snapshot",
+    "  forge doctor agent --target codex --json  Check adapter, hooks, and Agent Memory readiness",
+    "  forge doctor delta --json  Check DeltaDB writability, queue drain, redaction, and gitignore posture",
+    "  forge doctor runtime --json  Check generated freshness, local dev lifecycle, and PGlite posture",
+    "  forge agent ingest codex --watch --file .forge/agent/events.ndjson --json  Explicit queue watcher for debugging",
+    "  forge fabric install-skill [--dry-run] --json  Install the portable personal skill for this runtime",
+    "  forge fabric doctor --json  Diagnose the current Git project and its owner without starting workers",
+    "  forge fabric ensure-owner --json  Reuse or start the current Git project owner",
+    "  forge fabric project-register [--project-id <id>] --json  Register this Git root for MCP routing",
+    "  forge fabric project-list --json  List registered projects",
+    "  forge fabric capabilities --json  Report the connected Agent Fabric local capabilities",
+    "  forge fabric propose --file task.json --json  Record an untrusted coding task proposal",
+    "  forge fabric memory-add --file note.json --json  Retain a bounded private note for a source snapshot",
+    "  forge fabric memory-list --file paths.json --json  List current notes for a source snapshot",
+    "  forge fabric memory-delete <memory-id> --json  Delete a private note",
+    "  forge fabric status <task-id> --json  Read durable task control state",
+    "  forge fabric evidence <task-id> --json  Read bounded task provenance and result digests",
+    "  forge fabric change-propose --file request.json --json  Register a change request for independent review",
+    "  forge fabric change-status --task-id <change-id> --json  Read pinned change review state",
+    "  forge fabric change-evidence --task-id <change-id> --json  Read exact-diff review evidence",
+    "  forge fabric change-review --task-id <change-id> --json  Run the owner-invoked Codex CLI reviewer (uses Codex credits)",
+    "  forge fabric review <task-id> --json  Open the local owner review window",
+    "  forge fabric run <task-id> --json  Run one approved local Ollama attempt",
+    "  forge fabric cancel <task-id> --json  Request best-effort task cancellation",
+    "  forge fabric reconcile <task-id> --json  Read back an uncertain patch effect without rerunning it",
+    "  forge fabric verify <task-id> --json  Run owner-approved local checks in Docker Desktop",
+    "  forge fabric recover-verification <task-id> --json  Ask owner to clear a pre-container verification intent",
+    "  forge fabric review-result <task-id> --json  Review and record a local diff decision",
+    "  forge fabric attached-propose --file request.json --json  Register a Codex accompanied task (owner required)",
+    "  forge fabric attached-status --task-id <task-id> --json  Read snapshot-bound readiness",
+    "  forge fabric attached-context --task-id <task-id> --json  Recover accompanied task context",
+    "  forge fabric attached-<mutation> --file request.json --json  Record sessions, attempts, reviews and evidence",
+    "  forge fabric workflow-next --task-id <task-id> --json  Read eligible caller-driven workflow nodes",
+    "  forge fabric workflow-<mutation> --file request.json --json  Plan, claim, result, replan, reconcile or recover",
+    "  forge fabric run-start --file run.json --json  Start managed workflow workers (Codex can consume credits)",
+    "  forge fabric program-validate --file request.json --json  Lower/validate opt-in static workflow DSL against owner registry",
+    "  forge fabric program-start --file request.json --json  Start a durable v2 program (Codex can consume credits)",
+    "  forge fabric program-status --run-id <id> --json  Inspect v2 templates, attempts, candidates and gates",
+    "  forge fabric program-history|program-explain --run-id <id> --json  Inspect journal, scopes and admission",
+    "  forge fabric program-artifact-get|program-diff --file request.json --json  Read artifacts or inspect plan changes",
+    "  forge fabric program-<control> --file request.json --json  Pause, resume, signal, replan, reconcile, cancel or apply v2 work",
+    "  forge fabric run-status --run-id <run-id> --json  Read durable managed execution state",
+    "  forge fabric run-wait --file wait.json --json  Wait for managed events up to 30 seconds",
+    "  forge fabric run-<control> --file request.json --json  Steer, pause, resume, cancel or reconcile managed work",
+    "  forge fabric serve --json  Start the single local task owner for CLI and MCP clients",
+    "  forge fabric adaptive-propose --file input.json [--channel canary|stable] --json  Propose two bounded data-only workers",
+    "  forge fabric adaptive-review <run-id> --json  Open the local owner approval window",
+    "  forge fabric adaptive-run <run-id> --json  Run two permitted processes and join once",
+    "  forge fabric adaptive-status <run-id> --json  Read durable result after restart",
+    "  forge evolution register --manifest extension.json --json  Pin local extension bytes as an immutable candidate",
+    "  forge evolution evaluate <version-id> --json  Run the fixed local integrity suite",
+    "  forge evolution status <version-id> --json  Read bounded version and decision status",
+    "  forge evolution review canary|promote|rollback|revoke <version-id> --json  Open owner decision window",
+    "  forge evolution load <extension-key> --channel canary|stable --json  Verify selected loadability",
+    "  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  Check npm publish readiness plus separate production deploy readiness",
+    "  forge authmd generate       Write public/auth.md from the generated agent/auth contract",
+    "  forge auth check --production --json  Fail unless auth is jwt/oidc production-ready",
+    "  forge auth prove --provider workos --real --client-id client_... --file workos-seed.yml --json  Prove real WorkOS auth/setup evidence without opening the dashboard",
+    "  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/RBAC 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 env --client-id client_... --write --json  Create/update .env.local and web/.env.local for real WorkOS AuthKit proof",
+    "  forge workos seed --file workos-seed.yml --dry-run --json  Validate WorkOS seed without hosted changes",
+    "  forge workos prove --file workos-seed.yml --json  Prove local WorkOS/AuthKit/RBAC/seed readiness without dashboard changes",
+    "  forge workos setup --real --file workos-seed.yml --json  Apply redirect/CORS/homepage config and seed WorkOS without dashboard",
+    "  forge add auth workos --with-fga  Add optional WorkOS FGA resource-level authorization helpers",
+    "  forge workos fga plan --json  Derive the WorkOS FGA resource graph and proof scenarios from the app",
+    "  forge workos fga plan --write --json  Write .forge/workos-fga-setup.md for hosted FGA resource type setup",
+    "  forge workos fga sync --json  Record an idempotent local FGA graph state for deploy gates",
+    "  forge workos fga prove --json  Prove local FGA graph, cross-tenant denials, and state freshness",
+    "  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, 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",
+    "  forge delta compact --json  Compact redacted local agent queue history",
+    "  forge delta prune --older-than 30d --dry-run --json  Plan local Delta operational retention",
+    "  forge delta export --redacted --json  Export redacted Delta status, timeline, and agent memory",
+    "  forge studio open <app-path> --preview-port 5174 --target codex --json",
+    "  forge studio snapshot <app-path> --preview-port 5174 --target codex --probe-codex-server --json",
+    "  forge studio bridge <app-path> --preview-port 5174 --target codex --studio-url http://127.0.0.1:3765 --probe-codex-server --json",
+    "  forge studio doctor <app-path> --preview-port 5174 --target codex --json",
+    "  forge studio codex-server <app-path> --probe --json",
+    "  forge studio watch <app-path> --preview-port 5174 --target codex --json",
     "  forge dev                 Run API, DB/worker, watch, and web app when present",
     "  forge dev --once --json   One-shot health/diagnostic loop for agents and CI",
     "  forge do \"fix\" --json     Ask ForgeOS for the right workflow and commands",
-    "  forge inspect all --json  Read the generated machine contract",
+    "  forge cair snapshot         Compact CAIR project snapshot for agents",
+    "  forge cair query \"Q REFS S#1\"  Run a semantic CAIR query",
+    "  forge cair action --plan \"A RN t=S#1 nn=renamed\"  Plan a guarded semantic edit",
+    "  forge cair action \"A APPLY plan=<P#|path>\"  Apply a guarded CAIR plan",
+    "  forge agent print-context --json  Read the generated agent context pack",
+    "  forge inspect all --brief --json  Read the smallest aggregate project contract",
+    "  forge inspect all --json  Read the compact generated machine contract",
+    "  forge mcp serve          Serve ForgeOS Agent Memory tools over MCP stdio",
+    "  forge agent context --current --json  Read the Agent Memory context pack",
+    "  forge agent timeline --json  Read external-agent hook activity as a compact timeline",
     "  forge doctor windows --json  Diagnose native Windows setup and Bun shims",
+    "  forge bench compiler --json  Measure public compiler phase timings",
+    "  forge manifest validate ./forge.manifest.json --json  Validate an external runtime manifest",
     "",
     "Useful next commands:",
     "  forge generate",
     "  forge check --json",
+    "  forge verify              App-level default verification for the current project",
     "  forge verify --standard",
-    "  forge verify --strict",
+    "  forge verify quick        Alias for smoke/fast local checks",
+    "  forge verify agent        Alias for standard agent-loop verification",
+    "  forge verify release      Alias for strict app release verification",
+    "  forge verify framework    Maintainer-only ForgeOS framework test gate",
+    "  forge verify --strict --typechecker native --test-jobs 6",
+    "  forge verify framework --test-plan --json",
+    "",
+  ].join("\n");
+}
+
+function formatDevHelp(): string {
+  return [
+    "ForgeOS dev",
+    "",
+    "Usage:",
+    "  forge dev [status|stop] [options]",
+    "",
+    "Options:",
+    "  --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",
+    "  --web-only                        Start web server only, expecting an API runtime",
+    "  --no-worker                       Disable local worker",
+    "  --no-watch                        Disable file watching",
+    "  --seed                            Run the discovered seed command after the API runtime starts",
+    "  --seed-command <name>              Select a specific seed command for --seed",
+    "  --all-tenants                     With --seed, seed every discovered local tenant/persona",
+    "  --once --json                     Run one-shot diagnostics without starting servers",
+    "  --detach --json                   Start dev in the background with .forge/dev/dev.pid and .forge/dev/dev.log",
+    "",
+    "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",
+    "  forge dev --db pglite --once --json",
+    "  forge dev --detach --db memory --port 0 --json",
+    "  forge dev status --json",
+    "  forge dev stop --json",
     "",
   ].join("\n");
 }
 
 export async function main(argv: string[] = process.argv.slice(2)): Promise<number> {
+  if (argv[0] === "dev" && (argv.includes("--help") || argv.includes("-h"))) {
+    process.stdout.write(formatDevHelp());
+    return 0;
+  }
+
   if (argv.length === 0 || argv.includes("--help") || argv.includes("-h")) {
     process.stdout.write(formatHelp());
     return 0;
@@ -83,7 +264,19 @@ export async function main(argv: string[] = process.argv.slice(2)): Promise<numb
     return 1;
   }
 
-  return executeCommand(parsed.command);
+  const startedAt = Date.now();
+  const exitCode = await executeCommand(parsed.command);
+  const repositoryRead = parsed.command.kind === "repository" ||
+    (parsed.command.kind === "manifest" && parsed.command.subcommand === "validate") ||
+    (parsed.command.kind === "cair" && (() => { const repository = readRepositoryManifest(parsed.command.options.workspaceRoot, { manifestPath: parsed.command.options.manifestPath }); return !!repository.manifest || repository.diagnostics.length > 0; })());
+  if (repositoryRead) return exitCode;
+  await recordParsedCliCommand({
+    command: parsed.command,
+    argv,
+    exitCode,
+    durationMs: Date.now() - startedAt,
+  });
+  return exitCode;
 }
 
 if (isMainModule(import.meta)) {