@openagentpack/cli 0.4.0 → 0.7.0

package/README.md

@@ -13,12 +13,17 @@ The package installs the `agents` command.
 ## Quick start
 
 ```sh
-agents init
-agents validate
-agents plan
-agents apply
+agents project init
+agents project validate
+agents project build --dry-run
+agents project build --yes
+agents project publish --yes
 ```
 
+Directory projects store Agents and Skills as JSON, Markdown, and local files. `project build` previews full directory changes against the current version HEAD, organizes shared Skills, and writes `.openagentpack/build/agents.yaml`; `project publish` consumes only a current Build and records a full source-tree snapshot after complete remote success. Workbench and CLI use the same Git-independent switch under `agents project version ...`; snapshots include local Skill and binary content but exclude `.openagentpack/state.json`.
+
+The legacy `agents init|validate|plan|apply` YAML workflow and `agents playground -f agents.yaml` Session Preview remain available. YAML Apply is independent from directory versions.
+
 Use `agents <command> --help` for command-specific options.
 
 ## Documentation

package/dist/bin/agents.js

@@ -3,7 +3,7 @@ import {
   configureLogger,
   log,
   program
-} from "../chunk-V2QDO63Z.js";
+} from "../chunk-C7XMIB3W.js";
 
 // bin/agents.ts
 import { UserError } from "@openagentpack/sdk";

package/dist/{chunk-V2QDO63Z.js → chunk-C7XMIB3W.js}

@@ -7,6 +7,7 @@ import { Command as Command2, Option as Option2 } from "commander";
 // src/commands/apply.ts
 import * as p2 from "@clack/prompts";
 import { decideDestructive, executePlannedProject, UserError as UserError2 } from "@openagentpack/sdk";
+import { assertLegacyYamlNotShadowed } from "@openagentpack/sdk/project-workspace";
 import chalk3 from "chalk";
 
 // src/config-loader.ts
