@alexkroman1/aai-cli 5.11.0 → 5.13.0

package/dist/_preflight.d.ts

@@ -0,0 +1,57 @@
+/**
+ * The deploy-time credential preflight — the classic dev/prod failure, caught
+ * before the upload instead of at the deployed agent's first session.
+ *
+ * An agent that ran locally on shell-exported provider keys dies after deploy
+ * with what looks like a provider outage: `aai dev` falls back to the shell
+ * (`withHostCredentialFallback`), and the platform never will. Naming the key
+ * here turns that into one line of output while the developer is still in the
+ * directory that owns the `.env`.
+ *
+ * **This lives in the CLI because the agent's config does.** The platform
+ * stores no description of a bundle and never evaluates one (see "The
+ * platform stores no agent config" in packages/aai-server/CLAUDE.md), so the
+ * only place that knows an agent needs `CARTESIA_API_KEY` is the process that
+ * just built it.
+ *
+ * **It WARNS, and must not be turned into a hard failure.** The CLI sees the
+ * env it is about to upload; it cannot see what is already stored against the
+ * slug from an earlier `aai secret put`, so a key the platform holds looks
+ * missing from here. The server-side check this replaced could see both and
+ * so could reject — moving the config to where it is authored costs that
+ * accuracy, and a false rejection is worse than a false warning: it blocks a
+ * deploy that would have worked.
+ */
+import { requiredProviderEnvVars } from "@alexkroman1/aai/runtime";
+/**
+ * The config shape read out of a bundle's `__aaiConfig` export: the provider
+ * descriptors the credential derivation needs, plus the agent's declared
+ * `requiredEnv`. Deliberately structural rather than the SDK's `AgentConfig` —
+ * the export comes from the USER's installed SDK, which may be older or newer
+ * than this CLI's, so anything beyond these is not ours to assume.
+ *
+ * **The `__aaiConfig` export, not the bundle's default export.** They look
+ * interchangeable — `evalWorkerBundle` already returns the `AgentDef`, and
+ * `agentEnvWarnings` (`_dev-server.ts`) derives the same key set from one —
+ * but `__aaiConfig` is `toAgentConfig(def)`, which has run
+ * `normalizeAgentConveniences` and `defaultProviders`. A def written with an
+ * author shorthand (`llm: "gpt-5"`) still carries a STRING there, and
+ * `descriptorKind` reads a string as no kind at all, so deriving from the raw
+ * def silently omits that provider's key. The normalized config is what the
+ * runtime will actually resolve against, so it is what the preflight checks.
+ */
+export type PreflightConfig = Parameters<typeof requiredProviderEnvVars>[0] & {
+    requiredEnv?: readonly string[] | undefined;
+};
+/**
+ * Env var names the agent needs that the env being uploaded doesn't supply.
+ * Empty values count as missing — an empty credential authenticates nothing.
+ *
+ * Two sources: provider credentials derived from the stt/llm/tts/s2s
+ * descriptors (the same registry-backed derivation the runtime resolves keys
+ * with), and the agent's own declared `requiredEnv` — an `agent()` field for
+ * custom keys tools read from `ctx.env`, which no static derivation can see.
+ */
+export declare function missingCredentials(config: PreflightConfig, env: Record<string, string>): string[];
+/** One line naming the missing keys and what to do about them. */
+export declare function missingCredentialMessage(missing: string[]): string;

package/dist/{_server-common-DX8Bfrf5.mjs → _server-common-61fL__39.mjs}

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { r as errorCode } from "./_utils-8KKw-bzi.mjs";
+import { r as errorCode } from "./_utils-0DHbcqUb.mjs";
 import path from "node:path";
 import { parseEnv } from "node:util";
 import fs from "node:fs/promises";

package/dist/_slug-api-D30zPmsn.mjs

