forgeos 0.1.0-alpha.2 → 0.1.0-alpha.21

package/src/forge/cli/docs.ts

@@ -0,0 +1,265 @@
+import { spawnSync } from "node:child_process";
+import { dirname, join, normalize } from "node:path";
+import { nodeFileSystem } from "../compiler/fs/index.ts";
+import { createDiagnostic } from "../compiler/diagnostics/create.ts";
+import type { Diagnostic } from "../compiler/types/diagnostic.ts";
+import { docsReadyNextActions } from "./next-actions.ts";
+
+export type DocsSubcommand = "check";
+
+export interface DocsCheckOptions {
+  workspaceRoot: string;
+  json: boolean;
+  build?: boolean;
+  installVenv?: boolean;
+}
+
+export interface DocsCheck {
+  name: string;
+  ok: boolean;
+  status: "pass" | "fail" | "warning";
+  details?: unknown;
+}
+
+export interface DocsCheckResult {
+  ok: boolean;
+  checks: DocsCheck[];
+  diagnostics: Diagnostic[];
+  nextActions: string[];
+  exitCode: 0 | 1;
+}
+
+const REQUIRED_DOCS = [
+  "index.md",
+  "getting-started.md",
+  "agent-workflow.md",
+  "cli-reference.md",
+  "troubleshooting.md",
+  "production-readiness.md",
+  "self-host.md",
+  "release.md",
+] as const;
+
+const CONTENT_CHECKS: Array<{ file: string; contains: string[] }> = [
+  { file: ".readthedocs.yaml", contains: ["version: 2", "configuration: mkdocs.yml", "fail_on_warning: true", "requirements: docs/requirements.txt"] },
+  { file: "mkdocs.yml", contains: ["name: material", "markdown_extensions:", "extra_css:", "javascripts/mermaid-init.js"] },
+  { file: "docs/getting-started.md", contains: ["npm create forgeos-app@alpha", "Open the web URL"] },
+  { file: "docs/agent-workflow.md", contains: ["forge do", "forge status --json", "forge handoff --json"] },
+  { file: "docs/troubleshooting.md", contains: ["FORGE_DELTA_BUSY", "waiting-for-user-trust", "Studio target preview issues"] },
+  { file: "docs/release.md", contains: ["release:verify-public-alpha", "Documentation checklist"] },
+  { file: "docs/self-host.md", contains: ["forge self-host check"] },
+];
+
+function read(workspaceRoot: string, relative: string): string | null {
+  const path = join(workspaceRoot, relative);
+  if (!nodeFileSystem.exists(path)) {
+    return null;
+  }
+  return nodeFileSystem.readText(path) ?? "";
+}
+
+function checkFileExists(workspaceRoot: string, relative: string): DocsCheck {
+  return nodeFileSystem.exists(join(workspaceRoot, relative))
+    ? { name: relative, ok: true, status: "pass" }
+    : { name: relative, ok: false, status: "fail", details: { missing: true } };
+}
+
+function checkContains(workspaceRoot: string, file: string, contains: string[]): DocsCheck {
+  const content = read(workspaceRoot, file);
+  if (content === null) {
+    return { name: `${file}:content`, ok: false, status: "fail", details: { missing: true } };
+  }
+  const missing = contains.filter((needle) => !content.includes(needle));
+  return missing.length === 0
+    ? { name: `${file}:content`, ok: true, status: "pass" }
+    : { name: `${file}:content`, ok: false, status: "fail", details: { missing } };
+}
+
+function slugifyHeading(heading: string): string {
+  return heading
+    .trim()
+    .toLowerCase()
+    .replace(/[`*_]/g, "")
+    .replace(/[^a-z0-9\s-]/g, "")
+    .replace(/\s+/g, "-");
+}
+
+function anchorsFor(content: string): Set<string> {
+  const anchors = new Set<string>();
+  for (const line of content.split(/\r?\n/)) {
+    const match = /^(#{1,6})\s+(.+)$/.exec(line);
+    if (match) {
+      anchors.add(slugifyHeading(match[2] ?? ""));
+    }
+  }
+  return anchors;
+}
+
+function checkYamlShape(workspaceRoot: string, relative: string, requiredKeys: string[]): DocsCheck {
+  const content = read(workspaceRoot, relative);
+  if (content === null) {
+    return { name: `${relative}:yaml`, ok: false, status: "fail", details: { missing: true } };
+  }
+  const malformed = content
+    .split(/\r?\n/)
+    .filter((line) => line.trim() && !line.trimStart().startsWith("#"))
+    .filter((line) => !/^\s*-\s+/.test(line))
+    .filter((line) => !line.includes(":"));
+  const missingKeys = requiredKeys.filter((key) => !new RegExp(`^${key}:`, "m").test(content));
+  const ok = malformed.length === 0 && missingKeys.length === 0;
+  return ok
+    ? { name: `${relative}:yaml`, ok: true, status: "pass" }
+    : { name: `${relative}:yaml`, ok: false, status: "fail", details: { malformed, missingKeys } };
+}
+
+function checkInternalLinks(workspaceRoot: string): DocsCheck {
+  const missing: Array<{ file: string; target: string }> = [];
+  const docs = nodeFileSystem.exists(join(workspaceRoot, "docs"))
+    ? nodeFileSystem.readDir(join(workspaceRoot, "docs"))
+      .filter((entry) => entry.name.endsWith(".md"))
+      .map((entry) => `docs/${entry.name}`)
+    : [];
+  for (const file of docs) {
+    const content = read(workspaceRoot, file) ?? "";
+    const links = [...content.matchAll(/\[[^\]]+\]\(([^)]+)\)/g)]
+      .map((match) => match[1] ?? "")
+      .filter((target) =>
+        target &&
+        !target.startsWith("http://") &&
+        !target.startsWith("https://") &&
+        !target.startsWith("mailto:") &&
+        !target.startsWith("#") &&
+        !target.startsWith("`")
+      );
+    for (const target of links) {
+      const [pathPart, anchor] = target.split("#");
+      const resolved = normalize(join(dirname(file), decodeURIComponent(pathPart ?? ""))).replace(/\\/g, "/");
+      if (!nodeFileSystem.exists(join(workspaceRoot, resolved))) {
+        missing.push({ file, target });
+        continue;
+      }
+      if (anchor) {
+        const targetContent = read(workspaceRoot, resolved) ?? "";
+        if (!anchorsFor(targetContent).has(anchor)) {
+          missing.push({ file, target });
+        }
+      }
+    }
+  }
+  return missing.length === 0
+    ? { name: "docs-internal-links", ok: true, status: "pass" }
+    : { name: "docs-internal-links", ok: false, status: "fail", details: { missing } };
+}
+
+function checkMkdocsTooling(workspaceRoot: string): DocsCheck {
+  const result = spawnSync("python3", ["-m", "mkdocs", "--version"], {
+    cwd: workspaceRoot,
+    encoding: "utf8",
+    windowsHide: true,
+    stdio: ["ignore", "pipe", "pipe"],
+  });
+  if (result.status === 0) {
+    return {
+      name: "mkdocs-tooling",
+      ok: true,
+      status: "pass",
+      details: { version: (result.stdout ?? "").trim() },
+    };
+  }
+  return {
+    name: "mkdocs-tooling",
+    ok: true,
+    status: "warning",
+    details: {
+      message: "mkdocs is not importable in the current Python environment; install docs/requirements.txt before building docs locally",
+    },
+  };
+}
+
+function runOptionalDocsBuild(options: DocsCheckOptions): DocsCheck[] {
+  const checks: DocsCheck[] = [];
+  const python = process.platform === "win32"
+    ? join(options.workspaceRoot, ".venv-rtd", "Scripts", "python.exe")
+    : join(options.workspaceRoot, ".venv-rtd", "bin", "python");
+  if (options.installVenv) {
+    const venv = spawnSync("python3", ["-m", "venv", ".venv-rtd"], {
+      cwd: options.workspaceRoot,
+      encoding: "utf8",
+      windowsHide: true,
+      stdio: ["ignore", "pipe", "pipe"],
+    });
+    checks.push(venv.status === 0
+      ? { name: "mkdocs-venv-create", ok: true, status: "pass" }
+      : { name: "mkdocs-venv-create", ok: false, status: "fail", details: { stderr: venv.stderr } });
+    if (venv.status === 0) {
+      const install = spawnSync(python, ["-m", "pip", "install", "-r", "docs/requirements.txt"], {
+        cwd: options.workspaceRoot,
+        encoding: "utf8",
+        windowsHide: true,
+        stdio: ["ignore", "pipe", "pipe"],
+      });
+      checks.push(install.status === 0
+        ? { name: "mkdocs-venv-install", ok: true, status: "pass" }
+        : { name: "mkdocs-venv-install", ok: false, status: "fail", details: { stderr: install.stderr } });
+    }
+  }
+  if (options.build) {
+    const command = options.installVenv ? python : "python3";
+    const args = ["-m", "mkdocs", "build", "--strict"];
+    const build = spawnSync(command, args, {
+      cwd: options.workspaceRoot,
+      encoding: "utf8",
+      windowsHide: true,
+      stdio: ["ignore", "pipe", "pipe"],
+    });
+    checks.push(build.status === 0
+      ? { name: "mkdocs-build-strict", ok: true, status: "pass", details: { stdout: build.stdout?.trim() } }
+      : { name: "mkdocs-build-strict", ok: false, status: "fail", details: { stderr: build.stderr } });
+  }
+  return checks;
+}
+
+export function runDocsCheckCommand(options: DocsCheckOptions): DocsCheckResult {
+  const checks: DocsCheck[] = [
+    checkFileExists(options.workspaceRoot, ".readthedocs.yaml"),
+    checkFileExists(options.workspaceRoot, "mkdocs.yml"),
+    checkFileExists(options.workspaceRoot, "docs/requirements.txt"),
+    checkFileExists(options.workspaceRoot, "docs/stylesheets/forge.css"),
+    checkFileExists(options.workspaceRoot, "docs/javascripts/mermaid-init.js"),
+    ...REQUIRED_DOCS.map((file) => checkFileExists(options.workspaceRoot, `docs/${file}`)),
+    checkYamlShape(options.workspaceRoot, ".readthedocs.yaml", ["version", "build", "mkdocs"]),
+    checkYamlShape(options.workspaceRoot, "mkdocs.yml", ["site_name", "theme", "nav"]),
+    ...CONTENT_CHECKS.map((check) => checkContains(options.workspaceRoot, check.file, check.contains)),
+    checkInternalLinks(options.workspaceRoot),
+    checkMkdocsTooling(options.workspaceRoot),
+    ...runOptionalDocsBuild(options),
+  ];
+  const failed = checks.filter((check) => !check.ok);
+  const diagnostics = failed.map((check) => createDiagnostic({
+    severity: "error",
+    code: "FORGE_DOCS_CHECK_FAILED",
+    message: `documentation check failed: ${check.name}`,
+    suggestedCommands: ["forge docs check --json", "bun test tests/docs/readthedocs.test.ts"],
+  }));
+  const ok = failed.length === 0;
+  return {
+    ok,
+    checks,
+    diagnostics,
+    nextActions: ok
+      ? docsReadyNextActions()
+      : ["forge docs check --json", "bun test tests/docs/readthedocs.test.ts"],
+    exitCode: ok ? 0 : 1,
+  };
+}
+
+export function formatDocsCheckHuman(result: DocsCheckResult): string {
+  const lines = [
+    `docs check ${result.ok ? "ok" : "failed"}`,
+    ...result.checks.map((check) => `${check.status} ${check.name}`),
+  ];
+  if (result.nextActions.length > 0) {
+    lines.push("", "Next:", ...result.nextActions.map((action) => `  ${action}`));
+  }
+  return `${lines.join("\n")}\n`;
+}

