@animaapp/cli 0.7.1 → 0.9.0

package/dist/index.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 
 // src/index.ts
-import { Command as Command14 } from "commander";
+import { Command as Command23 } from "commander";
 
 // src/commands/create.ts
 import { Command } from "commander";
@@ -176,7 +176,19 @@ function validationError(message, detail) {
   );
 }
 function apiError(message, detail) {
-  return new CliError("API_ERROR", message, EXIT_CODES.API_ERROR, detail);
+  const text = message.replace(/^Error: /, "");
+  return new CliError("API_ERROR", withWorkspaceHint(text), EXIT_CODES.API_ERROR, detail);
+}
+function withWorkspaceHint(message) {
+  if (/\bworkspaceId\b/.test(message)) {
+    return `${message}
+Pass it with --workspace <id>; \`anima workspaces\` lists the ids.`;
+  }
+  if (message === "Workspace not found") {
+    return `${message}
+\`anima workspaces\` lists the workspaces you can reach, with their ids.`;
+  }
+  return message;
 }
 function timeoutError() {
   return new CliError(
@@ -423,9 +435,16 @@ import { CallToolResultSchema, ErrorCode } from "@modelcontextprotocol/sdk/types
 import { createRequire } from "module";
 var { version } = createRequire(import.meta.url)("../package.json");
 
+// src/clientIdentity.ts
+var ANIMA_CLIENT_IDENTITY = {
+  type: "cli",
+  name: "anima-cli",
+  version
+};
+
 // src/api/mcp.ts
 var MCP_PATH = "/v1/mcp";
-var CLIENT_INFO = { name: "anima-cli", version };
+var CLIENT_INFO = { name: ANIMA_CLIENT_IDENTITY.name, version: ANIMA_CLIENT_IDENTITY.version };
 var DEFAULT_TIMEOUT_MS = 6e5;
 var AnimaMcpClient = class {
   #client;
@@ -433,7 +452,10 @@ var AnimaMcpClient = class {
   #url;
   constructor(config) {
     const headers = {
-      Authorization: `Bearer ${config.token}`
+      Authorization: `Bearer ${config.token}`,
+      "X-Anima-Client-Type": ANIMA_CLIENT_IDENTITY.type,
+      "X-Anima-Client-Name": ANIMA_CLIENT_IDENTITY.name,
+      "X-Anima-Client-Version": ANIMA_CLIENT_IDENTITY.version
     };
     if (config.teamId) headers["X-Team-Id"] = config.teamId;
     if (config.figmaToken) headers["X-Figma-Token"] = config.figmaToken;
@@ -475,6 +497,11 @@ var AnimaMcpClient = class {
       if (err?.code === ErrorCode.RequestTimeout) {
         throw timeoutError();
       }
+      if (err?.code === ErrorCode.InvalidParams && /\bnot found\b/.test(err.message)) {
+        throw apiError(
+          `${name} is not available to this credential. An agent is offered it only once a human has granted it the access it needs in a workspace of this team (read to list, write to create).`
+        );
+      }
       throw err;
     }
     logEvent("mcp_tool_result", { tool: name, isError: result.isError ?? false });
@@ -608,8 +635,11 @@ function printSessionResult(result) {
   console.log();
   printSuccess("Artifact created successfully!");
   printKeyValue("Session ID", result.sessionId);
+  if (result.artifactUrl) {
+    printKeyValue("Your artifact", chalk.cyan.underline(result.artifactUrl));
+  }
   if (result.playgroundUrl) {
-    printKeyValue("Your artifact", chalk.cyan.underline(result.playgroundUrl));
+    printKeyValue("Edit in Playground", chalk.cyan.underline(result.playgroundUrl));
   }
   if (result.tokenUsage) {
     printKeyValue("Token usage", result.tokenUsage.toLocaleString());
@@ -710,8 +740,8 @@ function zipFolder(root) {
   });
   return zip.toBuffer();
 }
-function isProbablyBinary(path5, buffer) {
-  if (BINARY_EXTENSIONS.has(extname(path5).toLowerCase())) return true;
+function isProbablyBinary(path7, buffer) {
+  if (BINARY_EXTENSIONS.has(extname(path7).toLowerCase())) return true;
   return buffer.includes(0);
 }
 function collectProjectSource(fromPath) {
@@ -732,30 +762,33 @@ function collectProjectSource(fromPath) {
   }
   const files = {};
   let totalBytes = 0;
-  for (const path5 of paths) {
-    const buffer = readFileSync(join(fromPath, path5));
-    if (isProbablyBinary(path5, buffer)) {
-      return { kind: "zip", buffer: zipFolder(fromPath), reason: `binary file present (${path5})` };
+  for (const path7 of paths) {
+    const buffer = readFileSync(join(fromPath, path7));
+    if (isProbablyBinary(path7, buffer)) {
+      return { kind: "zip", buffer: zipFolder(fromPath), reason: `binary file present (${path7})` };
     }
     totalBytes += buffer.length;
     if (totalBytes > MAX_INLINE_BYTES) {
       return { kind: "zip", buffer: zipFolder(fromPath), reason: "project exceeds the inline size limit" };
     }
-    files[path5.split("\\").join("/")] = buffer.toString("utf8");
+    files[path7.split("\\").join("/")] = buffer.toString("utf8");
   }
   return { kind: "files", files, fileCount: paths.length };
 }
 
-// src/utils/playgroundUrl.ts
-var PLAYGROUND_BASE = "https://dev.animaapp.com/chat";
-function parsePlaygroundUrl(input) {
+// src/utils/artifactUrl.ts
+var ARTIFACT_BASE = "https://app.agentgrid.io/artifacts";
+function artifactUrlFor(sessionId) {
+  return `${ARTIFACT_BASE}/${sessionId}`;
+}
+function parseArtifactUrl(input) {
   if (!input.includes("/")) {
     return input;
   }
   try {
     const url = new URL(input);
     const parts = url.pathname.split("/").filter(Boolean);
-    const markerIndex = parts.findIndex((p) => p === "chat" || p === "artifacts");
+    const markerIndex = parts.findIndex((p) => p === "artifacts" || p === "chat");
     if (markerIndex !== -1 && markerIndex + 1 < parts.length) {
       return parts[markerIndex + 1];
     }
@@ -765,11 +798,63 @@ function parsePlaygroundUrl(input) {
   }
 }
 
+// src/utils/waitForArtifact.ts
+var STATUS_CALL_TIMEOUT_MS = 12e4;
+async function fetchArtifactStatus(client, sessionId, options = {}) {
+  return client.callTool(
+    "artifact-status",
+    { sessionId, wait: options.wait ?? false },
+    {
+      timeoutMs: STATUS_CALL_TIMEOUT_MS,
+      onProgress: options.onProgress ? (p) => options.onProgress(p.message ?? `Generating (${Math.round(p.progress * 100)}%)...`) : void 0
+    }
+  );
+}
+async function waitForArtifact(client, sessionId, options = { deadline: Date.now() }) {
+  for (; ; ) {
+    const result = await fetchArtifactStatus(client, sessionId, {
+      wait: true,
+      onProgress: options.onProgress
+    });
+    if (!result.success) {
+      throw new CliError(
+        "API_ERROR",
+        result.reason || result.error || "Could not read the artifact's status",
+        EXIT_CODES.API_ERROR,
+        result
+      );
+    }
+    if (result.status !== "generating") {
+      logEvent("generation_settled", { sessionId, status: result.status });
+      return result;
+    }
+    if (Date.now() >= options.deadline) {
+      logEvent("generation_wait_timeout", { sessionId, progress: result.progress });
+      throw generationTimeoutError(sessionId, result.progress);
+    }
+    options.onProgress?.(
+      result.progress !== void 0 ? `Generating (${result.progress}%)...` : "Generating..."
+    );
+  }
+}
+function generationTimeoutError(sessionId, progress) {
+  const reached = progress !== void 0 ? ` (reached ${progress}%)` : "";
+  return new CliError(
+    "TIMEOUT",
+    `Still generating${reached} when the wait budget ran out. Generation is NOT cancelled \u2014 it keeps running in the background.
+Pick the wait back up with: anima status ${sessionId} --wait
+Or allow longer next time with --timeout <ms>.`,
+    EXIT_CODES.TIMEOUT,
+    { sessionId, progress }
+  );
+}
+
 // src/api/anonymousCreate.ts
 async function createAnonymousArtifact(request, fetchFn = fetch) {
   const url = `${request.apiUrl.replace(/\/$/, "")}/v1/generationSessions`;
   const body = {
     type: "import",
+    clientType: ANIMA_CLIENT_IDENTITY.type,
     ...request.files ? { files: request.files } : {},
     ...request.zipUploadId ? { zipUploadId: request.zipUploadId } : {},
     ...request.framework ? { framework: request.framework } : {},
@@ -810,8 +895,16 @@ async function getAnonymousZipUploadUrl(apiUrl, fetchFn = fetch) {
   return { zipUploadId: payload.zipUploadId, uploadUrl: payload.uploadUrl };
 }
 
+// src/utils/workspaceFlag.ts
+function workspaceFlag(value) {
+  if (value !== void 0 && value.trim() === "") {
+    throw validationError("--workspace needs a workspace id; `anima workspaces` lists them");
+  }
+  return value;
+}
+
 // src/commands/create.ts
-var createCommand = new Command("create").description(
+var createCommand = new Command("create").summary("Create an artifact: your code, an empty repo, or AI generation").description(
   "Create an artifact from your own code: empty for code you'll push (instant) or import your existing code (instant). Also supports AI generation: p2c/l2c/f2c (3-7 min)."
 ).requiredOption(
   "-t, --type <type>",
@@ -822,13 +915,19 @@ var createCommand = new Command("create").description(
 ).option("--styling <style>", "tailwind | css | plain_css | css_modules | inline_styles", "tailwind").option("--language <lang>", "typescript | javascript").option("--ui-library <lib>", "mui | antd | shadcn | clean_react").option("--guidelines <text>", "Additional constraints (p2c only)").option(
   "--artifact-type <kind>",
   "app | markdown \u2014 what the artifact IS. app (default) needs an index.html; markdown needs .md files"
-).option("--name <name>", "Project name (empty/import only)").option("--from <path>", "Folder or .zip with your project (import only) \u2014 becomes the first commit").option(
+).option("--name <name>", "Project name (empty/import only)").option(
+  "-w, --workspace <id>",
+  "The workspace to create it in (id from `anima workspaces`). Optional when you can create in only one workspace; otherwise required, since there is no default"
+).option("--from <path>", "Folder or .zip with your project (import only) \u2014 becomes the first commit").option(
   "--anonymous",
   "Create without an account (import only). Returns a claim link to send a human, and a handoff token to log in with once they claim it"
 ).option(
   "--handoff <token>",
   "Add this artifact to an existing claim (--anonymous only), so one claim link covers them all. Defaults to the token from your last anonymous create"
-).option("--client-name <name>", "How this CLI is credited as the creator of an anonymous artifact", "AgentGrid CLI").option("--json", "Output as JSON").option("--timeout <ms>", "Timeout in milliseconds", "600000").option("--verbose", "Show progress on stderr").option("--api-url <url>", "API base URL (overrides config / ANIMA_API_URL)").option("--log-file <path>", "Append a JSON debug log of each step to this file").action(async (opts) => {
+).option("--client-name <name>", "How this CLI is credited as the creator of an anonymous artifact", "AgentGrid CLI").option("--json", "Output as JSON").option(
+  "--no-wait",
+  "Return as soon as generation starts (p2c/l2c/f2c), instead of waiting for the finished app. Poll with `anima status <sessionId> --wait`"
+).option("--timeout <ms>", "Timeout in milliseconds", "600000").option("--verbose", "Show progress on stderr").option("--api-url <url>", "API base URL (overrides config / ANIMA_API_URL)").option("--log-file <path>", "Append a JSON debug log of each step to this file").action(async (opts) => {
   const mode = detectOutputMode(opts);
   initLogger(opts.logFile);
   const progress = new ProgressReporter(mode, opts.verbose);
@@ -872,22 +971,44 @@ ${grant.nextSteps}` : message, grant);
     progress.start(
       type === "empty" ? "Creating empty artifact..." : type === "import" ? "Importing your project..." : `Creating ${type.toUpperCase()} artifact...`
     );
-    const result = await withMcp(
-      mcpConfig,
-      (client) => client.callTool("artifact-create", args, {
-        timeoutMs: parseInt(opts.timeout, 10),
-        onProgress: (p) => progress.update(p.message ?? `Generating (${Math.round(p.progress)}%)...`)
-      })
-    );
+    const timeoutMs = parseInt(opts.timeout, 10);
+    const deadline = Date.now() + timeoutMs;
+    const { result, settled } = await withMcp(mcpConfig, async (client) => {
+      const created = await client.callTool("artifact-create", args, { timeoutMs });
+      if (!created.success || !created.sessionId) return { created };
+      if (created.status !== "generating" || !opts.wait) return { created };
+      progress.update("Generating your app...");
+      const status2 = await waitForArtifact(client, created.sessionId, {
+        deadline,
+        onProgress: (message) => progress.update(message)
+      });
+      return { created, status: status2 };
+    }).then(({ created, status: status2 }) => ({ result: created, settled: status2 }));
     if (!result.success || !result.sessionId) {
-      const message = result.reason || result.error || "Generation failed";
+      const message = result.message || result.reason || result.error || "Generation failed";
       throw apiError(result.nextSteps ? `${message}
 ${result.nextSteps}` : message, result);
     }
-    const playgroundUrl = result.playgroundUrl || `${PLAYGROUND_BASE}/${result.sessionId}`;
-    progress.succeed("Artifact created!");
+    if (settled?.status === "failed") {
+      throw apiError(settled.error || "Generation failed", settled);
+    }
+    const artifactUrl = settled?.artifactUrl || result.artifactUrl || artifactUrlFor(result.sessionId);
+    const playgroundUrl = settled?.playgroundUrl ?? result.playgroundUrl;
+    const previewUrl = settled?.previewUrl ?? result.previewUrl;
+    const status = settled?.status ?? result.status ?? "ready";
+    progress.succeed(settled ? "Your app is ready!" : "Artifact created!");
     if (mode === "pretty") {
-      printSessionResult({ sessionId: result.sessionId, playgroundUrl });
+      printSessionResult({
+        sessionId: result.sessionId,
+        artifactUrl,
+        playgroundUrl
+      });
+      if (status === "generating") {
+        console.log(
+          `  Still generating. Wait for it with ${chalk2.cyan(`anima status ${result.sessionId} --wait`)}.`
+        );
+        console.log();
+      }
       if (result.gitRemoteUrl) {
         console.log(`  ${chalk2.cyan(`git clone ${result.gitRemoteUrl}`)}`);
         console.log();
@@ -920,7 +1041,14 @@ ${result.nextSteps}` : message, result);
       outputResult(mode, {
         success: true,
         sessionId: result.sessionId,
-        playgroundUrl,
+        status,
+        artifactUrl,
+        ...playgroundUrl ? { playgroundUrl } : {},
+        ...previewUrl ? { previewUrl } : {},
+        ...settled?.name ? { name: settled.name } : {},
+        ...status === "generating" ? {
+          nextSteps: `Generation is still running. Wait for it with: anima status ${result.sessionId} --wait`
+        } : {},
         ...result.gitRemoteUrl ? { gitRemoteUrl: result.gitRemoteUrl, access: result.access, expiresAt: result.expiresAt } : {},
         ...result.framework ? { framework: result.framework } : {},
         ...result.fileCount !== void 0 ? { fileCount: result.fileCount } : {},
@@ -1063,6 +1191,12 @@ Log in first for the other types: anima login`
   if (type !== "import" && opts.from) {
     throw validationError("--from is only valid with -t import");
   }
+  workspaceFlag(opts.workspace);
+  if (opts.workspace !== void 0 && opts.anonymous) {
+    throw validationError(
+      "--workspace does not apply to --anonymous creates \u2014 they belong to no team until a human claims them"
+    );
+  }
 }
 function resolveFigmaToken(opts, stored) {
   const figmaToken = opts.figmaToken || process.env.FIGMA_TOKEN || stored;
@@ -1081,7 +1215,8 @@ function buildCreateArgs(type, opts) {
       // import is what made markdown artifacts render as empty apps.
       ...opts.framework && opts.artifactType !== "markdown" ? { framework: opts.framework } : {},
       ...opts.artifactType ? { artifactType: opts.artifactType } : {},
-      ...opts.name ? { name: opts.name } : {}
+      ...opts.name ? { name: opts.name } : {},
+      ...opts.workspace !== void 0 ? { workspaceId: opts.workspace } : {}
     };
   }
   const framework = opts.framework ?? "html";
@@ -1096,6 +1231,7 @@ function buildCreateArgs(type, opts) {
   };
   if (language) args.language = language;
   if (opts.uiLibrary) args.uiLibrary = opts.uiLibrary;
+  if (opts.workspace !== void 0) args.workspaceId = opts.workspace;
   switch (type) {
     case "p2c":
       args.prompt = opts.prompt;
@@ -1120,22 +1256,107 @@ function buildCreateArgs(type, opts) {
   return args;
 }
 
-// src/commands/list.ts
+// src/commands/createKnowledge.ts
 import { Command as Command2 } from "commander";
+
+// src/commands/runner.ts
+async function withCommandErrors(mode, fn) {
+  try {
+    await fn();
+  } catch (err) {
+    if (err instanceof CliError) {
+      if (mode === "pretty") {
+        printError(err.message);
+      } else {
+        outputError(mode, { code: err.code, message: err.message });
+      }
+      process.exit(err.exitCode);
+    }
+    throw err;
+  }
+}
+
+// src/commands/createKnowledge.ts
+function buildCreateKnowledgeArgs(name, workspaceId) {
+  if (name !== void 0 && name.length > 120) {
+    throw validationError("--name must be at most 120 characters");
+  }
+  return {
+    ...name === void 0 ? {} : { name },
+    ...workspaceFlag(workspaceId) === void 0 ? {} : { workspaceId }
+  };
+}
+function makeCreateKnowledgeCommand() {
+  return new Command2("create-knowledge").summary("Create a knowledge artifact from Anima's template").description(
+    "Create a ready knowledge artifact from Anima's server-provided template. The template supplies the files and framework; only an optional display name is accepted."
+  ).option("--name <name>", 'Display name (defaults to "Untitled project"; max 120 characters)').option(
+    "-w, --workspace <id>",
+    "The workspace to create it in (id from `anima workspaces`). Optional when you can create in only one workspace; otherwise required, since there is no default"
+  ).option("--json", "Output as JSON").option("--verbose", "Show progress on stderr").option("--api-url <url>", "API base URL (overrides config / ANIMA_API_URL)").option("--log-file <path>", "Append a JSON debug log of each step to this file").action(async (opts) => {
+    const mode = detectOutputMode(opts);
+    initLogger(opts.logFile);
+    const progress = new ProgressReporter(mode, opts.verbose);
+    await withCommandErrors(mode, async () => {
+      try {
+        await run();
+      } catch (err) {
+        progress.fail("Failed");
+        throw err;
+      }
+    });
+    async function run() {
+      const args = buildCreateKnowledgeArgs(opts.name, opts.workspace);
+      const auth = await resolveAuth(opts.apiUrl);
+      progress.start("Creating knowledge artifact from template...");
+      const result = await withMcp(
+        { apiBaseUrl: resolveApiUrl(opts.apiUrl), token: auth.token, teamId: auth.teamId },
+        (client) => client.callTool("artifact-create_knowledge", args)
+      );
+      if (!result.success || !result.sessionId) {
+        throw apiError(result.message || result.reason || result.error || "Knowledge artifact creation failed", result);
+      }
+      progress.succeed("Knowledge artifact created");
+      if (mode === "pretty") {
+        printSessionResult({
+          sessionId: result.sessionId,
+          artifactUrl: result.artifactUrl,
+          playgroundUrl: result.playgroundUrl
+        });
+        if (result.fileCount !== void 0) {
+          printKeyValue("Template files", String(result.fileCount));
+        }
+        console.log();
+      } else {
+        outputResult(mode, result);
+      }
+    }
+  });
+}
+var createKnowledgeCommand = makeCreateKnowledgeCommand();
+
+// src/commands/list.ts
+import { Command as Command3 } from "commander";
 import chalk3 from "chalk";
-var listCommand = new Command2("list").aliases(["ls", "artifacts"]).description(
-  "List your team's artifacts (most-recently-updated first) so you can resume existing work."
+var listCommand = new Command3("list").summary("List the artifacts you can read, most-recently-updated first").aliases(["ls", "artifacts"]).description(
+  "List the artifacts you can read, across every workspace you can reach or in one (most-recently-updated first), so you can resume existing work."
+).option(
+  "-w, --workspace <id>",
+  "Only this workspace (id from `anima workspaces`); omit to span every workspace you can read"
 ).option("--json", "Output as JSON").option("--api-url <url>", "API base URL (overrides config / ANIMA_API_URL)").option("--log-file <path>", "Append a JSON debug log of each step to this file").action(async (opts) => {
   const mode = detectOutputMode(opts);
   initLogger(opts.logFile);
   try {
     const auth = await resolveAuth(opts.apiUrl);
+    const workspaceId = workspaceFlag(opts.workspace);
     const result = await withMcp(
       { apiBaseUrl: resolveApiUrl(opts.apiUrl), token: auth.token, teamId: auth.teamId },
-      (client) => client.callTool("workspace-list_artifacts", {})
+      (client) => client.callTool(
+        "workspace-list_artifacts",
+        workspaceId !== void 0 ? { workspaceId } : {}
+      )
     );
     if (!result.success) {
-      const message = result.reason || result.error || "Could not list artifacts";
+      const message = result.message || result.reason || result.error || "Could not list artifacts";
       throw apiError(message, result);
     }
     const artifacts = result.artifacts ?? [];
@@ -1144,22 +1365,19 @@ var listCommand = new Command2("list").aliases(["ls", "artifacts"]).description(
       if (artifacts.length === 0) {
         console.log();
         console.log(
-          "  No artifacts yet \u2014 create one with `create -t empty` or `create -t import`."
+          workspaceId !== void 0 ? "  Nothing you can read in that workspace." : "  No artifacts you can read \u2014 create one with `create -t empty` or `create -t import`."
         );
         console.log();
       } else {
         console.log();
         for (const a of artifacts) {
           console.log(`  ${chalk3.bold(a.name)} ${chalk3.gray(`(${a.type})`)}`);
-          if (a.sessionId) {
-            console.log(`    ${chalk3.gray("session:")} ${a.sessionId}`);
+          console.log(`    ${chalk3.gray("session:")} ${a.sessionId}`);
+          if (a.workspaceName) {
+            console.log(`    ${chalk3.gray("workspace:")} ${a.workspaceName}`);
           }
           console.log(`    ${chalk3.gray("updated:")} ${formatUpdatedAt(a.updatedAt)}`);
-          if (a.sessionId) {
-            console.log(
-              `    ${chalk3.cyan.underline(`${PLAYGROUND_BASE}/${a.sessionId}`)}`
-            );
-          }
+          console.log(`    ${chalk3.cyan.underline(artifactUrlFor(a.sessionId))}`);
           console.log();
         }
         if (result.truncated) {
@@ -1172,8 +1390,9 @@ var listCommand = new Command2("list").aliases(["ls", "artifacts"]).description(
     } else {
       outputResult(mode, {
         success: true,
-        workspaceId: result.workspaceId,
-        artifacts,
+        // The listing tool returns no URL; deriving it here saves every caller
+        // the same string concatenation, and keeps one definition of the link.
+        artifacts: artifacts.map((a) => ({ ...a, artifactUrl: artifactUrlFor(a.sessionId) })),
         truncated: result.truncated ?? false
       });
     }
@@ -1197,9 +1416,135 @@ function formatUpdatedAt(iso) {
   return `${relative2} (${iso})`;
 }
 
+// src/commands/workspaces.ts
+import { Command as Command4 } from "commander";
+import chalk4 from "chalk";
+var workspacesCommand = new Command4("workspaces").summary("List the workspaces you can reach, and what you may do in each").aliases(["ws"]).description(
+  "List the workspaces you can read in your team, with the capabilities you hold in each. Use a workspace id with `list --workspace` or `create --workspace`."
+).option("--json", "Output as JSON").option("--api-url <url>", "API base URL (overrides config / ANIMA_API_URL)").option("--log-file <path>", "Append a JSON debug log of each step to this file").action(async (opts) => {
+  const mode = detectOutputMode(opts);
+  initLogger(opts.logFile);
+  try {
+    const auth = await resolveAuth(opts.apiUrl);
+    const result = await withMcp(
+      { apiBaseUrl: resolveApiUrl(opts.apiUrl), token: auth.token, teamId: auth.teamId },
+      (client) => client.callTool("workspace-list_workspaces", {})
+    );
+    if (!result.success) {
+      const message = result.message || result.reason || result.error || "Could not list workspaces";
+      throw apiError(message, result);
+    }
+    const workspaces = result.workspaces ?? [];
+    logEvent("workspaces_listed", { count: workspaces.length });
+    if (mode === "pretty") {
+      console.log();
+      if (workspaces.length === 0) {
+        console.log("  You cannot reach any workspace in this team.");
+        console.log(
+          chalk4.gray("  Someone who manages the team can grant you access to one.")
+        );
+        console.log();
+      } else {
+        for (const workspace of workspaces) {
+          const label = workspace.isGeneral && workspace.name !== "General" ? chalk4.gray(" (General)") : "";
+          console.log(`  ${chalk4.bold(workspace.name)}${label}`);
+          console.log(`    ${chalk4.gray("id:")} ${workspace.workspaceId}`);
+          console.log(
+            `    ${chalk4.gray("you can:")} ${workspace.capabilities.join(", ") || chalk4.gray("nothing")}`
+          );
+          console.log();
+        }
+      }
+    } else {
+      outputResult(mode, { success: true, workspaces });
+    }
+  } catch (err) {
+    if (err instanceof CliError) {
+      if (mode === "pretty") {
+        console.error(err.message);
+      } else {
+        outputError(mode, { code: err.code, message: err.message });
+      }
+      process.exit(err.exitCode);
+    }
+    throw err;
+  }
+});
+
+// src/commands/status.ts
+import { Command as Command5 } from "commander";
+import chalk5 from "chalk";
+var statusCommand = new Command5("status").summary("Check whether an artifact finished generating").description(
+  "Check whether an artifact finished generating. --wait blocks until it is ready or failed."
+).argument("<artifactUrl>", "Artifact URL or session ID").option("--wait", "Block until generation finishes instead of returning a snapshot").option("--json", "Output as JSON").option("--timeout <ms>", "How long --wait may block", "600000").option("--verbose", "Show progress on stderr").option("--api-url <url>", "API base URL (overrides config / ANIMA_API_URL)").option("--log-file <path>", "Append a JSON debug log of each step to this file").action(async (artifactUrl, opts) => {
+  const mode = detectOutputMode(opts);
+  initLogger(opts.logFile);
+  const progress = new ProgressReporter(mode, opts.verbose);
+  try {
+    const sessionId = parseArtifactUrl(artifactUrl);
+    const auth = await resolveAuth(opts.apiUrl);
+    progress.start(opts.wait ? "Waiting for generation..." : "Checking status...");
+    const result = await withMcp(
+      { apiBaseUrl: resolveApiUrl(opts.apiUrl), token: auth.token, teamId: auth.teamId },
+      (client) => opts.wait ? waitForArtifact(client, sessionId, {
+        deadline: Date.now() + parseInt(opts.timeout, 10),
+        onProgress: (message) => progress.update(message)
+      }) : fetchArtifactStatus(client, sessionId)
+    );
+    if (!result.success) {
+      throw apiError(result.reason || result.error || "Could not read the artifact's status", result);
+    }
+    progress.succeed(`Status: ${result.status}`);
+    if (mode === "pretty") {
+      printArtifactStatus(sessionId, result);
+    } else {
+      outputResult(mode, { ...result, sessionId: result.sessionId ?? sessionId });
+    }
+    if (result.status === "failed") {
+      process.exit(1);
+    }
+  } catch (err) {
+    progress.fail("Failed");
+    if (err instanceof CliError) {
+      if (mode === "pretty") {
+        printError(err.message);
+      } else {
+        outputError(mode, { code: err.code, message: err.message });
+      }
+      process.exit(err.exitCode);
+    }
+    throw err;
+  }
+});
+function printArtifactStatus(sessionId, result) {
+  console.log();
+  if (result.status === "ready") {
+    printSuccess("Ready!");
+  } else if (result.status === "failed") {
+    printError(`Generation failed: ${result.error ?? "no reason given"}`);
+  }
+  printKeyValue("Session ID", result.sessionId ?? sessionId);
+  printKeyValue("Status", result.status ?? "unknown");
+  if (result.name) printKeyValue("Name", result.name);
+  if (result.status === "generating" && result.progress !== void 0) {
+    printKeyValue("Progress", `${result.progress}%`);
+  }
+  if (result.artifactUrl) {
+    printKeyValue("Your artifact", chalk5.cyan.underline(result.artifactUrl));
+  }
+  if (result.playgroundUrl) {
+    printKeyValue("Edit in Playground", chalk5.cyan.underline(result.playgroundUrl));
+  }
+  if (result.nextStep) {
+    console.log();
+    console.log(`  Still generating \u2014 run this again with --wait to keep waiting.`);
+  }
+  console.log();
+}
+
 // src/commands/publish.ts
-import { Command as Command3 } from "commander";
-var publishCommand = new Command3("publish").description("Deploy an artifact's app to a live public URL (1-3 min)").argument("<sessionId>", "Session ID from create command").option("--json", "Output as JSON").option("--verbose", "Show progress on stderr").option("--api-url <url>", "API base URL (overrides config / ANIMA_API_URL)").option("--log-file <path>", "Append a JSON debug log of each step to this file").action(async (sessionId, opts) => {
+import { Command as Command6 } from "commander";
+var publishCommand = new Command6("publish").summary("Deploy to a public live URL (only when asked)").description("Deploy an artifact's app to a live public URL (1-3 min)").argument("<sessionId>", "Session ID from create command").option("--json", "Output as JSON").option("--verbose", "Show progress on stderr").option("--api-url <url>", "API base URL (overrides config / ANIMA_API_URL)").option("--log-file <path>", "Append a JSON debug log of each step to this file").action(async (sessionId, opts) => {
   const mode = detectOutputMode(opts);
   initLogger(opts.logFile);
   const progress = new ProgressReporter(mode, opts.verbose);
@@ -1245,7 +1590,7 @@ var publishCommand = new Command3("publish").description("Deploy an artifact's a
 });
 
 // src/commands/codegen.ts
-import { Command as Command4 } from "commander";
+import { Command as Command7 } from "commander";
 
 // src/utils/files.ts
 import fs4 from "fs";
@@ -1273,7 +1618,7 @@ function writeFilesToDisk(files, outputDir) {
 }
 
 // src/commands/codegen.ts
-var codegenCommand = new Command4("codegen").description("Convert Figma design to code files (no artifact)").requiredOption("--file-key <key>", "Figma file key or URL").option("--nodes <nodes>", "Figma node IDs, comma-separated").option("--figma-token <token>", "Figma personal access token (or set FIGMA_TOKEN env var)").option("-o, --output <dir>", "Output directory", "./generated").option("--framework <fw>", "react | html", "react").option("--styling <style>", "tailwind | plain_css", "tailwind").option("--language <lang>", "typescript | javascript").option("--ui-library <lib>", "mui | antd | shadcn | clean_react").option("--json", "Output as JSON").option("--timeout <ms>", "Timeout in milliseconds", "600000").option("--verbose", "Show progress on stderr").option("--api-url <url>", "API base URL (overrides config / ANIMA_API_URL)").option("--log-file <path>", "Append a JSON debug log of each step to this file").action(async (opts) => {
+var codegenCommand = new Command7("codegen").summary("Convert a Figma design to local code files").description("Convert Figma design to code files (no artifact)").requiredOption("--file-key <key>", "Figma file key or URL").option("--nodes <nodes>", "Figma node IDs, comma-separated").option("--figma-token <token>", "Figma personal access token (or set FIGMA_TOKEN env var)").option("-o, --output <dir>", "Output directory", "./generated").option("--framework <fw>", "react | html", "react").option("--styling <style>", "tailwind | plain_css", "tailwind").option("--language <lang>", "typescript | javascript").option("--ui-library <lib>", "mui | antd | shadcn | clean_react").option("--json", "Output as JSON").option("--timeout <ms>", "Timeout in milliseconds", "600000").option("--verbose", "Show progress on stderr").option("--api-url <url>", "API base URL (overrides config / ANIMA_API_URL)").option("--log-file <path>", "Append a JSON debug log of each step to this file").action(async (opts) => {
   const mode = detectOutputMode(opts);
   initLogger(opts.logFile);
   const progress = new ProgressReporter(mode, opts.verbose);
@@ -1345,8 +1690,8 @@ var codegenCommand = new Command4("codegen").description("Convert Figma design t
 });
 
 // src/commands/getGitToken.ts
-import { Command as Command5 } from "commander";
-import chalk4 from "chalk";
+import { Command as Command8 } from "commander";
+import chalk6 from "chalk";
 
 // src/utils/gitToken.ts
 function preview(payload) {
@@ -1375,17 +1720,29 @@ function parseGitTokenResponse(payload) {
   return {
     gitRemoteUrl: body.gitRemoteUrl,
     access: body.access === "rw" ? "rw" : "ro",
-    expiresAt: body.expiresAt
+    expiresAt: body.expiresAt,
+    ...commitAuthorOf(body.commitAuthor) ? { commitAuthor: commitAuthorOf(body.commitAuthor) } : {}
   };
 }
+function commitAuthorOf(value) {
+  if (!value || typeof value.name !== "string" || typeof value.email !== "string") return void 0;
+  if (!value.name || !value.email) return void 0;
+  return { name: value.name, email: value.email };
+}
+function shellQuote(value) {
+  return `'${value.replace(/'/g, `'"'"'`)}'`;
+}
+function gitConfigCommands(commitAuthor) {
+  return `git config user.name ${shellQuote(commitAuthor.name)} && git config user.email ${shellQuote(commitAuthor.email)}`;
+}
 
 // src/commands/getGitToken.ts
-var getGitTokenCommand = new Command5("get-git-token").description("Mint a short-lived git remote URL for an artifact (clone/push with git)").argument("<artifactUrl>", "Artifact URL or session ID").option("--json", "Output as JSON").option("--verbose", "Show progress on stderr").option("--api-url <url>", "API base URL (overrides config / ANIMA_API_URL)").option("--log-file <path>", "Append a JSON debug log of each step to this file").action(async (artifactUrl, opts) => {
+var getGitTokenCommand = new Command8("get-git-token").summary("Mint git access to an artifact's repository").description("Mint a short-lived git remote URL for an artifact (clone/push with git)").argument("<artifactUrl>", "Artifact URL or session ID").option("--json", "Output as JSON").option("--verbose", "Show progress on stderr").option("--api-url <url>", "API base URL (overrides config / ANIMA_API_URL)").option("--log-file <path>", "Append a JSON debug log of each step to this file").action(async (artifactUrl, opts) => {
   const mode = detectOutputMode(opts);
   initLogger(opts.logFile);
   const progress = new ProgressReporter(mode, opts.verbose);
   try {
-    const sessionId = parsePlaygroundUrl(artifactUrl);
+    const sessionId = parseArtifactUrl(artifactUrl);
     const auth = await resolveAuth(opts.apiUrl);
     progress.start("Requesting git access...");
     const response = await withMcp(
@@ -1397,9 +1754,14 @@ var getGitTokenCommand = new Command5("get-git-token").description("Mint a short
     progress.succeed(`Git access granted (${grant.access === "rw" ? "read-write" : "read-only"})`);
     if (mode === "pretty") {
       console.log();
-      console.log(`  ${chalk4.cyan(`git clone ${grant.gitRemoteUrl}`)}`);
+      console.log(`  ${chalk6.cyan(`git clone ${grant.gitRemoteUrl}`)}`);
       console.log();
       if (grant.access === "rw") {
+        if (grant.commitAuthor) {
+          console.log("  In the clone, set who your commits are from:");
+          console.log(`    ${chalk6.cyan(gitConfigCommands(grant.commitAuthor))}`);
+          console.log();
+        }
         console.log("  Commit and push to update the live artifact.");
       } else {
         console.log("  Read-only: cloning works, pushing will be rejected.");
@@ -1407,7 +1769,7 @@ var getGitTokenCommand = new Command5("get-git-token").description("Mint a short
       if (grant.expiresAt) {
         console.log(
           `  The URL embeds a token that expires at ${grant.expiresAt} and cannot be renewed;
-  re-run this command and ${chalk4.cyan("git remote set-url origin <new url>")} to keep pushing.`
+  re-run this command and ${chalk6.cyan("git remote set-url origin <new url>")} to keep pushing.`
         );
       }
       console.log("  Treat the URL as a secret \u2014 it grants access to this artifact.");
@@ -1418,7 +1780,11 @@ var getGitTokenCommand = new Command5("get-git-token").description("Mint a short
         sessionId,
         gitRemoteUrl: grant.gitRemoteUrl,
         access: grant.access,
-        expiresAt: grant.expiresAt
+        expiresAt: grant.expiresAt,
+        ...grant.commitAuthor ? {
+          commitAuthor: grant.commitAuthor,
+          gitConfigCommand: gitConfigCommands(grant.commitAuthor)
+        } : {}
       });
     }
   } catch (err) {
@@ -1436,11 +1802,11 @@ var getGitTokenCommand = new Command5("get-git-token").description("Mint a short
 });
 
 // src/commands/mcpConfig.ts
-import { Command as Command7 } from "commander";
+import { Command as Command10 } from "commander";
 
 // src/commands/login.ts
-import { Command as Command6 } from "commander";
-import chalk5 from "chalk";
+import { Command as Command9 } from "commander";
+import chalk7 from "chalk";
 import open from "open";
 
 // src/auth/device.ts
@@ -1630,7 +1996,7 @@ function resolveDeadline(claimableUntil, now) {
 }
 
 // src/commands/login.ts
-var loginCommand = new Command6("login").description("Log in via the device flow, redeem an invite with --invite, or finish an anonymous create with --handoff").option("--invite <url-or-code>", "Redeem an invite link (\u2026/invite/<code>.md) or bare code \u2014 no approval step").option(
+var loginCommand = new Command9("login").summary("Connect this machine as a scoped agent identity").description("Log in via the device flow, redeem an invite with --invite, or finish an anonymous create with --handoff").option("--invite <url-or-code>", "Redeem an invite link (\u2026/invite/<code>.md) or bare code \u2014 no approval step").option(
   "--handoff [token]",
   "Log in with the handoff token from an anonymous create. Waits until a human claims the artifact. Defaults to your last one"
 ).option("--client-name <name>", "How this CLI appears on the consent screen", "AgentGrid CLI").option("--no-open", "Do not try to open the verification page in a browser").option("--json", "Output as JSON").option("--api-url <url>", "API base URL (overrides config / ANIMA_API_URL)").option("--log-file <path>", "Append a JSON debug log of each step to this file").option(
@@ -1700,9 +2066,9 @@ var loginCommand = new Command6("login").description("Log in via the device flow
           console.log();
           printInfo("To connect, open the verification page and enter this code:");
           console.log();
-          console.log(`    ${chalk5.cyan.underline(info.verificationUri)}`);
+          console.log(`    ${chalk7.cyan.underline(info.verificationUri)}`);
           console.log();
-          console.log(`    ${chalk5.bold.white(info.userCode)}`);
+          console.log(`    ${chalk7.bold.white(info.userCode)}`);
           console.log();
           printInfo(`Waiting for approval\u2026 (code expires in ${Math.round(info.expiresInSeconds / 60)} minutes)`);
         } else {
@@ -1779,7 +2145,7 @@ async function runHandoffLogin(opts, mode) {
       printInfo("Waiting for a human to claim the artifact:");
       if (pending.artifactUrl) {
         console.log();
-        console.log(`    ${chalk5.cyan.underline(pending.artifactUrl)}`);
+        console.log(`    ${chalk7.cyan.underline(pending.artifactUrl)}`);
       }
       console.log();
       printInfo(
@@ -1854,7 +2220,7 @@ function buildMcpConfig(apiUrl) {
 }
 
 // src/commands/mcpConfig.ts
-var mcpConfigCommand = new Command7("mcp-config").description("Print an MCP server config for your MCP client").option("--json", "Output as JSON").option("--api-url <url>", "API base URL (overrides config / ANIMA_API_URL)").action(async (opts) => {
+var mcpConfigCommand = new Command10("mcp-config").summary("Print an MCP server config for your MCP client").description("Print an MCP server config for your MCP client").option("--json", "Output as JSON").option("--api-url <url>", "API base URL (overrides config / ANIMA_API_URL)").action(async (opts) => {
   const mode = detectOutputMode(opts);
   try {
     const mcpConfig = buildMcpConfig(resolveApiUrl(opts.apiUrl));
@@ -1881,8 +2247,8 @@ var mcpConfigCommand = new Command7("mcp-config").description("Print an MCP serv
 });
 
 // src/commands/auth.ts
-import { Command as Command8 } from "commander";
-import chalk6 from "chalk";
+import { Command as Command11 } from "commander";
+import chalk8 from "chalk";
 var DEFAULT_API_URL2 = "https://api.agentgrid.io";
 function describePendingHandoff(pending, state) {
   return {
@@ -1900,10 +2266,10 @@ function printPendingHandoff(pending, state) {
     return;
   }
   printInfo(`Anonymous artifact ${pending.sessionId} is awaiting a claim (until ${pending.claimableUntil}):`);
-  console.log(`    ${chalk6.cyan.underline(pending.artifactUrl)}`);
-  console.log(`  Run ${chalk6.cyan("anima login --handoff")} to wait for it.`);
+  console.log(`    ${chalk8.cyan.underline(pending.artifactUrl)}`);
+  console.log(`  Run ${chalk8.cyan("anima login --handoff")} to wait for it.`);
 }
-var authCommand = new Command8("auth").description("Manage authentication").option("--token <token>", "Store AgentGrid API token").option("--figma-token <token>", "Store Figma personal access token").option("--team-id <teamId>", "Team ID to associate with token").option("--status", "Show current auth status").option("--logout", "Clear stored credentials (alias for `anima logout`)").option("--json", "Output as JSON").option("--api-url <url>", "API base URL", DEFAULT_API_URL2).action(async (opts) => {
+var authCommand = new Command11("auth").summary("Inspect or manage stored credentials").description("Manage authentication").option("--token <token>", "Store AgentGrid API token").option("--figma-token <token>", "Store Figma personal access token").option("--team-id <teamId>", "Team ID to associate with token").option("--status", "Show current auth status").option("--logout", "Clear stored credentials (alias for `anima logout`)").option("--json", "Output as JSON").option("--api-url <url>", "API base URL", DEFAULT_API_URL2).action(async (opts) => {
   const mode = detectOutputMode(opts);
   try {
     if (opts.token || opts.figmaToken) {
@@ -2003,13 +2369,13 @@ var authCommand = new Command8("auth").description("Manage authentication").opti
     if (mode === "pretty") {
       console.log();
       printInfo("Auth commands:");
-      console.log(`  ${chalk6.cyan("anima login")}                    Log in (device flow \u2014 approve on any browser)`);
-      console.log(`  ${chalk6.cyan("anima login --handoff")}          Wait for a human to claim your anonymous artifact`);
-      console.log(`  ${chalk6.cyan("anima logout")}                   Clear all credentials`);
-      console.log(`  ${chalk6.cyan("anima auth --status")}            Check auth status`);
-      console.log(`  ${chalk6.cyan("anima auth --figma-token <T>")}   Save Figma token (needed for codegen/f2c)`);
+      console.log(`  ${chalk8.cyan("anima login")}                    Log in (device flow \u2014 approve on any browser)`);
+      console.log(`  ${chalk8.cyan("anima login --handoff")}          Wait for a human to claim your anonymous artifact`);
+      console.log(`  ${chalk8.cyan("anima logout")}                   Clear all credentials`);
+      console.log(`  ${chalk8.cyan("anima auth --status")}            Check auth status`);
+      console.log(`  ${chalk8.cyan("anima auth --figma-token <T>")}   Save Figma token (needed for codegen/f2c)`);
       console.log();
-      console.log(`  Figma token: ${chalk6.cyan.underline("https://www.figma.com")} > Settings > Personal access tokens`);
+      console.log(`  Figma token: ${chalk8.cyan.underline("https://www.figma.com")} > Settings > Personal access tokens`);
       console.log();
     } else {
       outputResult(mode, {
@@ -2031,8 +2397,8 @@ var authCommand = new Command8("auth").description("Manage authentication").opti
 });
 
 // src/commands/logout.ts
-import { Command as Command9 } from "commander";
-var logoutCommand = new Command9("logout").description("Clear all stored credentials (AgentGrid + Figma tokens) from this machine").option("--json", "Output as JSON").option("--api-url <url>", "API base URL (overrides config / ANIMA_API_URL)").action(async (opts) => {
+import { Command as Command12 } from "commander";
+var logoutCommand = new Command12("logout").summary("Disconnect: revoke and clear every stored credential").description("Clear all stored credentials (AgentGrid + Figma tokens) from this machine").option("--json", "Output as JSON").option("--api-url <url>", "API base URL (overrides config / ANIMA_API_URL)").action(async (opts) => {
   const mode = detectOutputMode(opts);
   const revoked = await revokeStoredRefreshToken(resolveApiUrl(opts.apiUrl));
   const hadCredentials = clearStorage();
@@ -2050,8 +2416,8 @@ var logoutCommand = new Command9("logout").description("Clear all stored credent
 });
 
 // src/commands/unpublish.ts
-import { Command as Command10 } from "commander";
-var unpublishCommand = new Command10("unpublish").description("Take a published artifact offline (clears its live URL; code and artifact stay intact)").argument("<sessionId>", "Session ID of the published artifact").option("--json", "Output as JSON").option("--verbose", "Show progress on stderr").option("--api-url <url>", "API base URL (overrides config / ANIMA_API_URL)").option("--log-file <path>", "Append a JSON debug log of each step to this file").action(async (sessionId, opts) => {
+import { Command as Command13 } from "commander";
+var unpublishCommand = new Command13("unpublish").summary("Take a published artifact offline").description("Take a published artifact offline (clears its live URL; code and artifact stay intact)").argument("<sessionId>", "Session ID of the published artifact").option("--json", "Output as JSON").option("--verbose", "Show progress on stderr").option("--api-url <url>", "API base URL (overrides config / ANIMA_API_URL)").option("--log-file <path>", "Append a JSON debug log of each step to this file").action(async (sessionId, opts) => {
   const mode = detectOutputMode(opts);
   initLogger(opts.logFile);
   const progress = new ProgressReporter(mode, opts.verbose);
@@ -2086,8 +2452,8 @@ var unpublishCommand = new Command10("unpublish").description("Take a published
 });
 
 // src/commands/update.ts
-import { Command as Command11 } from "commander";
-var updateCommand = new Command11("update").description("Update an artifact's metadata: display name and/or visibility (never touches code)").argument("<sessionId>", "Session ID of the artifact").option("--name <name>", "New display name").option("--privacy <privacy>", "public (anyone with the link) | private (team only)").option("--json", "Output as JSON").option("--verbose", "Show progress on stderr").option("--api-url <url>", "API base URL (overrides config / ANIMA_API_URL)").option("--log-file <path>", "Append a JSON debug log of each step to this file").action(async (sessionId, opts) => {
+import { Command as Command14 } from "commander";
+var updateCommand = new Command14("update").summary("Rename an artifact or change its visibility").description("Update an artifact's metadata: display name and/or visibility (never touches code)").argument("<sessionId>", "Session ID of the artifact").option("--name <name>", "New display name").option("--privacy <privacy>", "public (anyone with the link) | private (team only)").option("--json", "Output as JSON").option("--verbose", "Show progress on stderr").option("--api-url <url>", "API base URL (overrides config / ANIMA_API_URL)").option("--log-file <path>", "Append a JSON debug log of each step to this file").action(async (sessionId, opts) => {
   const mode = detectOutputMode(opts);
   initLogger(opts.logFile);
   const progress = new ProgressReporter(mode, opts.verbose);
@@ -2132,8 +2498,8 @@ var updateCommand = new Command11("update").description("Update an artifact's me
 });
 
 // src/commands/config.ts
-import { Command as Command12 } from "commander";
-var configCommand = new Command12("config").description(
+import { Command as Command15 } from "commander";
+var configCommand = new Command15("config").summary("Store CLI preferences (e.g. a default API URL)").description(
   `Store CLI preferences (keys: ${configKeys().join(", ")})`
 );
 configCommand.command("set <key> <value>").description("Set a config value").option("--json", "Output as JSON").action((key, value, opts) => {
@@ -2199,27 +2565,34 @@ function assertUrl(value) {
 }
 
 // src/commands/duplicate.ts
-import { Command as Command13 } from "commander";
-import chalk7 from "chalk";
-function buildDuplicateArgs(artifactUrl, name) {
-  const sessionId = parsePlaygroundUrl(artifactUrl);
+import { Command as Command16 } from "commander";
+import chalk9 from "chalk";
+function buildDuplicateArgs(artifactUrl, name, workspaceId) {
+  const sessionId = parseArtifactUrl(artifactUrl);
   if (!sessionId) {
     throw validationError("A source artifact URL or session ID is required");
   }
   if (name !== void 0 && (name.length === 0 || name.length > 120)) {
     throw validationError("--name must be between 1 and 120 characters");
   }
-  return { sessionId, ...name !== void 0 ? { name } : {} };
+  return {
+    sessionId,
+    ...name !== void 0 ? { name } : {},
+    ...workspaceFlag(workspaceId) !== void 0 ? { workspaceId } : {}
+  };
 }
 function createDuplicateCommand() {
-  return new Command13("duplicate").description(
+  return new Command16("duplicate").summary("Copy an artifact into a new, independent one").description(
     "Duplicate an artifact into a new, independent artifact. Copies code, assets, and supported database content; chat and custom domains are not copied. Duplication is non-idempotent: if a request times out or its response is lost, list recent artifacts before retrying because the first request may already have created the copy."
-  ).argument("<artifactUrl>", "Source artifact URL or session ID").option("--name <name>", "Display name for the duplicate (defaults to '<source name> (Copy)')").option("--json", "Output as JSON").option("--verbose", "Show progress on stderr").option("--api-url <url>", "API base URL (overrides config / ANIMA_API_URL)").option("--log-file <path>", "Append a JSON debug log of each step to this file").action(async (artifactUrl, opts) => {
+  ).argument("<artifactUrl>", "Source artifact URL or session ID").option("--name <name>", "Display name for the duplicate (defaults to '<source name> (Copy)')").option(
+    "-w, --workspace <id>",
+    "The workspace to put the copy in (id from `anima workspaces`). Optional when you can create in only one workspace; otherwise required, since there is no default"
+  ).option("--json", "Output as JSON").option("--verbose", "Show progress on stderr").option("--api-url <url>", "API base URL (overrides config / ANIMA_API_URL)").option("--log-file <path>", "Append a JSON debug log of each step to this file").action(async (artifactUrl, opts) => {
     const mode = detectOutputMode(opts);
     initLogger(opts.logFile);
     const progress = new ProgressReporter(mode, opts.verbose);
     try {
-      const args = buildDuplicateArgs(artifactUrl, opts.name);
+      const args = buildDuplicateArgs(artifactUrl, opts.name, opts.workspace);
       const auth = await resolveAuth(opts.apiUrl);
       progress.start("Duplicating artifact...");
       const result = await withMcp(
@@ -2227,7 +2600,7 @@ function createDuplicateCommand() {
         (client) => client.callTool("artifact-duplicate", args)
       );
       if (!result.success) {
-        throw apiError(result.reason || result.error || "Artifact duplication failed", result);
+        throw apiError(result.message || result.reason || result.error || "Artifact duplication failed", result);
       }
       progress.succeed("Artifact duplicated");
       if (mode === "pretty") {
@@ -2236,8 +2609,13 @@ function createDuplicateCommand() {
         printKeyValue("Name", result.name);
         printKeyValue("Session ID", result.sessionId);
         printKeyValue("Source session", result.sourceSessionId);
-        printKeyValue("Artifact", chalk7.cyan.underline(result.playgroundUrl));
-        printKeyValue("Preview", chalk7.cyan.underline(result.previewUrl));
+        printKeyValue("Artifact", chalk9.cyan.underline(result.artifactUrl));
+        if (result.playgroundUrl) {
+          printKeyValue("Edit in Playground", chalk9.cyan.underline(result.playgroundUrl));
+        }
+        if (result.previewUrl) {
+          printKeyValue("Preview", chalk9.cyan.underline(result.previewUrl));
+        }
         printKeyValue("Next steps", result.nextSteps);
         console.log();
       } else {
@@ -2259,70 +2637,808 @@ function createDuplicateCommand() {
 }
 var duplicateCommand = createDuplicateCommand();
 
+// src/commands/explore.ts
+import { Command as Command17 } from "commander";
+import chalk10 from "chalk";
+
+// src/api/tool.ts
+async function runTool(toolName, args, options = {}) {
+  const auth = await resolveAuth(options.apiUrl);
+  const result = await withMcp(
+    {
+      apiBaseUrl: resolveApiUrl(options.apiUrl),
+      token: auth.token,
+      teamId: auth.teamId,
+      ...options.figmaToken ? { figmaToken: options.figmaToken } : {}
+    },
+    (client) => client.callTool(toolName, args, options.call)
+  );
+  if (result.success === false) {
+    throw apiError(describeFailure(result), result);
+  }
+  return result;
+}
+function describeFailure(result) {
+  const base = typeof result.error === "object" && result.error ? result.error.message || result.error.code || "The tool reported a failure" : result.reason || result.error || "The tool reported a failure";
+  const nextSteps = Array.isArray(result.nextSteps) ? result.nextSteps.join("\n") : result.nextSteps;
+  return nextSteps ? `${base}
+${nextSteps}` : base;
+}
+
+// src/commands/explore.ts
+var exploreCommand = new Command17("explore").summary("Read an artifact's files: list, search, read, history").description(
+  "Inspect an artifact's files without git: list them (--tree), search them (--search), read them (--read), or show commits (--history)."
+).argument("<artifactUrl>", "Artifact URL or session ID").option("--tree", "List file paths").option("--search <query>", "Find text inside files \u2014 start here when you don't know the file").option("--read <paths...>", "Return the contents of these files").option("--history", "List commits, newest first").option("--path <prefix>", "tree/search: a literal directory prefix (not a glob)").option("--range <start,end>", "read: line window, 1-based inclusive, for a single file").option("--revision <rev>", "Look at the artifact as it was at this commit").option("--regex", "search: treat the query as a JavaScript regular expression").option("--case-sensitive", "search: match case exactly").option("--include-excluded", "tree/search: also look inside node_modules, dist and build").option("--limit <n>", "tree/search/history: maximum rows to return").option("--cursor <cursor>", "history: continue after a previous response's nextCursor").option("--json", "Output as JSON").option("--api-url <url>", "API base URL (overrides config / ANIMA_API_URL)").option("--log-file <path>", "Append a JSON debug log of each step to this file").action(async (artifactUrl, opts) => {
+  const mode = detectOutputMode(opts);
+  initLogger(opts.logFile);
+  await withCommandErrors(mode, async () => {
+    const sessionId = parseArtifactUrl(artifactUrl);
+    const args = buildExploreArgs(sessionId, opts);
+    const result = await runTool("artifact-explore", args, { apiUrl: opts.apiUrl });
+    if (mode === "pretty") {
+      printExplore(args.action, result);
+    } else {
+      outputResult(mode, result);
+    }
+  });
+});
+function buildExploreArgs(sessionId, opts) {
+  const chosen = [
+    opts.tree ? "tree" : null,
+    opts.search ? "search" : null,
+    opts.read ? "read" : null,
+    opts.history ? "history" : null
+  ].filter(Boolean);
+  if (chosen.length !== 1) {
+    throw validationError(
+      "Pass exactly one of --tree, --search <query>, --read <paths...> or --history. Not sure which file to change? Start with --search."
+    );
+  }
+  const action = chosen[0];
+  const args = { sessionId, action };
+  if (opts.revision) args.revision = opts.revision;
+  if (opts.limit !== void 0) args.limit = parseLimit(opts.limit);
+  switch (action) {
+    case "tree":
+      if (opts.path) args.path = opts.path;
+      if (opts.includeExcluded) args.includeExcluded = true;
+      break;
+    case "search":
+      args.query = opts.search;
+      if (opts.path) args.path = opts.path;
+      if (opts.regex) args.regex = true;
+      if (opts.caseSensitive) args.caseSensitive = true;
+      if (opts.includeExcluded) args.includeExcluded = true;
+      break;
+    case "read": {
+      const paths = opts.read;
+      args.paths = paths;
+      if (opts.range) {
+        if (paths.length !== 1) {
+          throw validationError("--range applies to a single file; pass one path to --read.");
+        }
+        args.range = opts.range;
+      }
+      break;
+    }
+    case "history":
+      if (opts.cursor) args.cursor = opts.cursor;
+      break;
+  }
+  return args;
+}
+function parseLimit(value) {
+  const limit = Number(value);
+  if (!Number.isInteger(limit) || limit < 1) {
+    throw validationError(`--limit must be a positive whole number (got "${value}").`);
+  }
+  return limit;
+}
+function printExplore(action, result) {
+  console.log();
+  if (action === "tree") {
+    for (const file of result.files ?? []) {
+      const kind = result.unwritable?.[file];
+      console.log(`  ${file}${kind ? chalk10.gray(` (${kind} \u2014 git only)`) : ""}`);
+    }
+    if (result.matchedFiles !== void 0) {
+      console.log();
+      console.log(chalk10.gray(`  ${(result.files ?? []).length} of ${result.matchedFiles} shown`));
+    }
+  } else if (action === "search") {
+    for (const match of result.matches ?? []) {
+      console.log(`  ${chalk10.cyan(match.path)}:${match.line}  ${match.lineText.trim()}`);
+    }
+    if (!result.matches?.length) {
+      console.log("  No matches.");
+      const skipped = result.notSearched;
+      if (skipped?.excluded) {
+        console.log(
+          chalk10.yellow(
+            `  ${skipped.excluded} files were skipped (node_modules, dist, build) \u2014 retry with --include-excluded.`
+          )
+        );
+      }
+      if (skipped?.assets) {
+        console.log(chalk10.gray(`  ${skipped.assets} binary files cannot match a text query.`));
+      }
+    }
+  } else if (action === "read") {
+    for (const file of result.files ?? []) {
+      console.log(chalk10.bold(`  ${file.path}`));
+      if (file.asset) {
+        console.log(chalk10.gray(`    binary \u2014 ${file.size ?? "?"} bytes, ${file.mime ?? "unknown type"}`));
+      } else if (file.deferred) {
+        console.log(chalk10.yellow("    not returned: the response ran out of budget \u2014 read it on its own"));
+      } else {
+        console.log(file.content ?? "");
+        if (file.truncated) {
+          console.log(
+            chalk10.yellow(
+              `    lines ${file.startLine}-${file.endLine} of ${file.totalLines} \u2014 read the rest with --range`
+            )
+          );
+        }
+      }
+      console.log();
+    }
+    for (const missing of result.missingPaths ?? []) {
+      const near = result.suggestions?.[missing];
+      console.log(chalk10.yellow(`  Not found: ${missing}${near?.length ? ` \u2014 did you mean ${near.join(", ")}?` : ""}`));
+    }
+  } else {
+    const commits = result.commit ? [result.commit] : result.commits ?? [];
+    for (const commit of commits) {
+      console.log(`  ${chalk10.yellow(commit.revision.slice(0, 10))}  ${commit.message.split("\n")[0]}`);
+      console.log(chalk10.gray(`    ${commit.author} \u2014 ${commit.date}`));
+    }
+    for (const changed of result.commit?.changedFiles ?? []) {
+      console.log(chalk10.gray(`      ${changed.change.padEnd(8)} ${changed.path}`));
+    }
+  }
+  if (result.truncated) {
+    console.log(chalk10.yellow("  The list was capped \u2014 raise --limit to see more."));
+  }
+  if (result.revision) {
+    console.log();
+    console.log(chalk10.gray(`  revision: ${result.revision}  (pass to \`anima edit --base-revision\`)`));
+  }
+  console.log();
+}
+
+// src/commands/edit.ts
+import { Command as Command18 } from "commander";
+import fs5 from "fs";
+import chalk11 from "chalk";
+var editCommand = new Command18("edit").summary("Change an artifact's files and commit them").description(
+  "Change an artifact's files and commit them, without git. All changes land as one commit."
+).argument("<artifactUrl>", "Artifact URL or session ID").requiredOption("-m, --message <message>", "Commit message").option(
+  "--base-revision <rev>",
+  "The revision the edit applies to (from `anima explore`). Defaults to the artifact's current head"
+).option("--changes <json>", "The full change list as a JSON array \u2014 the general door").option("--changes-file <path>", "Read that JSON array from a file").option("--write <path>", "Shorthand: create or replace this file").option("--from-file <path>", "--write: take the content from this local file (default: stdin is not read)").option("--content <text>", "--write: the file's complete new content").option("--delete <path>", "Shorthand: delete this file").option("--move <path>", "Shorthand: rename this file (needs --to)").option("--to <path>", "--move: the new path").option("--replace <path>", "Shorthand: swap an exact snippet in this file (needs --old and --new)").option("--old <text>", "--replace: the exact text to replace").option("--new <text>", "--replace: the replacement text").option("--all", "--replace: replace every occurrence instead of requiring exactly one").option("--json", "Output as JSON").option("--api-url <url>", "API base URL (overrides config / ANIMA_API_URL)").option("--log-file <path>", "Append a JSON debug log of each step to this file").action(async (artifactUrl, opts) => {
+  const mode = detectOutputMode(opts);
+  initLogger(opts.logFile);
+  await withCommandErrors(mode, async () => {
+    const sessionId = parseArtifactUrl(artifactUrl);
+    const changes = buildChanges(opts);
+    const baseRevision = opts.baseRevision ?? await currentRevision(sessionId, opts.apiUrl);
+    const result = await runTool(
+      "artifact-edit",
+      { sessionId, baseRevision, commitMessage: opts.message, changes },
+      { apiUrl: opts.apiUrl }
+    );
+    if (mode === "pretty") {
+      console.log();
+      printSuccess("Committed.");
+      for (const changed of result.changedFiles ?? []) {
+        const detail = changed.op === "move" ? `${changed.fromPath} \u2192 ${changed.path}` : changed.replacements !== void 0 ? `${changed.path} (${changed.replacements} replaced)` : changed.path;
+        console.log(`  ${chalk11.gray(changed.op.padEnd(12))} ${detail}`);
+      }
+      console.log();
+      printKeyValue("Revision", result.revision ?? "unknown");
+      console.log();
+      console.log("  The live artifact reflects this commit.");
+      console.log();
+    } else {
+      outputResult(mode, result);
+    }
+  });
+});
+async function currentRevision(sessionId, apiUrl) {
+  const result = await runTool(
+    "artifact-explore",
+    { sessionId, action: "tree", limit: 1 },
+    { apiUrl }
+  );
+  if (!result.revision) {
+    throw validationError(
+      "Could not read the artifact's current revision. Pass --base-revision from `anima explore`."
+    );
+  }
+  return result.revision;
+}
+function buildChanges(opts) {
+  const explicit = opts.changes ?? opts.changesFile;
+  const shorthands = [opts.write, opts.delete, opts.move, opts.replace].filter(Boolean);
+  if (explicit && shorthands.length) {
+    throw validationError(
+      "--changes/--changes-file already carries the whole change list; drop the --write/--delete/--move/--replace shorthand."
+    );
+  }
+  if (explicit) {
+    const raw = opts.changesFile ? readFile(opts.changesFile) : opts.changes;
+    return parseChanges(raw);
+  }
+  if (shorthands.length !== 1) {
+    throw validationError(
+      "Nothing to change. Pass --changes <json> (or --changes-file), or exactly one of --write <path>, --delete <path>, --move <path> --to <path>, --replace <path> --old <text> --new <text>."
+    );
+  }
+  if (opts.write) {
+    if (opts.content === void 0 && !opts.fromFile) {
+      throw validationError("--write needs the file's content: pass --content <text> or --from-file <path>.");
+    }
+    if (opts.content !== void 0 && opts.fromFile) {
+      throw validationError("Pass either --content or --from-file for --write, not both.");
+    }
+    return [
+      {
+        op: "write",
+        path: opts.write,
+        content: opts.fromFile ? readFile(opts.fromFile) : opts.content
+      }
+    ];
+  }
+  if (opts.delete) {
+    return [{ op: "delete", path: opts.delete }];
+  }
+  if (opts.move) {
+    if (!opts.to) throw validationError("--move needs --to <path>, the new path.");
+    return [{ op: "move", fromPath: opts.move, toPath: opts.to }];
+  }
+  if (opts.old === void 0 || opts.new === void 0) {
+    throw validationError('--replace needs --old <text> and --new <text>. Pass --new "" to delete the snippet.');
+  }
+  return [
+    {
+      op: "str_replace",
+      path: opts.replace,
+      oldText: opts.old,
+      newText: opts.new,
+      ...opts.all ? { replaceAll: true } : {}
+    }
+  ];
+}
+function parseChanges(raw) {
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch (err) {
+    throw validationError(`--changes is not valid JSON: ${err.message}`);
+  }
+  if (!Array.isArray(parsed) || parsed.length === 0) {
+    throw validationError("--changes must be a non-empty JSON array of change objects.");
+  }
+  return parsed;
+}
+function readFile(path7) {
+  try {
+    return fs5.readFileSync(path7, "utf-8");
+  } catch (err) {
+    throw validationError(`Could not read ${path7}: ${err.message}`);
+  }
+}
+
+// src/commands/uploadAsset.ts
+import { Command as Command19 } from "commander";
+import fs6 from "fs";
+import path5 from "path";
+import chalk12 from "chalk";
+var uploadAssetCommand = new Command19("upload-asset").summary("Add an image, font or media file over 256 KB").description(
+  "Add a large image, font or media file (over 256 KB) to an artifact: stage it, upload it, and commit it at --path."
+).argument("<artifactUrl>", "Artifact URL or session ID").argument("<file>", "Local file to upload").option(
+  "--path <path>",
+  "Where the asset lands in the artifact (e.g. public/hero.png). Omit to stage only and print the assetUploadId"
+).option("-m, --message <message>", "Commit message for the write").option("--base-revision <rev>", "The revision the commit applies to. Defaults to the current head").option("--json", "Output as JSON").option("--verbose", "Show progress on stderr").option("--api-url <url>", "API base URL (overrides config / ANIMA_API_URL)").option("--log-file <path>", "Append a JSON debug log of each step to this file").action(async (artifactUrl, file, opts) => {
+  const mode = detectOutputMode(opts);
+  initLogger(opts.logFile);
+  const progress = new ProgressReporter(mode, opts.verbose);
+  await withCommandErrors(mode, async () => {
+    const sessionId = parseArtifactUrl(artifactUrl);
+    const bytes = readAsset(file);
+    progress.start("Staging the upload...");
+    const grant = await runTool(
+      "artifact-get_asset_upload_url",
+      { sessionId, filename: path5.basename(file) },
+      { apiUrl: opts.apiUrl }
+    );
+    if (!grant.uploadUrl || !grant.uploadFields || !grant.assetUploadId) {
+      throw apiError("The staging response carried no upload URL.", grant);
+    }
+    if (grant.maxBytes !== void 0 && bytes.byteLength > grant.maxBytes) {
+      throw validationError(
+        `${file} is ${bytes.byteLength} bytes; the limit is ${grant.maxBytes}. Push it with git instead: anima get-git-token ${sessionId}`
+      );
+    }
+    progress.update("Uploading...");
+    await postAsset(grant.uploadUrl, grant.uploadFields, bytes, path5.basename(file));
+    logEvent("asset_uploaded", { sessionId, assetUploadId: grant.assetUploadId });
+    if (!opts.path) {
+      progress.succeed("Uploaded \u2014 not committed yet.");
+      if (mode === "pretty") {
+        console.log();
+        printKeyValue("assetUploadId", grant.assetUploadId);
+        console.log();
+        console.log("  Commit it where it belongs with:");
+        console.log(
+          `    ${chalk12.cyan(
+            `anima edit ${sessionId} -m "Add asset" --changes '[{"op":"write","path":"public/${path5.basename(file)}","assetUploadId":"${grant.assetUploadId}"}]'`
+          )}`
+        );
+        console.log();
+      } else {
+        outputResult(mode, {
+          success: true,
+          sessionId,
+          assetUploadId: grant.assetUploadId,
+          expiresAt: grant.expiresAt,
+          nextSteps: "Call `anima edit <artifact> --changes` with a write change carrying this assetUploadId and the path the file should live at. The id is single-use and expires."
+        });
+      }
+      return;
+    }
+    progress.update("Committing...");
+    const baseRevision = opts.baseRevision ?? await currentRevision2(sessionId, opts.apiUrl);
+    const result = await runTool(
+      "artifact-edit",
+      {
+        sessionId,
+        baseRevision,
+        commitMessage: opts.message ?? `Add ${opts.path}`,
+        changes: [{ op: "write", path: opts.path, assetUploadId: grant.assetUploadId }]
+      },
+      { apiUrl: opts.apiUrl }
+    );
+    progress.succeed("Uploaded and committed!");
+    if (mode === "pretty") {
+      console.log();
+      printSuccess(`${file} \u2192 ${opts.path}`);
+      printKeyValue("Revision", result.revision ?? "unknown");
+      console.log();
+    } else {
+      outputResult(mode, {
+        success: true,
+        sessionId,
+        path: opts.path,
+        assetUploadId: grant.assetUploadId,
+        revision: result.revision
+      });
+    }
+  });
+});
+async function postAsset(uploadUrl, uploadFields, bytes, filename) {
+  const form = new FormData();
+  for (const [key, value] of Object.entries(uploadFields)) {
+    form.append(key, value);
+  }
+  form.append("file", new Blob([new Uint8Array(bytes)]), filename);
+  const response = await fetch(uploadUrl, { method: "POST", body: form });
+  if (!response.ok) {
+    const detail = await response.text().catch(() => "");
+    throw apiError(`Asset upload failed: HTTP ${response.status}${detail ? ` \u2014 ${detail.slice(0, 300)}` : ""}`);
+  }
+}
+async function currentRevision2(sessionId, apiUrl) {
+  const result = await runTool(
+    "artifact-explore",
+    { sessionId, action: "tree", limit: 1 },
+    { apiUrl }
+  );
+  if (!result.revision) {
+    throw validationError("Could not read the artifact's current revision. Pass --base-revision.");
+  }
+  return result.revision;
+}
+function readAsset(file) {
+  try {
+    return fs6.readFileSync(file);
+  } catch (err) {
+    throw validationError(`Could not read ${file}: ${err.message}`);
+  }
+}
+
+// src/commands/delete.ts
+import { Command as Command20 } from "commander";
+var deleteCommand = new Command20("delete").summary("Delete an artifact (reversible: hidden, not erased)").description("Soft-delete an artifact only when explicitly requested (unpublish it first; content is retained)").argument("<artifactUrl>", "Artifact URL or session ID to soft-delete").option("--json", "Output as JSON").option("--verbose", "Show progress on stderr").option("--api-url <url>", "API base URL (overrides config / ANIMA_API_URL)").option("--log-file <path>", "Append a JSON debug log of each step to this file").action(async (artifactUrl, opts) => {
+  const mode = detectOutputMode(opts);
+  initLogger(opts.logFile);
+  const progress = new ProgressReporter(mode, opts.verbose);
+  try {
+    const sessionId = parseArtifactUrl(artifactUrl);
+    if (!sessionId) {
+      throw validationError("An artifact URL or session ID is required");
+    }
+    const auth = await resolveAuth(opts.apiUrl);
+    progress.start("Deleting artifact...");
+    const result = await withMcp(
+      { apiBaseUrl: resolveApiUrl(opts.apiUrl), token: auth.token, teamId: auth.teamId },
+      (client) => client.callTool("artifact-delete", { sessionId })
+    );
+    if (!result.success) {
+      throw apiError(result.message || result.reason || result.error || "Artifact deletion failed", result);
+    }
+    progress.succeed("Artifact deleted");
+    if (mode === "pretty") {
+      printSuccess(result.message || `Artifact ${sessionId} is hidden and can be restored.`);
+    } else {
+      outputResult(mode, { success: true, sessionId, ...result.message ? { message: result.message } : {} });
+    }
+  } catch (err) {
+    progress.fail("Failed");
+    if (err instanceof CliError) {
+      const detail = err.detail;
+      const code = typeof detail?.code === "string" ? detail.code : err.code;
+      if (mode === "pretty") {
+        printError(code === err.code ? err.message : `${code}: ${err.message}`);
+      } else {
+        outputError(mode, { code, message: err.message });
+      }
+      process.exit(err.exitCode);
+    }
+    throw err;
+  }
+});
+
+// src/commands/review.ts
+import { Command as Command21 } from "commander";
+import chalk13 from "chalk";
+var listSubcommand = new Command21("list").summary("Read the comments addressed to you").description("Read the review comments addressed to you, newest artifact activity first").argument("[artifactUrl]", "Limit to one artifact; omit for every review addressed to you").option("--limit <n>", "Maximum reviews to return (1-50, default 20)").option("--json", "Output as JSON").option("--api-url <url>", "API base URL (overrides config / ANIMA_API_URL)").option("--log-file <path>", "Append a JSON debug log of each step to this file").action(async (artifactUrl, opts) => {
+  const mode = detectOutputMode(opts);
+  initLogger(opts.logFile);
+  await withCommandErrors(mode, async () => {
+    const args = {};
+    if (artifactUrl) args.sessionId = parseArtifactUrl(artifactUrl);
+    if (opts.limit !== void 0) args.limit = parseLimit2(opts.limit);
+    const result = await runTool("review-list", args, { apiUrl: opts.apiUrl });
+    if (mode === "pretty") {
+      printReviews(result);
+    } else {
+      outputResult(mode, result);
+    }
+  });
+});
+var resolveSubcommand = new Command21("resolve").summary("Close one comment without a commit").description("Close one comment without a commit \u2014 for a question answered, or a change you decided against").argument("<commentId>", "Comment to close, from `anima review list`").option("--note <text>", "What to tell the reviewer as the closing message").option("--json", "Output as JSON").option("--api-url <url>", "API base URL (overrides config / ANIMA_API_URL)").option("--log-file <path>", "Append a JSON debug log of each step to this file").action(async (commentId, opts) => {
+  const mode = detectOutputMode(opts);
+  initLogger(opts.logFile);
+  await withCommandErrors(mode, async () => {
+    const result = await runTool(
+      "review-resolve",
+      { commentId, ...opts.note ? { note: opts.note } : {} },
+      { apiUrl: opts.apiUrl }
+    );
+    if (mode === "pretty") {
+      console.log();
+      if (result.resolved) printSuccess(result.message ?? "Comment resolved.");
+      else printInfo(result.message ?? "Comment was already closed.");
+      console.log();
+    } else {
+      outputResult(mode, result);
+    }
+  });
+});
+var replySubcommand = new Command21("reply").summary("Answer one comment, leaving it open").description("Say something back on one comment and LEAVE IT OPEN \u2014 to ask, report, or say you are blocked").argument("<commentId>", "Comment to reply to, from `anima review list`").requiredOption("-m, --message <message>", "What to say to the reviewer").option("--json", "Output as JSON").option("--api-url <url>", "API base URL (overrides config / ANIMA_API_URL)").option("--log-file <path>", "Append a JSON debug log of each step to this file").action(async (commentId, opts) => {
+  const mode = detectOutputMode(opts);
+  initLogger(opts.logFile);
+  await withCommandErrors(mode, async () => {
+    const result = await runTool(
+      "review-reply",
+      { commentId, message: opts.message },
+      { apiUrl: opts.apiUrl }
+    );
+    if (mode === "pretty") {
+      console.log();
+      if (result.replied) printSuccess(result.message ?? "Reply posted.");
+      else printInfo(result.message ?? "The comment is closed, so nothing was posted.");
+      console.log();
+    } else {
+      outputResult(mode, result);
+    }
+  });
+});
+var reviewCommand = new Command21("review").summary("Read and answer the comments humans addressed to you").description("Read and answer the review comments humans addressed to you (list / resolve / reply)").addCommand(listSubcommand).addCommand(resolveSubcommand).addCommand(replySubcommand);
+function parseLimit2(value) {
+  const limit = Number(value);
+  if (!Number.isInteger(limit) || limit < 1 || limit > 50) {
+    throw validationError(`--limit must be a whole number between 1 and 50 (got "${value}").`);
+  }
+  return limit;
+}
+function printReviews(result) {
+  const reviews = result.reviews ?? [];
+  console.log();
+  if (reviews.length === 0) {
+    console.log(`  ${result.message ?? "No open reviews are addressed to you."}`);
+    console.log();
+    return;
+  }
+  for (const review of reviews) {
+    console.log(`  ${chalk13.bold(`Review ${review.reviewId}`)} ${chalk13.gray(`by ${review.author.name}`)}`);
+    console.log(`    ${chalk13.cyan.underline(review.artifactUrl)}`);
+    if (!review.isLatest) {
+      console.log(
+        chalk13.yellow("    The artifact moved since this was written \u2014 check the comments still apply.")
+      );
+    }
+    console.log();
+    for (const comment of review.comments) {
+      const marks = [
+        comment.status !== "open" ? chalk13.gray(comment.status) : null,
+        comment.unassigned ? chalk13.yellow("unassigned") : null
+      ].filter(Boolean).join(" ");
+      console.log(`    ${chalk13.bold(`#${comment.index}`)} ${comment.body}${marks ? ` ${marks}` : ""}`);
+      console.log(chalk13.gray(`       ${comment.commentId}${describeAnchor(comment)}`));
+      for (const reply of comment.replies ?? []) {
+        console.log(chalk13.gray(`       \u21B3 ${reply.author.name}: ${reply.body}`));
+      }
+      console.log();
+    }
+    printKeyValue("To close these in a commit", "");
+    for (const line of review.resolveTrailer.split("\n")) {
+      console.log(`      ${chalk13.gray(line)}`);
+    }
+    console.log();
+  }
+}
+function describeAnchor(comment) {
+  if (!comment.anchor) return " \u2014 about the artifact as a whole";
+  const anchor = comment.anchor;
+  const dom = anchor.dom;
+  const markdown = anchor.markdown;
+  if (dom?.sourceFile) {
+    const instances = typeof dom.instanceCount === "number" && dom.instanceCount > 1 ? dom.instanceCount : 0;
+    return ` \u2014 ${dom.sourceFile}${dom.sourceStart ? `:${dom.sourceStart}` : ""}${instances ? ` (shared markup: ${instances} instances)` : ""}`;
+  }
+  if (markdown?.quote) {
+    return ` \u2014 on "${String(markdown.quote).slice(0, 60)}"`;
+  }
+  return "";
+}
+
+// src/commands/skill.ts
+import { Command as Command22 } from "commander";
+import fs7 from "fs";
+import path6 from "path";
+import chalk14 from "chalk";
+var GUIDE_PATH = "/guide.md";
+function createSkillCommand() {
+  return new Command22("skill").summary("Install the AgentGrid guide as a skill your agent can read").description(
+    "Fetch the AgentGrid agent guide and write it as a SKILL.md your runtime can load, or print it to stdout. The guide comes from the API, so it stays current; the command reference is generated from this CLI's own commands."
+  ).argument(
+    "[path]",
+    "Where to write the SKILL.md (e.g. .claude/skills/agentgrid/SKILL.md). Omit to print to stdout"
+  ).option("--json", "Output as JSON").option("--api-url <url>", "API base URL (overrides config / ANIMA_API_URL)").option("--log-file <path>", "Append a JSON debug log of each step to this file").action(async (target, opts, command) => {
+    const mode = detectOutputMode(opts);
+    initLogger(opts.logFile);
+    await withCommandErrors(mode, async () => {
+      const apiUrl = resolveApiUrl(opts.apiUrl);
+      const guide = await fetchGuide(apiUrl);
+      const program2 = command.parent ?? command;
+      const body = [connectSection(), commandReference(program2), guide.trim(), provenance(apiUrl)].join(
+        "\n\n"
+      );
+      const document = `${frontmatter()}
+${body}
+`;
+      if (!target) {
+        process.stdout.write(document.endsWith("\n") ? document : `${document}
+`);
+        return;
+      }
+      writeDocument(target, document);
+      logEvent("skill_installed", { path: target, bytes: document.length });
+      if (mode === "pretty") {
+        console.log();
+        printSuccess(`Skill written to ${chalk14.cyan(target)}`);
+        console.log(`  ${chalk14.gray(`${document.length} bytes, from ${apiUrl}${GUIDE_PATH}`)}`);
+        console.log();
+      } else {
+        outputResult(mode, {
+          success: true,
+          path: path6.resolve(target),
+          bytes: document.length,
+          source: `${apiUrl}${GUIDE_PATH}`
+        });
+      }
+    });
+  });
+}
+var skillCommand = createSkillCommand();
+async function fetchGuide(apiUrl) {
+  const url = `${apiUrl.replace(/\/$/, "")}${GUIDE_PATH}`;
+  logEvent("skill_fetch", { url });
+  let response;
+  try {
+    response = await fetch(url);
+  } catch (err) {
+    throw apiError(`Could not reach ${url}: ${err.message}`);
+  }
+  if (response.status === 404) {
+    throw apiError(
+      `${url} returned 404. This API does not serve the agent guide yet \u2014 point --api-url at one that does.`
+    );
+  }
+  if (!response.ok) {
+    throw apiError(`Could not fetch the guide: HTTP ${response.status} from ${url}`);
+  }
+  const body = await response.text();
+  if (!body.trim()) {
+    throw apiError(`${url} returned an empty guide.`);
+  }
+  return body;
+}
+function frontmatter() {
+  return [
+    "---",
+    "name: agentgrid",
+    "description: >-",
+    "  Host, change, publish and share artifacts on AgentGrid from the command line.",
+    "  Use when asked to share an app or a document with a human, put work somewhere",
+    "  they can see it, create or edit an AgentGrid artifact, publish one to a live",
+    "  URL, or answer review comments left on one.",
+    "---"
+  ].join("\n");
+}
+function connectSection() {
+  return `# AgentGrid
+
+An **artifact** is a hosted app or document that is also a real git repository.
+Every command below runs one AgentGrid tool for you.
+
+## Connect first
+
+You act as a scoped agent identity a human approved and can revoke. Three doors \u2014
+the first is the usual one, because you arrive with something to show and they
+need no account until they claim it:
+
+\`\`\`bash
+# 1. You lead: create with no credential at all, then wait for the claim
+npx @animaapp/cli@latest create --anonymous -t import --from ./my-project \\
+  --client-name "<your product name>" --json     # returns artifactUrl \u2014 send it to your human
+npx @animaapp/cli@latest login --handoff --json  # blocks until they claim; stores your credentials
+
+# 2. A human is reachable and can approve a short code
+npx @animaapp/cli@latest login
+
+# 3. A human already sent you an invite link
+npx @animaapp/cli@latest login --invite <url-or-code>
+\`\`\`
+
+Credentials live in \`~/.config/anima/\` and the CLI renews them for you. Check
+with \`anima auth --status\`. Every command takes \`--json\` for machine-readable
+output on stdout, with progress on stderr.`;
+}
+function commandReference(program2) {
+  const rows = [];
+  for (const command of program2.commands) {
+    if (command.name() === "help") continue;
+    const subcommands = command.commands.filter((sub) => sub.name() !== "help");
+    if (subcommands.length > 0) {
+      for (const sub of subcommands) {
+        rows.push(row(`${command.name()} ${sub.name()}`, sub));
+      }
+      continue;
+    }
+    rows.push(row(command.name(), command));
+  }
+  return [
+    "## Command reference",
+    "",
+    `Generated from \`@animaapp/cli\` ${version}, so this is what your copy accepts.`,
+    "Run `anima <command> --help` for a command's full options.",
+    "",
+    "| Command | What it does |",
+    "| ------- | ------------ |",
+    ...rows
+  ].join("\n");
+}
+function row(name, command) {
+  const usage = command.usage().replace(/\[options\]\s*/, "").trim();
+  const invocation = `anima ${name}${usage ? ` ${usage}` : ""}`;
+  const summary = (command.summary() || command.description() || "").split("\n")[0];
+  return `| \`${invocation}\` | ${escapePipes(summary)} |`;
+}
+var escapePipes = (text) => text.replace(/\|/g, "\\|");
+function provenance(apiUrl) {
+  return `---
+
+_Guide fetched from ${apiUrl}${GUIDE_PATH}; command reference generated by @animaapp/cli ${version}._`;
+}
+function writeDocument(target, document) {
+  const directory = path6.dirname(path6.resolve(target));
+  try {
+    fs7.mkdirSync(directory, { recursive: true });
+  } catch (err) {
+    throw validationError(`Could not create ${directory}: ${err.message}`);
+  }
+  try {
+    fs7.writeFileSync(target, document, "utf-8");
+  } catch (err) {
+    throw validationError(`Could not write ${target}: ${err.message}`);
+  }
+}
+
 // src/index.ts
-var program = new Command14().name("anima").description(
-  `AgentGrid CLI \u2014 host, edit, and publish your work on AgentGrid. Every artifact is a
-real git repository; each command runs an AgentGrid tool for you.
+var program = new Command23().name("anima").description(
+  `AgentGrid CLI \u2014 create, change, publish and share artifacts on AgentGrid.
+An artifact is a real git repository, and every command below runs one
+AgentGrid MCP tool for you. The command list is at the bottom; run
+"anima <command> --help" for a command's own options.
 
 THE MAIN FLOW (build something and put it on AgentGrid):
-  1. npx @animaapp/cli login                                   # once; a human approves
-  2. npx @animaapp/cli create -t import --from ./my-project    # your code \u2192 a live app
+  1. anima login                                   # once; a human approves
+  2. anima create -t import --from ./my-project    # your code \u2192 a live app
      (or: create -t empty --framework html \u2014 an empty repo you push to)
-  3. The response includes a rw gitRemoteUrl \u2014 git clone, edit, commit, push:
-     every push updates the live artifact.
-  4. Share the playgroundUrl with your human. That IS sharing \u2014 the artifact
-     is visible at its URL. Do NOT run publish unless the human explicitly
-     asked for a public site; offer it as a follow-up question instead.
+     (can create in several workspaces? add --workspace <id>; see "workspaces")
+  3. Change it. Two doors, same git repository:
+     - no clone: "explore" to read the files, "edit" to commit them. Needs no
+       shell, no git binary and no network of its own \u2014 prefer it.
+     - a real checkout: "get-git-token" (create already returns one), then
+       git clone / commit / push. Worth it for a large refactor, running the
+       project, branches or rewriting history.
+  4. Share the artifactUrl \u2014 app.agentgrid.io/artifacts/<sessionId>. That IS
+     sharing: the artifact is already visible there. Do NOT run "publish"
+     unless a human explicitly asked for a public site; offer it as a
+     follow-up question instead.
+
+TIMING \u2014 how long the COMMAND blocks, not how long the server takes:
+  create -t p2c|l2c|f2c    BLOCKS 3-7 min. The generation itself is
+                           asynchronous, but create waits it out for you, so
+                           what it prints is a finished app and a failed
+                           generation exits non-zero. Keep the default
+                           600000ms --timeout. Pass --no-wait to get the
+                           sessionId back in seconds and do the waiting
+                           yourself with "anima status <sessionId> --wait".
+  publish / unpublish      BLOCKS 1-3 min
+  everything else          seconds, create -t empty|import included
 
 AUTHENTICATION:
-  npx @animaapp/cli login            # device flow \u2014 a human approves on any device
-  npx @animaapp/cli login --invite <url>   # redeem a pre-approved invite link (no approval step)
-  Credentials live in ~/.config/anima/; logout removes everything.
-
-TIMING (important for AI agents):
-  create -t empty|import \u2192 seconds
-  create -t p2c|l2c|f2c  \u2192 3-7 minutes AI generation (keep the default 600000ms timeout)
-  publish/unpublish      \u2192 1-3 minutes
-  duplicate / get-git-token / update \u2192 seconds
-
-COMMANDS:
-  login          Connect (device flow, or --invite to redeem an invite link)
-  logout         Full local reset \u2014 clears credentials and CLI config
-  list           List your team's artifacts (most-recently-updated first) to resume work
-  create         Make an artifact: import your code, empty repo, or AI-generated (p2c/l2c/f2c)
-  duplicate      Copy an artifact into a new, independent artifact
-  get-git-token  Fresh git access to an existing artifact (or after token expiry)
-  update         Rename an artifact or set visibility public/private (metadata only)
-  publish        Deploy to a public live URL \u2014 ONLY when the human asked for it
-  unpublish      Take a published artifact offline (inverse of publish)
-  mcp-config     Print an MCP server config from stored credentials (no new login)
-  codegen        Convert Figma design to local code files (no artifact)
-  config         Store CLI preferences (e.g. a default API URL)
-  auth           Inspect or manage credentials (status / figma token)
-
-EXAMPLES (headless flow):
-  npx @animaapp/cli login --invite https://api.agentgrid.io/invite/<code>.md
-  npx @animaapp/cli create -t import --from ./my-project
-  npx @animaapp/cli create -t empty --framework react --name "My app"
-  npx @animaapp/cli duplicate <artifactUrl> --name "My copy"
-  npx @animaapp/cli get-git-token <sessionId>
-  npx @animaapp/cli update <sessionId> --privacy public
-  npx @animaapp/cli publish <sessionId>        # only on explicit request
-  npx @animaapp/cli unpublish <sessionId>
-
-OUTPUT: JSON to stdout when piped (for AI tools), pretty text in terminals.
-  Progress is streamed to stderr via --verbose when in JSON mode.`
+  anima skill <path>           # install this guide where your runtime reads skills
+  anima login                  # device flow \u2014 a human approves on any device
+  anima login --invite <url>   # redeem a pre-approved invite (no approval step)
+  anima create --anonymous \u2026   # no account at all; hand off to a human later
+  Credentials live in ~/.config/anima/; "logout" removes everything.
+
+EXAMPLES:
+  anima create -t import --from ./my-project
+  anima status <sessionId> --wait
+  anima explore <sessionId> --search "buttonColor"
+  anima edit <sessionId> -m "Blue pill" --replace src/App.tsx --old red --new blue
+  anima review list                      # what humans asked you to change
+  anima publish <sessionId>              # only on explicit request
+
+OUTPUT: pretty text in a terminal; a single JSON object on stdout when piped
+  or given --json. Progress and prompts go to stderr, so stdout stays clean.
+  Add --verbose to stream progress in JSON mode.`
 ).version(version, "-v, --version");
 program.addCommand(loginCommand);
 program.addCommand(logoutCommand);
+program.addCommand(workspacesCommand);
 program.addCommand(listCommand);
 program.addCommand(createCommand);
+program.addCommand(createKnowledgeCommand);
+program.addCommand(statusCommand);
+program.addCommand(exploreCommand);
+program.addCommand(editCommand);
+program.addCommand(uploadAssetCommand);
+program.addCommand(getGitTokenCommand);
+program.addCommand(reviewCommand);
 program.addCommand(duplicateCommand);
 program.addCommand(publishCommand);
 program.addCommand(unpublishCommand);
 program.addCommand(updateCommand);
+program.addCommand(deleteCommand);
 program.addCommand(codegenCommand);
-program.addCommand(getGitTokenCommand);
+program.addCommand(skillCommand);
 program.addCommand(mcpConfigCommand);
 program.addCommand(configCommand);
 program.addCommand(authCommand);