@@ -0,0 +1,50 @@
+#!/usr/bin/env node
+import { n as getServerInfo } from "./_agent-C8Jk-ZcP.mjs";
+import { n as apiRequest, t as HINT_NOT_DEPLOYED } from "./_api-client-BX8Qv51n.mjs";
+//#region _slug-api.ts
+/**
+* Authenticated request against a deployed agent's slug-scoped resource
+* (`${serverUrl}/${slug}${resourcePath}`) — the one shape every per-agent
+* command (secret, storage) shares, including the standard "not deployed"
+* 404 hint.
+*
+* Its own module (rather than living beside `getServerInfo` in `_agent.ts`)
+* so tests can mock `_agent.ts`/`_api-client.ts` while this composition
+* stays real — an intra-module call would bypass those mocks.
+*/
+/**
+* A SECRET request, routed to the project when this directory is linked to
+* one and to the bare slug otherwise.
+*
+* A studio project deploys TWO agents — production and preview — and a
+* secret has to reach both or the preview fails at its first session while
+* production works. The project route fans out server-side
+* (`aai-studio-server/studio-secrets.ts`); this CLI used to write the
+* production slug alone, so a key set here was missing from the preview the
+* user's own `aai publish` had created. An unlinked directory has one agent
+* and keeps the per-slug route, which is the platform primitive underneath.
+*/
+async function secretRequest(cwd, resourcePath, init, server) {
+	const { serverUrl, slug, apiKey, studioProject } = await getServerInfo(cwd, server);
+	return {
+		data: await apiRequest(studioProject ? `${serverUrl}/studio/projects/${encodeURIComponent(studioProject)}/secret${resourcePath}` : `${serverUrl}/${slug}/secret${resourcePath}`, {
+			...init,
+			apiKey,
+			hints: { 404: HINT_NOT_DEPLOYED }
+		}),
+		target: studioProject ?? slug
+	};
+}
+async function slugRequest(cwd, resourcePath, init, server) {
+	const { serverUrl, slug, apiKey } = await getServerInfo(cwd, server);
+	return {
+		data: await apiRequest(`${serverUrl}/${slug}${resourcePath}`, {
+			...init,
+			apiKey,
+			hints: { 404: HINT_NOT_DEPLOYED }
+		}),
+		slug
+	};
+}
+//#endregion
+export { slugRequest as n, secretRequest as t };

package/dist/_slug-api.d.ts

@@ -9,6 +9,22 @@ import { type ApiRequestOptions } from "./_api-client.ts";
  * so tests can mock `_agent.ts`/`_api-client.ts` while this composition
  * stays real — an intra-module call would bypass those mocks.
  */
