@alexkroman1/aai-cli 5.5.1 → 5.7.0

package/README.md

@@ -1,6 +1,6 @@
 # @alexkroman1/aai-cli
 
-The `aai` command — scaffold, run, test, and deploy aai voice agents.
+The `aai` command — scaffold, run, test, and publish aai voice agents.
 
 ```sh
 npm i -g @alexkroman1/aai-cli   # or: npx @alexkroman1/aai-cli@latest
@@ -15,7 +15,10 @@ npm i -g @alexkroman1/aai-cli   # or: npx @alexkroman1/aai-cli@latest
 | `aai dev` | Local dev server: loads `agent.ts`, rebuilds on change, serves the browser client (`--port`) |
 | `aai test` | Run the project's vitest suite |
 | `aai build` | Bundle without deploying (type-checks first; `--skipTypecheck` opts out) |
-| `aai deploy` | Bundle and deploy to the platform (uploads `.env` as agent secrets) |
+| `aai list` | List your studio projects |
+| `aai pull <project>` | Pull a studio project into a local directory, ready for `aai dev` |
+| `aai push` | Sync this project's source to its studio workspace (fast-forward-checked; `--force` overwrites) |
+| `aai publish` | Push, then deploy to production — the studio's Publish button from the terminal (`.env` syncs as agent secrets) |
 | `aai delete` | Remove a deployed agent |
 | `aai secret put\|delete\|list` | Manage a deployed agent's secrets |
 | `aai storage status\|enable\|disable` | Manage the agent's opt-in SQL database (`ctx.db`) |
@@ -30,16 +33,22 @@ aai init my-agent --template pizza-ordering
 cd my-agent
 # put ASSEMBLYAI_API_KEY=... in .env
 aai dev            # talk to it at the printed URL
-aai deploy         # ship it; .env values become the agent's secrets
+aai publish        # ship it; .env values become the agent's secrets
 ```
 
-Deploys type-check the project, preflight required credentials (a missing
-provider key fails the deploy instead of the first call), and print the
-agent's public URL.
+Every published agent is also a **studio project**: publishing prints a
+studio link where the same source can be edited in the browser (with the
+coding agent), and `aai pull` brings those edits back to your machine.
+`push`/`pull` are fast-forward-only — an edit made in the studio since your
+last pull surfaces as a conflict instead of being overwritten.
+
+Publishes type-check the project locally, then build and deploy inside the
+project's sandbox — byte-for-byte the studio's Publish path — preflight
+required credentials, and print the agent's public URL.
 
 ## Notes
 
-- A bare `aai` in a project directory offers to deploy (TTY-confirmed);
+- A bare `aai` in a project directory offers to publish (TTY-confirmed);
   outside one it runs `init`.
 - `--server <url>` targets a self-hosted platform; the origin is remembered
   in your user config after explicit approval.

package/dist/{_agent-DMyOab9_.mjs → _agent-2nVugrN3.mjs}

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { a as readProjectConfig, i as readGlobalConfig, n as ensureApiKey, o as serverOrigin, t as approveServer } from "./_config-5AEqhh-O.mjs";
+import { a as readProjectConfig, i as readGlobalConfig, n as ensureApiKey, o as serverOrigin, t as approveServer } from "./_config-Y5V-5Krn.mjs";
 import { existsSync } from "node:fs";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
@@ -67,6 +67,25 @@ function resolveServerUrl(explicit, configUrl, approvedOrigins = []) {
   If you do intend to use that server, re-run with --server ${origin} to approve it.`);
 }
 /**
+* Reject a repo-supplied slug that isn't the platform's slug shape.
+*
+* Enforced before a slug is ever interpolated into a URL path.
+* `.aai/project.json` is part of the working tree, so a cloned repo controls
+* this value, and callers pair it with the user's API key — `aai publish`
+* hands it to `syncEnvSecrets`, which PUTs the whole `.env` to
+* `${serverUrl}/${slug}/secret`. A hostile `"slug": "x/../admin"` must not
+* steer that request to a path of the repo's choosing.
+*
+* Lives here, at the single point where repo-controlled config becomes a
+* credentialed target, rather than at each call site: the check used to
+* exist only in `getServerInfo` (secret/storage/delete), so `publish` — the
+* command users actually run — had no guard at all.
+*/
+function assertValidConfigSlug(slug) {
+	if (slug === void 0 || VALID_SLUG_RE.test(slug)) return;
+	throw new Error(`Invalid slug in .aai/project.json: ${JSON.stringify(slug)}\n  Expected lowercase letters, digits, \`-\`, \`_\` (2-64 chars). Fix or delete the file — \`aai publish\` will create a fresh deployment.`);
+}
+/**
 * Resolve everything needed to talk to the platform: project config (null if
 * the project has never been deployed), server URL, and API key.
 */