@@ -273,6 +274,7 @@ async function confirmDrift(actions, file) {
   return !p2.isCancel(shouldApply) && shouldApply;
 }
 async function applyCommand(options) {
+  await assertLegacyYamlNotShadowed(options.file);
   const ctx = await buildCliRuntime(options.file);
   assertProviderConfigured(ctx, options.provider);
   const planned = await planProjectWithRefresh(ctx, {
@@ -360,12 +362,13 @@ ${chalk3.green(`${creates.length} to create`)}, ${chalk3.yellow(`${updates.lengt
   const failed = result.results.filter((r) => r.status === "failed").length;
   const skipped = result.results.filter((r) => r.status === "skipped").length;
   s.stop("Apply finished.");
-  if (failed > 0) {
-    p2.log.warning(`${succeeded} succeeded, ${failed} failed, ${skipped} skipped.`, { output: process.stderr });
-    throw new UserError2("Apply failed.");
-  } else {
-    p2.log.success(`Apply complete! ${succeeded} actions executed successfully.`, { output: process.stderr });
+  if (failed > 0 || skipped > 0) {
+    p2.log.warning(`${succeeded} succeeded, ${failed} failed, ${skipped} skipped.`, {
+      output: process.stderr
+    });
+    throw new UserError2(failed > 0 ? "Apply failed." : "Apply incomplete: one or more actions were skipped.");
   }
+  p2.log.success(`Apply complete! ${succeeded} actions executed successfully.`, { output: process.stderr });
 }
 
 // src/commands/deployment.ts
@@ -520,8 +523,10 @@ import {
   destroyPlannedProjectResources,
   planDestroyProjectContext
 } from "@openagentpack/sdk";
+import { assertLegacyYamlNotShadowed as assertLegacyYamlNotShadowed2 } from "@openagentpack/sdk/project-workspace";
 import chalk6 from "chalk";
 async function destroyCommand(options) {
+  await assertLegacyYamlNotShadowed2(options.file);
   const ctx = await buildCliRuntime(options.file);
   const planned = planDestroyProjectContext(ctx);
   const resources = planned.resources;
@@ -630,6 +635,7 @@ function stopResourceSpinner(spinner4, result) {
 // src/commands/init.ts
 import { readFile, writeFile } from "fs/promises";
 import * as p4 from "@clack/prompts";
+import { UserError as UserError4 } from "@openagentpack/sdk";
 
 // src/utils/file-utils.ts
 import { existsSync } from "fs";
@@ -647,12 +653,10 @@ async function fileExists(path) {
 }
 
 // src/commands/init.ts
-var GITIGNORE_ADDITIONS = `
-# agents
-agents.state.json
-.env
-`;
-function buildTemplate(opts) {
+var PROVIDERS = ["bailian", "claude", "qoder", "ark", "all"];
+var LOCAL_GITIGNORE_PATTERNS = ["agents.state.json", ".openagentpack/versions/", ".env"];
+function buildTemplate(options) {
+  const agentKey = yamlMappingKey(options.agentName);
   const providers = {
     bailian: `  bailian:
     api_key: \${DASHSCOPE_API_KEY}
@@ -665,34 +669,29 @@ function buildTemplate(opts) {
     ark: `  ark:
     api_key: \${ARK_API_KEY}`
   };
-  let providerBlock;
-  if (opts.provider === "all") {
-    providerBlock = `${providers.bailian}
+  const providerBlock = options.provider === "all" ? `${providers.bailian}
 ${providers.claude}
 ${providers.qoder}
-${providers.ark}`;
-  } else {
-    providerBlock = providers[opts.provider];
-  }
+${providers.ark}` : providers[options.provider];
   const singleModel = {
-    bailian: `    model: qwen3.7-max`,
-    claude: `    model: claude-sonnet-4-6`,
-    qoder: `    model: ultimate`,
-    ark: `    model: doubao-seed-2-1-pro-260628`
+    bailian: "    model: qwen3.7-max",
+    claude: "    model: claude-sonnet-4-6",
+    qoder: "    model: ultimate",
+    ark: "    model: doubao-seed-2-1-pro-260628"
   };
-  const modelBlock = opts.provider === "all" ? `    model:
+  const modelBlock = options.provider === "all" ? `    model:
       bailian: qwen3.7-max
       claude: claude-sonnet-4-6
       qoder: ultimate
-      ark: doubao-seed-2-1-pro-260628` : singleModel[opts.provider];
-  const toolBlock = opts.provider === "bailian" ? "[bash, read, glob, grep]" : "[read, glob, grep, web_search, web_fetch]";
+      ark: doubao-seed-2-1-pro-260628` : singleModel[options.provider];
+  const toolBlock = options.provider === "bailian" ? "[bash, read, glob, grep]" : "[read, glob, grep, web_search, web_fetch]";
   return `version: "1"
 
 providers:
 ${providerBlock}
 
 defaults:
-  provider: ${opts.provider === "all" ? "all" : opts.provider}
+  provider: ${options.provider === "all" ? "all" : options.provider}
 
 environments:
   dev:
@@ -702,7 +701,7 @@ environments:
         type: unrestricted
 
 agents:
-  ${opts.agentName}:
+  ${agentKey}:
     description: "General-purpose assistant"
 ${modelBlock}
     instructions: |
@@ -712,61 +711,67 @@ ${modelBlock}
       builtin: ${toolBlock}
 `;
 }
-async function initCommand() {
+function yamlMappingKey(value) {
+  return /^[A-Za-z_][A-Za-z0-9._-]*$/.test(value) ? value : JSON.stringify(value);
+}
+function parseProvider(provider) {
+  if (PROVIDERS.includes(provider)) return provider;
+  throw new UserError4(`Unsupported provider '${provider}'. Choose one of: ${PROVIDERS.join(", ")}.`);
+}
+async function promptForProjectOptions(options) {
+  const provider = options.provider ? parseProvider(options.provider) : await p4.select({
+    message: "Which provider(s) do you want to use?",
+    options: [
+      { value: "bailian", label: "Bailian (\u963F\u91CC\u4E91\u767E\u70BC)" },
+      { value: "claude", label: "Claude" },
+      { value: "qoder", label: "Qoder" },
+      { value: "ark", label: "Ark\uFF08\u706B\u5C71\u65B9\u821F\uFF09" },
+      { value: "all", label: "All providers" }
+    ],
+    output: process.stderr
+  });
+  if (p4.isCancel(provider)) {
+    p4.cancel("Init cancelled.", { output: process.stderr });
+    process.exit(0);
+  }
+  const agentName = options.agentName ? options.agentName : await p4.text({
+    message: "Name your first agent:",
+    placeholder: "assistant",
+    defaultValue: "assistant",
+    output: process.stderr
+  });
+  if (p4.isCancel(agentName)) {
+    p4.cancel("Init cancelled.", { output: process.stderr });
+    process.exit(0);
+  }
+  const normalizedAgentName = agentName.trim();
+  if (!normalizedAgentName) throw new UserError4("Agent name cannot be empty.");
+  return { provider: parseProvider(provider), agentName: normalizedAgentName };
+}
+async function initCommand(options) {
   const configPath = "agents.yaml";
   if (await fileExists(configPath)) {
     log.warn(`${configPath} already exists, skipping.`);
     return;
   }
   p4.intro("agents init", { output: process.stderr });
-  const answers = await p4.group(
-    {
-      provider: () => p4.select({
-        message: "Which provider(s) do you want to use?",
-        options: [
-          { value: "bailian", label: "Bailian (\u963F\u91CC\u4E91\u767E\u70BC)" },
-          { value: "claude", label: "Claude" },
-          { value: "qoder", label: "Qoder" },
-          { value: "ark", label: "Ark\uFF08\u706B\u5C71\u65B9\u821F\uFF09" },
-          { value: "all", label: "All providers" }
-        ],
-        output: process.stderr
-      }),
-      agentName: () => p4.text({
-        message: "Name your first agent:",
-        placeholder: "assistant",
-        defaultValue: "assistant",
-        output: process.stderr
-      })
-    },
-    {
-      onCancel: () => {
-        p4.cancel("Init cancelled.", { output: process.stderr });
-        process.exit(0);
-      }
-    }
-  );
-  const template = buildTemplate({
-    provider: answers.provider,
-    agentName: answers.agentName
-  });
-  await writeFile(configPath, template, "utf8");
+  const answers = await promptForProjectOptions(options);
+  await writeFile(configPath, buildTemplate(answers), "utf8");
   p4.log.success(`Created ${configPath}`, { output: process.stderr });
   const gitignorePath = ".gitignore";
-  if (await fileExists(gitignorePath)) {
-    const content2 = await readFile(gitignorePath, "utf8");
-    if (!content2.includes("agents.state.json")) {
-      await writeFile(gitignorePath, content2 + GITIGNORE_ADDITIONS, "utf8");
-      p4.log.success("Updated .gitignore", { output: process.stderr });
-    }
-  } else {
-    await writeFile(gitignorePath, `${GITIGNORE_ADDITIONS.trim()}
+  const currentGitignore = await fileExists(gitignorePath) ? await readFile(gitignorePath, "utf8") : "";
+  const existingPatterns = new Set(currentGitignore.split(/\r?\n/).map((line) => line.trim()));
+  const missingPatterns = LOCAL_GITIGNORE_PATTERNS.filter((pattern) => !existingPatterns.has(pattern));
+  if (missingPatterns.length > 0) {
+    const separator = currentGitignore.length === 0 || currentGitignore.endsWith("\n") ? "" : "\n";
+    const heading = currentGitignore.length === 0 ? "# agents\n" : "\n# agents\n";
+    await writeFile(gitignorePath, `${currentGitignore}${separator}${heading}${missingPatterns.join("\n")}
 `, "utf8");
-    p4.log.success("Created .gitignore", { output: process.stderr });
+    p4.log.success(`${currentGitignore.length === 0 ? "Created" : "Updated"} .gitignore`, {
+      output: process.stderr
+    });
   }
-  p4.outro("Done! Next: edit agents.yaml, then run agents plan", {
-    output: process.stderr
-  });
+  p4.outro("Done! Next: edit agents.yaml, then run agents plan", { output: process.stderr });
 }
 
 // src/commands/memory.ts
@@ -785,13 +790,13 @@ import {
   listMemoryStores,
   listMemoryVersions,
   redactMemoryVersion,
-  UserError as UserError5,
+  UserError as UserError6,
   updateMemory,
   updateMemoryStore
 } from "@openagentpack/sdk";
 
 // src/runtime.ts
-import { listProviderNames, UserError as UserError4 } from "@openagentpack/sdk";
+import { listProviderNames, UserError as UserError5 } from "@openagentpack/sdk";
 import { Command, InvalidArgumentError, Option } from "commander";
 var DEFAULT_CONFIG_FILE = "agents.yaml";
 function isExplicitSource(source) {
@@ -826,13 +831,13 @@ function configFileArgs(args = process.argv.slice(2)) {
   }
   return values;
 }
-function configFileOption() {
-  return new Option("-f, --file <path>", "Config file path");
+function configFileOption(options = {}) {
+  return new Option(options.short === false ? "--file <path>" : "-f, --file <path>", "Config file path");
 }
 function resolveConfigFile(command) {
   const explicitFiles = [...new Set(configFileArgs())];
   if (explicitFiles.length > 1) {
-    throw new UserError4(
+    throw new UserError5(
       `Conflicting config files supplied: ${explicitFiles.join(" and ")}. Use only one --file value.`
     );
   }
@@ -842,7 +847,7 @@ function resolveConfigFile(command) {
   const localFile = command.getOptionValue("file");
   const localSource = command.getOptionValueSource("file");
   if (isExplicitSource(rootSource) && isExplicitSource(localSource) && rootFile && localFile && rootFile !== localFile) {
-    throw new UserError4(`Conflicting config files supplied: ${rootFile} and ${localFile}. Use only one --file value.`);
+    throw new UserError5(`Conflicting config files supplied: ${rootFile} and ${localFile}. Use only one --file value.`);
   }
   if (isExplicitSource(localSource) && localFile) return localFile;
   if (rootFile) return rootFile;
@@ -900,15 +905,15 @@ function writeJsonLine(value) {
 async function runtime(options) {
   const ctx = await buildCliRuntime(options.file);
   const provider = options.provider ?? (ctx.providers.size === 1 ? ctx.providers.keys().next().value : void 0);
-  if (!provider) throw new UserError5("Select a provider with --provider when multiple providers are configured.");
+  if (!provider) throw new UserError6("Select a provider with --provider when multiple providers are configured.");
   return { ctx, provider };
 }
 async function content(options) {
   if (options.content !== void 0 && options.contentFile)
-    throw new UserError5("Use either --content or --content-file, not both.");
+    throw new UserError6("Use either --content or --content-file, not both.");
   if (options.contentFile) return readFile2(options.contentFile, "utf8");
   if (options.content !== void 0) return options.content;
-  throw new UserError5("Memory content is required; use --content or --content-file.");
+  throw new UserError6("Memory content is required; use --content or --content-file.");
 }
 async function memoryStoreListCommand(options) {
   const { ctx, provider } = await runtime(options);
@@ -944,10 +949,10 @@ async function memoryCreateCommand(storeId, path, options) {
 async function memoryBatchCreateCommand(storeId, inputFile, options) {
   const { ctx, provider } = await runtime(options);
   const parsed = JSON.parse(await readFile2(inputFile, "utf8"));
-  if (!Array.isArray(parsed)) throw new UserError5("Batch input must be a JSON array of {path, content} objects.");
+  if (!Array.isArray(parsed)) throw new UserError6("Batch input must be a JSON array of {path, content} objects.");
   const items = parsed.map((item) => {
     if (!item || typeof item !== "object" || typeof item.path !== "string" || typeof item.content !== "string") {
-      throw new UserError5("Every batch item must contain string path and content fields.");
+      throw new UserError6("Every batch item must contain string path and content fields.");
     }
     return item;
   });
@@ -1000,25 +1005,25 @@ async function memoryVersionRedactCommand(storeId, versionId, options) {
 
 // src/commands/migrate.ts
 import { writeFile as writeFile2 } from "fs/promises";
-import { migrateConfig, UserError as UserError6 } from "@openagentpack/sdk";
+import { migrateConfig, UserError as UserError7 } from "@openagentpack/sdk";
 async function migrateCommand(options) {
   const fromPath = options.from ?? "agents.synced.yaml";
   const toPath = options.to ?? "agents.yaml";
   const toExists = await fileExists(toPath);
   if (!toExists) {
-    throw new UserError6(
+    throw new UserError7(
       `Target file '${toPath}' not found. Create a agents.yaml first (e.g. \`agents init\`), then run migrate.`
     );
   }
   const result = await migrateConfig({ fromPath, toPath });
   await writeFile2(toPath, result.yaml, "utf8");
   const addedParts = [];
-  for (const [group2, count] of Object.entries(result.added)) {
-    addedParts.push(`${count} ${group2}`);
+  for (const [group, count] of Object.entries(result.added)) {
+    addedParts.push(`${count} ${group}`);
   }
   const skippedParts = [];
-  for (const [group2, count] of Object.entries(result.skipped)) {
-    skippedParts.push(`${count} ${group2}`);
+  for (const [group, count] of Object.entries(result.skipped)) {
+    skippedParts.push(`${count} ${group}`);
   }
   if (addedParts.length) {
     log.success(`Migrated ${addedParts.join(", ")} into ${toPath}.`);
@@ -1119,9 +1124,11 @@ function formatPrice(factor) {
 }
 
 // src/commands/plan.ts
-import { UserError as UserError7 } from "@openagentpack/sdk";
+import { UserError as UserError8 } from "@openagentpack/sdk";
+import { assertLegacyYamlNotShadowed as assertLegacyYamlNotShadowed3 } from "@openagentpack/sdk/project-workspace";
 import chalk8 from "chalk";
 async function planCommand(options) {
+  await assertLegacyYamlNotShadowed3(options.file);
   const ctx = await buildCliRuntime(options.file);
   assertProviderConfigured(ctx, options.provider);
   const { plan } = await planProjectWithRefresh(ctx, {
@@ -1132,13 +1139,13 @@ async function planCommand(options) {
   if (options.json) {
     writeJson(plan);
     if (plan.diagnostics.some((d) => d.severity === "error")) {
-      throw new UserError7("Plan contains errors.");
+      throw new UserError8("Plan contains errors.");
     }
     return;
   }
   renderDiagnostics(plan.diagnostics);
   if (diagnosticsHaveErrors(plan.diagnostics)) {
-    throw new UserError7("Plan contains errors.");
+    throw new UserError8("Plan contains errors.");
   }
   const creates = plan.actions.filter((a) => a.action === "create");
   const updates = plan.actions.filter((a) => a.action === "update");
@@ -1191,16 +1198,15 @@ Plan: ${chalk8.green(`${creates.length} to create`)}, ${chalk8.yellow(`${updates
 
 // src/commands/playground.ts
 import { spawn } from "child_process";
+import { createHash, randomBytes } from "crypto";
 import { existsSync as existsSync2, readFileSync } from "fs";
 import { createRequire } from "module";
 import { dirname as dirname2, resolve as resolve2 } from "path";
 import { fileURLToPath } from "url";
-import { AGENTS_CONFIG_PROVIDERS } from "@openagentpack/sdk";
 var CLI_PKG = "@openagentpack/cli";
 var PLAYGROUND_PKG = "@openagentpack/playground";
 var DEFAULT_PORT = 4848;
 var PLAYGROUND_URL_RE = /running at http:\/\/localhost:(\d+)/;
-var SUPPORTED_PLAYGROUND_PROVIDERS = new Set(AGENTS_CONFIG_PROVIDERS);
 function cliVersion() {
   const here = dirname2(fileURLToPath(import.meta.url));
   const candidates = [
@@ -1255,7 +1261,7 @@ function watchPlaygroundPort(stdout, onPort) {
     onPort(Number(match[1]));
   });
 }
-async function waitForPlaygroundReady(child, fallbackPort, timeoutMs) {
+async function waitForPlaygroundReady(child, fallbackPort, timeoutMs, expectedProjectId) {
   let port = fallbackPort;
   let settled = false;
   return new Promise((resolve6) => {
@@ -1274,7 +1280,8 @@ async function waitForPlaygroundReady(child, fallbackPort, timeoutMs) {
       }
       try {
         const res = await fetch(`http://localhost:${port}/health`);
-        if (res.ok) {
+        const body = res.ok ? await res.json() : void 0;
+        if (body?.playground?.project_id === expectedProjectId) {
           settled = true;
           resolve6(port);
           return;
@@ -1295,6 +1302,50 @@ function openBrowser(url) {
     log.warn(`Could not open a browser automatically \u2014 visit ${url}`);
   }
 }
+function playgroundBrowserTargetFromSummary(baseUrl, summary, requestedAgent) {
+  if (summary.status !== "valid") return { url: baseUrl };
+  const agentIds = (summary.agents ?? []).map((entry) => entry.agent?.id?.trim()).filter((agentId) => Boolean(agentId));
+  const requested = requestedAgent?.trim();
+  if (requested) {
+    if (agentIds.includes(requested)) {
+      return { url: `${baseUrl}/agents/${encodeURIComponent(requested)}/preview` };
+    }
+    return {
+      url: baseUrl,
+      warning: `Agent '${requested}' was not found. Opening the project workbench instead.`
+    };
+  }
+  if (agentIds.length === 1) {
+    return { url: `${baseUrl}/agents/${encodeURIComponent(agentIds[0])}/preview` };
+  }
+  if (agentIds.length > 1) {
+    return {
+      url: baseUrl,
+      warning: "This project declares multiple Agents. Opening the workbench; rerun with --agent <id> for Preview."
+    };
+  }
+  return { url: baseUrl };
+}
+async function resolvePlaygroundBrowserTarget(port, requestedAgent) {
+  const baseUrl = `http://localhost:${port}`;
+  try {
+    const response = await fetch(`${baseUrl}/api/project`, { signal: AbortSignal.timeout(3e3) });
+    if (!response.ok) return { url: baseUrl };
+    return playgroundBrowserTargetFromSummary(
+      baseUrl,
+      await response.json(),
+      requestedAgent
+    );
+  } catch {
+    return { url: baseUrl };
+  }
+}
+async function openPlaygroundSurface(port, surface, options) {
+  if (options.open === false) return;
+  const target = surface === "workbench" ? { url: `http://localhost:${port}` } : await resolvePlaygroundBrowserTarget(port, options.agent);
+  if (target.warning) log.warn(target.warning);
+  openBrowser(target.url);
+}
 async function probeExistingPlayground(port) {
   try {
     const controller = new AbortController();
@@ -1304,7 +1355,11 @@ async function probeExistingPlayground(port) {
     if (!res.ok) return null;
     const body = await res.json();
     if (body.playground?.pid) {
-      return { version: body.playground.version ?? "unknown", pid: body.playground.pid };
+      return {
+        version: body.playground.version ?? "unknown",
+        pid: body.playground.pid,
+        projectId: body.playground.project_id
+      };
     }
   } catch {
   }
@@ -1324,22 +1379,20 @@ async function replaceExistingPlayground(existing, port) {
   }
   return false;
 }
-async function playgroundCommand(options) {
+async function launchPlayground(options, surface) {
   const port = options.port ? Number(options.port) : DEFAULT_PORT;
   if (!Number.isInteger(port) || port <= 0) {
     throw new Error(`Invalid --port '${options.port}'`);
   }
-  if (options.provider && !SUPPORTED_PLAYGROUND_PROVIDERS.has(options.provider)) {
-    const supported = [...SUPPORTED_PLAYGROUND_PROVIDERS].join(", ");
-    throw new Error(`Playground supports providers: ${supported}; received '${options.provider}'.`);
-  }
+  const sourcePath = surface === "workbench" ? resolve2(options.project ?? ".") : resolve2(options.file ?? "agents.yaml");
+  const projectId = createHash("sha256").update(sourcePath).digest("hex").slice(0, 16);
   const version = cliVersion();
   const existing = await probeExistingPlayground(port);
   if (existing) {
-    if (existing.version === version) {
-      const url2 = `http://localhost:${port}`;
-      log.success(`Playground v${version} already running at ${url2} (pid ${existing.pid})`);
-      if (options.open !== false) openBrowser(url2);
+    if (existing.version === version && existing.projectId === projectId) {
+      const baseUrl2 = `http://localhost:${port}`;
+      log.success(`Playground v${version} already running at ${baseUrl2} (pid ${existing.pid})`);
+      await openPlaygroundSurface(port, surface, options);
       return;
     }
     const freed = await replaceExistingPlayground(existing, port);
@@ -1350,10 +1403,17 @@ async function playgroundCommand(options) {
       return;
     }
   }
-  const env = { ...process.env, PORT: String(port) };
-  if (options.provider) {
-    env.AGENTS_PROVIDER = options.provider;
-    env.AGENTS_CLI_PROVIDER = options.provider;
+  const env = {
+    ...process.env,
+    PORT: String(port),
+    AGENTS_PLAYGROUND_TOKEN: randomBytes(32).toString("hex")
+  };
+  if (surface === "workbench") {
+    delete env.AGENTS_CONFIG_PATH;
+    env.AGENTS_PROJECT_ROOT = sourcePath;
+  } else {
+    delete env.AGENTS_PROJECT_ROOT;
+    env.AGENTS_CONFIG_PATH = sourcePath;
   }
   const { cmd, args } = resolveLauncher(version);
   if (cmd === "npx") log.info(`Fetching ${PLAYGROUND_PKG} (first run may take a moment)...`);
@@ -1366,14 +1426,274 @@ async function playgroundCommand(options) {
     log.error(`Failed to start playground: ${err instanceof Error ? err.message : String(err)}`);
     process.exit(1);
   });
-  const readyPort = await waitForPlaygroundReady(child, port, 3e4);
+  const readyPort = await waitForPlaygroundReady(child, port, 3e4, projectId);
   if (readyPort === null) {
     log.warn(`Playground did not become ready in time \u2014 check the logs above, then open http://localhost:${port}`);
     return;
   }
-  const url = `http://localhost:${readyPort}`;
-  log.success(`Playground ready at ${url}`);
-  if (options.open !== false) openBrowser(url);
+  const baseUrl = `http://localhost:${readyPort}`;
+  log.success(`Playground ready at ${baseUrl}`);
+  await openPlaygroundSurface(readyPort, surface, options);
+}
+async function playgroundCommand(options) {
+  await launchPlayground(options, "preview");
+}
+async function workbenchCommand(options) {
+  await launchPlayground(options, "workbench");
+}
+
+// src/commands/project.ts
+import * as prompts from "@clack/prompts";
+import { UserError as UserError9 } from "@openagentpack/sdk";
+import {
+  commitProjectBuild,
+  createDirectoryWorkspaceVersionService,
+  executeProjectPublish,
+  initializeDirectoryProject,
+  planProjectPublish,
+  previewProjectBuild,
+  validateDirectoryProject
+} from "@openagentpack/sdk/project-workspace";
+import chalk9 from "chalk";
+function projectRoot(options) {
+  return options.project ?? ".";
+}
+async function projectInitCommand(options) {
+  const result = await initializeDirectoryProject({ projectRoot: projectRoot(options) });
+  if (options.json) return writeJson(result);
+  log.success(
+    result.converted_from_yaml ? "Converted agents.yaml into a directory project." : "Created directory project."
+  );
+  if (result.state_migrated) log.success("Copied agents.state.json to .openagentpack/state.json.");
+  console.log(`Project: ${result.project_root}`);
+  console.log(`Baseline version: ${result.baseline_version}`);
+}
+async function projectValidateCommand(options) {
+  const inspection = await validateDirectoryProject(projectRoot(options));
+  if (options.json) return writeJson(inspection);
+  renderDiagnostics([...inspection.diagnostics, ...inspection.warnings]);
+  if (inspection.diagnostics.some((diagnostic) => diagnostic.severity === "error")) {
+    throw new UserError9("Directory project is invalid.");
+  }
+  log.success(`Project is valid (${inspection.project_revision.slice(0, 12)}).`);
+}
+async function projectBuildCommand(options) {
+  const preview = await previewProjectBuild(projectRoot(options));
+  if (options.json) {
+    if (options.dryRun) return writeJson(preview);
+  }
+  if (!options.json) renderDiagnostics([...preview.diagnostics, ...preview.warnings]);
+  if (!preview.can_build) throw new UserError9("Directory project is invalid and cannot be built.");
+  if (!options.json) {
+    const sourcePreview = await loadBuildSourcePreview(preview.project_root);
+    if (sourcePreview.projectRevision && sourcePreview.projectRevision !== preview.project_revision) {
+      throw new UserError9("Project source changed. Preview Build again.");
+    }
+    renderBuildSourcePreview(sourcePreview);
+    for (const move of preview.organization_moves) {
+      console.log(
+        chalk9.yellow(`move ${move.resource_type}.${move.resource_id}: ${move.from} -> ${move.to} (${move.reason})`)
+      );
+    }
+  }
+  if (options.dryRun) return;
+  if (!options.yes) {
+    const confirmed = await prompts.confirm({
+      message: "Write the Build, inferred resource associations, and Vault secret references (.env)?",
+      output: process.stderr
+    });
+    if (prompts.isCancel(confirmed) || !confirmed) {
+      prompts.cancel("Build cancelled. Project files were not changed.", { output: process.stderr });
+      return;
+    }
+  }
+  const result = await commitProjectBuild({
+    projectRoot: preview.project_root,
+    baseRevision: preview.project_revision
+  });
+  if (options.json) return writeJson(result.manifest);
+  log.success(`Build created at .openagentpack/build/agents.yaml (${result.manifest.yaml_hash.slice(0, 12)}).`);
+}
+async function projectPublishCommand(options) {
+  ensureCredentials();
+  const preview = await planProjectPublish(projectRoot(options), {
+    provider: options.provider,
+    refresh: options.refresh,
+    onFeedback: options.json ? void 0 : renderRuntimeFeedback,
+    quiet: options.json
+  });
+  if (!options.json) renderDiagnostics(preview.planned.plan.diagnostics);
+  if (preview.planned.plan.diagnostics.some((diagnostic) => diagnostic.severity === "error")) {
+    throw new UserError9("Cannot Publish: resolve the plan errors first.");
+  }
+  const actions = preview.planned.plan.actions.filter((action) => action.action !== "no-op");
+  if (!options.json) {
+    for (const action of actions) {
+      const color = action.action === "create" ? chalk9.green : action.action === "update" ? chalk9.yellow : chalk9.red;
+      console.log(
+        color(
+          `${action.action === "create" ? "+" : action.action === "update" ? "~" : "-"} ${formatResourceLabel(action.address)}`
+        )
+      );
+    }
+  }
+  if (!options.yes) {
+    const confirmed = await prompts.confirm({
+      message: actions.length === 0 ? "Publish this Build and record its version?" : `Publish ${actions.length} remote change(s)?`,
+      output: process.stderr
+    });
+    if (prompts.isCancel(confirmed) || !confirmed) {
+      prompts.cancel("Publish cancelled. No remote resources were changed.", { output: process.stderr });
+      return;
+    }
+  }
+  const result = await executeProjectPublish({
+    projectRoot: preview.project_root,
+    expectedProjectRevision: preview.project_revision,
+    expectedYamlHash: preview.build_manifest.yaml_hash,
+    expectedPlanFingerprint: preview.plan_fingerprint,
+    provider: options.provider,
+    refresh: options.refresh,
+    concurrency: options.concurrency,
+    policy: "force",
+    onFeedback: options.json ? void 0 : renderRuntimeFeedback
+  });
+  if (options.json) return writeJson(result);
+  const successful = result.execution?.results.filter((entry) => entry.status === "success").length ?? 0;
+  log.success(`Publish complete. ${successful} remote action(s) succeeded.`);
+  if (result.version) log.success(`Created project version ${result.version.short_version}.`);
+  if (result.working_tree_changed)
+    log.warn("Project files changed during Publish. The published Build is preserved, but a new Build is required.");
+}
+async function projectWorkbenchCommand(options) {
+  await workbenchCommand({ project: projectRoot(options), port: options.port, open: options.open });
+}
+async function projectVersionEnableCommand(options) {
+  const result = await createDirectoryWorkspaceVersionService(projectRoot(options)).enable(
+    "Initialize project versions"
+  );
+  if (options.json) return writeJson(result);
+  console.log(
+    result.version ? `Created baseline ${result.version.short_version}.` : "Current project source is already versioned."
+  );
+  console.log("Project versioning is enabled.");
+}
+async function projectVersionDisableCommand(options) {
+  const result = await createDirectoryWorkspaceVersionService(projectRoot(options)).disable();
+  if (options.json) return writeJson(result);
+  console.log("Project versioning is disabled. Existing versions were kept.");
+}
+async function projectVersionStatusCommand(options) {
+  const status = await createDirectoryWorkspaceVersionService(projectRoot(options)).status();
+  if (options.json) return writeJson(status);
+  console.log(`Versioning: ${status.enabled ? "enabled" : "disabled"}`);
+  console.log(`Head: ${status.head_version ?? "none"}`);
+  console.log(`Source: ${status.source_status}`);
+  console.log(`Store: ${status.store_root}`);
+  for (const blocker of [.../* @__PURE__ */ new Set([...status.write_blockers, ...status.restore_blockers])])
+    console.log(chalk9.yellow(`Blocker: ${blocker}`));
+}
+async function projectVersionListCommand(options) {
+  const page = await createDirectoryWorkspaceVersionService(projectRoot(options)).listVersions({
+    limit: options.limit,
+    cursor: options.cursor
+  });
+  if (options.json) return writeJson(page);
+  for (const version of page.versions)
+    console.log(
+      `${chalk9.yellow(version.short_version)} ${version.created_at} ${version.message} ${chalk9.dim(`(${version.created_by})`)}`
+    );
+  if (page.versions.length === 0) console.log("No project versions exist.");
+  if (page.next_cursor) console.log(chalk9.dim(`Next cursor: ${page.next_cursor}`));
+}
+async function projectVersionPreviewCommand(version, options) {
+  const preview = await createDirectoryWorkspaceVersionService(projectRoot(options)).previewVersion(version);
+  if (options.json) return writeJson(preview);
+  renderDirectoryVersionPreview(preview);
+}
+async function projectVersionRestoreCommand(version, options) {
+  const service = createDirectoryWorkspaceVersionService(projectRoot(options));
+  const preview = await service.previewVersion(version);
+  if (!options.json) renderDirectoryVersionPreview(preview);
+  if (!preview.can_restore)
+    throw new UserError9(preview.blockers[0] ?? preview.diagnostics[0]?.message ?? "Version cannot be restored.");
+  if (!options.yes) {
+    const confirmed = await prompts.confirm({
+      message: "Restore this version to the project working directory?",
+      output: process.stderr
+    });
+    if (prompts.isCancel(confirmed) || !confirmed) return;
+  }
+  const restored = await service.restoreVersion(version, {
+    headVersion: preview.base_head_version,
+    projectRevision: preview.base_project_revision
+  });
+  if (options.json) return writeJson(restored);
+  log.success(
+    `Restored ${version.slice(0, 12)} to the working directory. Version head and remote State were not changed.`
+  );
+}
+function renderDirectoryVersionPreview(preview) {
+  console.log(chalk9.bold(`Version ${preview.version_id}`));
+  for (const change of preview.changes) {
+    const color = change.change === "create" ? chalk9.green : change.change === "delete" ? chalk9.red : chalk9.yellow;
+    console.log(color(`${change.change} ${change.path}${change.binary ? " (binary)" : ""}`));
+    if (!change.binary) renderSimpleDiff(change.before ?? "", change.after ?? "");
+  }
+  renderDiagnostics(preview.diagnostics);
+  for (const blocker of preview.blockers) console.log(chalk9.yellow(`Blocker: ${blocker}`));
+  console.log(`Can restore: ${preview.can_restore ? "yes" : "no"}`);
+}
+async function loadBuildSourcePreview(projectRoot2) {
+  try {
+    const service = createDirectoryWorkspaceVersionService(projectRoot2);
+    const status = await service.status();
+    if (!status.head_version) return { baselineVersion: null, projectRevision: status.project_revision, changes: [] };
+    const preview = await service.previewVersion(status.head_version);
+    return {
+      baselineVersion: status.head_version,
+      projectRevision: preview.base_project_revision,
+      changes: preview.changes
+    };
+  } catch (error) {
+    return {
+      baselineVersion: null,
+      changes: [],
+      error: error instanceof Error ? error.message : String(error)
+    };
+  }
+}
+function renderBuildSourcePreview(preview) {
+  console.log(chalk9.bold("Project source changes"));
+  if (preview.error) {
+    console.log(chalk9.yellow(` Source Diff unavailable: ${preview.error}`));
+    return;
+  }
+  if (!preview.baselineVersion) {
+    console.log(chalk9.dim(" Source Diff unavailable: no project version baseline exists."));
+    return;
+  }
+  console.log(chalk9.dim(` baseline ${preview.baselineVersion.slice(0, 12)} -> working tree`));
+  if (preview.changes.length === 0) {
+    console.log(chalk9.dim(" no source changes"));
+    return;
+  }
+  for (const change of preview.changes) {
+    const displayedChange = change.change === "create" ? "delete" : change.change === "delete" ? "create" : "update";
+    const color = displayedChange === "create" ? chalk9.green : displayedChange === "delete" ? chalk9.red : chalk9.yellow;
+    console.log(color(`${displayedChange} ${change.path}${change.binary ? " (binary)" : ""}`));
+    if (!change.binary) renderSimpleDiff(change.after ?? "", change.before ?? "");
+  }
+}
+function renderSimpleDiff(before, after) {
+  if (before === after) {
+    console.log(chalk9.dim(" no content changes"));
+    return;
+  }
+  const beforeLines = before.split("\n");
+  const afterLines = after.split("\n");
+  for (const line of beforeLines) if (!afterLines.includes(line)) console.log(chalk9.red(`-${line}`));
+  for (const line of afterLines) if (!beforeLines.includes(line)) console.log(chalk9.green(`+${line}`));
 }
 
 // src/commands/session.ts
@@ -1388,10 +1708,10 @@ import {
   sendSessionMessageStreaming,
   startSessionRun,
   startSessionRunPolling,
-  UserError as UserError8
+  UserError as UserError10
 } from "@openagentpack/sdk";
 import { sanitizeSessionEvent, sanitizeSessionEvents } from "@openagentpack/sdk/session-events";
-import chalk9 from "chalk";
+import chalk10 from "chalk";
 function formatTimestamp(iso) {
   const d = new Date(iso);
   if (Number.isNaN(d.getTime())) return iso;
@@ -1413,7 +1733,7 @@ async function sessionCreateCommand(agentNameOrOptions, maybeOptions) {
   const options = maybeOptions ?? agentNameOrOptions;
   const positionalAgent = typeof agentNameOrOptions === "string" ? agentNameOrOptions : void 0;
   if (positionalAgent && options.agent && positionalAgent !== options.agent) {
-    throw new UserError8("Specify agent either positionally or with --agent, not both.");
+    throw new UserError10("Specify agent either positionally or with --agent, not both.");
   }
   const ctx = await buildCliRuntime(options.file);
   const run = await createSessionForAgent(ctx, {
@@ -1429,7 +1749,7 @@ async function sessionCreateCommand(agentNameOrOptions, maybeOptions) {
     title: options.title
   });
   const { agentName, session } = run;
-  log.success(`Session created: ${chalk9.bold(session.id)}`);
+  log.success(`Session created: ${chalk10.bold(session.id)}`);
   console.log(`  Agent:       ${agentName}`);
   console.log(`  Environment: ${session.environment_id}`);
   if (session.tunnel_id) console.log(`  Tunnel:      ${session.tunnel_id}`);
@@ -1476,10 +1796,10 @@ async function sessionListCommand(options) {
     const title = (s.title ?? "").slice(0, 18).padEnd(20);
     const agent = (agentNameMap.get(s.id) ?? s.agent_id.slice(0, 12)).padEnd(14);
     const statusText = s.status.padEnd(12);
-    const status = s.status === "idle" ? chalk9.green(statusText) : s.status === "processing" ? chalk9.yellow(statusText) : s.status === "failed" ? chalk9.red(statusText) : chalk9.gray(statusText);
+    const status = s.status === "idle" ? chalk10.green(statusText) : s.status === "processing" ? chalk10.yellow(statusText) : s.status === "failed" ? chalk10.red(statusText) : chalk10.gray(statusText);
     const created = formatTimestamp(s.created_at).padEnd(20);
     const duration = formatDuration(s.created_at, s.status === "idle" ? s.updated_at : void 0);
-    printTableRow([chalk9.bold(id), title, chalk9.cyan(agent), status, chalk9.dim(created), duration]);
+    printTableRow([chalk10.bold(id), title, chalk10.cyan(agent), status, chalk10.dim(created), duration]);
   }
   printTableFooter();
   if (hasMore) {
@@ -1489,7 +1809,7 @@ async function sessionListCommand(options) {
 async function sessionGetCommand(sessionId, options) {
   const ctx = await buildCliRuntime(options.file);
   const session = await getSession(ctx, sessionId, options.provider);
-  console.log(`  ID:          ${chalk9.bold(session.id)}`);
+  console.log(`  ID:          ${chalk10.bold(session.id)}`);
   console.log(`  Agent:       ${session.agent_id}`);
   console.log(`  Environment: ${session.environment_id}`);
   if (session.tunnel_id) console.log(`  Tunnel:      ${session.tunnel_id}`);
@@ -1510,7 +1830,7 @@ function shouldRenderLiveEvent(event) {
 }
 function renderTerminalStatus(status, json) {
   if (json) return;
-  const color = status === "idle" || status === "completed" ? chalk9.green : chalk9.red;
+  const color = status === "idle" || status === "completed" ? chalk10.green : chalk10.red;
   log.plain(color(`
 [session ${status}]`));
 }
@@ -1524,17 +1844,17 @@ function renderEvent(event) {
   if (event.type === "message" && event.content) {
     process.stdout.write(event.content);
   } else if (event.type === "tool_use") {
-    log.plain(chalk9.cyan(`
+    log.plain(chalk10.cyan(`
 [tool] ${event.tool_name}`));
   } else if (event.type === "tool_result" && event.content) {
     const preview = event.content.length > 200 ? `${event.content.slice(0, 200)}...` : event.content;
-    log.plain(chalk9.dim(preview));
+    log.plain(chalk10.dim(preview));
   } else if (event.type === "status") {
     if (event.status === "running") {
-      log.plain(chalk9.yellow("\n[session running]"));
+      log.plain(chalk10.yellow("\n[session running]"));
     }
   } else if (event.type === "error") {
-    log.plain(chalk9.red(`
+    log.plain(chalk10.red(`
 [error] ${event.content ?? "unknown error"}`));
   }
 }
@@ -1570,7 +1890,7 @@ async function sessionRunCommand(promptOrAgent, promptOrOptions, maybeOptions) {
   const prompt = hasPositionalAgent ? promptOrOptions : promptOrAgent;
   const options = hasPositionalAgent ? maybeOptions : promptOrOptions ?? maybeOptions;
   if (positionalAgent && options.agent && positionalAgent !== options.agent) {
-    throw new UserError8("Specify agent either positionally or with --agent, not both.");
+    throw new UserError10("Specify agent either positionally or with --agent, not both.");
   }
   const runOptions = {
     agent: positionalAgent ?? options.agent,
@@ -1589,7 +1909,7 @@ async function sessionRunCommand(promptOrAgent, promptOrOptions, maybeOptions) {
   const run = stream ? await startSessionRun(ctx, prompt, runOptions) : await startSessionRunPolling(ctx, prompt, runOptions);
   const session = run.session;
   if (!options.json) {
-    log.success(`Session created: ${chalk9.bold(session.id)}`);
+    log.success(`Session created: ${chalk10.bold(session.id)}`);
   }
   if (stream) {
     await streamAndRender(run.events, !!options.json);
@@ -1641,10 +1961,10 @@ async function sessionEventsCommand(sessionId, options) {
     else if (e.type === "tool_result") preview = (e.content ?? "").slice(0, 60);
     else if (e.type === "status") preview = `${e.status ?? ""}${e.stop_reason ? ` (${e.stop_reason})` : ""}`;
     else if (e.type === "error") preview = (e.content ?? "").slice(0, 60);
-    else if (e.type === "thinking") preview = chalk9.dim("(thinking)");
+    else if (e.type === "thinking") preview = chalk10.dim("(thinking)");
     else preview = e.raw_type;
-    const typeColor = e.type === "error" ? chalk9.red(typeLabel) : e.type === "status" ? chalk9.yellow(typeLabel) : e.type === "tool_use" ? chalk9.cyan(typeLabel) : typeLabel;
-    printTableRow([chalk9.dim(idx), typeColor, preview]);
+    const typeColor = e.type === "error" ? chalk10.red(typeLabel) : e.type === "status" ? chalk10.yellow(typeLabel) : e.type === "tool_use" ? chalk10.cyan(typeLabel) : typeLabel;
+    printTableRow([chalk10.dim(idx), typeColor, preview]);
   }
   printTableFooter();
   if (hasMore) {
@@ -1656,8 +1976,8 @@ function parseMemoryStores(value) {
 }
 
 // src/commands/state.ts
-import { importResource, parseStateAddress, UserError as UserError9 } from "@openagentpack/sdk";
-import chalk10 from "chalk";
+import { importResource, parseStateAddress, UserError as UserError11 } from "@openagentpack/sdk";
+import chalk11 from "chalk";
 async function stateListCommand(options) {
   const ctx = await buildCliRuntime(options.file);
   const resources = ctx.state.listResources();
@@ -1672,7 +1992,7 @@ async function stateListCommand(options) {
     const name = r.address.name.padEnd(20);
     const provider = r.address.provider.padEnd(10);
     const id = (r.remote_id ?? "(local)").slice(0, 30);
-    console.log(`  ${type}  ${name}${provider} ${chalk10.dim(id)}`);
+    console.log(`  ${type}  ${name}${provider} ${chalk11.dim(id)}`);
   }
   printTableFooter();
 }
@@ -1680,14 +2000,14 @@ async function stateShowCommand(address, options) {
   const ctx = await buildCliRuntime(options.file);
   const parsed = parseStateAddress(address, { requireProvider: false });
   const found = ctx.state.findResource(parsed);
-  if (!found) throw new UserError9(`Resource not found: ${address}`);
+  if (!found) throw new UserError11(`Resource not found: ${address}`);
   console.log(JSON.stringify(found, null, 2));
 }
 async function stateRemoveCommand(address, options) {
   const ctx = await buildCliRuntime(options.file);
   const parsed = parseStateAddress(address, { requireProvider: false });
   const found = ctx.state.findResource(parsed);
-  if (!found) throw new UserError9(`Resource not found: ${address}`);
+  if (!found) throw new UserError11(`Resource not found: ${address}`);
   ctx.state.removeResource(found.address);
   await ctx.state.save();
   log.success(`Removed ${address} from state (remote resource not deleted).`);
@@ -1708,14 +2028,14 @@ import {
   resolveSyncProvider,
   syncProviderResourcesFromContext,
   syncProviderResourcesFromEnv,
-  UserError as UserError10
+  UserError as UserError12
 } from "@openagentpack/sdk";
 import { stringify as stringifyYaml } from "yaml";
 var DEFAULT_SYNC_OUTPUT = "agents.synced.yaml";
 function ensureSyncOutputWritable(outPath, force) {
   if (force) return;
   if (fileExistsSync(outPath)) {
-    throw new UserError10(
+    throw new UserError12(
       `Output file '${outPath}' already exists. Use --force to overwrite, or -o/--out to write elsewhere.`
     );
   }
@@ -1777,7 +2097,7 @@ async function syncFromConfig(configPath, explicitProvider) {
 }
 async function syncFromEnv(explicitProvider) {
   if (!explicitProvider) {
-    throw new UserError10(
+    throw new UserError12(
       "agents sync requires --provider when no config file exists, e.g. `agents sync --provider claude`."
     );
   }
@@ -1989,7 +2309,7 @@ async function serializeConfig(config) {
 
 // src/commands/validate.ts
 import { resolve as resolve4 } from "path";
-import { resolveProjectConfig as resolveProjectConfig2, UserError as UserError11, validateProjectConfig } from "@openagentpack/sdk";
+import { resolveProjectConfig as resolveProjectConfig2, UserError as UserError13, validateProjectConfig } from "@openagentpack/sdk";
 async function validateCommand(options) {
   ensureCredentials();
   const configPath = resolve4(options.file);
@@ -2004,7 +2324,7 @@ async function validateCommand(options) {
   }
   const errorCount = diagnostics.filter((d) => d.severity === "error").length;
   if (errorCount > 0) {
-    throw new UserError11(`Validation failed with ${errorCount} error(s).`);
+    throw new UserError13(`Validation failed with ${errorCount} error(s).`);
   }
   log.success("Configuration is valid.");
 }
@@ -2059,8 +2379,21 @@ var program = new Command2().name("agents").version(readCliVersion()).descriptio
     color: opts.color !== false
   });
 });
-program.command("init").description("Create a new agents.yaml template").action(initCommand);
-program.command("playground").description("Launch the local web UI (fetches @openagentpack/playground on demand) and open it in a browser").option("--port <n>", "Port to serve on (default 4848)").addOption(providerOption("Provider the UI targets")).option("--no-open", "Do not open a browser automatically").action(playgroundCommand);
+program.command("init").description("Create an agents.yaml template").option("--provider <provider>", "Provider to configure (bailian, claude, qoder, ark, or all)").option("--agent-name <name>", "Name of the first Agent").action((options) => initCommand(options));
+program.command("playground").description("Launch a Session Preview for an agents.yaml Agent").addOption(configFileOption()).option("--agent <id>", "Agent to preview (required when the project declares multiple Agents)").option("--port <n>", "Port to serve on (default 4848)").option("--no-open", "Do not open a browser automatically").action(withResolvedConfigFile(playgroundCommand));
+var projectCmd = program.command("project").description("Manage a directory-based Agent project");
+projectCmd.command("init").description("Create or convert a directory-based Agent project").option("--project <directory>", "Project directory", ".").option("--json", "Output as JSON").action(projectInitCommand);
+projectCmd.command("validate").description("Validate all directory project source files").option("--project <directory>", "Project directory", ".").option("--json", "Output as JSON").action(projectValidateCommand);
+projectCmd.command("build").description("Organize project files and generate .openagentpack/build/agents.yaml").option("--project <directory>", "Project directory", ".").option("--dry-run", "Preview Build without changing files").option("-y, --yes", "Skip confirmation prompt").option("--json", "Output as JSON").action(projectBuildCommand);
+projectCmd.command("publish").description("Publish the current immutable Build to the configured provider").option("--project <directory>", "Project directory", ".").option("-y, --yes", "Skip confirmation prompt").option("--refresh <value>", "Refresh state before planning (true/false)", parseBooleanOption, true).option("--concurrency <n>", "Max independent resources to publish in parallel", parsePositiveInteger).addOption(providerOption("Target provider", { allowAll: true, defaultValue: "all" })).option("--json", "Output as JSON").action(projectPublishCommand);
+projectCmd.command("workbench").description("Launch the directory project Workbench").option("--project <directory>", "Project directory", ".").option("--port <n>", "Port to serve on (default 4848)").option("--no-open", "Do not open a browser automatically").action(projectWorkbenchCommand);
+var projectVersionCmd = projectCmd.command("version").description("Manage directory project snapshots");
+projectVersionCmd.command("enable").description("Enable Publish-time project versions and create a baseline when needed").option("--project <directory>", "Project directory", ".").option("--json", "Output as JSON").action(projectVersionEnableCommand);
+projectVersionCmd.command("disable").description("Disable Publish-time project versions without removing history").option("--project <directory>", "Project directory", ".").option("--json", "Output as JSON").action(projectVersionDisableCommand);
+projectVersionCmd.command("status").description("Show directory project version status").option("--project <directory>", "Project directory", ".").option("--json", "Output as JSON").action(projectVersionStatusCommand);
+projectVersionCmd.command("list").description("List directory project versions").option("--project <directory>", "Project directory", ".").option("--limit <n>", "Maximum versions to return", parsePositiveInteger).option("--cursor <cursor>", "Pagination cursor").option("--json", "Output as JSON").action(projectVersionListCommand);
+projectVersionCmd.command("preview <version>").description("Preview a historical directory project version").option("--project <directory>", "Project directory", ".").option("--json", "Output as JSON").action(projectVersionPreviewCommand);
+projectVersionCmd.command("restore <version>").description("Restore a historical version to the project working directory").option("--project <directory>", "Project directory", ".").option("-y, --yes", "Skip confirmation prompt").option("--json", "Output as JSON").action(projectVersionRestoreCommand);
 program.command("validate").description("Validate the configuration file (offline)").addOption(configFileOption()).action(withResolvedConfigFile(validateCommand));
 program.command("plan").description("Show what changes would be applied").addOption(configFileOption()).addOption(providerOption("Target provider", { allowAll: true, defaultValue: "all" })).option("--refresh <value>", "Refresh state from remote before planning (true/false)", parseBooleanOption, true).option("--refresh-only", "Refresh state and show drift without planning remote mutations").option("--json", "Output as JSON").action(withResolvedConfigFile(planCommand));
 program.command("apply").description("Apply the planned changes to create/update/delete resources").addOption(configFileOption()).option("-y, --yes", "Skip confirmation prompt").option("--refresh <value>", "Refresh state from remote before planning (true/false)", parseBooleanOption, true).option("--refresh-only", "Refresh state without mutating remote resources").option(

package/dist/src/program.js

@@ -1,6 +1,6 @@
 import {
   program
-} from "../chunk-V2QDO63Z.js";
+} from "../chunk-C7XMIB3W.js";
 export {
   program
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openagentpack/cli",
-  "version": "0.4.0",
+  "version": "0.7.0",
   "description": "Open Agent Pack — Declaratively manage AI agent infrastructure",
   "license": "Apache-2.0",
   "keywords": [
@@ -49,12 +49,12 @@
     "typecheck": "tsc --noEmit"
   },
   "devDependencies": {
-    "@openagentpack/playground": "0.4.0",
+    "@openagentpack/playground": "0.7.0",
     "@types/bun": "^1.3.14",
     "typescript": "^6.0.3"
   },
   "dependencies": {
-    "@openagentpack/sdk": "0.4.0",
+    "@openagentpack/sdk": "0.7.0",
     "@clack/prompts": "^1.5.1",
     "chalk": "^5.6.2",
     "commander": "^14.0.3",