@animaapp/cli 0.7.0 → 0.8.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 Command21 } from "commander";
 
 // src/commands/create.ts
 import { Command } from "commander";
@@ -87,7 +87,7 @@ function readPendingHandoff() {
   try {
     if (!fs.existsSync(HANDOFF_FILE)) return null;
     const parsed = JSON.parse(fs.readFileSync(HANDOFF_FILE, "utf-8"));
-    const required2 = ["handoffToken", "sessionId", "claimUrl", "claimableUntil", "apiUrl"];
+    const required2 = ["handoffToken", "sessionId", "artifactUrl", "claimableUntil", "apiUrl"];
     if (required2.some((field) => typeof parsed[field] !== "string")) return null;
     return parsed;
   } catch {
@@ -608,8 +608,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 +713,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 +735,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,6 +771,57 @@ 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`;
@@ -792,7 +849,7 @@ async function createAnonymousArtifact(request, fetchFn = fetch) {
     throw apiError(nextSteps ? `${message}
 ${nextSteps}` : message, payload);
   }
-  for (const field of ["sessionId", "handoffToken", "claimUrl", "claimableUntil"]) {
+  for (const field of ["sessionId", "handoffToken", "artifactUrl", "claimableUntil"]) {
     if (typeof payload[field] !== "string") {
       throw apiError(`The API's create response is missing \`${field}\`.`, payload);
     }
@@ -811,7 +868,7 @@ async function getAnonymousZipUploadUrl(apiUrl, fetchFn = fetch) {
 }
 
 // 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>",
@@ -828,7 +885,10 @@ var createCommand = new Command("create").description(
 ).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 +932,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";
       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 +1002,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 } : {},
@@ -979,19 +1068,19 @@ async function runAnonymousCreate(opts, mode, progress) {
     progress.update("Previous claim is no longer open \u2014 starting a new one...");
     return createAnonymousArtifact(request);
   }) : await createAnonymousArtifact(request);
-  const claimUrl = result.claimUrl;
+  const artifactUrl = result.artifactUrl;
   savePendingHandoff({
     handoffToken: result.handoffToken,
     sessionId: result.sessionId,
-    claimUrl,
+    artifactUrl,
     claimableUntil: result.claimableUntil,
     apiUrl
   });
   progress.succeed("Artifact created!");
   if (mode === "pretty") {
-    printSessionResult({ sessionId: result.sessionId, playgroundUrl: result.previewUrl });
+    printSessionResult({ sessionId: result.sessionId });
     console.log("  Send your human this link to claim it:");
-    console.log(`    ${chalk2.cyan.underline(claimUrl)}`);
+    console.log(`    ${chalk2.cyan.underline(artifactUrl)}`);
     console.log();
     console.log(`  Claimable until ${result.claimableUntil}. Until then the artifact is read-only.`);
     console.log(`  Then run ${chalk2.cyan("anima login --handoff")} to pick up your credentials.`);
@@ -1001,8 +1090,7 @@ async function runAnonymousCreate(opts, mode, progress) {
     outputResult(mode, {
       success: true,
       sessionId: result.sessionId,
-      previewUrl: result.previewUrl,
-      claimUrl,
+      artifactUrl,
       claimableUntil: result.claimableUntil,
       // Returned, not just stored: it is delivered exactly once and can never
       // be re-fetched, so a caller whose config does not outlive the process
@@ -1012,7 +1100,7 @@ async function runAnonymousCreate(opts, mode, progress) {
       ...result.fileCount !== void 0 ? { fileCount: result.fileCount } : {},
       ...result.skippedFiles?.length ? { skippedFiles: result.skippedFiles } : {},
       ...result.notes ? { notes: result.notes } : {},
-      nextSteps: `Send claimUrl to your human \u2014 that is the link that transfers the artifact to them. handoffToken is yours, never theirs: use it to log in (\`anima login --handoff\`, which waits until they claim and then stores your credentials), or to add more artifacts to the same claim (\`anima create --anonymous --handoff <token>\`). Run the login in the background if you have other work.`
+      nextSteps: `Send artifactUrl to your human \u2014 that is the artifact's page, and the link that transfers it to them. handoffToken is yours, never theirs: use it to log in (\`anima login --handoff\`, which waits until they claim and then stores your credentials), or to add more artifacts to the same claim (\`anima create --anonymous --handoff <token>\`). Run the login in the background if you have other work.`
     });
   }
 }
@@ -1124,7 +1212,7 @@ function buildCreateArgs(type, opts) {
 // src/commands/list.ts
 import { Command as Command2 } from "commander";
 import chalk3 from "chalk";
-var listCommand = new Command2("list").aliases(["ls", "artifacts"]).description(
+var listCommand = new Command2("list").summary("List your team's artifacts, most-recently-updated first").aliases(["ls", "artifacts"]).description(
   "List your team's artifacts (most-recently-updated first) so you can resume existing work."
 ).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);
@@ -1157,9 +1245,7 @@ var listCommand = new Command2("list").aliases(["ls", "artifacts"]).description(
           }
           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();
         }
@@ -1174,7 +1260,12 @@ var listCommand = new Command2("list").aliases(["ls", "artifacts"]).description(
       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,
+          ...a.sessionId ? { artifactUrl: artifactUrlFor(a.sessionId) } : {}
+        })),
         truncated: result.truncated ?? false
       });
     }