@@ -74,6 +93,7 @@ async function resolveDeployTarget(cwd, explicitServer) {
 	const [config, globalConfig] = await Promise.all([readProjectConfig(cwd), readGlobalConfig()]);
 	const serverUrl = resolveServerUrl(explicitServer, config?.serverUrl, globalConfig.approvedServers ?? []);
 	if (explicitServer) await approveServer(serverUrl);
+	assertValidConfigSlug(config?.slug);
 	return {
 		config,
 		serverUrl,
@@ -83,8 +103,7 @@ async function resolveDeployTarget(cwd, explicitServer) {
 /** Like resolveDeployTarget, but requires an existing deployment (project config). */
 async function getServerInfo(cwd, explicitServer) {
 	const { config, serverUrl, apiKey } = await resolveDeployTarget(cwd, explicitServer);
-	if (!config) throw new Error("No .aai/project.json found — run `aai deploy` first");
-	if (!VALID_SLUG_RE.test(config.slug)) throw new Error(`Invalid slug in .aai/project.json: ${JSON.stringify(config.slug)}\n  Expected lowercase letters, digits, \`-\`, \`_\` (2-64 chars). Fix the file or run \`aai deploy\` to create a fresh deployment.`);
+	if (!config?.slug) throw new Error("This project has no deployed agent — run `aai publish` first");
 	return {
 		serverUrl,
 		slug: config.slug,

package/dist/_agent.d.ts

@@ -25,8 +25,10 @@ export declare function resolveServerUrl(explicit?: string, configUrl?: string,
  */
 export declare function resolveDeployTarget(cwd: string, explicitServer?: string): Promise<{
     config: {
-        slug: string;
+        slug?: string | undefined;
         serverUrl: string;
+        studioProject?: string | undefined;
+        studioSourceHash?: string | undefined;
     } | null;
     serverUrl: string;
     apiKey: string;

package/dist/_api-client-B-upMGkc.mjs

@@ -0,0 +1,104 @@
+#!/usr/bin/env node
+import { FetchError, ofetch } from "ofetch";
+//#region _api-client.ts
+/**
+* Shared HTTP helper for platform API calls (deploy, delete, secrets).
+*
+* Built on ofetch: JSON bodies are serialized (with Content-Type set) and
+* responses parsed automatically, and transient failures (network errors,
+* 5xx/429) are retried before surfacing an error.
+*/
+const HINT_INVALID_API_KEY = "Your API key may be invalid. Run `aai` to re-enter your AssemblyAI API key.";
+/** 404 hint for requests scoped to a deployed agent's slug. */
+const HINT_NOT_DEPLOYED = "The agent may not be deployed. Check `.aai/project.json` for the correct slug.";
+/**
+* Send an authenticated request to the platform API and return the parsed
+* JSON response. Throws a descriptive error with status-specific hints on
+* failure (the 401 hint is always included; pass more via `hints`).
+*/
+async function apiRequest(url, opts) {
+	const client = opts.fetch ? ofetch.create({}, { fetch: opts.fetch }) : ofetch;
+	try {
+		return await client(url, {
+			method: opts.method ?? "GET",
+			headers: {
+				Authorization: `Bearer ${opts.apiKey}`,
+				...opts.headers
+			},
+			...opts.body !== void 0 ? { body: opts.body } : {},
+			retry: opts.retry ?? 2,
+			retryDelay: opts.retryDelay ?? 300
+		});
+	} catch (err) {
+		if (opts.allow404 && err instanceof FetchError && err.statusCode === 404) return null;
+		throw toApiError(err, url, opts);
+	}
+}
+/**
+* Collapse `{"error": "..."}` payloads embedded in a message into their own
+* text. Studio Publish runs the real `aai deploy` inside the sandbox, so its
+* failures arrive wrapped twice and stringifying them produced a
+* triple-escaped wall of JSON around one actionable sentence.
+*/
+function unwrapEmbeddedErrors(message, depth = 0) {
+	if (depth > 3) return message;
+	const start = message.indexOf("{\"error\"");
+	if (start === -1) return message;
+	const json = message.slice(start);
+	try {
+		const inner = JSON.parse(json).error;
+		if (typeof inner !== "string") return message;
+		return unwrapEmbeddedErrors(message.slice(0, start) + inner, depth + 1);
+	} catch {
+		return message;
+	}
+}
+/** The messages of a Zod issue tree, deduped and flattened. */
+function zodIssueMessages(value) {
+	if (Array.isArray(value)) return value.flatMap(zodIssueMessages);
+	if (value === null || typeof value !== "object") return [];
+	const node = value;
+	const nested = zodIssueMessages(node.issues);
+	if (nested.length > 0) return nested;
+	return typeof node.message === "string" ? [node.message] : [];
+}
+/**
+* A human-readable one-liner for a server error body.
+*
+* Servers answer with `{ error }`, or with a serialized ZodError whose useful
+* part is buried several levels down. Dumping the raw JSON turned a
+* one-character mistake (`aai secret put MY-KEY`) into a 515-character escaped
+* blob, so the shapes we actually emit are unwrapped here and anything else
+* falls back to the raw body rather than being dropped.
+*/
+function describeErrorBody(data) {
+	if (typeof data === "string") return data;
+	if (data === null || typeof data !== "object") return JSON.stringify(data ?? "");
+	const error = data.error;
+	if (typeof error === "string") return unwrapEmbeddedErrors(error);
+	if (error !== null && typeof error === "object") {
+		const { message } = error;
+		if (typeof message === "string") {
+			try {
+				const issues = zodIssueMessages(JSON.parse(message));
+				if (issues.length > 0) return [...new Set(issues)].join("; ");
+			} catch {}
+			return message;
+		}
+	}
+	return JSON.stringify(data);
+}
+/** Format an ofetch failure into a descriptive, action-centric error. */
+function toApiError(err, url, opts) {
+	if (err instanceof FetchError && err.statusCode !== void 0) {
+		const status = err.statusCode;
+		const body = describeErrorBody(err.data);
+		const hint = status === 401 ? HINT_INVALID_API_KEY : opts.hints?.[status];
+		return /* @__PURE__ */ new Error(`${opts.action} failed (HTTP ${status}): ${body}${hint ? `\n  ${hint}` : ""}`);
+	}
+	const hint = "Check your network connection and verify the server URL is correct.";
+	const cause = err instanceof FetchError && err.cause !== void 0 ? err.cause : err;
+	return new Error(`${opts.action} failed: could not reach ${url}\n  ${hint}`, { cause });
+}
+//#endregion
+export { apiRequest as n, HINT_NOT_DEPLOYED as t };

package/dist/_api-client.d.ts

@@ -28,6 +28,12 @@ export type ApiRequestOptions = {
     retryDelay?: number;
     /** Optional fetch implementation for testing. Defaults to globalThis.fetch. */
     fetch?: typeof globalThis.fetch;
+    /**
+     * Resolve `null` on a 404 instead of throwing — for existence probes
+     * ("is there a studio project with this name?") where absence is an
+     * answer, not a failure.
+     */
+    allow404?: boolean;
 };
 /**
  * Send an authenticated request to the platform API and return the parsed
@@ -35,3 +41,13 @@ export type ApiRequestOptions = {
  * failure (the 401 hint is always included; pass more via `hints`).
  */
 export declare function apiRequest<T = unknown>(url: string, opts: ApiRequestOptions): Promise<T>;
+/**
+ * A human-readable one-liner for a server error body.
+ *
+ * Servers answer with `{ error }`, or with a serialized ZodError whose useful
+ * part is buried several levels down. Dumping the raw JSON turned a
+ * one-character mistake (`aai secret put MY-KEY`) into a 515-character escaped
+ * blob, so the shapes we actually emit are unwrapped here and anything else
+ * falls back to the raw body rather than being dropped.
+ */
+export declare function describeErrorBody(data: unknown): string;

package/dist/_cli-common.d.ts

@@ -0,0 +1,65 @@
+import type { ArgsDef, CommandDef } from "citty";
+import { type CommandResult, type OutputMode } from "./_output.ts";
+/** Shared arg definitions for citty commands. */
+export declare const sharedArgs: {
+    readonly server: {
+        readonly type: "string";
+        readonly alias: "s";
+        readonly description: "Platform server URL";
+    };
+    readonly yes: {
+        readonly type: "boolean";
+        readonly alias: "y";
+        readonly description: "Accept defaults (no prompts)";
+    };
+    readonly json: {
+        readonly type: "boolean";
+        readonly description: "Output JSON (auto-detected in non-TTY)";
+    };
+};
+/**
+ * Flags in `rawArgs` that `argsDef` doesn't declare, in the form the user
+ * typed them.
+ *
+ * citty silently drops an unrecognized flag, so `aai push --serverr=http://x`
+ * exited 0 having pushed to the DEFAULT server — production, for an installed
+ * CLI — as if the flag had been honoured. Since `--server` is what decides
+ * where the API key and secret values are sent, a typo quietly retargeting it
+ * is worth failing on.
+ */
+export declare function findUnknownFlags(rawArgs: string[], argsDef: ArgsDef): string[];
+/**
+ * Any command in the tree, regardless of its args shape — the walk below only
+ * reads `subCommands` and `args`, and the concrete generics differ per command.
+ */
+type AnyCommandDef = CommandDef<ArgsDef>;
+/**
+ * Unknown flags in `argv` for whichever (possibly nested) subcommand it
+ * selects — `[]` when everything is declared.
+ *
+ * Walks the real command tree rather than re-listing flags, so this cannot
+ * drift from what the commands accept. An unknown SUBCOMMAND is not reported:
+ * citty already answers that with usage text and a non-zero exit.
+ */
+export declare function unknownFlagsForArgv(root: AnyCommandDef, argv: string[]): Promise<string[]>;
+/** Shared command setup: resolve cwd, optionally require agent.ts. */
+export declare function setup(opts?: {
+    agent?: boolean;
+}): Promise<string>;
+/**
+ * Run a command body with standard output-mode resolution, error handling,
+ * and result emission.
+ *
+ * - API key acquisition is owned by `resolveDeployTarget`/`getServerInfo`
+ *   inside the commands that talk to the platform — after the server-trust
+ *   check, so an untrusted `serverUrl` is refused without prompting for a
+ *   key, and commands with no platform traffic never prompt at all.
+ *
+ * A thrown error and a returned `fail(...)` converge here on one emitter:
+ * human mode logs the message, JSON mode writes exactly one result line,
+ * and both exit 1.
+ */
+export declare function runCommand(args: {
+    json?: boolean | undefined;
+}, fn: (mode: OutputMode) => Promise<CommandResult<unknown>>): Promise<void>;
+export {};

package/dist/{_config-5AEqhh-O.mjs → _config-Y5V-5Krn.mjs}

@@ -1,8 +1,9 @@
 #!/usr/bin/env node
-import { a as unwrapCancel, n as log, o as CliError } from "./_ui-8kOEB-JH.mjs";
+import { n as log, o as CliError } from "./_ui-8kOEB-JH.mjs";
 import { a as errorMessage, c as readJson, d as writeJson } from "./_utils-Ch0J4s6a.mjs";
+import { mkdtempSync } from "node:fs";
 import path from "node:path";
-import * as p from "@clack/prompts";
+import { tmpdir } from "node:os";
 import envPaths from "env-paths";
 import { z } from "zod";
 //#region _config.ts
@@ -18,8 +19,17 @@ import { z } from "zod";
 * that isn't an approved http(s) origin.
 */
 const ProjectConfigSchema = z.object({
-	slug: z.string(),
-	serverUrl: z.string()
+	/** Deployed agent slug — absent for a pulled project never published. */
+	slug: z.string().optional(),
+	serverUrl: z.string(),
+	/** Studio project this directory is linked to (`aai pull`/`aai push`). */
+	studioProject: z.string().optional(),
+	/**
+	* The workspace files hash at the last pull/push — `aai push` sends it
+	* back as the fast-forward token, so an edit made in the studio since
+	* then surfaces as a 409 instead of being silently overwritten.
+	*/
+	studioSourceHash: z.string().optional()
 });
 /**
 * Resolve the global config directory (the platform-conventional env-paths
@@ -33,8 +43,19 @@ const ProjectConfigSchema = z.object({
 function getConfigDir() {
 	const override = process.env.AAI_CONFIG_DIR?.trim();
 	if (override) return override;
+	if (process.env.VITEST) return testConfigDir();
 	return envPaths("aai", { suffix: "" }).config;
 }
+/**
+* Per-process throwaway config dir used only under vitest. Memoized: callers
+* read-modify-write the same config across calls, so a fresh dir per call
+* would silently drop what the previous one wrote.
+*/
+let _testConfigDir;
+function testConfigDir() {
+	_testConfigDir ??= mkdtempSync(path.join(tmpdir(), "aai-vitest-config-"));
+	return _testConfigDir;
+}
 async function readProjectConfig(agentDir) {
 	const file = path.join(agentDir, ".aai", "project.json");
 	let data;
@@ -53,6 +74,23 @@ async function writeProjectConfig(agentDir, data) {
 	await writeJson(path.join(agentDir, ".aai", "project.json"), data);
 }
 /**
+* Merge `patch` into the existing project config rather than replacing the
+* file — a publish recording its `slug` must not drop the studio link
+* fields a pull wrote, and vice versa.
+*/
+async function updateProjectConfig(agentDir, patch) {
+	let existing = null;
+	try {
+		existing = await readProjectConfig(agentDir);
+	} catch {}
+	const merged = {
+		...existing,
+		...patch
+	};
+	await writeProjectConfig(agentDir, merged);
+	return merged;
+}
+/**
 * Origin of `url`, or `null` when it is not an absolute http(s) URL.
 *
 * Non-HTTP schemes are rejected rather than returned: `new URL()` yields the
@@ -106,6 +144,20 @@ async function trySaveApiKey(dir, config, apiKey) {
 		log.warn(`Couldn't save your API key to ${path.join(dir, "config.json")}: ${errorMessage(err)} — you'll be prompted again next run.`);
 	}
 }
+/**
+* The credential every platform command runs on.
+*
+* Two sources, in order: the key `aai login` saved, then
+* `ASSEMBLYAI_API_KEY` for non-interactive callers (CI, scripts, the eval
+* harnesses).
+*
+* There is deliberately NO "paste a key" prompt. Pasting one produced a
+* half-configured CLI — able to push and publish while linked to no account
+* the user could see in the studio — and it made `aai login`, which is the
+* real onboarding path, optional in practice. It was also the riskier code
+* path: a hidden password prompt reads stdin, so a piped invocation could
+* have its input eaten and persisted as the API key.
+*/
 async function ensureApiKey(configDir) {
 	const dir = configDir ?? getConfigDir();
 	const config = await readGlobalConfig(dir);
@@ -115,10 +167,7 @@ async function ensureApiKey(configDir) {
 		await trySaveApiKey(dir, config, envKey);
 		return envKey;
 	}
-	if (!process.stdin.isTTY) throw new CliError("no_api_key", "No API key configured and no TTY to prompt for one.", "Set the ASSEMBLYAI_API_KEY environment variable, or run `aai login` interactively once to save a key.");
-	const apiKey = unwrapCancel(await p.password({ message: "Enter your AssemblyAI API key" }), "Setup cancelled");
-	await trySaveApiKey(dir, config, apiKey);
-	return apiKey;
+	throw new CliError("not_logged_in", "You're not logged in.", "Run `aai login` to link your account, or set ASSEMBLYAI_API_KEY for non-interactive use.");
 }
 //#endregion
-export { readProjectConfig as a, writeProjectConfig as c, readGlobalConfig as i, ensureApiKey as n, serverOrigin as o, getConfigDir as r, writeGlobalConfig as s, approveServer as t };
+export { readProjectConfig as a, writeGlobalConfig as c, readGlobalConfig as i, writeProjectConfig as l, ensureApiKey as n, serverOrigin as o, getConfigDir as r, updateProjectConfig as s, approveServer as t };

package/dist/_config.d.ts

@@ -11,8 +11,10 @@ import { z } from "zod";
  * that isn't an approved http(s) origin.
  */
 declare const ProjectConfigSchema: z.ZodObject<{
-    slug: z.ZodString;
+    slug: z.ZodOptional<z.ZodString>;
     serverUrl: z.ZodString;
+    studioProject: z.ZodOptional<z.ZodString>;
+    studioSourceHash: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>;
 /**
  * Resolve the global config directory (the platform-conventional env-paths
@@ -27,6 +29,12 @@ export declare function getConfigDir(): string;
 export type ProjectConfig = z.infer<typeof ProjectConfigSchema>;
 export declare function readProjectConfig(agentDir: string): Promise<ProjectConfig | null>;
 export declare function writeProjectConfig(agentDir: string, data: ProjectConfig): Promise<void>;
+/**
+ * Merge `patch` into the existing project config rather than replacing the
+ * file — a publish recording its `slug` must not drop the studio link
+ * fields a pull wrote, and vice versa.
+ */
+export declare function updateProjectConfig(agentDir: string, patch: Partial<ProjectConfig> & Pick<ProjectConfig, "serverUrl">): Promise<ProjectConfig>;
 export type GlobalConfig = {
     apiKey?: string;
     /**
@@ -53,5 +61,19 @@ export declare function serverOrigin(url: string): string | null;
 export declare function approveServer(url: string, configDir?: string): Promise<void>;
 export declare function readGlobalConfig(configDir?: string): Promise<GlobalConfig>;
 export declare function writeGlobalConfig(configDir: string, data: GlobalConfig): Promise<void>;
+/**
+ * The credential every platform command runs on.
+ *
+ * Two sources, in order: the key `aai login` saved, then
+ * `ASSEMBLYAI_API_KEY` for non-interactive callers (CI, scripts, the eval
+ * harnesses).
+ *
+ * There is deliberately NO "paste a key" prompt. Pasting one produced a
+ * half-configured CLI — able to push and publish while linked to no account
+ * the user could see in the studio — and it made `aai login`, which is the
+ * real onboarding path, optional in practice. It was also the riskier code
+ * path: a hidden password prompt reads stdin, so a piped invocation could
+ * have its input eaten and persisted as the API key.
+ */
 export declare function ensureApiKey(configDir?: string): Promise<string>;
 export {};

package/dist/_deploy.d.ts

@@ -15,6 +15,13 @@ export type DeployOpts = {
      * panel needs a deployed slug to attach secrets to).
      */
     allowMissingSecrets?: boolean;
+    /**
+     * Ask the server to permit a `-preview`-suffixed slug (`aai deploy
+     * --allow-preview-slug`). That suffix is reserved for the studio's
+     * auto-preview deploys — the server rejects it otherwise — and this is set
+     * by the studio's own in-guest deploy, not by ordinary users.
+     */
+    allowPreviewSlug?: boolean;
     /** Retry delay override for tests (0 = no real sleeps on retry paths). */
     retryDelay?: number;
     /** Optional fetch implementation for testing. Defaults to globalThis.fetch. */

package/dist/{_dev-server-vV05Fnki.mjs → _dev-server-BB5N8kdh.mjs}

@@ -4,7 +4,7 @@ import { a as errorMessage, r as errorCode } from "./_utils-Ch0J4s6a.mjs";
 import { n as fallbackHtmlPlugin } from "./client-bundler-yiWoXrgb.mjs";
 import { buildWorker } from "./worker-bundler.mjs";
 import { n as createWorkerEvaluator } from "./_bundler-Cjaxa2wi.mjs";
-import { n as ensureApiKey } from "./_config-5AEqhh-O.mjs";
+import { n as ensureApiKey } from "./_config-Y5V-5Krn.mjs";
 import { t as resolveServerEnv } from "./_server-common-CnaP_Urf.mjs";
 import { createRequire } from "node:module";
 import { existsSync } from "node:fs";
@@ -44,7 +44,7 @@ function agentEnvWarnings(agentDef, env, shellEnv = process.env) {
 	const missing = required.filter((name) => !(env[name] || shellEnv[name]));
 	if (missing.length > 0) warnings.push(`Missing provider credential${s(missing)}: ${missing.join(", ")}. Set ${them(missing)} in .env or the environment.`);
 	const shellOnly = required.filter((name) => !env[name] && shellEnv[name]);
-	if (shellOnly.length > 0) warnings.push(`${shellOnly.join(", ")} resolved from your shell, not .env — deployed agents won't have ${them(shellOnly)}. Declare ${them(shellOnly)} in .env before \`aai deploy\`.`);
+	if (shellOnly.length > 0) warnings.push(`${shellOnly.join(", ")} resolved from your shell, not .env — deployed agents won't have ${them(shellOnly)}. Declare ${them(shellOnly)} in .env before \`aai publish\`.`);
 	const declared = (agentDef.requiredEnv ?? []).filter((name) => !env[name]);
 	if (declared.length > 0) warnings.push(`Missing requiredEnv key${s(declared)} declared by the agent: ${declared.join(", ")}. Set ${them(declared)} in .env — ctx.env will not contain ${them(declared)} otherwise.`);
 	return warnings;

package/dist/{_init-BZ9t_Kz-.mjs → _init-D7JIT-IJ.mjs}

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 import { c as readJson, d as writeJson, s as isEexist } from "./_utils-Ch0J4s6a.mjs";
-import { r as isDevMode, t as getMonorepoRoot } from "./_agent-DMyOab9_.mjs";
-import { REPO_URL, downloadAndMergeTemplate } from "./_templates-Bv8CR800.mjs";
+import { r as isDevMode, t as getMonorepoRoot } from "./_agent-2nVugrN3.mjs";
+import { REPO_URL, downloadAndMergeTemplate } from "./_templates-Bt6u9_68.mjs";
 import path from "node:path";
 import fs from "node:fs/promises";
 //#region _init.ts
@@ -15,7 +15,7 @@ A voice agent built with [aai](${REPO_URL}).
 \`\`\`sh
 npm install        # Install dependencies
 aai dev            # Run locally (opens browser)
-aai deploy         # Deploy to production
+aai publish        # Publish to production (and sync to the studio)
 \`\`\`
 
 ## Secrets

package/dist/{_slug-api-DaqQJHk8.mjs → _slug-api-CGJSST9B.mjs}

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
-import { n as getServerInfo } from "./_agent-DMyOab9_.mjs";
-import { n as apiRequest, t as HINT_NOT_DEPLOYED } from "./_api-client-MenP4-O7.mjs";
+import { n as getServerInfo } from "./_agent-2nVugrN3.mjs";
+import { n as apiRequest, t as HINT_NOT_DEPLOYED } from "./_api-client-B-upMGkc.mjs";
 //#region _slug-api.ts
 /**
 * Authenticated request against a deployed agent's slug-scoped resource

package/dist/_studio-commands.d.ts

@@ -0,0 +1,73 @@
+export declare const list: import("citty").CommandDef<{
+    readonly server: {
+        readonly type: "string";
+        readonly alias: "s";
+        readonly description: "Platform server URL";
+    };
+    readonly json: {
+        readonly type: "boolean";
+        readonly description: "Output JSON (auto-detected in non-TTY)";
+    };
+}>;
+export declare const pull: import("citty").CommandDef<{
+    readonly project: {
+        readonly type: "positional";
+        readonly description: "Studio project name (see `aai list`)";
+        readonly required: true;
+    };
+    readonly dir: {
+        readonly type: "positional";
+        readonly description: "Target directory (default: the project name)";
+        readonly required: false;
+    };
+    readonly force: {
+        readonly type: "boolean";
+        readonly alias: "f";
+        readonly description: "Overwrite files in a non-empty directory";
+    };
+    readonly server: {
+        readonly type: "string";
+        readonly alias: "s";
+        readonly description: "Platform server URL";
+    };
+    readonly json: {
+        readonly type: "boolean";
+        readonly description: "Output JSON (auto-detected in non-TTY)";
+    };
+}>;
+export declare const push: import("citty").CommandDef<{
+    readonly force: {
+        readonly type: "boolean";
+        readonly alias: "f";
+        readonly description: "Overwrite studio-side changes instead of failing the fast-forward check";
+    };
+    readonly server: {
+        readonly type: "string";
+        readonly alias: "s";
+        readonly description: "Platform server URL";
+    };
+    readonly json: {
+        readonly type: "boolean";
+        readonly description: "Output JSON (auto-detected in non-TTY)";
+    };
+}>;
+export declare const publish: import("citty").CommandDef<{
+    readonly force: {
+        readonly type: "boolean";
+        readonly alias: "f";
+        readonly description: "Overwrite studio-side changes instead of failing the fast-forward check";
+    };
+    readonly server: {
+        readonly type: "string";
+        readonly alias: "s";
+        readonly description: "Platform server URL";
+    };
+    readonly json: {
+        readonly type: "boolean";
+        readonly description: "Output JSON (auto-detected in non-TTY)";
+    };
+    readonly skipTypecheck: {
+        readonly type: "boolean";
+        readonly description: "Skip type checking before publishing";
+    };
+}>;