+/**
+ * A SECRET request, routed to the project when this directory is linked to
+ * one and to the bare slug otherwise.
+ *
+ * A studio project deploys TWO agents — production and preview — and a
+ * secret has to reach both or the preview fails at its first session while
+ * production works. The project route fans out server-side
+ * (`aai-studio-server/studio-secrets.ts`); this CLI used to write the
+ * production slug alone, so a key set here was missing from the preview the
+ * user's own `aai publish` had created. An unlinked directory has one agent
+ * and keeps the per-slug route, which is the platform primitive underneath.
+ */
+export declare function secretRequest<T = unknown>(cwd: string, resourcePath: string, init: Pick<ApiRequestOptions, "method" | "body" | "action">, server?: string): Promise<{
+    data: T;
+    target: string;
+}>;
 export declare function slugRequest<T = unknown>(cwd: string, resourcePath: string, init: Pick<ApiRequestOptions, "method" | "body" | "action">, server?: string): Promise<{
     data: T;
     slug: string;

package/dist/_studio-D2ciIhbi.mjs

@@ -0,0 +1,94 @@
+#!/usr/bin/env node
+import { n as apiRequest } from "./_api-client-BX8Qv51n.mjs";
+import path from "node:path";
+import { MAX_SLUG_LENGTH, PREVIEW_SLUG_SUFFIX, VALID_SLUG_RE } from "@alexkroman1/aai/utils";
+import { slugifyName } from "@alexkroman1/aai/slugify";
+import { isLocalOnlyFile, snapshotWorkspaceFiles } from "@alexkroman1/aai/workspace-files";
+//#region _studio.ts
+/**
+* Internals of the studio-workspace commands (`aai list/pull/push/publish`):
+* the local source-file walk and the thin clients for the platform's
+* `/studio/projects` routes. The workspace is the single source of truth —
+* these helpers only move files between a local directory and the project's
+* workspace row; production deploys happen exclusively through the studio's
+* Publish route (which runs the deploy machinery in the project's sandbox).
+*/
+/**
+* Snapshot the local project into a workspace file map.
+*
+* The walk, the caps, the skip rules and the strict UTF-8 decode all come
+* from the SDK (`@alexkroman1/aai/workspace-files`), which is also what the
+* guest's end-of-turn sync uses — the two write the same map from opposite
+* ends, and a disagreement between them is not an error but a file silently
+* dropped here and resurrected there.
+*
+* `isLocalOnlyFile` is the one rule this side adds: `.env` rides the secret
+* routes and lockfiles are install output, so neither belongs in a row.
+*/
+function collectSourceFiles(dir) {
+	return snapshotWorkspaceFiles(dir, {
+		subject: "Project",
+		skipFile: isLocalOnlyFile
+	});
+}
+/**
+* A studio project name derived from a directory name, or null if unusable.
+*
+* The normalization is the platform's own (`slugifyName`), not a local
+* regex. This used to strip `[^a-z0-9-_]` by hand, which differs from the
+* studio's slugifier on exactly the names people give agents: `Café
+* Ordering` reduced to `caf-ordering` here and `cafe-ordering` there, so the
+* same directory produced a different project depending on whether it was
+* created by `aai push` or by typing the name into the studio.
+*
+* A `-preview` suffix is deliberately unusable. Publishing a project deploys
+* it under the project's own name, so a `*-preview` project would claim a
+* slug the studio's orphan-preview sweep reaps hourly — deleting the agent,
+* its app-database schema, and its secrets on a schedule the user never
+* asked for. Refusing the name is recoverable (rename the directory); losing
+* a published agent to the reaper is not.
+*/
+function projectNameFromDir(dir) {
+	const name = slugifyName(path.basename(dir), MAX_SLUG_LENGTH);
+	if (name.endsWith(PREVIEW_SLUG_SUFFIX)) return null;
+	return VALID_SLUG_RE.test(name) ? name : null;
+}
+/** The shareable studio URL for a project — what every command prints. */
+function studioProjectUrl(serverUrl, project) {
+	return `${serverUrl}/studio/chat/${project}`;
+}
+function listStudioProjects(serverUrl, apiKey) {
+	return apiRequest(`${serverUrl}/studio/projects`, {
+		apiKey,
+		action: "list"
+	}).then((res) => res.projects);
+}
+/** Fetch a project, or null when it doesn't exist (the push existence probe). */
+function fetchStudioProject(serverUrl, apiKey, project) {
+	return apiRequest(`${serverUrl}/studio/projects/${encodeURIComponent(project)}`, {
+		apiKey,
+		action: "pull",
+		allow404: true
+	});
+}
+/** `PUT /studio/projects/:project/source` — the atomic whole-tree push. */
+function pushStudioSource(serverUrl, apiKey, project, body) {
+	return apiRequest(`${serverUrl}/studio/projects/${encodeURIComponent(project)}/source`, {
+		apiKey,
+		action: "push",
+		method: "PUT",
+		body,
+		hints: { 409: "The studio has newer changes. Run `aai pull` to fetch them, or `aai push --force` to overwrite." }
+	});
+}
+/** `POST /studio/projects/:project/deploy` — Publish, in the project's sandbox. */
+function publishStudioProject(serverUrl, apiKey, project) {
+	return apiRequest(`${serverUrl}/studio/projects/${encodeURIComponent(project)}/deploy`, {
+		apiKey,
+		action: "publish",
+		method: "POST",
+		retry: 0
+	});
+}
+//#endregion
+export { publishStudioProject as a, projectNameFromDir as i, fetchStudioProject as n, pushStudioSource as o, listStudioProjects as r, studioProjectUrl as s, collectSourceFiles as t };

package/dist/_studio.d.ts

@@ -6,27 +6,30 @@
  * workspace row; production deploys happen exclusively through the studio's
  * Publish route (which runs the deploy machinery in the project's sandbox).
  */
+import { type WorkspaceSnapshot } from "@alexkroman1/aai/workspace-files";
 /**
- * Mirrors of the studio workspace caps (`aai-studio-server/studio-limits.ts`)
- * — by value, like `aai-guest/limits.ts`, since the CLI cannot depend on the
- * private server package. The server re-validates every push; these exist so
- * an oversized file is a named warning locally instead of a rejected upload.
+ * Snapshot the local project into a workspace file map.
+ *
+ * The walk, the caps, the skip rules and the strict UTF-8 decode all come
+ * from the SDK (`@alexkroman1/aai/workspace-files`), which is also what the
+ * guest's end-of-turn sync uses — the two write the same map from opposite
+ * ends, and a disagreement between them is not an error but a file silently
+ * dropped here and resurrected there.
+ *
+ * `isLocalOnlyFile` is the one rule this side adds: `.env` rides the secret
+ * routes and lockfiles are install output, so neither belongs in a row.
  */
-export declare const MAX_STUDIO_FILE_BYTES = 256000;
-export declare const MAX_STUDIO_FILES = 100;
-/**
- * Walk a local project into the path→content record a workspace stores —
- * the CLI-side twin of the guest's `snapshotWorkspace`: same ignored
- * directories, same caps, oversized and non-text files skipped with a
- * warning rather than failing the whole push.
- */
-export declare function collectSourceFiles(dir: string): Promise<{
-    files: Record<string, string>;
-    warnings: string[];
-}>;
+export declare function collectSourceFiles(dir: string): Promise<WorkspaceSnapshot>;
 /**
  * A studio project name derived from a directory name, or null if unusable.
  *
+ * The normalization is the platform's own (`slugifyName`), not a local
+ * regex. This used to strip `[^a-z0-9-_]` by hand, which differs from the
+ * studio's slugifier on exactly the names people give agents: `Café
+ * Ordering` reduced to `caf-ordering` here and `cafe-ordering` there, so the
+ * same directory produced a different project depending on whether it was
+ * created by `aai push` or by typing the name into the studio.
+ *
  * A `-preview` suffix is deliberately unusable. Publishing a project deploys
  * it under the project's own name, so a `*-preview` project would claim a
  * slug the studio's orphan-preview sweep reaps hourly — deleting the agent,

package/dist/{_templates-DmdG-voA.mjs → _templates-B1kt3BGt.mjs}

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
-import { a as errorMessage } from "./_utils-8KKw-bzi.mjs";
-import { t as getMonorepoRoot } from "./_agent-DS2PUJcl.mjs";
+import { a as errorMessage } from "./_utils-0DHbcqUb.mjs";
+import { t as getMonorepoRoot } from "./_agent-C8Jk-ZcP.mjs";
 import { existsSync } from "node:fs";
 import path from "node:path";
 import fs from "node:fs/promises";

package/dist/{_typecheck-gate-DB-PY0A3.mjs → _typecheck-gate-4v9UBZHh.mjs}

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 import { t as CliError } from "./_output-CC300DzW.mjs";
-import { n as log } from "./_ui-DfwfDbT-.mjs";
+import { n as log } from "./_ui-u7T4YooX.mjs";
 import { typecheckProject } from "./typecheck.mjs";
 //#region _typecheck-gate.ts
 /**

package/dist/{_ui-DfwfDbT-.mjs → _ui-u7T4YooX.mjs}

@@ -37,6 +37,10 @@ function notify(level, message) {
 	}
 	process.stderr.write(`${message}\n`);
 }
+/** Whether `silenceOutput()` has been called — i.e. we are in JSON mode. */
+function outputSilenced() {
+	return silenced;
+}
 /**
 * Unwrap a clack prompt result, exiting cleanly if the user cancelled.
 * `message` lets the caller name what was cancelled (e.g. "Setup cancelled").
@@ -65,4 +69,4 @@ function parsePort(raw) {
 	return port;
 }
 //#endregion
-export { silenceOutput as a, parsePort as i, log as n, unwrapCancel as o, notify as r, fmtUrl as t };
+export { parsePort as a, outputSilenced as i, log as n, silenceOutput as o, notify as r, unwrapCancel as s, fmtUrl as t };

package/dist/_ui.d.ts

@@ -23,6 +23,8 @@ export declare function silenceOutput(): void;
  * line — while a human tailing the log sees what happened.
  */
 export declare function notify(level: "error" | "warn" | "info" | "success", message: string): void;
+/** Whether `silenceOutput()` has been called — i.e. we are in JSON mode. */
+export declare function outputSilenced(): boolean;
 /**
  * Unwrap a clack prompt result, exiting cleanly if the user cancelled.
  * `message` lets the caller name what was cancelled (e.g. "Setup cancelled").

package/dist/{_utils-8KKw-bzi.mjs → _utils-0DHbcqUb.mjs}

@@ -2,7 +2,7 @@
 import { readFileSync } from "node:fs";
 import path from "node:path";
 import fs from "node:fs/promises";
-import { errorDetail, errorMessage, errorMessage as errorMessage$1 } from "@alexkroman1/aai/utils";
+import { errorDetail, errorMessage, errorMessage as errorMessage$1, omitUndefined } from "@alexkroman1/aai/utils";
 //#region _utils.ts
 /**
 * The file that marks a directory as an agent project — the single source
@@ -93,7 +93,7 @@ async function writeJson(filePath, data, opts = {}) {
 		...opts.mode !== void 0 ? { mode: 448 } : {}
 	});
 	const tmpPath = `${filePath}.${process.pid}.${Math.random().toString(36).slice(2)}.tmp`;
-	await fs.writeFile(tmpPath, `${JSON.stringify(data, null, 2)}\n`, { ...opts.mode !== void 0 ? { mode: opts.mode } : {} });
+	await fs.writeFile(tmpPath, `${JSON.stringify(data, null, 2)}\n`, omitUndefined({ mode: opts.mode }));
 	try {
 		await fs.rename(tmpPath, filePath);
 	} catch (err) {

package/dist/{build-CACFbdQ4.mjs → build-DQJ1ZSm9.mjs}

@@ -1,9 +1,9 @@
 #!/usr/bin/env node
 import { a as ok, t as CliError } from "./_output-CC300DzW.mjs";
-import { n as log } from "./_ui-DfwfDbT-.mjs";
-import { r as evalWorkerBundle, t as buildAgentBundle } from "./_bundler-DC17suWN.mjs";
-import { assertTypechecks } from "./_typecheck-gate-DB-PY0A3.mjs";
-import { classifyVitestError, runVitest } from "./test-C-V98oC-.mjs";
+import { n as log } from "./_ui-u7T4YooX.mjs";
+import { r as evalWorkerBundle, t as buildAgentBundle } from "./_bundler-BuIyDdvs.mjs";
+import { assertTypechecks } from "./_typecheck-gate-4v9UBZHh.mjs";
+import { classifyVitestError, runVitest } from "./test-2LWBcXvY.mjs";
 //#region build.ts
 /**
 * `aai build` — bundle the agent without deploying, behind the same gates

package/dist/cli.d.ts

@@ -1 +1,2 @@
-export declare const mainCommand: import("citty").CommandDef<import("citty").ArgsDef>;
+import { type ArgsDef, type CommandDef } from "citty";
+export declare const mainCommand: CommandDef<ArgsDef>;

package/dist/cli.mjs

@@ -1,11 +1,11 @@
 #!/usr/bin/env node
 import { i as installStdoutGuard, n as fail, o as writeLine, r as getOutputMode, t as CliError } from "./_output-CC300DzW.mjs";
-import { a as silenceOutput, n as log } from "./_ui-DfwfDbT-.mjs";
-import { a as errorMessage, l as resolveCwd, o as fileExists, t as AGENT_ENTRY } from "./_utils-8KKw-bzi.mjs";
+import { n as log, o as silenceOutput } from "./_ui-u7T4YooX.mjs";
+import { a as errorMessage, l as resolveCwd, o as fileExists, t as AGENT_ENTRY } from "./_utils-0DHbcqUb.mjs";
 import { existsSync, readFileSync } from "node:fs";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
-import { defineCommand, runMain } from "citty";
+import { defineCommand, runMain, showUsage } from "citty";
 //#region _cli-common.ts
 /** Shared arg definitions for citty commands. */
 const sharedArgs = {
@@ -55,11 +55,11 @@ function findUnknownFlags(rawArgs, argsDef) {
 * A flag's comparison key: dashes dropped and lower-cased, with a leading
 * `no` negation removed.
 *
-* citty accepts both `--allowMissingSecrets` and `--allow-missing-secrets` for
-* an arg declared as `allowMissingSecrets`, and the guest's in-sandbox Publish
-* spawns the kebab-case spelling. Comparing the literal text rejected
-* `--allow-missing-secrets` as unknown and broke Publish for every studio
-* user, so both sides are normalized to one key.
+* citty accepts both `--allowPreviewSlug` and `--allow-preview-slug` for an
+* arg declared as `allowPreviewSlug`, and the guest's in-sandbox Publish
+* spawns the kebab-case spelling. Comparing the literal text rejected the
+* kebab-case form as unknown and broke Publish for every studio user, so both
+* sides are normalized to one key.
 */
 function canonicalFlag(flag) {
 	return flag.replace(/^--?/, "").replace(/^no-/, "").replace(/-/g, "").toLowerCase();
@@ -166,7 +166,7 @@ const list = defineCommand({
 	async run({ args }) {
 		await runCommand(args, async () => {
 			const cwd = resolveCwd();
-			const { executeList } = await import("./studio-DPDFKZ9i.mjs");
+			const { executeList } = await import("./studio-GSFd4s5O.mjs");
 			return executeList({
 				cwd,
 				server: args.server
@@ -201,7 +201,7 @@ const pull = defineCommand({
 	async run({ args }) {
 		await runCommand(args, async () => {
 			const cwd = resolveCwd();
-			const { executePull } = await import("./studio-DPDFKZ9i.mjs");
+			const { executePull } = await import("./studio-GSFd4s5O.mjs");
 			return executePull({
 				cwd,
 				project: args.project,
@@ -229,7 +229,7 @@ const push = defineCommand({
 	async run({ args }) {
 		await runCommand(args, async () => {
 			const cwd = await setup({ agent: true });
-			const { executePush } = await import("./studio-DPDFKZ9i.mjs");
+			const { executePush } = await import("./studio-GSFd4s5O.mjs");
 			return executePush({
 				cwd,
 				server: args.server,
@@ -259,7 +259,7 @@ const publish = defineCommand({
 	async run({ args }) {
 		await runCommand(args, async () => {
 			const cwd = await setup({ agent: true });
-			const { executePublish } = await import("./studio-DPDFKZ9i.mjs");
+			const { executePublish } = await import("./studio-GSFd4s5O.mjs");
 			return executePublish({
 				cwd,
 				server: args.server,
@@ -286,6 +286,22 @@ function readCliVersion(dir) {
 	return "unknown";
 }
 const VERSION = readCliVersion(cliDir);
+/**
+* `aai secret put` for a subcommand, `aai` for the root — the name to put in
+* front of `--help` when telling someone which usage to read.
+*
+* `meta` is a `Resolvable`, so it can be a function or a promise; only the
+* plain-object form carries a name synchronously and anything else degrades
+* to the binary name rather than blocking the error path on a resolve.
+*/
+function commandPath(cmd, parent) {
+	const nameOf = (c) => {
+		const meta = c?.meta;
+		return meta && typeof meta === "object" && "name" in meta && typeof meta.name === "string" ? meta.name : void 0;
+	};
+	const path = [nameOf(parent), nameOf(cmd)].filter((n) => n !== void 0).join(" ");
+	return path.startsWith("aai") ? path : `aai ${path}`.trim();
+}
 const init = defineCommand({
 	meta: {
 		name: "init",
@@ -317,7 +333,7 @@ const init = defineCommand({
 	},
 	async run({ args }) {
 		await runCommand(args, async (mode) => {
-			const { executeInit } = await import("./init-BBAoRI_f.mjs");
+			const { executeInit } = await import("./init-BppxMR8r.mjs");
 			return executeInit({
 				dir: args.dir,
 				force: args.force,
@@ -346,7 +362,7 @@ const dev = defineCommand({
 	async run({ args }) {
 		await runCommand(args, async () => {
 			const cwd = await setup({ agent: true });
-			const { executeDev } = await import("./dev-CdeRcYiQ.mjs");
+			const { executeDev } = await import("./dev-CvPH5dbF.mjs");
 			return executeDev({
 				cwd,
 				port: args.port
@@ -362,8 +378,8 @@ const test = defineCommand({
 	args: { json: sharedArgs.json },
 	async run({ args }) {
 		await runCommand(args, async () => {
-			const cwd = await setup();
-			const { executeTest } = await import("./test-C-V98oC-.mjs");
+			const cwd = await setup({ agent: true });
+			const { executeTest } = await import("./test-2LWBcXvY.mjs");
 			return executeTest(cwd);
 		});
 	}
@@ -387,7 +403,7 @@ const build = defineCommand({
 	async run({ args }) {
 		await runCommand(args, async () => {
 			const cwd = await setup({ agent: true });
-			const { executeBuild } = await import("./build-CACFbdQ4.mjs");
+			const { executeBuild } = await import("./build-DQJ1ZSm9.mjs");
 			return executeBuild({
 				cwd,
 				skipTests: args.skipTests,
@@ -412,7 +428,7 @@ const eject = defineCommand({
 	async run({ args }) {
 		await runCommand(args, async () => {
 			const cwd = await setup({ agent: true });
-			const { executeEject } = await import("./eject-DSrAp8PL.mjs");
+			const { executeEject } = await import("./eject-LgBRfnbH.mjs");
 			return executeEject({
 				cwd,
 				force: args.force
@@ -429,10 +445,6 @@ const deploy = defineCommand({
 	args: {
 		server: sharedArgs.server,
 		json: sharedArgs.json,
-		allowMissingSecrets: {
-			type: "boolean",
-			description: "Deploy even when the agent's providers are missing credentials (the server warns instead of rejecting; set them afterwards with `aai secret put`)"
-		},
 		allowPreviewSlug: {
 			type: "boolean",
 			description: "Permit a `-preview`-suffixed slug (reserved for studio auto-previews; studio-internal — a slug you claim this way is subject to the preview reaper)"
@@ -445,11 +457,10 @@ const deploy = defineCommand({
 	async run({ args }) {
 		await runCommand(args, async () => {
 			const cwd = await setup({ agent: true });
-			const { executeDeploy } = await import("./deploy-Ch0d_jje.mjs");
+			const { executeDeploy } = await import("./deploy-DjsEV-40.mjs");
 			return executeDeploy({
 				cwd,
 				server: args.server,
-				allowMissingSecrets: args.allowMissingSecrets,
 				allowPreviewSlug: args.allowPreviewSlug,
 				skipTypecheck: args.skipTypecheck
 			});
@@ -468,7 +479,7 @@ const del = defineCommand({
 	async run({ args }) {
 		await runCommand(args, async () => {
 			const cwd = await setup();
-			const { executeDelete } = await import("./delete-DEZ7u3u4.mjs");
+			const { executeDelete } = await import("./delete-DCRX3d96.mjs");
 			return executeDelete({
 				cwd,
 				server: args.server
@@ -499,7 +510,7 @@ const secret = defineCommand({
 			async run({ args }) {
 				await runCommand(args, async (mode) => {
 					const cwd = await setup();
-					const { executeSecretPut, NO_INPUT, readStdin } = await import("./secret-4_dYyrpA.mjs");
+					const { executeSecretPut, NO_INPUT, readStdin } = await import("./secret-Ds9dvqAj.mjs");
 					const value = mode === "json" ? await readStdin() : void 0;
 					if (mode === "json" && !value) throw new CliError(...NO_INPUT);
 					return executeSecretPut(cwd, args.name, value, args.server);
@@ -523,7 +534,7 @@ const secret = defineCommand({
 			async run({ args }) {
 				await runCommand(args, async () => {
 					const cwd = await setup();
-					const { executeSecretDelete } = await import("./secret-4_dYyrpA.mjs");
+					const { executeSecretDelete } = await import("./secret-Ds9dvqAj.mjs");
 					return executeSecretDelete(cwd, args.name, args.server);
 				});
 			}
@@ -540,7 +551,7 @@ const secret = defineCommand({
 			async run({ args }) {
 				await runCommand(args, async () => {
 					const cwd = await setup();
-					const { executeSecretList } = await import("./secret-4_dYyrpA.mjs");
+					const { executeSecretList } = await import("./secret-Ds9dvqAj.mjs");
 					return executeSecretList(cwd, args.server);
 				});
 			}
@@ -575,7 +586,7 @@ const storage = defineCommand({
 			},
 			async run({ args }) {
 				await runCommand(args, async () => {
-					const { executeStorageStatus } = await import("./storage-BTfErOOW.mjs");
+					const { executeStorageStatus } = await import("./storage-DbrQSHFk.mjs");
 					return executeStorageStatus(resolveStorageCwd(args.dir), args.server);
 				});
 			}
@@ -592,7 +603,7 @@ const storage = defineCommand({
 			},
 			async run({ args }) {
 				await runCommand(args, async () => {
-					const { executeStorageEnable } = await import("./storage-BTfErOOW.mjs");
+					const { executeStorageEnable } = await import("./storage-DbrQSHFk.mjs");
 					return executeStorageEnable(resolveStorageCwd(args.dir), args.server);
 				});
 			}
@@ -614,7 +625,7 @@ const storage = defineCommand({
 			},
 			async run({ args }) {
 				await runCommand(args, async () => {
-					const { executeStorageDisable } = await import("./storage-BTfErOOW.mjs");
+					const { executeStorageDisable } = await import("./storage-DbrQSHFk.mjs");
 					return executeStorageDisable(resolveStorageCwd(args.dir), {
 						server: args.server,
 						force: args.force
@@ -635,7 +646,7 @@ const login = defineCommand({
 	},
 	async run({ args }) {
 		await runCommand(args, async () => {
-			const { executeLogin } = await import("./login-BeFUiU6M.mjs");
+			const { executeLogin } = await import("./login-BQQaxJhL.mjs");
 			return executeLogin({ server: args.server });
 		});
 	}
@@ -648,7 +659,7 @@ const templates = defineCommand({
 	args: { json: sharedArgs.json },
 	async run({ args }) {
 		await runCommand(args, async (mode) => {
-			const { listTemplates } = await import("./_templates-DmdG-voA.mjs");
+			const { listTemplates } = await import("./_templates-B1kt3BGt.mjs");
 			const names = await listTemplates();
 			if (mode === "human") {
 				for (const name of names) log.message(name);
@@ -702,6 +713,31 @@ if (process.env.VITEST !== "true") {
 		process.argv.splice(2, 0, "publish");
 	};
 	/**
+	* Render usage the way the active output mode allows.
+	*
+	* citty calls `showUsage` from two places: the `--help` path, and its
+	* `catch` for a `CLIError` (a missing positional, an unknown subcommand) —
+	* where it writes the usage block to STDOUT and the reason to stderr. That
+	* second one breaks JSON mode's contract of exactly one result line on
+	* stdout, and JSON mode is auto-detected on a pipe: `aai secret put --json`
+	* put a usage block where a script's `jq` expected a result, with no JSON
+	* emitted at all. Every other failure path in this CLI converges on one
+	* emitter and gets this right.
+	*
+	* `--help` is explicitly still the human block whatever the mode — piping
+	* it into a pager is the normal way to read it, and it is not an error.
+	* The specific reason keeps going to stderr as citty already writes it, so
+	* nothing is lost to a human watching the terminal.
+	*/
+	const usageForMode = async (cmd, parent) => {
+		const argv = process.argv.slice(2);
+		if (argv.includes("--help") || argv.includes("-h") || getOutputMode({}) === "human") {
+			await showUsage(cmd, parent);
+			return;
+		}
+		await writeLine(`${JSON.stringify(fail("usage", `Invalid arguments for \`${commandPath(cmd, parent)}\`.`, `Run \`${commandPath(cmd, parent)} --help\` to see the arguments it accepts.`))}\n`);
+	};
+	/**
 	* Refuse an unrecognized flag instead of ignoring it.
 	*
 	* citty drops one silently, so `aai push --serverr=http://x` exited 0 having
@@ -715,7 +751,7 @@ if (process.env.VITEST !== "true") {
 		log.info("Run `aai <command> --help` to see the options it accepts.");
 		process.exit(1);
 	};
-	runDefault().then(assertKnownFlags).then(() => runMain(mainCommand)).catch((err) => {
+	runDefault().then(assertKnownFlags).then(() => runMain(mainCommand, { showUsage: usageForMode })).catch((err) => {
 		log.error(errorMessage(err));
 		process.exitCode = 1;
 	});

package/dist/{client-bundler-DONm-khu.mjs → client-bundler-C9qXL8A2.mjs}

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { a as errorMessage$1, o as fileExists } from "./_utils-8KKw-bzi.mjs";
+import { a as errorMessage$1, o as fileExists } from "./_utils-0DHbcqUb.mjs";
 import { t as withPreservedNodeEnv } from "./_vite-env-Dg_QlVv0.mjs";
 import { existsSync, unlinkSync, writeFileSync } from "node:fs";
 import path from "node:path";

package/dist/client-bundler.mjs

@@ -1,3 +1,3 @@
 #!/usr/bin/env node
-import { t as buildClient } from "./client-bundler-DONm-khu.mjs";
+import { t as buildClient } from "./client-bundler-C9qXL8A2.mjs";
 export { buildClient };