@andreprado/agentkit 0.1.0-alpha.2 → 0.1.0-alpha.21

package/src/cli/index.ts

@@ -1,14 +1,15 @@
 import { spawn } from "node:child_process";
-import { mkdir, readFile, rm, writeFile } from "node:fs/promises";
-import { homedir } from "node:os";
-import { join, resolve } from "node:path";
+import { existsSync } from "node:fs";
+import { chmod, mkdir, readFile, writeFile } from "node:fs/promises";
+import { dirname, join, relative, resolve } from "node:path";
 
 import { createProject } from "../create-project";
 import { buildAgentCapsule } from "../runtime/build";
 import { findAgentCapsuleRoot, loadAgentCapsule } from "../runtime/config";
 import { readLocalDeployStateIfExists, type LocalDeployState } from "../runtime/core/deploy-state";
-import { listTargetsWithCapability, resolveBuildTarget, resolveDeployTarget } from "../runtime/core/targets";
+import { resolveBuildTarget, resolveDeployTarget } from "../runtime/core/targets";
 import { getConversationFromCwd, listConversationsFromCwd } from "../runtime/conversations";
+import { getConversationTraceFromCwd } from "../runtime/traces";
 import { runAgentMessageFromCwd } from "../runtime/chat";
 import { deployBuildToAgentKitCloud, writeLocalDeployState } from "../runtime/deploy";
 import {
@@ -17,182 +18,205 @@ import {
   resetLocalDatabase,
   seedLocalDatabase,
 } from "../runtime/db-commands";
-import { runEvalsFromCwd } from "../runtime/evals";
+import { runEvalsFromCwd, writeEvalFromConversation } from "../runtime/evals";
 import { findAgentKitDocs } from "../runtime/docs";
 import { listCapsuleEnv, setCapsuleEnv, unsetCapsuleEnv } from "../runtime/env";
-import { loadDeployReadinessContext, stableCloudProjectId, type DeployReadinessContext } from "../runtime/deploy-readiness";
+import { collectDeployImproveBundle, collectLocalImproveBundle, generateImproveEvals, replayImproveBundle } from "../runtime/improve";
+import { checkAgentSpec, initializeAgentSpec } from "../runtime/spec";
+import { checkDefaultSkillStatus, syncDefaultSkillFiles } from "../runtime/skills";
+import { initializeSyncScaffold, runCapsuleSync } from "../runtime/sync";
 import { runToolFromCwd } from "../runtime/tool-runner";
 import { startAgentDevServer } from "../runtime/dev-server";
 import { inspectAgentCapsule } from "../runtime/inspect";
 import { AgentKitError, isAgentKitError } from "../runtime/errors";
 import { prepareVpsDeploy } from "../runtime/targets/vps/deploy";
+import { parseArgs, isHelpRequested, type ParsedArgs } from "./args";
+import {
+  defaultAgentKitDevPort,
+  defaultDeployChatAccessTokenName,
+  defaultDeployChatAccessTokenPath,
+} from "./constants";
+import {
+  clearCloudAuth,
+  cloudApiRequest,
+  readCloudAuth,
+  readCloudAuthForApiUrl,
+  readCloudError,
+  resolveCloudApiUrl,
+  verifyCloudLogin,
+  writeCloudAuth,
+  type AccountApiTokenCreateResponse,
+  type AccountApiTokenListResponse,
+  type BillingCheckoutIntentResponse,
+  type BillingCheckoutResponse,
+  type BillingClaimResponse,
+  type BillingPortalResponse,
+  type CloudMeResponse,
+  type DeployAccessTokenCreateResponse,
+  type DeployAccessTokenListResponse,
+} from "./cloud-client";
+import {
+  checkDeployReadiness,
+  formatReadinessError,
+  printDeployReadinessReport,
+  resolveProjectIdForSecretCommand,
+  syncHostedSecretsFromLocal,
+} from "./deploy-readiness";
+import { readDeployAccessTokenForUi, startDeployChatUiServer } from "./deploy-chat-ui";
+import {
+  parseCloudApiUrl,
+  parseOptionalStringFlag,
+  parsePort,
+  parseRequiredStringFlag,
+  parseTargetFlag,
+  resolveSecretInputValue,
+} from "./flags";
+import { renderCommandHelp, renderCommandReference, renderHelp } from "./help";
+import { runInheritedCommand, waitForShutdown } from "./process";
+import { handleChannelsCommand } from "./commands/channels";
+import { handleFeedbackCommand } from "./commands/feedback";
+import { handleKnowledgeCommand } from "./commands/knowledge";
+import { handleTranscribeCommand } from "./commands/transcribe";
+
+const hostedDeployEntitlement = "agentkit_cloud_deploy";
 
-const defaultAgentKitCloudApiUrl = "https://agentkit-cloud.aibuilders.com.br";
-
-function renderHelp(): string {
-  return `AgentKit
-
-Usage:
-  agentkit new <name> [--template blank|support]
-  agentkit dev
-  agentkit chat --message <text>
-  agentkit tool <name> [--input <path-or-json>]
-  agentkit db migrate
-  agentkit db reset --yes
-  agentkit db shell
-  agentkit db seed [--file <path>]
-  agentkit eval run
-  agentkit conversations list
-  agentkit conversations show <conversation-id>
-  agentkit channels list
-  agentkit channels add <website|telegram|whatsapp> <name> [--provider zapster|meta] [--api <url>]
-  agentkit channels setup <name> [--apply] [--api <url>]
-  agentkit channels status <name> [--api <url>]
-  agentkit channels test <name> [--message <text>] [--fixture <path>] [--api <url>]
-  agentkit channels deliveries list <name> [--api <url>]
-  agentkit channels deliveries show <delivery-id> [--api <url>]
-  agentkit inspect
-  agentkit build [--target cloudflare]
-  agentkit login --token <token> [--api <url>]
-  agentkit logout
-  agentkit deploy [--target cloudflare|vps] [--host <host>] [--api <url>] [--dry-run] [--anonymous] [--local-wrangler]
-  agentkit deploy doctor [--api <url>] [--anonymous]
-  agentkit deploy status [--api <url>]
-  agentkit deploy pause [--api <url>]
-  agentkit deploy resume [--api <url>]
-  agentkit secret set <NAME> <VALUE> [--api <url>]
-  agentkit secret list [--api <url>]
-  agentkit secret unset <NAME> [--api <url>]
-  agentkit access token create <name> [--api <url>]
-  agentkit access token list [--api <url>]
-  agentkit access token revoke <token-id> [--api <url>]
-  agentkit env set <NAME> <VALUE>
-  agentkit env list
-  agentkit env unset <NAME>
-  agentkit docs path
-  agentkit docs llms
-  agentkit docs full
-  agentkit handoff codex [goal]
-  agentkit --help
-
-Commands:
-  new             Create a new Agent Capsule
-  dev             Run the Agent Capsule locally
-  chat            Send one message to the local Agent Capsule
-  tool            Run one registered tool directly
-  db              Manage the local SQLite database
-  eval            Run local eval files
-  conversations   List and inspect stored local conversations
-  channels        Manage hosted channel resources
-  inspect         Print machine-readable Agent Capsule state
-  build           Build a hosted deploy artifact
-  login           Store an AgentKit Cloud alpha token outside the capsule
-  logout          Remove the stored AgentKit Cloud alpha token
-  deploy          Build and send a hosted artifact to AgentKit Cloud
-  secret          Manage hosted AgentKit Cloud secrets without readback
-  access          Manage hosted deploy access tokens
-  env             Manage local .env values without opening code
-  docs            Print AgentKit docs locations
-  handoff         Print a ready-to-paste prompt for another coding agent
-
-Examples:
-  agentkit new support-agent --template support
-  cd support-agent
-  agentkit dev
-  agentkit tool lookup_order --input '{"orderId":"A100"}'
-  agentkit eval run
-`;
-}
+async function main() {
+  const args = parseArgs(process.argv.slice(2));
 
-type ParsedArgs = {
-  command?: string;
-  positional: string[];
-  flags: Record<string, string | boolean>;
-};
+  if (!args.command || args.command === "--help" || args.command === "-h") {
+    console.log(renderHelp());
+    return;
+  }
 
-function parseArgs(argv: string[]): ParsedArgs {
-  const [command, ...rest] = argv;
-  const positional: string[] = [];
-  const flags: Record<string, string | boolean> = {};
+  if (isHelpRequested(args)) {
+    console.log(renderCommandHelp(args.command));
+    return;
+  }
 
-  for (let index = 0; index < rest.length; index += 1) {
-    const value = rest[index];
+  if (args.command === "help") {
+    const [topic] = args.positional;
 
-    if (!value.startsWith("--")) {
-      positional.push(value);
-      continue;
+    if (!topic) {
+      console.log(renderHelp());
+      return;
     }
 
-    const name = value.slice(2);
-    const next = rest[index + 1];
-
-    if (next && !next.startsWith("--")) {
-      flags[name] = next;
-      index += 1;
-    } else {
-      flags[name] = true;
+    if (topic === "commands") {
+      console.log(renderCommandReference());
+      return;
     }
-  }
-
-  return { command, positional, flags };
-}
 
-async function main() {
-  const args = parseArgs(process.argv.slice(2));
-
-  if (!args.command || args.command === "--help" || args.command === "-h") {
-    console.log(renderHelp());
-    return;
+    throw new Error("Usage: agentkit help [commands]");
   }
 
   if (args.command === "new") {
     const [name] = args.positional;
     const template = String(args.flags.template ?? "blank");
+    const shouldInstall = args.flags["no-install"] !== true;
 
     if (!name) {
-      throw new Error("Missing project name. Usage: agentkit new <name> [--template blank|support]");
+      throw new Error("Missing project name. Usage: agentkit new <name> [--template blank|support|dentista] [--no-install]");
     }
 
     const result = await createProject({ name, template, cwd: process.cwd() });
     console.log(`Created ${result.name} at ${result.path}`);
+
+    if (shouldInstall) {
+      console.log("");
+      console.log("Installing dependencies...");
+      await installProjectDependencies(result.path);
+    }
+
     console.log("");
     console.log("Next:");
     if (resolve(result.path) !== resolve(process.cwd())) {
       console.log(`  cd ${result.name}`);
     }
-    console.log("  npm install");
+    if (!shouldInstall) {
+      console.log("  npm install");
+    }
     console.log("  open this folder in Codex or Claude Code");
+    console.log("  coding agents start at skills/agentkit-capsule/SKILL.md");
     console.log('  ask: "Develop an appointment and intake agent for an ophthalmology office"');
     console.log('  npm run chat -- --message "hello"');
     console.log("  npm run dev");
     console.log("  npm run agentkit -- deploy");
     console.log("");
-    console.log("Optional: manage local secrets with `npm run agentkit -- env set <NAME> <VALUE>`.");
+    console.log("Optional: manage local secrets with `printf %s \"$VALUE\" | npm run agentkit -- env set <NAME> --stdin`.");
     return;
   }
 
   if (args.command === "dev") {
-    const port = parsePort(args.flags.port);
-    const devServer = await startAgentDevServer(process.cwd(), { port });
+    const port = parsePort(args.flags.port, "agentkit dev --port <number>");
+    const devServer = await startAgentDevServer(process.cwd(), { port, basePort: localDevBasePort() });
 
     console.log("Agent Capsule running");
     console.log("");
+    if (devServer.portConflict) {
+      const owner = devServer.portConflict.agent ? ` by ${devServer.portConflict.agent}` : "";
+      console.log(
+        `Port ${devServer.portConflict.port} is already used${owner}. Started ${devServer.capsule.config.name} at ${devServer.urls.chat}.`,
+      );
+      console.log("");
+    }
     console.log(`Chat:      ${devServer.urls.chat}`);
     console.log(`API:       ${devServer.urls.api}`);
     console.log(`Inspect:   ${devServer.urls.inspect}`);
     console.log(`Storage:   ${devServer.storage ?? "managed"}`);
+    console.log("Reload:    prompts/config reload per request; restart after changing tool modules or dependencies");
     await waitForShutdown(devServer.stop);
     return;
   }
 
+  if (args.command === "open") {
+    const server = await findRunningLocalDevServer(process.cwd());
+
+    if (!server) {
+      console.log("No running AgentKit dev server found for this capsule.");
+      console.log("Run: npm run dev");
+      return;
+    }
+
+    await openLocalUrl(server.url);
+    console.log(`Opened ${server.url}`);
+    return;
+  }
+
+  if (args.command === "chat-ui") {
+    if (!args.flags.deploy) {
+      throw new Error("Usage: agentkit chat-ui --deploy [--port <number>] [--token-file <path>]");
+    }
+
+    const port = parsePort(args.flags.port, "agentkit chat-ui --deploy --port <number>") ?? 4124;
+    const tokenFile = parseOptionalStringFlag(
+      args.flags["token-file"],
+      "token-file",
+      "agentkit chat-ui --deploy --token-file <path>",
+    );
+    const server = await startDeployChatUiServer(process.cwd(), { port, tokenFile });
+
+    console.log("AgentKit hosted chat UI running");
+    console.log("");
+    console.log(`Chat:       ${server.url}`);
+    console.log(`Production: ${server.deployUrl}`);
+    console.log(`Token:      ${server.tokenSource}`);
+    await waitForShutdown(server.stop);
+    return;
+  }
+
   if (args.command === "chat") {
     const message = args.flags.message;
+    const conversationId = parseOptionalStringFlag(
+      args.flags["conversation-id"] ?? args.flags.conversation,
+      "conversation id",
+      'agentkit chat --message "hello" [--conversation-id <id>]',
+    );
 
     if (typeof message !== "string") {
-      throw new Error('Missing message. Usage: agentkit chat --message "hello"');
+      throw new Error('Missing message. Usage: agentkit chat --message "hello" [--conversation-id <id>]');
     }
 
-    const result = await runAgentMessageFromCwd(process.cwd(), { message });
+    const result = await runAgentMessageFromCwd(process.cwd(), { message, conversationId });
     console.log(result.message.content);
     return;
   }
@@ -217,6 +241,8 @@ async function main() {
       const result = await migrateLocalDatabase(process.cwd());
       console.log("Local database migrated");
       console.log(`Database: ${result.databasePath}`);
+      console.log(`Migrations: ${result.migrationsPath ?? "none"}`);
+      console.log(`Applied:    ${result.migrationsApplied.length > 0 ? result.migrationsApplied.join(", ") : "none"}`);
       console.log(`Schema:   ${result.schemaPath ?? "none"}`);
       return;
     }
@@ -230,6 +256,8 @@ async function main() {
       console.log("Local database reset");
       console.log(`Deleted:  ${result.resetPath}`);
       console.log(`Database: ${result.databasePath}`);
+      console.log(`Migrations: ${result.migrationsPath ?? "none"}`);
+      console.log(`Applied:    ${result.migrationsApplied.length > 0 ? result.migrationsApplied.join(", ") : "none"}`);
       console.log(`Schema:   ${result.schemaPath ?? "none"}`);
       return;
     }
@@ -252,6 +280,8 @@ async function main() {
       const result = await seedLocalDatabase(process.cwd(), seedFile);
       console.log("Local database seeded");
       console.log(`Database: ${result.databasePath}`);
+      console.log(`Migrations: ${result.migrationsPath ?? "none"}`);
+      console.log(`Applied:    ${result.migrationsApplied.length > 0 ? result.migrationsApplied.join(", ") : "none"}`);
       console.log(`Schema:   ${result.schemaPath ?? "none"}`);
       console.log(`Seed:     ${result.seedPath}`);
       return;
@@ -261,10 +291,39 @@ async function main() {
   }
 
   if (args.command === "eval") {
-    const [subcommand] = args.positional;
+    const [subcommand, conversationId] = args.positional;
+
+    if (subcommand === "from-conversation") {
+      if (!conversationId) {
+        throw new Error("Missing conversation id. Usage: agentkit eval from-conversation <conversation-id> [--out <path>] [--force]");
+      }
+
+      const out = parseOptionalStringFlag(
+        args.flags.out,
+        "out",
+        "agentkit eval from-conversation <conversation-id> --out <path>",
+      );
+      const name = parseOptionalStringFlag(
+        args.flags.name,
+        "name",
+        "agentkit eval from-conversation <conversation-id> --name <name>",
+      );
+      const result = await writeEvalFromConversation(process.cwd(), {
+        conversationId,
+        out,
+        name,
+        force: args.flags.force === true,
+      });
+
+      console.log("Eval created from conversation");
+      console.log(`Conversation: ${result.conversationId}`);
+      console.log(`File:         ${relativePath(result.root, result.file)}`);
+      console.log(`Turns:        ${result.turns}`);
+      return;
+    }
 
     if (subcommand !== "run") {
-      throw new Error("Usage: agentkit eval run");
+      throw new Error("Usage: agentkit eval run | agentkit eval from-conversation <conversation-id> [--out <path>] [--force]");
     }
 
     const summary = await runEvalsFromCwd(process.cwd());
@@ -287,10 +346,132 @@ async function main() {
     return;
   }
 
+  if (args.command === "improve") {
+    const [subcommand, bundlePath] = args.positional;
+
+    if (subcommand === "collect") {
+      const since = parseOptionalStringFlag(args.flags.since, "since", 'agentkit improve collect --since "24h"');
+      const conversationId = parseOptionalStringFlag(
+        args.flags["conversation-id"] ?? args.flags.conversation,
+        "conversation id",
+        "agentkit improve collect --conversation-id <id>",
+      );
+      const out = parseOptionalStringFlag(args.flags.out, "out", "agentkit improve collect --out <directory>");
+      const deployState = args.flags.deploy === true ? await requireLocalDeployState() : null;
+      const apiUrl = args.flags.deploy === true ? await resolveCloudApiUrl(args.flags.api) : null;
+      const cloudAuth = apiUrl ? await readCloudAuthForApiUrl(apiUrl) : null;
+      const result = args.flags.deploy === true
+        ? await collectDeployImproveBundle(process.cwd(), {
+            deployId: deployState?.deploy_id ?? "",
+            since,
+            conversationId,
+            out,
+            collector: {
+              ...(cloudAuth && apiUrl && deployState
+                ? {
+                    exportEvidence: (input: { deployId: string; since?: string; conversationId?: string }) =>
+                      fetchDeployImproveEvidence(apiUrl, input),
+                  }
+                : {}),
+              listConversations: () => fetchDeployConversationJson(process.cwd(), "/v1/conversations"),
+              getTrace: (id: string) =>
+                fetchDeployConversationJson(process.cwd(), `/v1/conversations/${encodeURIComponent(id)}/trace`),
+            },
+          })
+        : await collectLocalImproveBundle(process.cwd(), {
+            since,
+            conversationId,
+            out,
+          });
+
+      console.log("Improve bundle collected");
+      console.log(`Source:    ${result.source}`);
+      console.log(`Directory: ${relativePath(result.root, result.directory)}`);
+      console.log(`Bundle:    ${relativePath(result.root, result.bundlePath)}`);
+      console.log(`Report:    ${relativePath(result.root, result.reportPath)}`);
+      console.log(`Traces:    ${result.traceCount}`);
+      console.log("");
+      console.log(`Next:      agentkit improve evals ${relativePath(result.root, result.directory)}`);
+      console.log(`Replay:    agentkit replay ${relativePath(result.root, result.directory)} --against local`);
+      return;
+    }
+
+    if (subcommand === "evals") {
+      if (!bundlePath) {
+        throw new Error("Missing bundle path. Usage: agentkit improve evals <bundle-dir-or-json> [--force]");
+      }
+
+      const result = await generateImproveEvals(process.cwd(), {
+        bundle: bundlePath,
+        force: args.flags.force === true,
+      });
+
+      console.log("Improve evals generated");
+      console.log(`Bundle: ${relativePath(result.root, result.bundlePath)}`);
+      console.log(`Files:  ${result.files.length}`);
+      for (const file of result.files) {
+        console.log(`  ${relativePath(result.root, file)}`);
+      }
+      if (result.skipped.length > 0) {
+        console.log(`Skipped: ${result.skipped.length}`);
+        for (const skipped of result.skipped) {
+          console.log(`  ${skipped.trace_id}: ${skipped.reason}`);
+        }
+      }
+      return;
+    }
+
+    throw new Error("Usage: agentkit improve collect [--deploy] [--since <duration|iso>] [--conversation-id <id>] [--out <directory>] | agentkit improve evals <bundle-dir-or-json> [--force]");
+  }
+
+  if (args.command === "replay") {
+    const [bundlePath] = args.positional;
+
+    if (!bundlePath) {
+      throw new Error("Missing bundle path. Usage: agentkit replay <bundle-dir-or-json> --against local");
+    }
+
+    const against = parseOptionalStringFlag(args.flags.against, "against", "agentkit replay <bundle> --against local") ?? "local";
+
+    if (against !== "local") {
+      throw new Error("Usage: agentkit replay <bundle-dir-or-json> --against local");
+    }
+
+    const result = await replayImproveBundle(process.cwd(), {
+      bundle: bundlePath,
+      against,
+    });
+
+    for (const item of result.results) {
+      console.log(`${item.status.toUpperCase()} ${item.conversation_id} (${item.turns} turns)`);
+      if (item.error) {
+        console.log(`  - ${item.error}`);
+      }
+    }
+
+    console.log("");
+    console.log(`Replay passed: ${result.passed}`);
+    console.log(`Replay failed: ${result.failed}`);
+    console.log(`Replay skipped: ${result.skipped}`);
+
+    if (result.failed > 0) {
+      process.exitCode = 1;
+    }
+
+    return;
+  }
+
   if (args.command === "conversations") {
     const [subcommand, conversationId] = args.positional;
+    const fromDeploy = args.flags.deploy === true;
 
     if (subcommand === "list") {
+      if (fromDeploy) {
+        const payload = await fetchDeployConversationJson(process.cwd(), "/v1/conversations");
+        printJson(payload);
+        return;
+      }
+
       const conversations = await listConversationsFromCwd(process.cwd());
 
       if (conversations.length === 0) {
@@ -316,7 +497,16 @@ async function main() {
 
     if (subcommand === "show") {
       if (!conversationId) {
-        throw new Error("Missing conversation id. Usage: agentkit conversations show <conversation-id>");
+        throw new Error("Missing conversation id. Usage: agentkit conversations show <conversation-id> [--deploy]");
+      }
+
+      if (fromDeploy) {
+        const payload = await fetchDeployConversationJson(
+          process.cwd(),
+          `/v1/conversations/${encodeURIComponent(conversationId)}`,
+        );
+        printJson(payload);
+        return;
       }
 
       const conversation = await getConversationFromCwd(process.cwd(), conversationId);
@@ -333,7 +523,107 @@ async function main() {
       return;
     }
 
-    throw new Error("Usage: agentkit conversations list | agentkit conversations show <conversation-id>");
+    if (subcommand === "trace") {
+      if (!conversationId) {
+        throw new Error("Missing conversation id. Usage: agentkit conversations trace <conversation-id> [--deploy]");
+      }
+
+      if (fromDeploy) {
+        const trace = await fetchDeployConversationJson(
+          process.cwd(),
+          `/v1/conversations/${encodeURIComponent(conversationId)}/trace`,
+        );
+        printJson(trace);
+        return;
+      }
+
+      const trace = await getConversationTraceFromCwd(process.cwd(), conversationId);
+      console.log(JSON.stringify(trace, null, 2));
+      return;
+    }
+
+    throw new Error("Usage: agentkit conversations list [--deploy] | agentkit conversations show <conversation-id> [--deploy] | agentkit conversations trace <conversation-id> [--deploy]");
+  }
+
+  if (args.command === "knowledge") {
+    await handleKnowledgeCommand(args);
+    return;
+  }
+
+  if (args.command === "feedback") {
+    await handleFeedbackCommand(args);
+    return;
+  }
+
+  if (args.command === "sync") {
+    const [subcommand] = args.positional;
+
+    if (subcommand === "init") {
+      const result = await initializeSyncScaffold(process.cwd(), {
+        force: args.flags.force === true,
+      });
+
+      console.log("Sync scaffold ready");
+      if (result.files.length === 0) {
+        console.log("Files: none written; existing files kept");
+      } else {
+        console.log(`Files: ${result.files.join(", ")}`);
+      }
+      return;
+    }
+
+    if (subcommand === "run") {
+      const file = parseOptionalStringFlag(args.flags.file, "file", "agentkit sync run --file <path>");
+      const result = await runCapsuleSync(process.cwd(), { file });
+
+      console.log("Sync completed");
+      console.log(`File:   ${relativePath(result.root, result.file)}`);
+      console.log(`Output: ${JSON.stringify(result.output)}`);
+      return;
+    }
+
+    throw new Error("Usage: agentkit sync init [--force] | agentkit sync run [--file <path>]");
+  }
+
+  if (args.command === "spec") {
+    const [subcommand] = args.positional;
+
+    if (subcommand === "init") {
+      const brief = parseRequiredStringFlag(
+        args.flags.brief,
+        "brief",
+        'agentkit spec init --brief "agent for a real estate brokerage"',
+      );
+      const out = parseOptionalStringFlag(args.flags.out, "out", "agentkit spec init --out <path>");
+      const result = await initializeAgentSpec(process.cwd(), {
+        brief,
+        out,
+        force: args.flags.force === true,
+      });
+
+      console.log("Agent spec created");
+      console.log(`File: ${relativePath(result.root, result.file)}`);
+      return;
+    }
+
+    if (subcommand === "check") {
+      const file = parseOptionalStringFlag(args.flags.file, "file", "agentkit spec check --file <path>");
+      const result = await checkAgentSpec(process.cwd(), file);
+
+      if (result.ok) {
+        console.log(`Agent spec ok: ${relativePath(result.root, result.file)}`);
+        return;
+      }
+
+      console.log(`Agent spec incomplete: ${relativePath(result.root, result.file)}`);
+      for (const heading of result.missingHeadings) {
+        console.log(`  - missing ## ${heading}`);
+      }
+      process.exitCode = 1;
+      return;
+    }
+
+    throw new Error('Usage: agentkit spec init --brief "<owner request>" [--out <path>] [--force] | agentkit spec check [--file <path>]');
   }
 
   if (args.command === "inspect") {
@@ -351,8 +641,27 @@ async function main() {
 
   if (args.command === "login") {
     const token = parseRequiredStringFlag(args.flags.token, "token", "agentkit login --token <token> [--api <url>]");
-    await writeCloudAuth({ apiUrl: parseCloudApiUrl(args.flags.api), token });
-    console.log("AgentKit Cloud token stored.");
+    const apiUrl = parseCloudApiUrl(args.flags.api);
+    const verified = await verifyCloudLogin(apiUrl, token);
+    await writeCloudAuth({ apiUrl, token });
+    const email = verified.me.account?.email;
+    console.log(email ? `Logged in to AgentKit Cloud as ${email}.` : "AgentKit Cloud token verified and stored.");
+
+    const hasHostedDeploy = (verified.capabilities.capabilities ?? []).some(
+      (capability) =>
+        (capability.name === "cloudflare_deploy_alpha" || capability.name === hostedDeployEntitlement) &&
+        capability.status === "active",
+    );
+    console.log(
+      hasHostedDeploy
+        ? "Entitlement: hosted deploy active."
+        : `Warning: cloudflare_deploy_alpha or ${hostedDeployEntitlement} entitlement was not found for this account.`,
+    );
+
+    if (process.env.AGENTKIT_CLOUD_API_TOKEN && process.env.AGENTKIT_CLOUD_API_TOKEN !== token) {
+      console.log("Warning: AGENTKIT_CLOUD_API_TOKEN is set and will override this saved login in the current shell.");
+    }
+
     return;
   }
 
@@ -362,94 +671,317 @@ async function main() {
     return;
   }
 
-  if (args.command === "deploy") {
-    const [deploySubcommand] = args.positional;
+  if (args.command === "account") {
+    const [noun, verb, value] = args.positional;
 
-    if (deploySubcommand === "doctor") {
-      const report = await checkDeployReadiness({
-        apiUrl: await resolveCloudApiUrl(args.flags.api),
-        requireLogin: !args.flags.anonymous,
-      });
-      printDeployReadinessReport(report);
+    if (noun !== "token") {
+      throw new Error("Usage: agentkit account token create <name> [--use] [--out <path>] | list | revoke <token-id> [--api <url>]");
+    }
 
-      if (!report.ok) {
-        process.exitCode = 1;
-      }
+    const apiUrl = await resolveCloudApiUrl(args.flags.api);
 
-      return;
-    }
+    if (verb === "create" && value) {
+      const payload = (await cloudApiRequest(apiUrl, "/v1/account/tokens", {
+        method: "POST",
+        body: JSON.stringify({ name: value }),
+      })) as AccountApiTokenCreateResponse;
+      const token = payload.token;
 
-    if (deploySubcommand === "status" || deploySubcommand === "pause" || deploySubcommand === "resume") {
-      const state = await requireLocalDeployState();
-      const apiUrl = await resolveCloudApiUrl(args.flags.api);
+      if (!token?.token || !token.id) {
+        throw new AgentKitError("account_token_invalid", "AgentKit Cloud returned an invalid account token payload.");
+      }
 
-      if (deploySubcommand === "status") {
-        const payload = await cloudApiRequest(apiUrl, `/v1/deploys/${encodeURIComponent(state.deploy_id)}`, {
-          method: "GET",
-        });
+      const outPath = parseOptionalStringFlag(
+        args.flags.out,
+        "out",
+        "agentkit account token create <name> [--api <url>] [--use] [--out <path>]",
+      );
+
+      if (outPath) {
+        const absolutePath = resolve(process.cwd(), outPath);
+        await writeSecretJson(absolutePath, payload);
+        console.log(`Account token written to ${absolutePath}`);
+      } else {
         printJson(payload);
-        return;
       }
 
-      const payload = await cloudApiRequest(apiUrl, `/v1/deploys/${encodeURIComponent(state.deploy_id)}/${deploySubcommand}`, {
+      if (args.flags.use === true) {
+        await writeCloudAuth({ apiUrl, token: token.token });
+        console.log(`Saved ${token.id} as the current AgentKit Cloud login.`);
+      }
+
+      return;
+    }
+
+    if (verb === "list" && !value) {
+      const payload = (await cloudApiRequest(apiUrl, "/v1/account/tokens", {
+        method: "GET",
+      })) as AccountApiTokenListResponse;
+      printJson(payload);
+      return;
+    }
+
+    if (verb === "revoke" && value) {
+      const payload = await cloudApiRequest(apiUrl, `/v1/account/tokens/${encodeURIComponent(value)}/revoke`, {
         method: "POST",
       });
       printJson(payload);
       return;
     }
 
-    const target = resolveDeployTarget(parseTargetFlag(args.flags.target, "deploy"));
-    const anonymous = Boolean(args.flags.anonymous);
+    throw new Error("Usage: agentkit account token create <name> [--use] [--out <path>] | list | revoke <token-id> [--api <url>]");
+  }
 
-    if (target.id === "vps") {
-      const host = parseRequiredStringFlag(args.flags.host, "host", "agentkit deploy --target vps --host <host>");
-      const container = await buildAgentCapsule(process.cwd(), { target: "container" });
-      const plan = await prepareVpsDeploy(container, { host, dryRun: Boolean(args.flags["dry-run"]) });
-      printBuildResult(container);
-      printVpsDeployPlan(plan);
-      return;
-    }
+  if (args.command === "billing") {
+    const [subcommand, intentId] = args.positional;
+    const apiUrl = await resolveCloudApiUrl(args.flags.api);
 
-    if (!args.flags["dry-run"] && !args.flags["local-wrangler"]) {
-      const report = await checkDeployReadiness({
-        apiUrl: await resolveCloudApiUrl(args.flags.api),
-        requireLogin: !anonymous,
-      });
+    if (subcommand === "checkout") {
+      const slots = parsePositiveIntegerFlag(
+        args.flags.slots,
+        "slots",
+        "agentkit billing checkout --slots <count> [--email <email>] [--api <url>]",
+      );
+      const email = parseOptionalStringFlag(
+        args.flags.email,
+        "email",
+        "agentkit billing checkout --slots <count> --email <email>",
+      );
+      const payload = (await cloudApiRequest(apiUrl, "/v1/billing/checkout", {
+        method: "POST",
+        body: JSON.stringify({
+          slots,
+          ...(email ? { email } : {}),
+        }),
+      })) as BillingCheckoutResponse;
+      const checkoutUrl = payload.checkout?.url;
+      const billingIntentId = payload.billing_intent?.id;
+      const secret = payload.billing_intent?.secret;
+
+      if (!checkoutUrl || !billingIntentId || !secret) {
+        throw new AgentKitError("billing_checkout_invalid", "AgentKit Cloud returned an invalid billing checkout payload.");
+      }
 
-      if (!report.ok) {
-        printDeployReadinessReport(report);
-        throw new AgentKitError(
-          "deploy_readiness_failed",
-          "Fix deploy readiness failures before running agentkit deploy.",
-        );
+      if (args.flags.json === true) {
+        printJson(payload);
+      } else {
+        console.log("AgentKit Cloud checkout");
+        console.log("");
+        console.log(`URL:    ${checkoutUrl}`);
+        console.log(`Intent: ${billingIntentId}`);
+        console.log(`Secret: ${secret}`);
+        console.log("");
+        console.log(`After payment: agentkit billing claim ${billingIntentId} --secret ${secret} --api ${apiUrl}`);
       }
-    }
 
-    const result = await buildAgentCapsule(process.cwd(), { target: target.id });
-    if (result.target !== "cloudflare") {
-      throw new Error(`Unsupported AgentKit Cloud deploy target: ${result.target}`);
-    }
-    printBuildResult(result);
+      if (args.flags.open === true) {
+        await openLocalUrl(checkoutUrl);
+      }
 
-    if (args.flags["dry-run"]) {
-      console.log("");
-      console.log("Dry run only. Artifact is ready for AgentKit Cloud.");
       return;
     }
 
-    if (args.flags["local-wrangler"]) {
-      await deployCloudflare(result.wranglerPath, result.buildDir);
+    if (subcommand === "status" && intentId) {
+      const secret = parseRequiredStringFlag(
+        args.flags.secret,
+        "secret",
+        "agentkit billing status <billing-intent-id> --secret <secret> [--api <url>]",
+      );
+      const payload = (await cloudApiRequest(
+        apiUrl,
+        `/v1/billing/checkout-intents/${encodeURIComponent(intentId)}?secret=${encodeURIComponent(secret)}`,
+        { method: "GET" },
+      )) as BillingCheckoutIntentResponse;
+      printJson(payload);
       return;
     }
 
-    const apiUrl = await resolveCloudApiUrl(args.flags.api);
-    const auth = await readCloudAuth();
-    const deploy = await deployBuildToAgentKitCloud(result, {
-      apiUrl,
-      apiToken: auth?.token,
-      anonymous: anonymous || !auth?.token,
-    });
+    if (subcommand === "claim" && intentId) {
+      const secret = parseRequiredStringFlag(
+        args.flags.secret,
+        "secret",
+        "agentkit billing claim <billing-intent-id> --secret <secret> [--token-name <name>] [--api <url>]",
+      );
+      const tokenName = parseOptionalStringFlag(
+        args.flags["token-name"],
+        "token-name",
+        "agentkit billing claim <billing-intent-id> --secret <secret> --token-name <name>",
+      );
+      const payload = (await cloudApiRequest(apiUrl, `/v1/billing/checkout-intents/${encodeURIComponent(intentId)}/claim`, {
+        method: "POST",
+        body: JSON.stringify({
+          secret,
+          ...(tokenName ? { token_name: tokenName } : {}),
+        }),
+      })) as BillingClaimResponse;
+      const token = payload.token;
+
+      if (!token?.token || !token.id) {
+        throw new AgentKitError("billing_claim_invalid", "AgentKit Cloud returned an invalid billing claim payload.");
+      }
+
+      await writeCloudAuth({ apiUrl, token: token.token });
+
+      const outPath = parseOptionalStringFlag(
+        args.flags.out,
+        "out",
+        "agentkit billing claim <billing-intent-id> --secret <secret> [--out <path>]",
+      );
+
+      if (outPath) {
+        const absolutePath = resolve(process.cwd(), outPath);
+        await writeSecretJson(absolutePath, payload);
+        console.log(`Account token written to ${absolutePath}`);
+      } else if (args.flags.json === true) {
+        printJson(payload);
+      } else {
+        console.log("AgentKit Cloud account token claimed and saved.");
+        console.log(`Token: ${token.id}`);
+        console.log(`API:   ${apiUrl}`);
+      }
+
+      return;
+    }
+
+    if (subcommand === "portal") {
+      const payload = (await cloudApiRequest(apiUrl, "/v1/billing/portal", {
+        method: "POST",
+        body: JSON.stringify({}),
+      })) as BillingPortalResponse;
+      const portalUrl = payload.portal?.url;
+
+      if (!portalUrl) {
+        throw new AgentKitError("billing_portal_invalid", "AgentKit Cloud returned an invalid billing portal payload.");
+      }
+
+      if (args.flags.json === true) {
+        printJson(payload);
+      } else {
+        console.log("AgentKit Cloud billing portal");
+        console.log(`URL: ${portalUrl}`);
+      }
+
+      if (args.flags.open === true) {
+        await openLocalUrl(portalUrl);
+      }
+
+      return;
+    }
+
+    throw new Error(
+      "Usage: agentkit billing checkout --slots <count> [--email <email>] | status <intent-id> --secret <secret> | claim <intent-id> --secret <secret> | portal [--api <url>]",
+    );
+  }
+
+  if (args.command === "deploy") {
+    const [deploySubcommand] = args.positional;
+
+    if (deploySubcommand === "smoke") {
+      const message =
+        parseOptionalStringFlag(args.flags.message ?? args.flags.smoke, "message", 'agentkit deploy smoke --message "hello"') ??
+        "hello";
+      const state = await requireLocalDeployState();
+      const token = await readDeployAccessTokenForHostedRequest(process.cwd());
+      await runDeploySmoke({
+        deployUrl: requireDeployUrl(state),
+        message,
+        token,
+      });
+      return;
+    }
+
+    if (deploySubcommand === "doctor") {
+      const report = await checkDeployReadiness({
+        apiUrl: await resolveCloudApiUrl(args.flags.api),
+        requireLogin: !args.flags.anonymous,
+      });
+      printDeployReadinessReport(report);
+
+      if (!report.ok) {
+        process.exitCode = 1;
+      }
+
+      return;
+    }
+
+    if (deploySubcommand === "status" || deploySubcommand === "pause" || deploySubcommand === "resume") {
+      const state = await requireLocalDeployState();
+      const apiUrl = await resolveCloudApiUrl(args.flags.api);
+
+      if (deploySubcommand === "status") {
+        const payload = await cloudApiRequest(apiUrl, `/v1/deploys/${encodeURIComponent(state.deploy_id)}`, {
+          method: "GET",
+        });
+        printJson(payload);
+        return;
+      }
+
+      const payload = await cloudApiRequest(apiUrl, `/v1/deploys/${encodeURIComponent(state.deploy_id)}/${deploySubcommand}`, {
+        method: "POST",
+      });
+      printJson(payload);
+      return;
+    }
+
+    const target = resolveDeployTarget(parseTargetFlag(args.flags.target, "deploy"));
+    const anonymous = Boolean(args.flags.anonymous);
+    const smokeMessage = parseOptionalStringFlag(args.flags.smoke, "smoke", 'agentkit deploy --smoke "hello"');
+
+    if (target.id === "vps") {
+      const host = parseRequiredStringFlag(args.flags.host, "host", "agentkit deploy --target vps --host <host>");
+      const container = await buildAgentCapsule(process.cwd(), { target: "container" });
+      const plan = await prepareVpsDeploy(container, { host, dryRun: Boolean(args.flags["dry-run"]) });
+      printBuildResult(container);
+      printVpsDeployPlan(plan);
+      return;
+    }
+
+    if (!args.flags["dry-run"] && !args.flags["local-wrangler"]) {
+      const report = await checkDeployReadiness({
+        apiUrl: await resolveCloudApiUrl(args.flags.api),
+        requireLogin: !anonymous,
+      });
+
+      if (!report.ok) {
+        printDeployReadinessReport(report);
+        throw new AgentKitError(
+          "deploy_readiness_failed",
+          "Fix deploy readiness failures before running agentkit deploy.",
+        );
+      }
+    }
+
+    const result = await buildAgentCapsule(process.cwd(), { target: target.id });
+    if (result.target !== "cloudflare") {
+      throw new Error(`Unsupported AgentKit Cloud deploy target: ${result.target}`);
+    }
+    printBuildResult(result);
+
+    if (args.flags["dry-run"]) {
+      console.log("");
+      console.log("Dry run only. Artifact is ready for AgentKit Cloud.");
+      return;
+    }
+
+    if (args.flags["local-wrangler"]) {
+      await deployCloudflare(result.wranglerPath, result.buildDir);
+      return;
+    }
+
+    const apiUrl = await resolveCloudApiUrl(args.flags.api);
+    const auth = anonymous ? null : await readCloudAuthForApiUrl(apiUrl);
+    const deploy = await deployBuildToAgentKitCloud(result, {
+      apiUrl,
+      apiToken: anonymous ? null : auth?.token,
+      anonymous: anonymous || !auth?.token,
+    });
     const statePath = await writeLocalDeployState(result.root, deploy);
+    const chatAccess = await ensureDeployChatAccessToken({
+      apiUrl,
+      root: result.root,
+      deployId: deploy.deploy.id,
+      skip: anonymous || !auth?.token,
+    });
 
     console.log("");
     console.log("Deploy ready");
@@ -457,13 +989,40 @@ async function main() {
     console.log(`Project:   ${deploy.project.id}`);
     console.log(`Deploy:    ${deploy.deploy.id}`);
     console.log(`State:     ${statePath}`);
+
+    if (chatAccess?.status === "ready") {
+      console.log(`Chat auth: ${relativePath(process.cwd(), chatAccess.path)}`);
+    } else if (chatAccess?.status === "skipped") {
+      console.log("Chat auth: anonymous deploy; no local chat token was created.");
+    } else if (chatAccess?.status === "failed") {
+      console.log(`Chat auth: could not create local chat token. ${formatReadinessError(chatAccess.error)}`);
+      console.log(`Run:       agentkit access token create ${defaultDeployChatAccessTokenName} --out ${defaultDeployChatAccessTokenPath}`);
+    }
+
+    if (smokeMessage) {
+      if (chatAccess?.status === "failed") {
+        throw new AgentKitError("deploy_smoke_failed", "Could not run deploy smoke because chat access token creation failed.");
+      }
+
+      await runDeploySmoke({
+        deployUrl: requireDeployUrl({
+          deploy_id: deploy.deploy.id,
+          url: deploy.deploy.url,
+        }),
+        message: smokeMessage,
+        token:
+          chatAccess?.status === "ready"
+            ? await readDeployAccessTokenForUi(chatAccess.path)
+            : undefined,
+      });
+    }
     return;
   }
 
   if (args.command === "secret") {
     const [subcommand, name, ...valueParts] = args.positional;
-    const projectId = await resolveProjectIdForSecretCommand(process.cwd());
     const apiUrl = await resolveCloudApiUrl(args.flags.api);
+    const projectId = await resolveProjectIdForSecretCommand(process.cwd(), apiUrl);
 
     if (subcommand === "list") {
       const payload = await cloudApiRequest(apiUrl, `/v1/projects/${encodeURIComponent(projectId)}/secrets`, {
@@ -474,10 +1033,19 @@ async function main() {
     }
 
     if (subcommand === "set") {
-      const value = valueParts.join(" ");
+      const value = await resolveSecretInputValue({
+        name,
+        valueParts,
+        stdinFlag: args.flags.stdin,
+        fromEnvFlag: args.flags["from-env"],
+        fromLocalEnvFlag: args.flags["from-local-env"],
+        localEnvRoot: args.flags["from-local-env"] !== undefined ? await findAgentCapsuleRoot(process.cwd()) : undefined,
+        usage: "agentkit secret set <NAME> <VALUE> | agentkit secret set <NAME> --stdin | agentkit secret set <NAME> --from-env [ENV_NAME] | agentkit secret set <NAME> --from-local-env [--api <url>]",
+        inlineSensitiveHelp: "Prefer --stdin, --from-env, or --from-local-env so the value does not enter shell history.",
+      });
 
-      if (!name || value.length === 0) {
-        throw new Error("Usage: agentkit secret set <NAME> <VALUE> [--api <url>]");
+      if (!name) {
+        throw new Error("Usage: agentkit secret set <NAME> <VALUE> | agentkit secret set <NAME> --stdin | agentkit secret set <NAME> --from-env [ENV_NAME] | agentkit secret set <NAME> --from-local-env [--api <url>]");
       }
 
       const payload = await cloudApiRequest(apiUrl, `/v1/projects/${encodeURIComponent(projectId)}/secrets/${encodeURIComponent(name)}`, {
@@ -488,6 +1056,15 @@ async function main() {
       return;
     }
 
+    if (subcommand === "sync") {
+      if (args.flags["from-local"] !== true) {
+        throw new Error("Usage: agentkit secret sync --from-local [--api <url>]");
+      }
+
+      await syncHostedSecretsFromLocal({ apiUrl, projectId });
+      return;
+    }
+
     if (subcommand === "unset") {
       if (!name) {
         throw new Error("Usage: agentkit secret unset <NAME> [--api <url>]");
@@ -500,14 +1077,14 @@ async function main() {
       return;
     }
 
-    throw new Error("Usage: agentkit secret set <NAME> <VALUE> | agentkit secret list | agentkit secret unset <NAME>");
+    throw new Error("Usage: agentkit secret set <NAME> <VALUE> | agentkit secret set <NAME> --stdin | agentkit secret set <NAME> --from-env [ENV_NAME] | agentkit secret set <NAME> --from-local-env | agentkit secret sync --from-local | agentkit secret list | agentkit secret unset <NAME>");
   }
 
   if (args.command === "access") {
     const [subcommand, noun, name] = args.positional;
 
     if (subcommand !== "token") {
-      throw new Error("Usage: agentkit access token create <name> | list | revoke <token-id> [--api <url>]");
+      throw new Error("Usage: agentkit access token create <name> [--out <path>] | list | revoke <token-id> [--api <url>]");
     }
 
     const state = await requireLocalDeployState();
@@ -518,7 +1095,7 @@ async function main() {
         method: "POST",
         body: JSON.stringify({ name }),
       });
-      printJson(payload);
+      await printJsonOrWrite(payload, args.flags.out, "agentkit access token create <name> [--api <url>] [--out <path>]");
       return;
     }
 
@@ -540,7 +1117,7 @@ async function main() {
       return;
     }
 
-    throw new Error("Usage: agentkit access token create <name> | list | revoke <token-id> [--api <url>]");
+    throw new Error("Usage: agentkit access token create <name> [--out <path>] | list | revoke <token-id> [--api <url>]");
   }
 
   if (args.command === "channels") {
@@ -548,6 +1125,121 @@ async function main() {
     return;
   }
 
+  if (args.command === "transcribe") {
+    await handleTranscribeCommand(args);
+    return;
+  }
+
+  if (args.command === "skills") {
+    const [subcommand] = args.positional;
+    const root = await findAgentCapsuleRoot(process.cwd());
+
+    if (subcommand === "status") {
+      const status = await checkDefaultSkillStatus(root);
+      printSkillStatus(status);
+      if (status.status !== "current") {
+        process.exitCode = 1;
+      }
+      return;
+    }
+
+    if (subcommand === "sync") {
+      const result = await syncDefaultSkillFiles(root);
+      console.log(`Synced ${result.files.length} AgentKit skill files.`);
+      console.log("Status: current");
+      return;
+    }
+
+    throw new Error("Usage: agentkit skills status | agentkit skills sync");
+  }
+
+  if (args.command === "integrations") {
+    const [subcommand, provider] = args.positional;
+
+    if (provider !== undefined && provider !== "composio") {
+      throw new Error("Usage: agentkit integrations status | connect composio [--toolkit <slug>] [--callback-url <url>] [--api <url>]");
+    }
+
+    const state = await requireLocalDeployState();
+    const apiUrl = await resolveCloudApiUrl(args.flags.api);
+
+    if (subcommand === "status") {
+      const toolkit = parseOptionalStringFlag(
+        args.flags.toolkit,
+        "toolkit",
+        "agentkit integrations status --toolkit <slug>",
+      );
+      const payload = await cloudApiRequest(
+        apiUrl,
+        `/v1/deploys/${encodeURIComponent(state.deploy_id)}/integrations/composio/status${
+          toolkit ? `?toolkit=${encodeURIComponent(toolkit)}` : ""
+        }`,
+        { method: "GET" },
+      );
+      printJson(payload);
+      return;
+    }
+
+    if (subcommand === "connect" && provider === "composio") {
+      const toolkit = parseOptionalStringFlag(
+        args.flags.toolkit,
+        "toolkit",
+        "agentkit integrations connect composio --toolkit <slug>",
+      );
+      const callbackUrl = parseOptionalStringFlag(
+        args.flags["callback-url"],
+        "callback-url",
+        "agentkit integrations connect composio --callback-url <url>",
+      );
+      const payload = (await cloudApiRequest(
+        apiUrl,
+        `/v1/deploys/${encodeURIComponent(state.deploy_id)}/integrations/composio/connect-link`,
+        {
+          method: "POST",
+          body: JSON.stringify({
+            ...(toolkit ? { toolkit } : {}),
+            ...(callbackUrl ? { callback_url: callbackUrl } : {}),
+          }),
+        },
+      )) as {
+        connect_link?: {
+          toolkit?: string;
+          user_id?: string;
+          redirect_url?: string;
+          expires_at?: string;
+          connected_account_id?: string;
+          auth_config_source?: string;
+        };
+      };
+
+      const link = payload.connect_link;
+
+      if (!link?.redirect_url) {
+        throw new AgentKitError("integration_response_invalid", "AgentKit Cloud returned an invalid Composio connect-link payload.");
+      }
+
+      console.log("Composio connect link");
+      console.log(`Toolkit: ${link.toolkit ?? toolkit ?? "unknown"}`);
+      console.log(`User:    ${link.user_id ?? "unknown"}`);
+      if (link.auth_config_source) {
+        console.log(`Auth:    ${link.auth_config_source}`);
+      }
+      console.log(`URL:     ${link.redirect_url}`);
+
+      if (link.expires_at) {
+        console.log(`Expires: ${link.expires_at}`);
+      }
+
+      if (link.connected_account_id) {
+        console.log(`Account: ${link.connected_account_id}`);
+      }
+
+      return;
+    }
+
+    throw new Error("Usage: agentkit integrations status | connect composio [--toolkit <slug>] [--callback-url <url>] [--api <url>]");
+  }
+
   if (args.command === "env") {
     const [subcommand, name, ...valueParts] = args.positional;
     const root = await findAgentCapsuleRoot(process.cwd());
@@ -568,10 +1260,18 @@ async function main() {
     }
 
     if (subcommand === "set") {
-      const value = valueParts.join(" ");
+      const value = await resolveSecretInputValue({
+        name,
+        valueParts,
+        stdinFlag: args.flags.stdin,
+        fromEnvFlag: args.flags["from-env"],
+        fromLocalEnvFlag: undefined,
+        usage: "agentkit env set <NAME> <VALUE> | agentkit env set <NAME> --stdin | agentkit env set <NAME> --from-env [ENV_NAME]",
+        inlineSensitiveHelp: "Prefer --stdin or --from-env so the value does not enter shell history.",
+      });
 
-      if (!name || value.length === 0) {
-        throw new Error("Usage: agentkit env set <NAME> <VALUE>");
+      if (!name) {
+        throw new Error("Usage: agentkit env set <NAME> <VALUE> | agentkit env set <NAME> --stdin | agentkit env set <NAME> --from-env [ENV_NAME]");
       }
 
       await setCapsuleEnv(root, name, value);
@@ -589,7 +1289,7 @@ async function main() {
       return;
     }
 
-    throw new Error("Usage: agentkit env list | agentkit env set <NAME> <VALUE> | agentkit env unset <NAME>");
+    throw new Error("Usage: agentkit env list | agentkit env set <NAME> <VALUE> | agentkit env set <NAME> --stdin | agentkit env set <NAME> --from-env [ENV_NAME] | agentkit env unset <NAME>");
   }
 
   if (args.command === "docs") {
@@ -623,15 +1323,17 @@ async function main() {
 
     const root = await findAgentCapsuleRoot(process.cwd());
     const docs = findAgentKitDocs();
-    console.log(renderHandoffPrompt({ target, root, docsFull: docs.llmsFull, goal: goalParts.join(" ").trim() }));
+    console.log(renderHandoffPrompt({ target, root, docsLlms: docs.llms, goal: goalParts.join(" ").trim() }));
     return;
   }
 
   throw new Error(`Unknown command: ${args.command}`);
 }
 
-function renderHandoffPrompt(input: { target: string; root: string; docsFull: string; goal: string }): string {
+function renderHandoffPrompt(input: { target: string; root: string; docsLlms: string; goal: string }): string {
   const agentName = input.target === "claude" ? "Claude Code" : "Codex";
+  const skillRouter = join(input.root, "skills/agentkit-capsule/SKILL.md");
+  const skillLine = existsSync(skillRouter) ? `- ${skillRouter}\n` : "";
   const goal = input.goal
     ? `Owner request:
 ${input.goal}`
@@ -645,17 +1347,22 @@ ${input.root}
 Read these files first:
 
 - ${join(input.root, "AGENTKIT.md")}
-- ${input.docsFull}
+${skillLine}- ${input.docsLlms}
 
 ${goal}
 
 Rules:
-- Follow the AgentKit contract in llms-full.txt.
+- Start with the AgentKit capsule skill when it exists.
+- Use llms.txt as the docs router.
+- Read llms-full.txt only when a skill or ambiguous framework behavior requires the complete contract.
 - Treat the owner's request as the brief.
 - Build or update the agent inside this capsule as far as you can without asking for obvious restatements.
+- Do not wait for a wizard or recipe; implement directly in the capsule files.
 - Edit agent behavior in prompts/instructions.md.
 - Edit the agent contract in agentkit.config.ts.
 - Add TypeScript tools under tools/.
+- Keep the first useful version runnable with test/fake unless the owner has already chosen a real provider.
+- Before testing real conversation behavior, ask the owner to choose OpenRouter, OpenAI, Anthropic, or another supported provider. Do not choose for them.
 - Keep local secrets in .env only.
 - Do not commit or print secret values.
 - Do not edit .agentkit/ directly.
@@ -666,7 +1373,6 @@ Verification:
 Run these before you finish:
 
 \`\`\`sh
-npm install
 npm run typecheck
 npm run agentkit -- inspect
 npm run chat -- --message "hello"
@@ -678,883 +1384,282 @@ If you add a tool, also run a tool smoke test with the fake provider, for exampl
 npm run agentkit -- tool tool_name --input '{}'
 \`\`\`
 
+UI testing:
+- For local UI testing, run \`npm run dev\`, open the printed \`Chat:\` URL, and tell the owner the exact URL.
+- For hosted UI testing after deploy, run \`npm run agentkit -- chat-ui --deploy\`, open the printed \`Chat:\` URL, and tell the owner it is connected to the hosted deploy.
+- If the provider is still \`test/fake\`, say the UI was tested only with the deterministic fake provider.
+
 Final response:
 - Summarize what changed.
 - List files changed.
 - Paste the verification commands and results.
+- State whether testing used \`test/fake\` or a real provider selected by the owner.
 - Call out any missing user details or blocked checks.
 `;
 }
 
-type DeployReadinessStatus = "pass" | "fail" | "warn" | "info";
-
-type DeployReadinessCheck = {
-  status: DeployReadinessStatus;
-  title: string;
-  message: string;
-  action?: string;
-};
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
 
-type DeployReadinessReport = {
-  ok: boolean;
-  apiUrl: string;
-  context: DeployReadinessContext;
-  checks: DeployReadinessCheck[];
-};
-
-type CloudMeResponse = {
-  account?: {
-    email?: string;
-    status?: string;
-  };
-};
-
-type CloudCapabilitiesResponse = {
-  capabilities?: Array<{
-    name?: string;
-    status?: string;
-  }>;
-};
-
-type CloudSecretsResponse = {
-  secrets?: Array<{
-    name?: string;
-    status?: string;
-    updated_at?: string;
-  }>;
-};
-
-async function checkDeployReadiness(options: {
+async function ensureDeployChatAccessToken(options: {
   apiUrl: string;
-  requireLogin: boolean;
-}): Promise<DeployReadinessReport> {
-  const context = await loadDeployReadinessContext(process.cwd(), process.env);
-  const auth = await readCloudAuth();
-  const checks: DeployReadinessCheck[] = [];
-  let cloudAuthUsable = false;
-
-  if (context.runtime !== "edge") {
-    checks.push({
-      status: "fail",
-      title: "Target runtime",
-      message: 'Cloudflare deploy requires runtime: "edge" in agentkit.config.ts.',
-      action: "set runtime: \"edge\" before deploying to AgentKit Cloud",
-    });
-  } else {
-    checks.push({
-      status: "pass",
-      title: "Target runtime",
-      message: "Capsule is configured for edge deploy.",
-    });
+  root: string;
+  deployId: string;
+  skip: boolean;
+}): Promise<
+  | { status: "ready"; path: string; tokenId: string; created: boolean }
+  | { status: "skipped" }
+  | { status: "failed"; error: unknown }
+> {
+  if (options.skip) {
+    return { status: "skipped" };
   }
 
-  if (!auth?.token) {
-    checks.push({
-      status: options.requireLogin ? "fail" : "warn",
-      title: "Login",
-      message: options.requireLogin
-        ? "No AgentKit Cloud token was found for hosted production deploy."
-        : "No AgentKit Cloud token was found; deploy will request anonymous mode.",
-      action: "agentkit login --token <token>",
-    });
-  } else {
-    try {
-      const me = (await cloudApiRequest(options.apiUrl, "/v1/me", { method: "GET" })) as CloudMeResponse;
-      const email = me.account?.email;
-      checks.push({
-        status: "pass",
-        title: "Login",
-        message: email ? `Authenticated as ${email}.` : "AgentKit Cloud token is accepted.",
-      });
-      cloudAuthUsable = true;
-    } catch (error) {
-      checks.push({
-        status: "fail",
-        title: "Login",
-        message: `AgentKit Cloud rejected the stored token. ${formatReadinessError(error)}`,
-        action: "agentkit login --token <token>",
-      });
-    }
-  }
+  try {
+    const path = join(options.root, defaultDeployChatAccessTokenPath);
+    const existing = await readDeployAccessTokenFile(path);
 
-  if (cloudAuthUsable) {
-    try {
-      const payload = (await cloudApiRequest(options.apiUrl, "/v1/me/capabilities", {
-        method: "GET",
-      })) as CloudCapabilitiesResponse;
-      const capabilities = payload.capabilities ?? [];
-      const hasCloudflareAlpha = capabilities.some(
-        (capability) => capability.name === "cloudflare_deploy_alpha" && capability.status === "active",
+    if (existing?.deploy_id === options.deployId && existing.id) {
+      const listed = (await cloudApiRequest(
+        options.apiUrl,
+        `/v1/deploys/${encodeURIComponent(options.deployId)}/access-tokens`,
+        { method: "GET" },
+      )) as DeployAccessTokenListResponse;
+      const stillUsable = (listed.access_tokens ?? []).some(
+        (token) => token.id === existing.id && deployAccessTokenMetadataIsUsable(token),
       );
 
-      checks.push({
-        status: hasCloudflareAlpha ? "pass" : "fail",
-        title: "Deploy entitlement",
-        message: hasCloudflareAlpha
-          ? "cloudflare_deploy_alpha is active."
-          : "This account is missing the cloudflare_deploy_alpha entitlement.",
-        ...(hasCloudflareAlpha ? {} : { action: "log in with an invited AgentKit Cloud alpha token" }),
-      });
-    } catch (error) {
-      checks.push({
-        status: "fail",
-        title: "Deploy entitlement",
-        message: `Could not verify AgentKit Cloud capabilities. ${formatReadinessError(error)}`,
-      });
+      if (stillUsable) {
+        await chmod(path, 0o600);
+        return { status: "ready", path, tokenId: existing.id, created: false };
+      }
     }
-  }
-
-  if (context.agentKitManagedSecrets.length > 0) {
-    checks.push({
-      status: "info",
-      title: "AgentKit-managed secrets",
-      message: `${context.agentKitManagedSecrets.join(", ")} ${
-        context.agentKitManagedSecrets.length === 1 ? "is" : "are"
-      } provisioned by AgentKit Cloud during deploy.`,
-    });
-  }
 
-  if (context.accessMode === "private") {
-    checks.push({
-      status: "info",
-      title: "Private access",
-      message: "AGENTKIT_PRIVATE_TOKEN is required at runtime; AgentKit Cloud generates it and saves it in .agentkit/deploy.json.",
-    });
-  }
+    const created = (await cloudApiRequest(
+      options.apiUrl,
+      `/v1/deploys/${encodeURIComponent(options.deployId)}/access-tokens`,
+      {
+        method: "POST",
+        body: JSON.stringify({ name: defaultDeployChatAccessTokenName }),
+      },
+    )) as DeployAccessTokenCreateResponse;
+    const token = created.access_token;
 
-  if (context.userManagedSecrets.length === 0) {
-    checks.push({
-      status: "pass",
-      title: "Hosted secrets",
-      message: "No user-managed hosted secrets are required by this capsule.",
-    });
-  } else if (!cloudAuthUsable) {
-    checks.push({
-      status: options.requireLogin ? "fail" : "warn",
-      title: "Hosted secrets",
-      message: `Could not check hosted secrets without a valid AgentKit Cloud login. Required: ${context.userManagedSecrets.join(", ")}.`,
-      action: "agentkit secret list",
-    });
-  } else {
-    try {
-      const payload = (await cloudApiRequest(
-        options.apiUrl,
-        `/v1/projects/${encodeURIComponent(context.projectId)}/secrets`,
-        { method: "GET" },
-      )) as CloudSecretsResponse;
-      const hostedSecretNames = new Set((payload.secrets ?? []).map((secret) => secret.name).filter(isString));
-      const missing = context.userManagedSecrets.filter((name) => !hostedSecretNames.has(name));
-
-      if (missing.length === 0) {
-        checks.push({
-          status: "pass",
-          title: "Hosted secrets",
-          message: "All user-managed hosted secrets are set.",
-        });
-      } else {
-        for (const secret of missing) {
-          const localSource = context.localSecrets[secret];
-          checks.push({
-            status: "fail",
-            title: `Hosted secret ${secret}`,
-            message: localSource
-              ? `${secret} is present locally but has not been set in AgentKit Cloud.`
-              : `${secret} is required but missing from AgentKit Cloud.`,
-            action: secretSetCommand(secret, localSource),
-          });
-        }
-      }
-    } catch (error) {
-      checks.push({
-        status: "fail",
-        title: "Hosted secrets",
-        message: `Could not list hosted secrets for project ${context.projectId}. ${formatReadinessError(error)}`,
-        action: "agentkit secret list",
-      });
+    if (!token?.id || token.deploy_id !== options.deployId || !token.token) {
+      throw new AgentKitError("access_token_invalid", "AgentKit Cloud returned an invalid deploy access token payload.");
     }
-  }
 
-  return {
-    ok: checks.every((check) => check.status !== "fail"),
-    apiUrl: options.apiUrl,
-    context,
-    checks,
-  };
+    await writeSecretJson(path, created);
+    return { status: "ready", path, tokenId: token.id, created: true };
+  } catch (error) {
+    return { status: "failed", error };
+  }
 }
 
-function printDeployReadinessReport(report: DeployReadinessReport): void {
-  console.log("AgentKit deploy readiness");
-  console.log(`Project: ${report.context.projectName}`);
-  console.log(`Project ID: ${report.context.projectId}`);
-  console.log(`Target: ${report.context.target}`);
-  console.log(`API: ${report.apiUrl}`);
-  console.log("");
+function deployAccessTokenMetadataIsUsable(token: { expires_at?: string }): boolean {
+  if (!token.expires_at) {
+    return true;
+  }
 
-  for (const check of report.checks) {
-    console.log(`[${check.status}] ${check.title}: ${check.message}`);
+  const expiresAtMs = Date.parse(token.expires_at);
+  return Number.isFinite(expiresAtMs) && expiresAtMs > Date.now();
+}
 
-    if (check.action) {
-      console.log(`  Run: ${check.action}`);
-    }
+async function readDeployAccessTokenFile(path: string): Promise<{ id?: string; deploy_id?: string } | null> {
+  try {
+    const parsed = JSON.parse(await readFile(path, "utf8")) as DeployAccessTokenCreateResponse;
+    return parsed.access_token ?? null;
+  } catch {
+    return null;
   }
 }
 
-function secretSetCommand(secret: string, source: DeployReadinessContext["localSecrets"][string] | undefined): string {
-  if (source?.dotenv) {
-    return `agentkit secret set ${secret} <value-from-.env>`;
-  }
+async function writeSecretJson(path: string, value: unknown): Promise<void> {
+  await mkdir(dirname(path), { recursive: true });
+  await writeFile(path, `${JSON.stringify(value, null, 2)}\n`, { mode: 0o600 });
+  await chmod(path, 0o600);
+}
+
+async function requireLocalDeployState(): Promise<LocalDeployState> {
+  const state = await readLocalDeployStateIfExists(process.cwd());
 
-  if (source?.environment) {
-    return `agentkit secret set ${secret} "$${secret}"`;
+  if (!state) {
+    throw new Error("No .agentkit/deploy.json found. Run agentkit deploy first.");
   }
 
-  return `agentkit secret set ${secret} <value>`;
+  return state;
 }
 
-function formatReadinessError(error: unknown): string {
-  if (isAgentKitError(error)) {
-    return `${error.code}: ${error.message}`;
+function requireDeployUrl(state: Pick<LocalDeployState, "deploy_id" | "url">): string {
+  if (!state.url) {
+    throw new Error(`Deploy ${state.deploy_id} does not have a URL. Run agentkit deploy again.`);
   }
 
-  return error instanceof Error ? error.message : String(error);
+  return state.url;
 }
 
-function isString(value: unknown): value is string {
-  return typeof value === "string";
+async function readDeployAccessTokenForHostedRequest(cwd: string): Promise<string> {
+  const root = await findAgentCapsuleRoot(cwd);
+  return readDeployAccessTokenForUi(join(root, defaultDeployChatAccessTokenPath));
 }
 
-async function handleChannelsCommand(args: ParsedArgs): Promise<void> {
-  const [subcommand, first, second, third] = args.positional;
-
-  if (subcommand === "list") {
-    const deployState = await readDeployStateIfExists(process.cwd());
-
-    if (deployState) {
-      const channels = await cloudGet<{ channels: CloudChannel[] }>(
-        parseCloudApiUrl(args.flags.api),
-        `/v1/deploys/${encodeURIComponent(deployState.deploy_id)}/channels`,
-      );
-      printChannelsTable(channels.channels);
-      return;
-    }
+async function runDeploySmoke(input: { deployUrl: string; message: string; token?: string }): Promise<void> {
+  const headers = new Headers({ "Content-Type": "application/json" });
 
-    const capsule = await loadAgentCapsule(process.cwd());
-    printChannelsTable(
-      (capsule.config.channels ?? []).map((channel) => ({
-        id: "",
-        name: channel.name,
-        type: channel.type,
-        provider: channel.provider,
-        status: "local_config",
-        webhook_url: "",
-        required_secrets: channel.secrets.map((name) => ({ name, status: "missing" })),
-      })),
-    );
-    return;
-  }
-
-  if (subcommand === "add") {
-    const type = first;
-    const name = second;
-
-    if (!type || !name || (type !== "website" && type !== "telegram" && type !== "whatsapp")) {
-      throw new Error("Usage: agentkit channels add <website|telegram|whatsapp> <name> [--provider zapster|meta]");
-    }
-
-    const deployState = await readDeployStateRequired(process.cwd());
-    const provider = channelProviderForCli(type, args.flags.provider);
-    const payload = {
-      name,
-      type,
-      provider,
-      secrets: defaultChannelSecretsForCli(type, provider),
-    };
-    const response = await cloudPost<{ channel: CloudChannel }>(
-      parseCloudApiUrl(args.flags.api),
-      `/v1/deploys/${encodeURIComponent(deployState.deploy_id)}/channels`,
-      payload,
-    );
-    printChannelStatus(response.channel);
-    return;
-  }
-
-  if (subcommand === "setup") {
-    if (!first) {
-      throw new Error("Usage: agentkit channels setup <name> [--apply]");
-    }
-
-    const channel = await resolveCloudChannelByName(first, args.flags.api);
-    printChannelStatus(channel);
-    if (channel.type === "telegram") {
-      if (args.flags.apply) {
-        await applyTelegramWebhook(channel);
-        console.log("Telegram webhook updated.");
-      } else {
-        console.log(`Setup: call Telegram setWebhook with ${channel.webhook_url}`);
-        console.log("Use --apply to mutate Telegram webhook settings.");
-      }
-    } else if (channel.type === "whatsapp") {
-      console.log(`Next step: paste this URL into ${channel.provider}'s webhook settings.`);
-    } else {
-      console.log(`Website endpoint: ${channel.webhook_url}`);
-      console.log("Use this endpoint from the AgentKit website client or a signed server-to-server test.");
-    }
-    return;
-  }
-
-  if (subcommand === "status") {
-    if (!first) {
-      throw new Error("Usage: agentkit channels status <name>");
-    }
-
-    const channel = await resolveCloudChannelByName(first, args.flags.api);
-    printChannelStatus(channel);
-    await printChannelDeliverySummary(channel, args.flags.api);
-    return;
-  }
-
-  if (subcommand === "test") {
-    if (!first) {
-      throw new Error('Usage: agentkit channels test <name> [--message "hello"] [--fixture <path>]');
-    }
-
-    const channel = await resolveCloudChannelByName(first, args.flags.api);
-    const apiUrl = parseCloudApiUrl(args.flags.api);
-    const body = await channelTestBody(channel, args.flags.message, args.flags.fixture);
-    const path = new URL(channel.webhook_url).pathname;
-    const headers = channelTestHeaders(channel);
-    const response = await cloudFetch(apiUrl, path, {
-      method: channel.type === "whatsapp" && channel.provider === "meta" ? "POST" : "POST",
-      headers,
-      body,
-    });
-    const payload = await response.json();
-
-    console.log(JSON.stringify(payload, null, 2));
-    if (!response.ok) {
-      process.exitCode = 1;
-    }
-    return;
-  }
-
-  if (subcommand === "deliveries") {
-    if (first === "list") {
-      if (!second) {
-        throw new Error("Usage: agentkit channels deliveries list <name>");
-      }
-
-      const channel = await resolveCloudChannelByName(second, args.flags.api);
-      const response = await cloudGet<{ deliveries: CloudDelivery[] }>(
-        parseCloudApiUrl(args.flags.api),
-        `/v1/channels/${encodeURIComponent(channel.id)}/deliveries`,
-      );
-
-      if (response.deliveries.length === 0) {
-        console.log("No channel deliveries found.");
-        return;
-      }
-
-      console.log("ID\tCHANNEL\tDIRECTION\tSTATUS\tPROVIDER_EVENT\tRECEIVED");
-      for (const delivery of response.deliveries) {
-        console.log(
-          [
-            delivery.id,
-            delivery.channel_id,
-            delivery.direction,
-            delivery.status,
-            delivery.provider.event_id ?? "",
-            delivery.received_at,
-          ].join("\t"),
-        );
-      }
-      return;
-    }
-
-    if (first === "show") {
-      if (!second) {
-        throw new Error("Usage: agentkit channels deliveries show <delivery-id>");
-      }
-
-      const response = await cloudGet<{ delivery: CloudDelivery }>(
-        parseCloudApiUrl(args.flags.api),
-        `/v1/channel-deliveries/${encodeURIComponent(second)}`,
-      );
-      console.log(JSON.stringify(response.delivery, null, 2));
-      return;
-    }
-  }
-
-  throw new Error(
-    "Usage: agentkit channels list | add | setup | status | test | deliveries list | deliveries show",
-  );
-}
-
-type DeployState = LocalDeployState;
-
-type CloudChannel = {
-  id: string;
-  name: string;
-  type: "website" | "telegram" | "whatsapp";
-  provider: "agentkit" | "telegram" | "zapster" | "meta";
-  status: string;
-  webhook_url: string;
-  required_secrets: Array<{ name: string; status: string }>;
-};
-
-type CloudDelivery = {
-  id: string;
-  channel_id: string;
-  direction: string;
-  status: string;
-  provider: {
-    event_id?: string;
-  };
-  received_at: string;
-};
-
-async function applyTelegramWebhook(channel: CloudChannel): Promise<void> {
-  const botToken = process.env.TELEGRAM_BOT_TOKEN;
-  const secretToken = process.env.TELEGRAM_WEBHOOK_SECRET;
-
-  if (!botToken || !secretToken) {
-    throw new Error("TELEGRAM_BOT_TOKEN and TELEGRAM_WEBHOOK_SECRET must be set to apply Telegram setup.");
+  if (input.token) {
+    headers.set("Authorization", `Bearer ${input.token}`);
   }
 
   let response: Response;
 
   try {
-    response = await fetch(`https://api.telegram.org/bot${botToken}/setWebhook`, {
+    response = await fetch(new URL("/v1/chat", input.deployUrl).href, {
       method: "POST",
-      headers: { "Content-Type": "application/json" },
-      body: JSON.stringify({
-        url: channel.webhook_url,
-        secret_token: secretToken,
-        allowed_updates: ["message"],
-      }),
+      headers,
+      body: JSON.stringify({ message: input.message }),
     });
-  } catch {
-    throw new Error("Telegram setWebhook request failed before Telegram returned a response.");
-  }
-
-  const payload = await response.json().catch(() => ({}));
-
-  if (!response.ok || !isTelegramOk(payload)) {
-    throw new Error(readTelegramSetupError(payload, response.status));
-  }
-}
-
-function isTelegramOk(payload: unknown): payload is { ok: true } {
-  return Boolean(payload && typeof payload === "object" && "ok" in payload && payload.ok === true);
-}
-
-function readTelegramSetupError(payload: unknown, status: number): string {
-  if (payload && typeof payload === "object" && "description" in payload && typeof payload.description === "string") {
-    return `Telegram setWebhook failed: ${payload.description}`;
-  }
-
-  return `Telegram setWebhook failed with HTTP ${status}.`;
-}
-
-async function readDeployStateIfExists(cwd: string): Promise<DeployState | null> {
-  return readLocalDeployStateIfExists(cwd);
-}
-
-async function readDeployStateRequired(cwd: string): Promise<DeployState> {
-  const state = await readDeployStateIfExists(cwd);
-
-  if (!state?.deploy_id) {
-    throw new Error("No .agentkit/deploy.json found. Run agentkit deploy before creating hosted channels.");
-  }
-
-  return state;
-}
-
-function printChannelsTable(channels: CloudChannel[]): void {
-  if (channels.length === 0) {
-    console.log("No channels found.");
-    return;
-  }
-
-  console.log("NAME\tTYPE\tPROVIDER\tSTATUS\tLAST_EVENT");
-  for (const channel of channels) {
-    console.log([channel.name, channel.type, channel.provider, channel.status, ""].join("\t"));
-  }
-}
-
-function printChannelStatus(channel: CloudChannel): void {
-  console.log(`Channel: ${channel.name}`);
-  if (channel.id) {
-    console.log(`ID: ${channel.id}`);
-  }
-  console.log(`Type: ${channel.type}`);
-  console.log(`Provider: ${channel.provider}`);
-  console.log(`Status: ${channel.status}`);
-  if (channel.webhook_url) {
-    console.log(`Webhook URL: ${channel.webhook_url}`);
-  }
-  console.log("Required secrets:");
-  for (const secret of channel.required_secrets) {
-    console.log(`  ${secret.name}: ${secret.status}`);
-  }
-}
-
-async function printChannelDeliverySummary(
-  channel: CloudChannel,
-  apiFlag: string | boolean | undefined,
-): Promise<void> {
-  const response = await cloudGet<{ deliveries: CloudDelivery[] }>(
-    parseCloudApiUrl(apiFlag),
-    `/v1/channels/${encodeURIComponent(channel.id)}/deliveries`,
-  );
-  const inbound = [...response.deliveries].reverse().find((delivery) => delivery.direction === "inbound");
-  const outbound = [...response.deliveries].reverse().find((delivery) => delivery.direction === "outbound");
-
-  console.log("Recent delivery:");
-  console.log(`  Last inbound: ${inbound ? `${inbound.status} ${inbound.received_at}` : "none"}`);
-  console.log(`  Last outbound: ${outbound ? `${outbound.status} ${outbound.received_at}` : "none"}`);
-  console.log("Provider health: not_checked");
-}
-
-async function resolveCloudChannelByName(name: string, apiFlag: string | boolean | undefined): Promise<CloudChannel> {
-  const deployState = await readDeployStateRequired(process.cwd());
-  const response = await cloudGet<{ channels: CloudChannel[] }>(
-    parseCloudApiUrl(apiFlag),
-    `/v1/deploys/${encodeURIComponent(deployState.deploy_id)}/channels`,
-  );
-  const channel = response.channels.find((candidate) => candidate.name === name);
-
-  if (!channel) {
-    throw new Error(`Channel "${name}" was not found for deploy ${deployState.deploy_id}.`);
+  } catch (error) {
+    throw new AgentKitError(
+      "deploy_smoke_failed",
+      `Deploy smoke request failed before a response: ${error instanceof Error ? error.message : String(error)}`,
+    );
   }
 
-  return channel;
-}
-
-function channelProviderForCli(type: string, providerFlag: string | boolean | undefined): string {
-  if (type === "website") {
-    return "agentkit";
-  }
+  const payload = await response.json().catch(() => null);
 
-  if (type === "telegram") {
-    return "telegram";
+  if (!response.ok) {
+    throw new AgentKitError("deploy_smoke_failed", readCloudError(payload, response.status));
   }
 
-  const provider = providerFlag ?? "zapster";
+  const content =
+    payload && typeof payload === "object" && "message" in payload && isRecord((payload as { message?: unknown }).message)
+      ? (payload as { message: { content?: unknown } }).message.content
+      : undefined;
 
-  if (provider !== "zapster" && provider !== "meta") {
-    throw new Error('WhatsApp provider must be "zapster" or "meta".');
+  console.log("");
+  console.log("Deploy smoke verified");
+  console.log(`URL:      ${input.deployUrl}`);
+  console.log(`Message:  ${input.message}`);
+  if (typeof content === "string") {
+    console.log(`Response: ${content}`);
   }
-
-  return provider;
 }
 
-function defaultChannelSecretsForCli(type: string, provider: string): string[] {
-  if (type === "website") {
-    return ["AGENTKIT_WEBSITE_CHANNEL_TOKEN"];
-  }
+async function fetchDeployConversationJson(cwd: string, path: string): Promise<unknown> {
+  const state = await requireLocalDeployState();
+  const deployUrl = requireDeployUrl(state);
+  const token = await readDeployAccessTokenForHostedRequest(cwd);
+  const headers = new Headers();
 
-  if (type === "telegram") {
-    return ["TELEGRAM_BOT_TOKEN", "TELEGRAM_WEBHOOK_SECRET"];
-  }
+  headers.set("Authorization", `Bearer ${token}`);
 
-  if (type === "whatsapp" && provider === "zapster") {
-    return ["ZAPSTER_API_KEY", "ZAPSTER_WEBHOOK_SECRET"];
-  }
-
-  if (type === "whatsapp" && provider === "meta") {
-    return ["META_WHATSAPP_ACCESS_TOKEN", "META_WHATSAPP_APP_SECRET", "META_WHATSAPP_VERIFY_TOKEN"];
-  }
-
-  return [];
-}
-
-async function channelTestBody(
-  channel: CloudChannel,
-  messageFlag: string | boolean | undefined,
-  fixtureFlag: string | boolean | undefined,
-): Promise<string> {
-  if (typeof fixtureFlag === "string") {
-    return readFile(resolve(process.cwd(), fixtureFlag), "utf8");
-  }
-
-  const message = typeof messageFlag === "string" ? messageFlag : "hello";
-
-  if (channel.type === "telegram") {
-    return JSON.stringify({
-      update_id: Date.now(),
-      message: {
-        message_id: 1,
-        chat: { id: 456, type: "private" },
-        from: { id: 123, first_name: "AgentKit" },
-        text: message,
-      },
-    });
-  }
+  let response: Response;
 
-  if (channel.type === "whatsapp") {
-    return JSON.stringify({
-      event_id: `evt_${Date.now()}`,
-      instance_id: "local",
-      message: {
-        id: `msg_${Date.now()}`,
-        from: "5511999999999",
-        type: "text",
-        text: { body: message },
-      },
+  try {
+    response = await fetch(new URL(path, deployUrl).href, {
+      method: "GET",
+      headers,
     });
+  } catch (error) {
+    throw new AgentKitError(
+      "deploy_conversation_request_failed",
+      `Could not read hosted conversation data: ${error instanceof Error ? error.message : String(error)}`,
+    );
   }
 
-  return JSON.stringify({
-    event_id: `web_${Date.now()}`,
-    visitor_id: "visitor_test",
-    message: {
-      id: `msg_${Date.now()}`,
-      text: message,
-    },
-  });
-}
-
-function channelTestHeaders(channel: CloudChannel): Headers {
-  const headers = new Headers({ "Content-Type": "application/json" });
-
-  if (channel.type === "website") {
-    const token = process.env.AGENTKIT_WEBSITE_CHANNEL_TOKEN;
-
-    if (token) {
-      headers.set("Authorization", `Bearer ${token}`);
-    }
-  }
-
-  if (channel.type === "telegram") {
-    headers.set("X-Telegram-Bot-Api-Secret-Token", process.env.TELEGRAM_WEBHOOK_SECRET ?? "");
-  }
-
-  if (channel.type === "whatsapp" && channel.provider === "zapster") {
-    headers.set("X-Zapster-Webhook-Secret", process.env.ZAPSTER_WEBHOOK_SECRET ?? "");
-  }
-
-  return headers;
-}
-
-async function cloudGet<T>(apiUrl: string, path: string): Promise<T> {
-  const response = await cloudFetch(apiUrl, path);
-  const payload = await response.json();
-
-  if (!response.ok) {
-    throw new Error(readCloudError(payload, response.status));
-  }
-
-  return payload as T;
-}
-
-async function cloudPost<T>(apiUrl: string, path: string, body: unknown): Promise<T> {
-  const response = await cloudFetch(apiUrl, path, {
-    method: "POST",
-    headers: { "Content-Type": "application/json" },
-    body: JSON.stringify(body),
-  });
-  const payload = await response.json();
+  const payload = await response.json().catch(() => null);
 
   if (!response.ok) {
-    throw new Error(readCloudError(payload, response.status));
+    throw new AgentKitError("deploy_conversation_request_failed", readCloudError(payload, response.status));
   }
 
-  return payload as T;
-}
-
-function cloudFetch(apiUrl: string, path: string, init: RequestInit = {}): Promise<Response> {
-  const headers = new Headers(init.headers);
-  const apiToken = process.env.AGENTKIT_CLOUD_API_TOKEN;
-
-  if (apiToken && !headers.has("Authorization")) {
-    headers.set("Authorization", `Bearer ${apiToken}`);
-  }
-
-  return fetch(new URL(path, parseCloudApiUrl(apiUrl)).href, {
-    ...init,
-    headers,
-  });
-}
-
-type CloudAuthConfig = {
-  apiUrl: string;
-  token: string;
-};
-
-function cloudAuthPath(): string {
-  return join(homedir(), ".agentkit", "cloud.json");
+  return payload;
 }
 
-async function readCloudAuth(): Promise<CloudAuthConfig | null> {
-  if (process.env.AGENTKIT_CLOUD_API_TOKEN) {
-    return {
-      apiUrl: process.env.AGENTKIT_CLOUD_API_URL ?? defaultAgentKitCloudApiUrl,
-      token: process.env.AGENTKIT_CLOUD_API_TOKEN,
-    };
-  }
-
+async function fetchDeployImproveEvidence(
+  apiUrl: string,
+  input: { deployId: string; since?: string; conversationId?: string },
+): Promise<unknown | null> {
   try {
-    const parsed = JSON.parse(await readFile(cloudAuthPath(), "utf8"));
-
-    if (parsed && typeof parsed === "object" && typeof parsed.token === "string") {
-      return {
-        apiUrl: typeof parsed.apiUrl === "string" ? parsed.apiUrl : defaultAgentKitCloudApiUrl,
-        token: parsed.token,
-      };
+    return await cloudApiRequest(apiUrl, `/v1/deploys/${encodeURIComponent(input.deployId)}/improve/export`, {
+      method: "POST",
+      body: JSON.stringify({
+        status: "all",
+        ...(input.since ? { since: input.since } : {}),
+        ...(input.conversationId ? { conversation_id: input.conversationId } : {}),
+      }),
+    });
+  } catch (error) {
+    if (
+      isAgentKitError(error) &&
+      (error.code === "improve_evidence_store_not_configured" || error.code === "not_found")
+    ) {
+      return null;
     }
-  } catch {
-    return null;
-  }
-
-  return null;
-}
-
-async function writeCloudAuth(config: CloudAuthConfig): Promise<void> {
-  await mkdir(join(homedir(), ".agentkit"), { recursive: true });
-  await writeFile(cloudAuthPath(), `${JSON.stringify(config, null, 2)}\n`, { mode: 0o600 });
-}
-
-async function clearCloudAuth(): Promise<void> {
-  await rm(cloudAuthPath(), { force: true });
-}
-
-async function resolveCloudApiUrl(flag: string | boolean | undefined): Promise<string> {
-  if (flag !== undefined) {
-    return parseCloudApiUrl(flag);
-  }
-
-  const auth = await readCloudAuth();
-  return auth?.apiUrl ?? parseCloudApiUrl(undefined);
-}
-
-async function requireLocalDeployState(): Promise<LocalDeployState> {
-  const state = await readLocalDeployStateIfExists(process.cwd());
-
-  if (!state) {
-    throw new Error("No .agentkit/deploy.json found. Run agentkit deploy first.");
-  }
-
-  return state;
-}
-
-async function resolveProjectIdForSecretCommand(cwd: string): Promise<string> {
-  const state = await readLocalDeployStateIfExists(cwd);
 
-  if (state?.project_id) {
-    return state.project_id;
+    throw error;
   }
-
-  const root = await findAgentCapsuleRoot(cwd);
-  const capsule = await loadAgentCapsule(root);
-  return stableCloudProjectId(capsule.config.name);
-}
-
-async function cloudApiRequest(apiUrl: string, path: string, init: RequestInit): Promise<unknown> {
-  const auth = await readCloudAuth();
-  const headers = new Headers(init.headers);
-
-  if (!headers.has("Content-Type") && init.body !== undefined) {
-    headers.set("Content-Type", "application/json");
-  }
-
-  if (auth?.token && !headers.has("Authorization")) {
-    headers.set("Authorization", `Bearer ${auth.token}`);
-  }
-
-  const response = await fetch(new URL(path, parseCloudApiUrl(apiUrl)).href, {
-    ...init,
-    headers,
-  });
-  const payload = await response.json().catch(() => null);
-
-  if (!response.ok) {
-    const code =
-      payload && typeof payload === "object" && "error" in payload
-        ? String((payload as { error?: { code?: unknown } }).error?.code ?? "cloud_request_failed")
-        : "cloud_request_failed";
-    throw new AgentKitError(code, readCloudError(payload, response.status));
-  }
-
-  return payload;
 }
 
 function printJson(value: unknown): void {
   console.log(JSON.stringify(value, null, 2));
 }
 
-function readCloudError(payload: unknown, status: number): string {
-  if (payload && typeof payload === "object" && "error" in payload) {
-    const error = (payload as { error?: { message?: unknown } }).error;
-    if (typeof error?.message === "string") {
-      return error.message;
+function printSkillStatus(status: Awaited<ReturnType<typeof checkDefaultSkillStatus>>): void {
+  console.log("AgentKit skills");
+  console.log(`Status: ${status.status}`);
+  console.log(`Checked: ${status.checked}`);
+
+  if (status.missing.length > 0) {
+    console.log(`Missing: ${status.missing.length}`);
+    for (const file of status.missing.slice(0, 10)) {
+      console.log(`  ${file}`);
     }
   }
 
-  return `AgentKit Cloud request failed with HTTP ${status}.`;
-}
-
-function parsePort(value: string | boolean | undefined): number | undefined {
-  if (value === undefined) {
-    return undefined;
+  if (status.outdated.length > 0) {
+    console.log(`Outdated: ${status.outdated.length}`);
+    for (const file of status.outdated.slice(0, 10)) {
+      console.log(`  ${file}`);
+    }
   }
 
-  if (typeof value !== "string") {
-    throw new Error("Missing port. Usage: agentkit dev --port <number>");
+  if (status.status !== "current") {
+    console.log("Run: npm run agentkit -- skills sync");
   }
-
-  const port = Number(value);
-
-  if (!Number.isInteger(port) || port <= 0 || port > 65535) {
-    throw new Error("Invalid port. Usage: agentkit dev --port <number>");
-  }
-
-  return port;
 }
 
-function parseTargetFlag(value: string | boolean | undefined, capability: "build" | "deploy"): string {
-  if (value === undefined) {
-    return "cloudflare";
-  }
+async function printJsonOrWrite(value: unknown, outFlag: string | boolean | undefined, usage: string): Promise<void> {
+  const outPath = parseOptionalStringFlag(outFlag, "out", usage);
 
-  if (typeof value !== "string") {
-    throw new Error(
-      `Missing target. Usage: agentkit ${capability} --target ${listTargetsWithCapability(capability).join("|")}`,
-    );
+  if (!outPath) {
+    printJson(value);
+    return;
   }
 
-  return value;
+  const absolutePath = resolve(process.cwd(), outPath);
+  await writeSecretJson(absolutePath, value);
+  console.log(`Deploy access token written to ${absolutePath}`);
 }
 
-function parseCloudApiUrl(value: string | boolean | undefined): string {
-  if (value === undefined) {
-    return process.env.AGENTKIT_CLOUD_API_URL ?? defaultAgentKitCloudApiUrl;
-  }
-
+function parsePositiveIntegerFlag(value: string | boolean | undefined, name: string, usage: string): number {
   if (typeof value !== "string") {
-    throw new Error("Missing API URL. Usage: agentkit deploy --api <url>");
-  }
-
-  return value;
-}
-
-function parseRequiredStringFlag(value: string | boolean | undefined, name: string, usage: string): string {
-  if (typeof value !== "string" || value.trim().length === 0) {
     throw new Error(`Missing ${name}. Usage: ${usage}`);
   }
 
-  return value.trim();
-}
+  const parsed = Number(value);
 
-function parseOptionalStringFlag(value: string | boolean | undefined, name: string, usage: string): string | undefined {
-  if (value === undefined) {
-    return undefined;
+  if (!Number.isInteger(parsed) || parsed <= 0) {
+    throw new Error(`Invalid ${name}. Usage: ${usage}`);
   }
 
-  if (typeof value !== "string" || value.trim().length === 0) {
-    throw new Error(`Missing ${name}. Usage: ${usage}`);
-  }
+  return parsed;
+}
 
-  return value.trim();
+function relativePath(root: string, path: string): string {
+  const output = relative(root, path);
+  return output.startsWith("..") ? path : output || ".";
 }
 
 function printBuildResult(result: Awaited<ReturnType<typeof buildAgentCapsule>>): void {
@@ -1614,16 +1719,12 @@ async function deployCloudflare(wranglerPath: string, buildDir: string): Promise
   }
 }
 
-function runInheritedCommand(command: string, args: string[], cwd: string): Promise<number> {
-  return new Promise((resolvePromise, reject) => {
-    const child = spawn(command, args, {
-      cwd,
-      stdio: "inherit",
-    });
+async function installProjectDependencies(projectPath: string): Promise<void> {
+  const exitCode = await runInheritedCommand("npm", ["install"], projectPath);
 
-    child.once("error", reject);
-    child.once("close", (code) => resolvePromise(code ?? 1));
-  });
+  if (exitCode !== 0) {
+    throw new Error(`Dependency install failed with exit code ${exitCode}. Run \`npm install\` in ${projectPath}.`);
+  }
 }
 
 async function parseToolInput(
@@ -1669,21 +1770,81 @@ function parseJsonInput(source: string, label: string): unknown {
   }
 }
 
-async function waitForShutdown(stop: () => Promise<void>): Promise<void> {
-  await new Promise<void>((resolve) => {
-    let stopped = false;
+async function findRunningLocalDevServer(cwd: string): Promise<{ url: string; agent: string } | null> {
+  const capsule = await loadAgentCapsule(cwd);
+  const basePort = localDevBasePort();
 
-    const shutdown = () => {
-      if (stopped) {
-        return;
-      }
+  for (let port = basePort; port <= basePort + 50; port += 1) {
+    const state = await fetchLocalAgentKitState(`http://localhost:${port}/_agentkit`);
 
-      stopped = true;
-      void stop().finally(resolve);
-    };
+    if (state?.agent === capsule.config.name) {
+      return {
+        url: `http://localhost:${port}`,
+        agent: state.agent,
+      };
+    }
+  }
 
-    process.once("SIGINT", shutdown);
-    process.once("SIGTERM", shutdown);
+  return null;
+}
+
+function localDevBasePort(): number {
+  const value = process.env.AGENTKIT_DEV_BASE_PORT;
+
+  if (!value) {
+    return defaultAgentKitDevPort;
+  }
+
+  const parsed = Number(value);
+  return Number.isInteger(parsed) && parsed > 0 && parsed <= 65535 ? parsed : defaultAgentKitDevPort;
+}
+
+async function fetchLocalAgentKitState(url: string): Promise<{ agent?: string } | null> {
+  const controller = new AbortController();
+  const timeout = setTimeout(() => controller.abort(), 300);
+
+  try {
+    const response = await fetch(url, { signal: controller.signal });
+    const payload = await response.json().catch(() => null);
+
+    if (payload && typeof payload === "object") {
+      return {
+        agent: typeof (payload as { agent?: unknown }).agent === "string" ? (payload as { agent: string }).agent : undefined,
+      };
+    }
+  } catch {
+    return null;
+  } finally {
+    clearTimeout(timeout);
+  }
+
+  return null;
+}
+
+async function openLocalUrl(url: string): Promise<void> {
+  if (process.env.AGENTKIT_OPEN_COMMAND === "none") {
+    return;
+  }
+
+  const command =
+    process.env.AGENTKIT_OPEN_COMMAND ??
+    (process.platform === "darwin" ? "open" : process.platform === "win32" ? "cmd" : "xdg-open");
+  const args = process.env.AGENTKIT_OPEN_COMMAND
+    ? [url]
+    : process.platform === "win32"
+      ? ["/c", "start", "", url]
+      : [url];
+
+  await new Promise<void>((resolvePromise, reject) => {
+    const child = spawn(command, args, {
+      detached: true,
+      stdio: "ignore",
+    });
+    child.once("error", reject);
+    child.once("spawn", () => {
+      child.unref();
+      resolvePromise();
+    });
   });
 }
 
@@ -1691,5 +1852,6 @@ main().catch((error: unknown) => {
   const message = error instanceof Error ? error.message : String(error);
   const prefix = isAgentKitError(error) ? `agentkit ${error.code}` : "agentkit";
   console.error(`${prefix}: ${message}`);
+  console.error("Feedback draft: agentkit feedback create --about last-run --kind bug --summary <text>");
   process.exitCode = 1;
 });