package/src/forge/cli/handoff.ts

@@ -0,0 +1,250 @@
+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 { buildWorkspaceGitSummary } from "../workspace/git-summary.ts";
+
+export interface HandoffCommandOptions {
+  workspaceRoot: string;
+  json: 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;
+    stagedFiles: number;
+    unstagedFiles: number;
+    untrackedFiles: number;
+    lastTestRun: "passed" | "failed" | "missing";
+    lastUiRun: "passed" | "failed" | "missing";
+  };
+  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;
+    };
+    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[];
+  };
+  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"];
+}): string {
+  const agent = input.dev.summary.agentContext;
+  const changedByType = summarizeChangeTypes(input.git.changeSummary.changed);
+  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"}.`,
+    `${agent.changedFiles} changed file(s)${changedByType ? `: ${changedByType}` : ""}; ${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(" ");
+}
+
+export async function runHandoffCommand(options: HandoffCommandOptions): Promise<HandoffCommandResult> {
+  const workspaceRoot = options.workspaceRoot.replace(/\\/g, "/");
+  const dev = await runDevConsoleCycle({
+    workspaceRoot,
+    mode: "once",
+    includeImpact: true,
+  });
+  const git = buildWorkspaceGitSummary(workspaceRoot);
+  const recentRuns = summarizeRecentRuns(workspaceRoot);
+  const agent = dev.summary.agentContext;
+  const risks = [
+    ...agent.blockingIssues,
+    ...(git.untracked.count > 0 ? [`${git.untracked.count} untracked file(s) are not in git history`] : []),
+    ...(recentRuns.test && !recentRuns.test.ok ? ["last test run failed"] : []),
+    ...(recentRuns.ui && !recentRuns.ui.ok ? ["last UI run failed"] : []),
+  ];
+  const nextActions = [
+    ...agent.recommendedCommands,
+    ...(git.changed.count > 0 ? ["forge review run --changed --json"] : []),
+    "forge handoff --json",
+  ];
+  const ok = dev.ok &&
+    agent.blockingIssues.length === 0 &&
+    (!recentRuns.test || recentRuns.test.ok) &&
+    (!recentRuns.ui || recentRuns.ui.ok);
+
+  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: agent.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",
+    },
+    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 }),
+      recommendedReadFiles: agent.recommendedReadFiles,
+      recommendedCommands: [...new Set(nextActions)].slice(0, 10),
+      risks,
+    },
+    diagnostics: dev.diagnostics,
+    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}`));
+  }
+  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/main.ts

