@alexkroman1/aai-cli 5.10.1 → 5.11.0

package/dist/{_init-CYLvYU-B.mjs → _init-5hHkHe-V.mjs}

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 import { c as readJson, d as writeJson, s as isEexist } from "./_utils-8KKw-bzi.mjs";
 import { r as isDevMode, t as getMonorepoRoot } from "./_agent-DS2PUJcl.mjs";
-import { REPO_URL, downloadAndMergeTemplate } from "./_templates-BWJOiWOO.mjs";
+import { REPO_URL, downloadAndMergeTemplate } from "./_templates-DmdG-voA.mjs";
 import path from "node:path";
 import fs from "node:fs/promises";
 //#region _init.ts

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

@@ -119,6 +119,18 @@ async function readJsonFile(file) {
 	}
 }
 /**
+* Directory holding the base scaffold — the files every project gets
+* underneath its template (package.json, tsconfig, `server.mjs`, …).
+*
+* Exported so `aai eject` can copy one file out of it rather than carrying a
+* second copy of that file's contents: the scaffold is the single definition
+* of the self-hosted entrypoint, and a project retrofitted with `eject` gets
+* byte-identical output to one `aai init` scaffolded.
+*/
+function scaffoldDir() {
+	return path.join(resolveTemplatesDir(), "scaffold");
+}
+/**
 * Layer the base scaffold (package.json, tsconfig, …) into targetDir
 * WITHOUT overwriting anything already there. Shared by `aai init`
 * (underneath a template) and `aai pull` (underneath the studio workspace
@@ -130,14 +142,14 @@ async function readJsonFile(file) {
 * {@link layerScaffoldManifest}.
 */
 async function layerScaffold(targetDir) {
-	const scaffoldDir = path.join(resolveTemplatesDir(), "scaffold");
-	if (!existsSync(scaffoldDir)) return;
-	await fs.cp(scaffoldDir, targetDir, {
+	const dir = scaffoldDir();
+	if (!existsSync(dir)) return;
+	await fs.cp(dir, targetDir, {
 		recursive: true,
 		force: false,
 		errorOnExist: false
 	});
-	await layerScaffoldManifest(scaffoldDir, targetDir);
+	await layerScaffoldManifest(dir, targetDir);
 }
 /**
 * Copy a template into targetDir, merging scaffold files underneath.
@@ -154,4 +166,4 @@ async function downloadAndMergeTemplate(template, targetDir) {
 	await layerScaffold(targetDir);
 }
 //#endregion
-export { REPO_URL, downloadAndMergeTemplate, layerScaffold, listTemplates };
+export { REPO_URL, downloadAndMergeTemplate, layerScaffold, listTemplates, scaffoldDir };

package/dist/_templates.d.ts

@@ -35,6 +35,16 @@ type Manifest = Record<string, unknown>;
  * Returns null when nothing was missing, so the common case writes no file.
  */
 export declare function mergeScaffoldManifest(existing: Manifest, scaffold: Manifest): Manifest | null;
+/**
+ * Directory holding the base scaffold — the files every project gets
+ * underneath its template (package.json, tsconfig, `server.mjs`, …).
+ *
+ * Exported so `aai eject` can copy one file out of it rather than carrying a
+ * second copy of that file's contents: the scaffold is the single definition
+ * of the self-hosted entrypoint, and a project retrofitted with `eject` gets
+ * byte-identical output to one `aai init` scaffolded.
+ */
+export declare function scaffoldDir(): string;
 /**
  * Layer the base scaffold (package.json, tsconfig, …) into targetDir
  * WITHOUT overwriting anything already there. Shared by `aai init`

package/dist/cli.mjs

@@ -166,7 +166,7 @@ const list = defineCommand({
 	async run({ args }) {
 		await runCommand(args, async () => {
 			const cwd = resolveCwd();
-			const { executeList } = await import("./studio-LNvXtWak.mjs");
+			const { executeList } = await import("./studio-DPDFKZ9i.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-LNvXtWak.mjs");
+			const { executePull } = await import("./studio-DPDFKZ9i.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-LNvXtWak.mjs");
+			const { executePush } = await import("./studio-DPDFKZ9i.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-LNvXtWak.mjs");
+			const { executePublish } = await import("./studio-DPDFKZ9i.mjs");
 			return executePublish({
 				cwd,
 				server: args.server,
@@ -317,7 +317,7 @@ const init = defineCommand({
 	},
 	async run({ args }) {
 		await runCommand(args, async (mode) => {
-			const { executeInit } = await import("./init-GQsNWkLJ.mjs");
+			const { executeInit } = await import("./init-BBAoRI_f.mjs");
 			return executeInit({
 				dir: args.dir,
 				force: args.force,
@@ -396,6 +396,30 @@ const build = defineCommand({
 		});
 	}
 });
+const eject = defineCommand({
+	meta: {
+		name: "eject",
+		description: "Add the self-hosted server.mjs entrypoint to an older project"
+	},
+	args: {
+		force: {
+			type: "boolean",
+			alias: "f",
+			description: "Replace an existing server.mjs"
+		},
+		json: sharedArgs.json
+	},
+	async run({ args }) {
+		await runCommand(args, async () => {
+			const cwd = await setup({ agent: true });
+			const { executeEject } = await import("./eject-DSrAp8PL.mjs");
+			return executeEject({
+				cwd,
+				force: args.force
+			});
+		});
+	}
+});
 const deploy = defineCommand({
 	meta: {
 		name: "deploy",
@@ -624,7 +648,7 @@ const templates = defineCommand({
 	args: { json: sharedArgs.json },
 	async run({ args }) {
 		await runCommand(args, async (mode) => {
-			const { listTemplates } = await import("./_templates-BWJOiWOO.mjs");
+			const { listTemplates } = await import("./_templates-DmdG-voA.mjs");
 			const names = await listTemplates();
 			if (mode === "human") {
 				for (const name of names) log.message(name);
@@ -648,6 +672,7 @@ const mainCommand = defineCommand({
 		dev,
 		test,
 		build,
+		eject,
 		list,
 		pull,
 		push,

package/dist/eject-DSrAp8PL.mjs

@@ -0,0 +1,90 @@
+#!/usr/bin/env node
+import { a as ok, t as CliError } from "./_output-CC300DzW.mjs";
+import { n as log } from "./_ui-DfwfDbT-.mjs";
+import { a as errorMessage, c as readJson, d as writeJson, o as fileExists } from "./_utils-8KKw-bzi.mjs";
+import { scaffoldDir } from "./_templates-DmdG-voA.mjs";
+import path from "node:path";
+import fs from "node:fs/promises";
+//#region eject.ts
+/**
+* `aai eject` — retrofit the self-hosted entrypoint into an existing project.
+*
+* Every project scaffolded from this CLI version onwards already has
+* `server.mjs` and an `npm start` script: the scaffold ships them, so
+* self-hosting is the default rather than something to opt into. This command
+* exists for the projects that predate that — `aai init` before it, or a
+* workspace pulled from a studio that was created earlier — where the files
+* are simply missing.
+*
+* It COPIES from the scaffold rather than writing its own contents. Two
+* definitions of "the self-hosted entrypoint" would drift, and the one nobody
+* runs locally is the one that would rot; this way an ejected project is
+* byte-identical to a freshly scaffolded one.
+*/
+/** The file `npm start` runs. Named once — the scaffold ships it under this name. */
+const SERVER_ENTRY = "server.mjs";
+/** The `scripts.start` value that runs {@link SERVER_ENTRY}. */
+const START_SCRIPT = `node ${SERVER_ENTRY}`;
+/**
+* Add `scripts.start` unless the project already declares one.
+*
+* An existing `start` is left alone even under `--force`: `--force` is about
+* replacing the entrypoint file, and silently rewriting the command a project
+* boots with is a different, larger act. The mismatch is reported instead, so
+* the choice stays the author's.
+*/
+async function ensureStartScript(cwd) {
+	const manifestPath = path.join(cwd, "package.json");
+	const manifest = await readJson(manifestPath);
+	if (!manifest) {
+		log.warn(`No package.json here — add "start": "${START_SCRIPT}" yourself to get \`npm start\`.`);
+		return false;
+	}
+	const existing = manifest.scripts?.start;
+	if (existing === START_SCRIPT) return false;
+	if (existing !== void 0) {
+		log.warn(`Kept your existing "start" script (${existing}) — run \`node ${SERVER_ENTRY}\`.`);
+		return false;
+	}
+	manifest.scripts = {
+		...manifest.scripts,
+		start: START_SCRIPT
+	};
+	await writeJson(manifestPath, manifest);
+	return true;
+}
+/**
+* A missing scaffold source means a broken install (or an `AAI_TEMPLATES_DIR`
+* pointed somewhere wrong), not anything the user did — so the message names
+* the file and where it was looked for.
+*
+* Built here and thrown by the caller, the shape `build.ts` uses for the same
+* reason: `useErrorCause` reads a `throw new Error` inside a `catch` as
+* dropping the cause, and cannot see that `CliError` takes its options fourth.
+*/
+function scaffoldMissingError(source, err) {
+	return new CliError("scaffold_missing", `Could not read the scaffold's ${SERVER_ENTRY} at ${source}: ${errorMessage(err)}`, "Reinstall @alexkroman1/aai-cli.", { cause: err });
+}
+async function executeEject(opts) {
+	const { cwd, force } = opts;
+	const target = path.join(cwd, SERVER_ENTRY);
+	const overwritten = await fileExists(target);
+	if (overwritten && !force) throw new CliError("server_exists", `${SERVER_ENTRY} already exists — this project can already be self-hosted.`, `Run \`npm start\`, or re-run with --force to replace it with the current scaffold's copy.`);
+	const source = path.join(scaffoldDir(), SERVER_ENTRY);
+	try {
+		await fs.copyFile(source, target);
+	} catch (err) {
+		throw scaffoldMissingError(source, err);
+	}
+	const addedStartScript = await ensureStartScript(cwd);
+	log.success(`Wrote ${SERVER_ENTRY}${overwritten ? " (replaced)" : ""}`);
+	if (await fileExists(path.join(cwd, "client.tsx"))) log.info("This project has a custom UI: run `aai build` first so it is served.");
+	log.info("Next: npm start (PORT and HOST override the 127.0.0.1:3000 default)");
+	return ok({
+		file: target,
+		overwritten,
+		addedStartScript
+	});
+}
+//#endregion
+export { executeEject };

package/dist/eject.d.ts

@@ -0,0 +1,33 @@
+/**
+ * `aai eject` — retrofit the self-hosted entrypoint into an existing project.
+ *
+ * Every project scaffolded from this CLI version onwards already has
+ * `server.mjs` and an `npm start` script: the scaffold ships them, so
+ * self-hosting is the default rather than something to opt into. This command
+ * exists for the projects that predate that — `aai init` before it, or a
+ * workspace pulled from a studio that was created earlier — where the files
+ * are simply missing.
+ *
+ * It COPIES from the scaffold rather than writing its own contents. Two
+ * definitions of "the self-hosted entrypoint" would drift, and the one nobody
+ * runs locally is the one that would rot; this way an ejected project is
+ * byte-identical to a freshly scaffolded one.
+ */
+import { type CommandResult } from "./_output.ts";
+/** The file `npm start` runs. Named once — the scaffold ships it under this name. */
+export declare const SERVER_ENTRY = "server.mjs";
+/** The `scripts.start` value that runs {@link SERVER_ENTRY}. */
+export declare const START_SCRIPT = "node server.mjs";
+type EjectData = {
+    /** Absolute path of the entrypoint written. */
+    file: string;
+    /** True when an existing `server.mjs` was replaced (`--force`). */
+    overwritten: boolean;
+    /** True when `scripts.start` was added to package.json by this run. */
+    addedStartScript: boolean;
+};
+export declare function executeEject(opts: {
+    cwd: string;
+    force?: boolean | undefined;
+}): Promise<CommandResult<EjectData>>;
+export {};

package/dist/{init-GQsNWkLJ.mjs → init-BBAoRI_f.mjs}

@@ -75,7 +75,7 @@ function resolveTargetDir(dir) {
 }
 /** Publish after init and return deploy metadata if successful. */
 async function tryPublish(cwd, server) {
-	const { executePublish } = await import("./studio-LNvXtWak.mjs");
+	const { executePublish } = await import("./studio-DPDFKZ9i.mjs");
 	try {
 		const result = await executePublish({
 			cwd,
@@ -94,7 +94,7 @@ async function tryPublish(cwd, server) {
 }
 /** Scaffold the project, optionally showing a spinner. */
 async function scaffoldProject(dir, cwd, template, silent) {
-	const { runInit } = await import("./_init-CYLvYU-B.mjs");
+	const { runInit } = await import("./_init-5hHkHe-V.mjs");
 	const s = silent ? void 0 : p.spinner();
 	s?.start(`Creating ${dir}`);
 	await runInit({

package/dist/scaffold/CLAUDE.md

@@ -54,6 +54,29 @@ The scaffold's `package.json` exposes `dev`, `build`, `test`, and `deploy`
 as `pnpm <name>` shortcuts. Other commands (`init`, `templates`, `delete`, `secret`)
 are CLI-only.
 
+## Running it yourself (`npm start`)
+
+`server.mjs` serves this agent from a plain Node process — no CLI, no
+bundler, no platform account. It is the deployment counterpart of `aai dev`:
+
+```sh
+npm start                          # http://127.0.0.1:3000
+PORT=8080 HOST=0.0.0.0 npm start   # bind every interface, e.g. in a container
+```
+
+Secrets work the same as everywhere else: `ctx.env` holds the keys declared
+in `.env` (or `.env.example`), and a real environment variable of that name
+wins — so `docker run -e MY_API_KEY=…` needs no `.env` in the image.
+
+Two things to know. It binds **loopback by default**, because this server has
+no request authentication of its own; set `HOST=0.0.0.0` only behind your own
+proxy or auth. And with a custom `client.tsx`, run `npm run build` first —
+otherwise it serves the default UI and says so at startup.
+
+Deleting `server.mjs` costs nothing: `aai dev`, `aai publish` and the managed
+platform never read it. `run_code` is the one feature that does not follow —
+it needs the platform's sandbox and refuses outside one.
+
 ## Project structure
 
 ```text

package/dist/scaffold/package.json

@@ -6,20 +6,21 @@
   },
   "scripts": {
     "dev": "aai dev",
+    "start": "node server.mjs",
     "build": "aai build",
     "test": "aai test",
     "publish:agent": "aai publish"
   },
   "dependencies": {
-    "@alexkroman1/aai": "^5.10.1",
-    "@alexkroman1/aai-ui": "^5.10.1",
+    "@alexkroman1/aai": "^5.11.0",
+    "@alexkroman1/aai-ui": "^5.11.0",
     "react": "^19.2.8",
     "react-dom": "^19.2.8",
     "tailwindcss": "^4.0.0",
     "zod": "^4.4.3"
   },
   "devDependencies": {
-    "@alexkroman1/aai-cli": "^5.10.1",
+    "@alexkroman1/aai-cli": "^5.11.0",
     "@tailwindcss/vite": "^4.3.3",
     "@types/node": "^26.1.1",
     "@types/react": "^19.2.17",

package/dist/scaffold/server.mjs

@@ -0,0 +1,156 @@
+// Self-hosted entrypoint — this is what `npm start` runs.
+//
+// It serves the agent over HTTP + WebSocket from your own Node process: no
+// platform account, no CLI at run time, no bundler. `aai dev` is the
+// development counterpart (file watching, Vite, a browser that opens itself);
+// this file is the deployment.
+//
+//   npm start                          # http://127.0.0.1:3000
+//   PORT=8080 HOST=0.0.0.0 npm start   # bind every interface, e.g. in a container
+//
+// Anything that can run Node can host it: copy the project, install
+// dependencies, provide the secrets, run this file. Deleting it costs nothing
+// — `aai dev`, `aai publish` and the managed platform never read it.
+
+import { existsSync, readFileSync } from "node:fs";
+import { readFile } from "node:fs/promises";
+import { registerHooks } from "node:module";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { parseEnv } from "node:util";
+import { createAgentServer, withHostCredentialFallback } from "@alexkroman1/aai/runtime";
+import { defaultClientDir } from "@alexkroman1/aai-ui/client-dir";
+
+const root = path.dirname(fileURLToPath(import.meta.url));
+
+/**
+ * Teach Node the two non-JavaScript import shapes the `aai` bundler supports,
+ * so one `agent.ts` runs unchanged under `aai dev`, `aai publish`, and here.
+ *
+ * - `import prompt from "./system-prompt.md?raw"` — a Vite convention; Node
+ *   would look for a file literally named `system-prompt.md?raw`.
+ * - `import data from "./data.json"` with no import attribute — TypeScript's
+ *   `resolveJsonModule` allows it; Node requires `with { type: "json" }` and
+ *   otherwise fails with ERR_IMPORT_ATTRIBUTE_MISSING. An import that DOES
+ *   carry the attribute is left to Node, whose own handling is correct.
+ *
+ * Nothing is transformed beyond that: `.ts` itself needs no help, because Node
+ * strips the types natively (this project needs Node 24+). That is why there
+ * is no build step here, and no second copy of the agent in JavaScript that
+ * could drift from the one you deploy.
+ */
+registerHooks({
+  resolve(specifier, context, nextResolve) {
+    if (specifier.startsWith(".") && specifier.endsWith("?raw")) {
+      // Resolved by hand rather than through nextResolve: the default
+      // resolver has no format for `.md` and the query would be lost anyway.
+      return {
+        url: new URL(specifier, context.parentURL).href,
+        format: "module",
+        shortCircuit: true,
+      };
+    }
+    return nextResolve(specifier, context);
+  },
+  load(url, context, nextLoad) {
+    const asRaw = url.endsWith("?raw");
+    const asBareJson = url.endsWith(".json") && context.importAttributes?.type !== "json";
+    if (!(asRaw || asBareJson)) return nextLoad(url, context);
+    const text = readFileSync(fileURLToPath(asRaw ? url.slice(0, -"?raw".length) : url), "utf-8");
+    return {
+      format: "module",
+      // `export default <literal>` for both: a JSON document is already a
+      // valid JS expression, and JSON.stringify makes any file safe to embed
+      // as a string. Emitting `format: "json"` instead would put the import
+      // back under the attribute check this exists to satisfy.
+      source: `export default ${asRaw ? JSON.stringify(text) : text};`,
+      shortCircuit: true,
+    };
+  },
+});
+
+// Imported dynamically, and this is load-bearing: static `import` statements
+// are hoisted and evaluated BEFORE any statement in this file, so an
+// `import agent from "./agent.ts"` at the top would load the agent — and every
+// `?raw` import inside it — before the hooks above were ever registered.
+const { default: agent } = await import("./agent.ts");
+
+/** Parse a dotenv-syntax file into a record; `{}` when it does not exist. */
+async function readEnvFile(file) {
+  try {
+    return parseEnv(await readFile(path.join(root, file), "utf-8"));
+  } catch (err) {
+    // Absent is normal — `.env` is gitignored, and a container usually has
+    // neither file. Unreadable is not: the agent would boot with no
+    // credentials and fail later as an opaque provider auth error.
+    if (err.code !== "ENOENT") throw err;
+    return {};
+  }
+}
+
+/**
+ * Build `ctx.env` — what this agent's own tool code reads.
+ *
+ * The rule is the one `aai dev` follows: only DECLARED keys are exposed, and a
+ * real environment variable wins over the file's value. Nothing else from
+ * process.env comes along, so the agent cannot come to depend on a variable
+ * (PATH, HOME, …) that will not exist wherever you deploy it.
+ *
+ * `.env.example` counts as a declaration too, which is what lets a container
+ * run with no `.env` at all: the committed file names the secrets the agent
+ * needs, and `docker run -e MY_API_KEY=…` supplies the values. Declare
+ * `DATABASE_URL` the same way to give your tools `ctx.db`.
+ */
+async function resolveAgentEnv() {
+  const declared = { ...(await readEnvFile(".env.example")), ...(await readEnvFile(".env")) };
+  const env = {};
+  for (const [key, fileValue] of Object.entries(declared)) {
+    const value = process.env[key] ?? fileValue;
+    // An empty value is worse than a missing one: a provider would try to
+    // authenticate with "" rather than report the credential as absent. The
+    // example file is full of them by design (`BRAVE_API_KEY=`).
+    if (value !== "") env[key] = value;
+  }
+  return env;
+}
+
+/**
+ * Static assets served at `/`: this project's own UI once `client.tsx` has been
+ * built (`npm run build` leaves it in `.aai/client`), otherwise the prebuilt
+ * default client that ships inside @alexkroman1/aai-ui.
+ */
+function resolveClientDir() {
+  const built = path.join(root, ".aai", "client");
+  if (existsSync(path.join(built, "index.html"))) return built;
+  if (existsSync(path.join(root, "client.tsx"))) {
+    console.warn("client.tsx is not built — serving the default UI. Run `npm run build` first.");
+  }
+  return defaultClientDir();
+}
+
+const env = await resolveAgentEnv();
+
+const server = createAgentServer({
+  agent,
+  env,
+  // Provider credentials may ALSO arrive straight from the environment without
+  // being declared, and without becoming ctx.env — the ordinary way to hand
+  // ASSEMBLYAI_API_KEY to a container. Anything in `env` still wins.
+  providerEnv: withHostCredentialFallback(env),
+  clientDir: resolveClientDir(),
+});
+
+// Loopback by default: this server has no request authentication of its own,
+// so exposing it is a deliberate act. Set HOST=0.0.0.0 to bind every interface
+// behind your own proxy or auth. An empty HOST means unset, not "everything".
+const host = process.env.HOST?.trim() || undefined;
+await server.listen(Number(process.env.PORT ?? 3000), host);
+console.log(`${agent.name} listening on http://${host ?? "127.0.0.1"}:${server.port}`);
+
+for (const signal of ["SIGINT", "SIGTERM"]) {
+  process.once(signal, async () => {
+    // close() shuts the runtime down too — no separate runtime.shutdown().
+    await server.close();
+    process.exit(0);
+  });
+}

package/dist/{studio-LNvXtWak.mjs → studio-DPDFKZ9i.mjs}

@@ -4,7 +4,7 @@ import { n as log, t as fmtUrl } from "./_ui-DfwfDbT-.mjs";
 import { s as updateProjectConfig } from "./_config-DMyolIk9.mjs";
 import { t as resolveServerEnv } from "./_server-common-DX8Bfrf5.mjs";
 import { i as resolveDeployTarget } from "./_agent-DS2PUJcl.mjs";
-import { layerScaffold } from "./_templates-BWJOiWOO.mjs";
+import { layerScaffold } from "./_templates-DmdG-voA.mjs";
 import { n as apiRequest } from "./_api-client-B-upMGkc.mjs";
 import path from "node:path";
 import { mkdir, readFile, readdir, stat, writeFile } from "node:fs/promises";
@@ -93,19 +93,30 @@ async function collectSourceFiles(dir) {
 	const files = {};
 	const warnings = [];
 	if (paths.length > 100) warnings.push(`Project has ${paths.length} files; only the first 100 sync to the studio.`);
-	for (const rel of paths.slice(0, 100)) {
+	const read = await Promise.all(paths.slice(0, 100).map(async (rel) => {
 		const abs = path.join(dir, rel);
 		const st = await stat(abs);
-		if (st.size > 256e3) {
-			warnings.push(`${rel} is ${st.size} bytes (max ${MAX_STUDIO_FILE_BYTES}) — not synced.`);
-			continue;
-		}
+		if (st.size > 256e3) return {
+			ok: false,
+			warning: `${rel} is ${st.size} bytes (max ${MAX_STUDIO_FILE_BYTES}) — not synced.`
+		};
 		const content = decodeUtf8(await readFile(abs));
-		if (content === null) {
-			warnings.push(`${rel} is not valid UTF-8 (binary file?) — not synced.`);
+		if (content === null) return {
+			ok: false,
+			warning: `${rel} is not valid UTF-8 (binary file?) — not synced.`
+		};
+		return {
+			ok: true,
+			rel,
+			content
+		};
+	}));
+	for (const entry of read) {
+		if (!entry.ok) {
+			warnings.push(entry.warning);
 			continue;
 		}
-		files[rel.split(path.sep).join("/")] = content;
+		files[entry.rel.split(path.sep).join("/")] = entry.content;
 	}
 	return {
 		files,
@@ -188,17 +199,40 @@ async function executeList(opts) {
 }
 /** Write a pulled file map under `dir`, refusing paths that escape it. */
 async function materializeFiles(dir, files) {
-	for (const [rel, content] of Object.entries(files)) {
+	const targets = Object.entries(files).map(([rel, content]) => {
 		const abs = path.resolve(dir, rel);
 		if (abs !== dir && !abs.startsWith(dir + path.sep)) throw new Error(`Pulled file path escapes the project directory: ${rel}`);
+		return {
+			abs,
+			content
+		};
+	});
+	await Promise.all(targets.map(async ({ abs, content }) => {
 		await mkdir(path.dirname(abs), { recursive: true });
 		await writeFile(abs, content, "utf-8");
-	}
+	}));
+}
+/**
+* The hint for a pull that found nothing, which is where the two causes have
+* to be told apart — and only the project LIST can do it. A typo has other
+* projects beside it; an empty list means this login sees no projects at all,
+* i.e. the CLI is authenticated as a different account than the browser the
+* project was created in (the account's key is what decides studio scope —
+* see `resolveBearer` server-side). Naming the visible projects is also the
+* answer to a typo, so the round trip pays for itself either way. Best
+* effort: the list is a second request on an already-failing path, and its
+* own failure must not replace the 404 the user needs to see.
+*/
+async function notFoundHint(serverUrl, apiKey) {
+	const projects = await listStudioProjects(serverUrl, apiKey).catch(() => null);
+	if (projects === null) return "Run `aai list` to see your projects.";
+	if (projects.length === 0) return "This login has no studio projects at all. If yours are in the studio, the CLI is linked to a different account — run `aai login` again, approve it in a browser signed in to the account that owns the project, then `aai list`.";
+	return `Your projects: ${projects.slice(0, 10).join(", ")}${projects.length > 10 ? `, and ${projects.length - 10} more` : ""}.`;
 }
 async function executePull(opts) {
 	const { serverUrl, apiKey } = await resolveDeployTarget(opts.cwd, opts.server);
 	const remote = await fetchStudioProject(serverUrl, apiKey, opts.project);
-	if (!remote) throw new CliError("not_found", `No studio project named "${opts.project}".`, "Run `aai list` to see your projects.");
+	if (!remote) throw new CliError("not_found", `No studio project named "${opts.project}".`, await notFoundHint(serverUrl, apiKey));
 	const target = path.resolve(opts.cwd, opts.dir ?? opts.project);
 	if ((await readdir(target).catch(() => [])).length > 0 && !opts.force) throw new CliError("dir_not_empty", `${target} is not empty.`, "Pull into a fresh directory, or pass --force to overwrite files in place.");
 	await materializeFiles(target, remote.files);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@alexkroman1/aai-cli",
-  "version": "5.10.1",
+  "version": "5.11.0",
   "type": "module",
   "bin": {
     "aai": "bin.mjs"
@@ -38,8 +38,8 @@
     "p-timeout": "^7.0.1",
     "vite": "^8.1.5",
     "zod": "^4.4.3",
-    "@alexkroman1/aai": "5.10.1",
-    "@alexkroman1/aai-ui": "5.10.1"
+    "@alexkroman1/aai": "5.11.0",
+    "@alexkroman1/aai-ui": "5.11.0"
   },
   "devDependencies": {
     "playwright": "^1.61.1",