@@ -1198,9 +1289,80 @@ function formatUpdatedAt(iso) {
   return `${relative2} (${iso})`;
 }
 
-// src/commands/publish.ts
+// src/commands/status.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 chalk4 from "chalk";
+var statusCommand = new Command3("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", chalk4.cyan.underline(result.artifactUrl));
+  }
+  if (result.playgroundUrl) {
+    printKeyValue("Edit in Playground", chalk4.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 Command4 } from "commander";
+var publishCommand = new Command4("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);
@@ -1246,7 +1408,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 Command5 } from "commander";
 
 // src/utils/files.ts
 import fs4 from "fs";
@@ -1274,7 +1436,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 Command5("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);
@@ -1346,8 +1508,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 Command6 } from "commander";
+import chalk5 from "chalk";
 
 // src/utils/gitToken.ts
 function preview(payload) {
@@ -1376,17 +1538,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 Command6("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(
@@ -1398,9 +1572,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(`  ${chalk5.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(`    ${chalk5.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.");
@@ -1408,7 +1587,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 ${chalk5.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.");
@@ -1419,7 +1598,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) {
@@ -1437,11 +1620,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 Command8 } from "commander";
 
 // src/commands/login.ts
-import { Command as Command6 } from "commander";
-import chalk5 from "chalk";
+import { Command as Command7 } from "commander";
+import chalk6 from "chalk";
 import open from "open";
 
 // src/auth/device.ts
@@ -1631,7 +1814,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 Command7("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(
@@ -1701,9 +1884,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(`    ${chalk6.cyan.underline(info.verificationUri)}`);
           console.log();
-          console.log(`    ${chalk5.bold.white(info.userCode)}`);
+          console.log(`    ${chalk6.bold.white(info.userCode)}`);
           console.log();
           printInfo(`Waiting for approval\u2026 (code expires in ${Math.round(info.expiresInSeconds / 60)} minutes)`);
         } else {
@@ -1763,7 +1946,7 @@ var loginCommand = new Command6("login").description("Log in via the device flow
 async function runHandoffLogin(opts, mode) {
   const explicitToken = typeof opts.handoff === "string" ? opts.handoff : void 0;
   const stored = readPendingHandoff();
-  const pending = stored && (!explicitToken || stored.handoffToken === explicitToken) ? stored : explicitToken ? { handoffToken: explicitToken, sessionId: "", claimUrl: "", claimableUntil: "", apiUrl: resolveApiUrl() } : null;
+  const pending = stored && (!explicitToken || stored.handoffToken === explicitToken) ? stored : explicitToken ? { handoffToken: explicitToken, sessionId: "", artifactUrl: "", claimableUntil: "", apiUrl: resolveApiUrl() } : null;
   if (!pending) {
     const message = "No handoff token. Pass one (`anima login --handoff <token>`), or run `anima create --anonymous -t import --from <path>` to get one. (Already logged in another way? `anima auth --status`.)";
     if (mode === "pretty") {
@@ -1778,9 +1961,9 @@ async function runHandoffLogin(opts, mode) {
     if (mode === "pretty") {
       console.log();
       printInfo("Waiting for a human to claim the artifact:");
-      if (pending.claimUrl) {
+      if (pending.artifactUrl) {
         console.log();
-        console.log(`    ${chalk5.cyan.underline(pending.claimUrl)}`);
+        console.log(`    ${chalk6.cyan.underline(pending.artifactUrl)}`);
       }
       console.log();
       printInfo(
@@ -1790,7 +1973,7 @@ async function runHandoffLogin(opts, mode) {
       process.stderr.write(
         JSON.stringify({
           event: "claim_required",
-          ...pending.claimUrl ? { claimUrl: pending.claimUrl } : {},
+          ...pending.artifactUrl ? { artifactUrl: pending.artifactUrl } : {},
           ...pending.sessionId ? { sessionId: pending.sessionId } : {},
           ...pending.claimableUntil ? { claimableUntil: pending.claimableUntil } : {}
         }) + "\n"
@@ -1855,7 +2038,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 Command8("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));
@@ -1882,16 +2065,16 @@ 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 Command9 } from "commander";
+import chalk7 from "chalk";
 var DEFAULT_API_URL2 = "https://api.agentgrid.io";
 function describePendingHandoff(pending, state) {
   return {
     state,
     sessionId: pending.sessionId,
-    claimUrl: pending.claimUrl,
+    artifactUrl: pending.artifactUrl,
     claimableUntil: pending.claimableUntil,
-    nextSteps: state === "expired" ? "The claim window closed. Create another artifact, or ask your human for an agent invite: anima login --invite <url-or-code>" : "Send claimUrl to your human, then run `anima login --handoff` to wait for the credentials their claim grants."
+    nextSteps: state === "expired" ? "The claim window closed. Create another artifact, or ask your human for an agent invite: anima login --invite <url-or-code>" : "Send artifactUrl to your human, then run `anima login --handoff` to wait for the credentials their claim grants."
   };
 }
 function printPendingHandoff(pending, state) {
@@ -1901,10 +2084,10 @@ function printPendingHandoff(pending, state) {
     return;
   }
   printInfo(`Anonymous artifact ${pending.sessionId} is awaiting a claim (until ${pending.claimableUntil}):`);
-  console.log(`    ${chalk6.cyan.underline(pending.claimUrl)}`);
-  console.log(`  Run ${chalk6.cyan("anima login --handoff")} to wait for it.`);
+  console.log(`    ${chalk7.cyan.underline(pending.artifactUrl)}`);
+  console.log(`  Run ${chalk7.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 Command9("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) {
@@ -2004,13 +2187,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(`  ${chalk7.cyan("anima login")}                    Log in (device flow \u2014 approve on any browser)`);
+      console.log(`  ${chalk7.cyan("anima login --handoff")}          Wait for a human to claim your anonymous artifact`);
+      console.log(`  ${chalk7.cyan("anima logout")}                   Clear all credentials`);
+      console.log(`  ${chalk7.cyan("anima auth --status")}            Check auth status`);
+      console.log(`  ${chalk7.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: ${chalk7.cyan.underline("https://www.figma.com")} > Settings > Personal access tokens`);
       console.log();
     } else {
       outputResult(mode, {
@@ -2032,8 +2215,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 Command10 } from "commander";
+var logoutCommand = new Command10("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();
@@ -2051,8 +2234,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 Command11 } from "commander";
+var unpublishCommand = new Command11("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);
@@ -2087,8 +2270,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 Command12 } from "commander";
+var updateCommand = new Command12("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);
@@ -2133,8 +2316,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 Command13 } from "commander";
+var configCommand = new Command13("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) => {
@@ -2200,10 +2383,10 @@ function assertUrl(value) {
 }
 
 // src/commands/duplicate.ts
-import { Command as Command13 } from "commander";
-import chalk7 from "chalk";
+import { Command as Command14 } from "commander";
+import chalk8 from "chalk";
 function buildDuplicateArgs(artifactUrl, name) {
-  const sessionId = parsePlaygroundUrl(artifactUrl);
+  const sessionId = parseArtifactUrl(artifactUrl);
   if (!sessionId) {
     throw validationError("A source artifact URL or session ID is required");
   }
@@ -2213,7 +2396,7 @@ function buildDuplicateArgs(artifactUrl, name) {
   return { sessionId, ...name !== void 0 ? { name } : {} };
 }
 function createDuplicateCommand() {
-  return new Command13("duplicate").description(
+  return new Command14("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) => {
     const mode = detectOutputMode(opts);
@@ -2237,8 +2420,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", chalk8.cyan.underline(result.artifactUrl));
+        if (result.playgroundUrl) {
+          printKeyValue("Edit in Playground", chalk8.cyan.underline(result.playgroundUrl));
+        }
+        if (result.previewUrl) {
+          printKeyValue("Preview", chalk8.cyan.underline(result.previewUrl));
+        }
         printKeyValue("Next steps", result.nextSteps);
         console.log();
       } else {
@@ -2260,70 +2448,822 @@ function createDuplicateCommand() {
 }
 var duplicateCommand = createDuplicateCommand();
 
+// src/commands/explore.ts
+import { Command as Command15 } from "commander";
+import chalk9 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/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/explore.ts
+var exploreCommand = new Command15("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 ? chalk9.gray(` (${kind} \u2014 git only)`) : ""}`);
+    }
+    if (result.matchedFiles !== void 0) {
+      console.log();
+      console.log(chalk9.gray(`  ${(result.files ?? []).length} of ${result.matchedFiles} shown`));
+    }
+  } else if (action === "search") {
+    for (const match of result.matches ?? []) {
+      console.log(`  ${chalk9.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(
+          chalk9.yellow(
+            `  ${skipped.excluded} files were skipped (node_modules, dist, build) \u2014 retry with --include-excluded.`
+          )
+        );
+      }
+      if (skipped?.assets) {
+        console.log(chalk9.gray(`  ${skipped.assets} binary files cannot match a text query.`));
+      }
+    }
+  } else if (action === "read") {
+    for (const file of result.files ?? []) {
+      console.log(chalk9.bold(`  ${file.path}`));
+      if (file.asset) {
+        console.log(chalk9.gray(`    binary \u2014 ${file.size ?? "?"} bytes, ${file.mime ?? "unknown type"}`));
+      } else if (file.deferred) {
+        console.log(chalk9.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(
+            chalk9.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(chalk9.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(`  ${chalk9.yellow(commit.revision.slice(0, 10))}  ${commit.message.split("\n")[0]}`);
+      console.log(chalk9.gray(`    ${commit.author} \u2014 ${commit.date}`));
+    }
+    for (const changed of result.commit?.changedFiles ?? []) {
+      console.log(chalk9.gray(`      ${changed.change.padEnd(8)} ${changed.path}`));
+    }
+  }
+  if (result.truncated) {
+    console.log(chalk9.yellow("  The list was capped \u2014 raise --limit to see more."));
+  }
+  if (result.revision) {
+    console.log();
+    console.log(chalk9.gray(`  revision: ${result.revision}  (pass to \`anima edit --base-revision\`)`));
+  }
+  console.log();
+}
+
+// src/commands/edit.ts
+import { Command as Command16 } from "commander";
+import fs5 from "fs";
+import chalk10 from "chalk";
+var editCommand = new Command16("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(`  ${chalk10.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 Command17 } from "commander";
+import fs6 from "fs";
+import path5 from "path";
+import chalk11 from "chalk";
+var uploadAssetCommand = new Command17("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(
+          `    ${chalk11.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 Command18 } from "commander";
+var deleteCommand = new Command18("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 Command19 } from "commander";
+import chalk12 from "chalk";
+var listSubcommand = new Command19("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 Command19("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 Command19("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 Command19("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(`  ${chalk12.bold(`Review ${review.reviewId}`)} ${chalk12.gray(`by ${review.author.name}`)}`);
+    console.log(`    ${chalk12.cyan.underline(review.artifactUrl)}`);
+    if (!review.isLatest) {
+      console.log(
+        chalk12.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" ? chalk12.gray(comment.status) : null,
+        comment.unassigned ? chalk12.yellow("unassigned") : null
+      ].filter(Boolean).join(" ");
+      console.log(`    ${chalk12.bold(`#${comment.index}`)} ${comment.body}${marks ? ` ${marks}` : ""}`);
+      console.log(chalk12.gray(`       ${comment.commentId}${describeAnchor(comment)}`));
+      for (const reply of comment.replies ?? []) {
+        console.log(chalk12.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(`      ${chalk12.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 Command20 } from "commander";
+import fs7 from "fs";
+import path6 from "path";
+import chalk13 from "chalk";
+var GUIDE_PATH = "/guide.md";
+function createSkillCommand() {
+  return new Command20("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 ${chalk13.cyan(target)}`);
+        console.log(`  ${chalk13.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 Command21().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.
+  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(listCommand);
 program.addCommand(createCommand);
+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);