@@ -4,23 +4,61 @@ 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";
 
 function formatHelp(): string {
   return [
     "ForgeOS",
     "",
     "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 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 agent ingest codex --watch --file .forge/agent/events.ndjson --json",
+    "  forge docs check --json  Check public docs, ReadTheDocs config, links, and local MkDocs tooling",
+    "  forge docs check --build --install-venv --json  Build docs strictly in a local RTD-style venv",
+    "  forge release doctor --json  Aggregate release, sourcemaps, self-host, and docs readiness",
+    "  forge 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 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");
 }
@@ -83,7 +121,15 @@ 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);
+  await recordParsedCliCommand({
+    command: parsed.command,
+    argv,
+    exitCode,
+    durationMs: Date.now() - startedAt,
+  });
+  return exitCode;
 }
 
 if (isMainModule(import.meta)) {

package/src/forge/cli/new.ts

@@ -8,7 +8,7 @@ import { run as runGenerate } from "../compiler/orchestrator/run.ts";
 import { resolvePackageManagerArgv } from "../compiler/package-manager/executor.ts";
 import { moduleDir } from "../platform/module.ts";
 
-export type NewTemplateName = "b2b-support-web" | "minimal-web";
+export type NewTemplateName = "agent-workroom" | "b2b-support-web" | "minimal-web";
 export type NewPackageManager = "bun" | "npm" | "pnpm" | "yarn";
 
 export interface NewCommandOptions {
@@ -45,6 +45,7 @@ const REQUIRED_GITIGNORE_PATHS = [
   "forge.lock",
   ".forge/cache/",
   ".forge/pglite/",
+  ".forge/delta/",
   ".forge/local/",
   ".forge/test-cache/",
   ".forge/test-runs/",
@@ -55,6 +56,7 @@ const REQUIRED_GITIGNORE_PATHS = [
   ".forge/reviews/",
   ".forge/impact/",
   ".forge/agent-adapters/",
+  ".forge/studio/",
 ] as const;
 
 const DEFAULT_FORGE_PACKAGE_SPEC = "npm:forgeos@alpha";

package/src/forge/cli/next-actions.ts

@@ -0,0 +1,23 @@
+export function uniqueNextActions(actions: string[]): string[] {
+  return [...new Set(actions)].filter(Boolean);
+}
+
+export function releasePrepareNextActions(): string[] {
+  return ["forge release prepare --env production", "forge release check --json"];
+}
+
+export function releaseReadyNextActions(): string[] {
+  return ["forge artifacts verify --json", "forge sourcemaps check --json"];
+}
+
+export function selfHostPrepareNextActions(): string[] {
+  return ["forge self-host compose", "forge self-host env", "forge self-host check --json"];
+}
+
+export function selfHostReadyNextActions(): string[] {
+  return ["docker compose -f deploy/docker-compose.yml config", "forge release prepare --env production"];
+}
+
+export function docsReadyNextActions(): string[] {
+  return ["bun test tests/docs/readthedocs.test.ts", "mkdocs build --strict"];
+}