@edgestore/cli 1.0.0-next.3 → 1.0.0-next.4

package/dist/bin.mjs

@@ -1,8 +1,9 @@
 #!/usr/bin/env node
 import { createRequire } from 'node:module';
+import { fileURLToPath } from 'node:url';
 import { CommanderError, Command } from 'commander';
-import { randomUUID } from 'node:crypto';
-import { rm, rmdir, readFile, mkdir, writeFile, rename, stat, access, chmod, readdir, glob } from 'node:fs/promises';
+import { randomUUID, createHash } from 'node:crypto';
+import { rm, rmdir, readFile, mkdir, writeFile, rename, stat, unlink, lstat, readdir, realpath, access, chmod, glob } from 'node:fs/promises';
 import path from 'node:path';
 import { z } from 'zod';
 import { EdgeStoreApiError, EdgeStoreNetworkError, EdgeStoreTimeoutError, EdgeStoreAbortError, createEdgeStoreSdk, EdgeStoreUploadCleanupError } from '@edgestore/sdk';
@@ -13,13 +14,19 @@ import open from 'open';
 import * as oauth from 'openid-client';
 import { createServer } from 'node:http';
 import { password, isCancel, text, confirm, select } from '@clack/prompts';
-import { findRoot, NoPkgJsonFound } from '@manypkg/find-root';
+import { parseTree, findNodeAtLocation, applyEdits, modify } from 'jsonc-parser';
+import { parse } from 'smol-toml';
+import { homedir } from 'node:os';
 import { getPackages } from '@manypkg/get-packages';
+import { Writable, Readable } from 'node:stream';
+import { detect } from 'package-manager-detector/detect';
+import { findRoot, NoPkgJsonFound } from '@manypkg/find-root';
+import { parse as parse$1 } from '@babel/parser';
+import { isIdentifier, traverseFast, isStringLiteral, isObjectProperty } from '@babel/types';
 import { createWriteStream, constants, openAsBlob } from 'node:fs';
-import { Readable, Writable } from 'node:stream';
 import { pipeline } from 'node:stream/promises';
-import { detect } from 'package-manager-detector/detect';
 import { promisify } from 'node:util';
+import { createLogUpdate } from 'log-update';
 
 function renderCliCommand(flags, command, options = {}) {
     const args = [
@@ -133,7 +140,7 @@ function resolveApiUrl(flagValue, envValue) {
     try {
         url = new URL(rawValue);
     } catch  {
-        throw usageError('invalid_api_url', `Invalid EdgeStore API URL: ${rawValue}`);
+        throw usageError('invalid_api_url', 'Invalid EdgeStore API URL. Supply an http or https origin.');
     }
     if (url.protocol !== 'http:' && url.protocol !== 'https:') {
         throw usageError('invalid_api_url', 'The EdgeStore API URL must use http or https.');
@@ -1181,7 +1188,8 @@ function createDefaultRuntime(signal) {
             stdout: process.stdout,
             stderr: process.stderr,
             inputIsTty: Boolean(process.stdin.isTTY),
-            outputIsTty: Boolean(process.stdout.isTTY)
+            outputIsTty: Boolean(process.stdout.isTTY),
+            stderrIsTty: Boolean(process.stderr.isTTY)
         },
         signal,
         setCwd (cwd) {
@@ -1465,6 +1473,545 @@ function missingAccountError() {
     ]);
 }
 
+const MCP_URL = 'https://api.edgestore.dev/mcp';
+const CLIENTS = [
+    'codex',
+    'claude',
+    'cursor'
+];
+function clientConfig(client, root, { global, codexHome }) {
+    if (client === 'codex') {
+        const directory = global && codexHome ? path.resolve(codexHome) : path.join(root, '.codex');
+        return {
+            file: path.join(directory, 'config.toml'),
+            root: global && codexHome ? directory : root
+        };
+    }
+    return {
+        root,
+        file: path.join(root, client === 'claude' ? global ? '.claude.json' : '.mcp.json' : '.cursor/mcp.json')
+    };
+}
+function expectedEntry(client) {
+    return client === 'claude' ? {
+        type: 'http',
+        url: MCP_URL
+    } : {
+        url: MCP_URL
+    };
+}
+function object(value) {
+    return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+function parseConfig(client, source) {
+    if (source === undefined) return {};
+    try {
+        if (client === 'codex') return parse(source);
+        const errors = [];
+        const tree = parseTree(source, errors, {
+            allowTrailingComma: true
+        });
+        if (errors.length || tree?.type !== 'object') throw new Error();
+        return readTree(tree);
+    } catch  {
+        throw usageError('invalid_agent_config', 'Agent configuration is malformed or contains duplicate keys. Repair it before continuing.');
+    }
+}
+function readTree(node) {
+    if (node.type === 'object') {
+        const result = Object.create(null);
+        for (const property of node.children ?? []){
+            const key = property.children[0].value;
+            if (Object.hasOwn(result, key)) throw new Error();
+            result[key] = readTree(property.children[1]);
+        }
+        return result;
+    }
+    if (node.type === 'array') return node.children?.map(readTree);
+    return node.value;
+}
+function serverEntries(client, config) {
+    const servers = config[client === 'codex' ? 'mcp_servers' : 'mcpServers'];
+    if (servers === undefined) return {};
+    if (!object(servers)) throw usageError('invalid_agent_config', 'The MCP server configuration must be an object/table.');
+    return servers;
+}
+const CODEX_BLOCK = `# BEGIN EDGESTORE MCP\n[mcp_servers.edgestore]\nurl = "${MCP_URL}"\n# END EDGESTORE MCP\n`;
+function entrySource(client, source) {
+    if (source === undefined) return '';
+    if (client === 'codex') {
+        const entry = serverEntries(client, parseConfig(client, source)).edgestore;
+        return JSON.stringify({
+            entry,
+            managedBlock: source.includes(CODEX_BLOCK)
+        });
+    }
+    const node = findNodeAtLocation(parseTree(source), [
+        'mcpServers',
+        'edgestore'
+    ]);
+    return node ? source.slice(node.offset, node.offset + node.length) : '';
+}
+function editConnection(client, source, remove) {
+    let result;
+    if (client === 'codex') {
+        if (remove) {
+            if (!source?.includes(CODEX_BLOCK) || source.indexOf(CODEX_BLOCK) !== source.lastIndexOf(CODEX_BLOCK)) {
+                throw usageError('modified_agent_config', 'The managed Codex block was edited; remove it manually.');
+            }
+            result = source.replace(CODEX_BLOCK, '');
+        } else {
+            result = `${source ?? ''}${source && !source.endsWith('\n') ? '\n' : ''}\n${CODEX_BLOCK}`;
+        }
+    } else {
+        const text = source ?? '{}\n';
+        result = applyEdits(text, modify(text, [
+            'mcpServers',
+            'edgestore'
+        ], remove ? undefined : expectedEntry(client), {
+            formattingOptions: {
+                insertSpaces: true,
+                tabSize: 2
+            }
+        }));
+    }
+    const parsed = parseConfig(client, result);
+    const entry = serverEntries(client, parsed).edgestore;
+    if (remove ? entry !== undefined : !object(entry) || entry.url !== MCP_URL) {
+        throw usageError('agent_config_conflict', 'The existing config layout cannot safely accept this MCP entry. Configure it manually.');
+    }
+    return result;
+}
+function hasPlugin(config) {
+    return object(config.plugins) && Object.entries(config.plugins).some(([name, entry])=>name.split('@')[0] === 'edgestore' && object(entry) && entry.enabled === true);
+}
+
+function digest(value) {
+    return createHash('sha256').update(value).digest('hex');
+}
+// Reject symlinks below the explicitly selected root, including dangling ones.
+async function validatePath(file, root) {
+    const relative = path.relative(root, file);
+    if (!relative || relative.startsWith(`..${path.sep}`) || relative === '..' || path.isAbsolute(relative)) {
+        throw usageError('unsafe_agent_path', 'Agent asset path is outside its selected root.');
+    }
+    let current = root;
+    for (const part of [
+        '',
+        ...relative.split(path.sep)
+    ]){
+        current = path.join(current, part);
+        try {
+            if ((await lstat(current)).isSymbolicLink()) {
+                throw usageError('unsafe_agent_path', 'Refusing to follow a symlink in an agent asset path.');
+            }
+        } catch (error) {
+            if (error.code !== 'ENOENT') throw error;
+        }
+    }
+}
+async function readOptional(file, root) {
+    await validatePath(file, root);
+    try {
+        return await readFile(file, 'utf8');
+    } catch (error) {
+        if (error.code === 'ENOENT') return undefined;
+        throw new CliError('agent_file_unreadable', 'Could not read an agent configuration file.', {
+            details: {
+                file
+            }
+        });
+    }
+}
+async function applyChanges(changes) {
+    for (const change of changes)await checkUnchanged(change);
+    const applied = [];
+    try {
+        for (const change of changes){
+            await validatePath(change.file, change.root);
+            if (change.after === undefined) {
+                await checkUnchanged(change);
+                await unlink(change.file);
+                applied.push(change.file);
+                continue;
+            }
+            await mkdir(path.dirname(change.file), {
+                recursive: true
+            });
+            await checkUnchanged(change);
+            const temporary = `${change.file}.${randomUUID()}.tmp`;
+            try {
+                await writeFile(temporary, change.after, {
+                    flag: 'wx',
+                    mode: 0o600
+                });
+                await rename(temporary, change.file);
+                applied.push(change.file);
+            } finally{
+                await unlink(temporary).catch(()=>undefined);
+            }
+        }
+    } catch  {
+        // Underlying errors or file contents can contain credentials. Return only paths.
+        throw new CliError('agent_write_failed', 'Agent configuration was not fully applied. Inspect the listed files before retrying.', {
+            details: {
+                applied
+            }
+        });
+    }
+}
+async function checkUnchanged(change) {
+    if (await readOptional(change.file, change.root) !== change.before) {
+        throw usageError('agent_file_changed', 'An agent configuration file changed after inspection; retry the command.');
+    }
+}
+
+const stateSchema$1 = z.object({
+    schemaVersion: z.literal(1),
+    mcp: z.record(z.string(), z.object({
+        location: z.string(),
+        hash: z.string()
+    })).default({})
+}).passthrough();
+async function planMcp(options, action) {
+    const { client, project, home, global = false } = options;
+    const target = clientConfig(client, global ? home : project, {
+        global,
+        codexHome: options.codexHome
+    });
+    const before = await readOptional(target.file, target.root);
+    const config = parseConfig(client, before);
+    const servers = serverEntries(client, config);
+    const entry = servers.edgestore;
+    const stateRoot = global ? options.stateRoot : project;
+    const stateFile = path.join(stateRoot, global ? 'agent-assets.json' : '.edgestore/agent-assets.json');
+    const stateBefore = await readOptional(stateFile, stateRoot);
+    let state;
+    try {
+        state = stateSchema$1.parse(stateBefore === undefined ? {
+            schemaVersion: 1
+        } : JSON.parse(stateBefore));
+    } catch  {
+        throw usageError('invalid_agent_state', 'Agent installation metadata is malformed; preserve it and inspect before continuing.');
+    }
+    const location = global ? target.file : path.relative(project, target.file);
+    const owned = state.mcp[client];
+    const matches = owned?.location === location && owned.hash === digest(entrySource(client, before));
+    const duplicate = Object.entries(servers).some(([name, value])=>name !== 'edgestore' && isEdgeStore(value));
+    const globalTarget = clientConfig(client, home, {
+        global: true,
+        codexHome: options.codexHome
+    });
+    const globalConfig = global ? config : parseConfig(client, await readOptional(globalTarget.file, globalTarget.root));
+    const inherited = global ? undefined : inheritedConnection(options, globalConfig);
+    const plugin = client === 'codex' && (hasPlugin(config) || hasPlugin(globalConfig));
+    let status = owned ? 'missing' : 'not-configured';
+    if (inherited) status = inherited;
+    if (duplicate) status = 'configured-under-other-name';
+    if (entry !== undefined) {
+        status = isEdgeStore(entry) ? 'unmanaged' : 'conflict';
+        if (owned) status = 'modified';
+        if (matches) status = 'configured';
+    }
+    // Claude's private local scope overrides project config. Be conservative on conflicts.
+    if (inherited === 'conflict') status = 'conflict';
+    const changes = [];
+    if (action !== 'status') {
+        if (status === 'modified' || status === 'conflict') {
+            throw usageError('agent_config_conflict', 'The EdgeStore entry is user-owned or modified. It was preserved; inspect it before continuing.');
+        }
+        if (action === 'setup' && (status === 'not-configured' || status === 'missing')) {
+            const after = editConnection(client, before, false);
+            changes.push({
+                ...target,
+                before,
+                after
+            });
+            state.mcp[client] = {
+                location,
+                hash: digest(entrySource(client, after))
+            };
+        }
+        if (action === 'remove' && owned?.location === location && (matches || entry === undefined)) {
+            if (matches) changes.push({
+                ...target,
+                before,
+                after: editConnection(client, before, true)
+            });
+            delete state.mcp[client];
+        }
+        if (changes.length || action === 'remove' && owned && !state.mcp[client]) {
+            changes.push({
+                file: stateFile,
+                root: stateRoot,
+                before: stateBefore,
+                after: `${JSON.stringify(state, null, 2)}\n`
+            });
+        }
+    }
+    return {
+        // Never expose config contents: other servers may contain credentials.
+        result: {
+            schemaVersion: 1,
+            client,
+            scope: global ? 'global' : 'project',
+            configPath: target.file,
+            status,
+            endpoint: MCP_URL,
+            authentication: 'not-checked',
+            pluginDiscovery: 'visible-config-only',
+            warnings: plugin ? [
+                'An EdgeStore plugin is enabled. Check its MCP connection before adding a separate one.'
+            ] : [],
+            plannedFiles: changes.map(({ file })=>file)
+        },
+        changes
+    };
+}
+function isEdgeStore(entry) {
+    return object(entry) && entry.url === MCP_URL;
+}
+function inheritedConnection(options, config) {
+    // A named global entry with another endpoint is ambiguous, not a connection to adopt.
+    const servers = serverEntries(options.client, config);
+    if (servers.edgestore !== undefined && !isEdgeStore(servers.edgestore)) {
+        return 'conflict';
+    }
+    if (options.client === 'claude' && object(config.projects)) {
+        const project = config.projects[options.project];
+        if (object(project) && object(project.mcpServers)) {
+            if (project.mcpServers.edgestore !== undefined && !isEdgeStore(project.mcpServers.edgestore)) {
+                return 'conflict';
+            }
+            if (Object.values(project.mcpServers).some(isEdgeStore)) return 'inherited';
+        }
+    }
+    return Object.values(servers).some(isEdgeStore) ? 'inherited' : undefined;
+}
+
+async function agentOptions(runtime, flags, input) {
+    let client = input.client;
+    if (!client && isInteractive(runtime, flags)) client = await runtime.prompts.select('Coding agent', CLIENTS.map((value)=>({
+            value,
+            label: value
+        })));
+    if (!CLIENTS.includes(client)) throw usageError('agent_client_required', 'Select --client codex, claude, or cursor.');
+    return {
+        client: client,
+        project: await findGitRoot(runtime.cwd) ?? await findPackageRoot(runtime.cwd),
+        home: path.resolve(runtime.env.HOME ?? homedir()),
+        stateRoot: path.dirname(runtime.globalConfig.path),
+        global: input.global,
+        codexHome: runtime.env.CODEX_HOME
+    };
+}
+
+const bundleSchema = z.object({
+    schemaVersion: z.literal(1),
+    revision: z.string(),
+    files: z.record(z.string(), z.string())
+});
+const stateSchema = z.object({
+    schemaVersion: z.literal(1),
+    clients: z.record(z.string(), z.object({
+        location: z.string(),
+        revision: z.string(),
+        hashes: z.record(z.string(), z.string())
+    }))
+});
+const SKILL_NAME = 'edgestore-setup';
+async function loadSkillBundle(file) {
+    try {
+        const bundle = bundleSchema.parse(JSON.parse(await readFile(file, 'utf8')));
+        if (digest(JSON.stringify(bundle.files)) !== bundle.revision || !bundle.files[`${SKILL_NAME}/SKILL.md`]) throw new Error();
+        for (const name of Object.keys(bundle.files))validateAssetName(name);
+        return bundle;
+    } catch  {
+        throw usageError('invalid_skill_bundle', 'The CLI skill bundle is missing or invalid. Reinstall a complete CLI artifact.');
+    }
+}
+function skillDirectory(client, root) {
+    return path.join(root, client === 'codex' ? '.agents' : client === 'claude' ? '.claude' : '.cursor', 'skills');
+}
+async function planSkills(options, bundle, action) {
+    const root = options.global ? options.home : options.project;
+    const directory = skillDirectory(options.client, root);
+    const stateRoot = options.global ? options.stateRoot : options.project;
+    const stateFile = path.join(stateRoot, options.global ? 'skill-assets.json' : '.edgestore/skill-assets.json');
+    const stateBefore = await readOptional(stateFile, stateRoot);
+    let state;
+    try {
+        state = stateSchema.parse(stateBefore === undefined ? {
+            schemaVersion: 1,
+            clients: {}
+        } : JSON.parse(stateBefore));
+        for (const entry of Object.values(state.clients))for (const name of Object.keys(entry.hashes))validateAssetName(name);
+    } catch  {
+        throw usageError('invalid_skill_state', 'Skill ownership metadata is invalid; inspect it before continuing.');
+    }
+    const location = options.global ? directory : path.relative(root, directory);
+    const owned = state.clients[options.client];
+    const names = new Set([
+        ...Object.keys(bundle.files),
+        ...Object.keys(owned?.hashes ?? {})
+    ]);
+    const current = {};
+    for (const name of names)current[name] = await readOptional(path.join(directory, name), root);
+    const existingFiles = await installedFiles(path.join(directory, SKILL_NAME), root);
+    const untracked = existingFiles.filter((name)=>!owned?.hashes[name]);
+    const modified = owned && (owned.location !== location || Object.entries(owned.hashes).some(([name, hash])=>current[name] === undefined || digest(current[name]) !== hash));
+    const otherSources = await visibleSkills(options, directory);
+    let status = existingFiles.length ? 'unmanaged' : 'not-installed';
+    if (!existingFiles.length && otherSources.length) status = 'other-source';
+    if (owned) status = owned.revision === bundle.revision ? 'current' : 'update-available';
+    if (owned && (modified || untracked.length)) status = 'modified';
+    const changes = [];
+    const needsWrite = status === 'not-installed' || status === 'update-available' && action === 'update';
+    if (action !== 'status' && (status === 'modified' || status === 'unmanaged')) throw usageError('skill_conflict', 'The skill contains user-owned or modified files. They were preserved; review them before installation or update.');
+    if (action !== 'status' && needsWrite) {
+        for (const name of names){
+            const after = bundle.files[name];
+            if (current[name] !== after) changes.push({
+                file: path.join(directory, name),
+                root,
+                before: current[name],
+                after
+            });
+        }
+        state.clients[options.client] = {
+            location,
+            revision: bundle.revision,
+            hashes: Object.fromEntries(Object.entries(bundle.files).map(([name, text])=>[
+                    name,
+                    digest(text)
+                ]))
+        };
+        changes.push({
+            file: stateFile,
+            root: stateRoot,
+            before: stateBefore,
+            after: `${JSON.stringify(state, null, 2)}\n`
+        });
+    }
+    return {
+        result: {
+            status,
+            directory: path.join(directory, SKILL_NAME),
+            installedRevision: owned?.revision,
+            bundledRevision: bundle.revision,
+            otherSources,
+            discovery: 'visible-files-only'
+        },
+        changes
+    };
+}
+function validateAssetName(name) {
+    if (!name.startsWith(`${SKILL_NAME}/`) || name.split('/').some((part)=>part === '..' || part === '.' || !part) || name.includes('\\') || path.isAbsolute(name)) throw new Error('Invalid skill asset path');
+}
+async function installedFiles(directory, root) {
+    const base = path.dirname(directory);
+    const files = [];
+    let visited = 0;
+    async function visit(directory) {
+        await validatePath(directory, root);
+        if (path.relative(base, directory).split(path.sep).length > 8) throw usageError('skill_conflict', 'Skill directory is too deeply nested to inspect safely.');
+        const entries = await readdir(directory, {
+            withFileTypes: true
+        }).catch((error)=>{
+            if (error.code === 'ENOENT') return [];
+            throw usageError('skill_conflict', 'The skill directory could not be inspected safely.');
+        });
+        for (const entry of entries){
+            if (++visited > 200) throw usageError('skill_conflict', 'Skill directory is too large to inspect safely.');
+            if (entry.isSymbolicLink()) throw usageError('skill_conflict', 'A skill entry is symlinked; it was preserved.');
+            const file = path.join(directory, entry.name);
+            if (entry.isDirectory()) await visit(file);
+            else files.push(path.relative(base, file).replaceAll(path.sep, '/'));
+        }
+    }
+    await visit(directory);
+    return files;
+}
+async function visibleSkills(options, target) {
+    const candidates = [
+        skillDirectory(options.client, options.home)
+    ];
+    if (options.client === 'cursor') candidates.push(path.join(options.project, '.agents/skills'), path.join(options.home, '.agents/skills'));
+    const visible = [];
+    for (const directory of new Set(candidates)){
+        if (directory === target) continue;
+        const file = path.join(directory, SKILL_NAME, 'SKILL.md');
+        // Presence only: do not follow another installer's symlink or read its content.
+        if (await lstat(file).then(()=>true, ()=>false)) visible.push(file);
+    }
+    return visible;
+}
+
+async function configurationStatus(runtime, flags, assetFile) {
+    const bundle = await loadSkillBundle(assetFile).catch(()=>undefined);
+    return Promise.all(CLIENTS.map(async (client)=>{
+        const options = await agentOptions(runtime, flags, {
+            client
+        });
+        const skills = bundle ? await planSkills(options, bundle, 'status').then((plan)=>plan.result, unavailable) : {
+            status: 'bundle-unavailable'
+        };
+        const mcp = await planMcp(options, 'status').then((plan)=>plan.result, unavailable);
+        return {
+            client,
+            skills,
+            mcp
+        };
+    }));
+}
+function unavailable(error) {
+    return {
+        status: 'not-inspected',
+        code: error instanceof CliError ? error.code : 'configuration_unreadable'
+    };
+}
+
+function applicationKind(dependencies) {
+    if (dependencies['@tanstack/react-start']) return {
+        framework: 'tanstack-start',
+        role: 'fullstack'
+    };
+    if (dependencies.next) return {
+        framework: 'next',
+        role: 'fullstack'
+    };
+    if (dependencies['@react-router/dev'] || dependencies['@remix-run/react']) return {
+        framework: 'react-router',
+        role: 'fullstack'
+    };
+    if (dependencies.astro) return {
+        framework: 'astro',
+        role: dependencies.react ? 'fullstack' : 'backend'
+    };
+    for (const framework of [
+        'hono',
+        'express',
+        'fastify'
+    ]){
+        if (dependencies[framework]) return {
+            framework,
+            role: dependencies.react ? 'fullstack' : 'backend'
+        };
+    }
+    if (dependencies.vite && dependencies.react) return {
+        framework: 'vite',
+        role: 'frontend'
+    };
+    if (dependencies.react) return {
+        framework: 'react',
+        role: 'frontend'
+    };
+    return {
+        framework: 'unknown',
+        role: 'unknown'
+    };
+}
+
 async function resolveWorkingDirectory(current, requested) {
     const resolved = path.resolve(current, requested);
     try {
@@ -1580,104 +2127,616 @@ async function exists(candidate) {
     }
 }
 
-async function loginCommand(runtime, flags, options) {
-    if (options.device && options.token) {
-        throw usageError('conflicting_login_modes', '--device and --token cannot be used together.');
-    }
-    const machineOutputFlag = flags.json ? '--json' : flags.plain ? '--plain' : undefined;
-    if (!options.token && machineOutputFlag) {
-        throw usageError('interactive_input_disabled', `OAuth login is interactive and cannot be used with ${machineOutputFlag}.`, [
-            'edgestore login',
-            'edgestore login --device'
-        ]);
-    }
-    if (options.device) return await oauthLogin(runtime, flags, 'device');
-    if (!options.token) return await oauthLogin(runtime, flags, 'browser');
-    if (machineOutputFlag && runtime.io.inputIsTty) {
-        throw usageError('interactive_input_disabled', `Interactive token input is disabled with ${machineOutputFlag}.`, [
-            `printf %s "$EDGESTORE_TOKEN" | edgestore login --token ${machineOutputFlag}`
-        ]);
-    }
-    const token = await runtime.prompts.readToken(runtime.io.stdin, runtime.io.inputIsTty);
-    const apiUrl = apiUrlFor(runtime, flags);
-    const sdk = runtime.sdkFactory({
-        token,
-        baseUrl: apiUrl.sdkBaseUrl
-    });
-    const identity = await sdk.management.whoami({
-        signal: runtime.signal
-    });
-    const environmentTokenActive = hasEnvironmentToken(runtime);
-    await runtime.credentials.set(apiUrl.displayUrl, token);
-    if (!environmentTokenActive) {
-        await updateActiveAccountAfterLogin(runtime, flags, identity.actor);
-    }
-    const output = outputFor(runtime, flags);
-    output.result(loginResult(identity.actor, environmentTokenActive), `Logged in as ${actorLabel(identity.actor)}.`, actorLabel(identity.actor));
-    warnWhenStoredLoginIsInactive(output, environmentTokenActive);
-}
-async function logoutCommand(runtime, flags) {
-    const apiOrigin = apiUrlFor(runtime, flags).displayUrl;
-    const output = outputFor(runtime, flags);
-    const stored = await runtime.credentials.get(apiOrigin);
-    let oauthCredential;
-    try {
-        oauthCredential = parseStoredOAuthCredential(stored);
-    } catch  {
-        output.warning('The stored OAuth login is invalid. Skipping remote revocation.');
-    }
-    let oauthRevoked;
-    let revocationFailure;
-    if (oauthCredential) {
-        try {
-            await runtime.oauth.revoke(oauthCredential, runtime.signal);
-            oauthRevoked = true;
-        } catch (error) {
-            if (runtime.signal.aborted) throw error;
-            oauthRevoked = false;
-            revocationFailure = normalizeError(error);
-            output.warning('The OAuth grant could not be revoked remotely. The login will still be removed locally.');
-        }
-    }
-    let deleted;
+async function detectPackages(cwd, options = {}) {
+    const resolvedCwd = path.resolve(cwd);
+    const workspaceRoot = await findWorkspaceRoot(resolvedCwd);
+    const packagePath = path.join(cwd, 'package.json');
+    let manifest;
+    let contents;
     try {
-        deleted = await runtime.credentials.delete(apiOrigin);
+        contents = await readFile(packagePath, 'utf8');
     } catch (error) {
-        const deletionFailure = normalizeError(error);
-        if (oauthRevoked) {
-            throw new CliError('logout_partial_failure', 'The OAuth grant was revoked, but the stored login could not be removed.', {
+        if (!isMissingPathError(error)) {
+            throw new CliError('package_manifest_unreadable', `Could not read package manifest at ${packagePath}.`, {
                 details: {
-                    status: 'partial',
-                    oauthGrant: {
-                        status: 'revoked'
-                    },
-                    localCredential: {
-                        status: 'delete_failed',
-                        cause: errorDetails$2(deletionFailure)
-                    }
-                },
-                requestId: deletionFailure.options.requestId,
-                suggestions: [
-                    renderCliCommand(flags, [
-                        'logout'
-                    ])
-                ],
-                exitCode: deletionFailure.exitCode
+                    path: packagePath,
+                    cause: error instanceof Error ? error.message : String(error)
+                }
             });
         }
-        if (revocationFailure) {
-            throw new CliError('logout_failed', 'The OAuth grant could not be revoked and the stored login could not be removed.', {
-                details: {
-                    status: 'failed',
-                    oauthGrant: {
-                        status: 'revocation_failed',
-                        cause: errorDetails$2(revocationFailure)
-                    },
-                    localCredential: {
-                        status: 'delete_failed',
-                        cause: errorDetails$2(deletionFailure)
-                    }
-                },
+        return {
+            framework: 'unknown',
+            manager: await detectPackageManager(cwd),
+            missing: []
+        };
+    }
+    try {
+        manifest = JSON.parse(contents);
+    } catch (error) {
+        throw new CliError('invalid_package_manifest', `Invalid package manifest at ${packagePath}.`, {
+            details: {
+                path: packagePath,
+                cause: error instanceof Error ? error.message : String(error)
+            },
+            exitCode: 2
+        });
+    }
+    const dependencies = {
+        ...manifest.dependencies,
+        ...manifest.devDependencies
+    };
+    const { framework, role } = applicationKind(dependencies);
+    const wanted = role === 'fullstack' ? [
+        '@edgestore/server',
+        '@edgestore/react'
+    ] : role === 'frontend' ? [
+        '@edgestore/react'
+    ] : [
+        '@edgestore/server'
+    ];
+    return {
+        framework: framework === 'unknown' ? 'node' : framework,
+        manager: await detectPackageManager(cwd),
+        missing: wanted.filter((name)=>!dependencies[name]),
+        installAtWorkspaceRoot: options.installAtWorkspaceRoot,
+        ...workspaceRoot && workspaceRoot !== resolvedCwd ? {
+            workspace: {
+                root: workspaceRoot,
+                ...manifest.name ? {
+                    packageName: manifest.name
+                } : {}
+            }
+        } : {}
+    };
+}
+async function installPackages(runtime, plan, options) {
+    if (!plan.manager || !plan.missing.length) return {
+        ran: false
+    };
+    const args = installArgs(plan.manager, plan.missing, plan.installAtWorkspaceRoot);
+    const command = renderInstallCommand(plan.manager, args, {
+        plan,
+        packageCwd: options.cwd,
+        invocationCwd: options.invocationCwd
+    });
+    const shouldInstall = options.requested ?? (options.interactive ? await runtime.prompts.confirm(`Install EdgeStore packages with ${plan.manager}?`, true) : false);
+    if (!shouldInstall) return {
+        command,
+        cwd: options.cwd,
+        ran: false
+    };
+    const captured = options.structured ? createOutputCapture() : undefined;
+    try {
+        await runtime.runCommand(plan.manager, args, {
+            cwd: options.cwd,
+            ...captured ? {
+                stdout: captured.stream,
+                stderr: captured.stream
+            } : {}
+        });
+    } catch (error) {
+        const diagnostics = captured?.read().trim();
+        if (diagnostics && !options.json) {
+            runtime.io.stderr.write(`${diagnostics}\n`);
+        }
+        throw new CliError('package_install_failed', error instanceof Error ? error.message : 'Package installation failed.', {
+            ...diagnostics ? {
+                details: {
+                    diagnostics
+                }
+            } : {},
+            suggestions: [
+                command
+            ]
+        });
+    }
+    const diagnostics = captured?.read();
+    if (diagnostics) {
+        runtime.io.stderr.write(diagnostics.endsWith('\n') ? diagnostics : `${diagnostics}\n`);
+    }
+    return {
+        command,
+        cwd: options.cwd,
+        ran: true
+    };
+}
+function renderInstallCommand(manager, args, context) {
+    const { plan, packageCwd, invocationCwd } = context;
+    const workspace = plan.workspace;
+    if (invocationCwd === workspace?.root) {
+        const workspacePath = path.relative(workspace.root, packageCwd).replaceAll(path.sep, '/');
+        if (manager === 'pnpm') {
+            return renderShellCommand([
+                manager,
+                '--filter',
+                `./${workspacePath}`,
+                ...args
+            ]);
+        }
+        if (manager === 'npm') {
+            return renderShellCommand([
+                manager,
+                ...args,
+                '--workspace',
+                workspacePath
+            ]);
+        }
+        if (manager === 'yarn' && workspace.packageName) {
+            return renderShellCommand([
+                manager,
+                'workspace',
+                workspace.packageName,
+                ...args
+            ]);
+        }
+    }
+    const relativeCwd = path.relative(invocationCwd, packageCwd) || '.';
+    if (relativeCwd === '.') return renderShellCommand([
+        manager,
+        ...args
+    ]);
+    if (manager === 'npm') {
+        return renderShellCommand([
+            manager,
+            '--prefix',
+            relativeCwd,
+            ...args
+        ]);
+    }
+    if (manager === 'pnpm') {
+        return renderShellCommand([
+            manager,
+            '--dir',
+            relativeCwd,
+            ...args
+        ]);
+    }
+    return renderShellCommand([
+        manager,
+        '--cwd',
+        relativeCwd,
+        ...args
+    ]);
+}
+function packageNextSteps(framework) {
+    if (framework === 'next' || framework === 'tanstack-start') {
+        return [
+            'Next steps:',
+            `  Configure an EdgeStore router using the ${framework} adapter.`,
+            '  Add the EdgeStore provider to your client layout.'
+        ];
+    }
+    if (framework === 'react' || framework === 'vite') {
+        return [
+            'Next steps:',
+            '  Reuse or choose a separate backend for the EdgeStore server endpoint.',
+            '  Add the EdgeStore provider to your React app.'
+        ];
+    }
+    return [
+        'Next steps:',
+        '  Configure an EdgeStore router and server endpoint.'
+    ];
+}
+function createOutputCapture(limit = 32_768) {
+    let output = '';
+    return {
+        stream: new Writable({
+            write (chunk, _encoding, callback) {
+                output = `${output}${Buffer.from(chunk).toString('utf8')}`.slice(-limit);
+                callback();
+            }
+        }),
+        read: ()=>output
+    };
+}
+function isMissingPathError(error) {
+    return error instanceof Error && 'code' in error && (error.code === 'ENOENT' || error.code === 'ENOTDIR');
+}
+async function detectPackageManager(cwd) {
+    const start = path.resolve(cwd);
+    const boundary = await findWorkspaceRoot(start) ?? await findGitRoot(start) ?? start;
+    let directory = start;
+    while(true){
+        for (const strategy of [
+            'packageManager-field',
+            'lockfile',
+            'devEngines-field'
+        ]){
+            const result = await detect({
+                cwd: directory,
+                stopDir: directory,
+                strategies: [
+                    strategy
+                ],
+                packageJsonParser: (contents)=>packageJsonForStrategy(contents, strategy)
+            });
+            if (result?.name === 'pnpm' || result?.name === 'npm' || result?.name === 'yarn' || result?.name === 'bun') {
+                return result.name;
+            }
+        }
+        if (directory === boundary) break;
+        directory = path.dirname(directory);
+    }
+    return 'npm';
+}
+function packageJsonForStrategy(contents, strategy) {
+    const manifest = JSON.parse(contents);
+    if (strategy !== 'packageManager-field') delete manifest.packageManager;
+    if (strategy !== 'devEngines-field') delete manifest.devEngines;
+    return manifest;
+}
+function installArgs(manager, packages, installAtWorkspaceRoot = false) {
+    if (manager === 'npm') return [
+        'install',
+        ...packages
+    ];
+    if (manager === 'pnpm' && installAtWorkspaceRoot) {
+        return [
+            'add',
+            '-w',
+            ...packages
+        ];
+    }
+    return [
+        'add',
+        ...packages
+    ];
+}
+
+const manifestSchema = z.object({
+    name: z.string().optional(),
+    dependencies: z.record(z.string(), z.string()).optional(),
+    devDependencies: z.record(z.string(), z.string()).optional()
+});
+const installedSchema = z.object({
+    name: z.string(),
+    version: z.string()
+});
+const packageNames = [
+    '@edgestore/server',
+    '@edgestore/react',
+    '@edgestore/sdk'
+];
+async function inspectApplication(directory) {
+    const manifestPath = path.join(directory, 'package.json');
+    let manifest;
+    try {
+        manifest = manifestSchema.parse(JSON.parse(await readFile(manifestPath, 'utf8')));
+    } catch  {
+        // Never include arbitrary manifest contents or parser snippets in agent output.
+        throw usageError('invalid_package_manifest', `Could not read a valid package manifest at ${manifestPath}.`);
+    }
+    const dependencies = {
+        ...manifest.dependencies,
+        ...manifest.devDependencies
+    };
+    const workspaceRoot = await findWorkspaceRoot(directory);
+    const resolutionRoot = workspaceRoot ?? await findGitRoot(directory) ?? directory;
+    const resolutionFiles = await readdir(resolutionRoot);
+    const plugAndPlay = resolutionFiles.includes('.pnp.cjs') || resolutionFiles.includes('.pnp.js');
+    const candidates = workspaceRoot === directory ? (await getPackages(directory)).packages.filter((pkg)=>pkg.dir !== directory).map((pkg)=>({
+            directory: pkg.dir,
+            name: pkg.packageJson.name
+        })) : [];
+    const packages = await Promise.all(packageNames.map((name)=>inspectPackage(directory, name, {
+            declaredVersion: dependencies[name],
+            plugAndPlay
+        })));
+    const versions = packages.flatMap((pkg)=>pkg.version ? [
+            pkg.version
+        ] : []);
+    const families = new Set(versions.map(versionFamily));
+    const compatibility = packages.some((pkg)=>pkg.status === 'unsupported-resolution') ? 'unresolved' : families.size > 1 ? 'mixed' : [
+        ...families
+    ][0] ?? 'not-installed';
+    const warnings = [];
+    if (compatibility === 'unresolved') warnings.push("Yarn Plug'n'Play package resolution is not supported. Installed versions and bundled references were not inspected; this does not mean dependencies are missing.");
+    if (compatibility === 'legacy') warnings.push('Choose whether to maintain 0.2 or migrate before changing APIs. Do not upgrade implicitly.');
+    if (compatibility === 'mixed' || compatibility === 'unsupported') warnings.push('Resolve package compatibility explicitly before implementing; do not mix API generations.');
+    if (new Set(versions).size > 1) warnings.push('Installed EdgeStore package versions differ. Read each package’s own references and verify compatibility.');
+    const files = (await readdir(directory)).filter((name)=>/^\.env(?:\.[\w.-]+)?$/.test(name));
+    const environmentFiles = [];
+    for (const name of files.sort()){
+        if ((await stat(path.join(directory, name))).isFile()) environmentFiles.push(path.join(directory, name));
+    }
+    return {
+        directory,
+        name: manifest.name,
+        ...applicationKind(dependencies),
+        packageManager: await detectPackageManager(directory),
+        workspaceRoot,
+        candidateWorkspaces: candidates,
+        packages,
+        compatibility,
+        warnings,
+        environmentFiles
+    };
+}
+function versionFamily(version) {
+    if (/^1\.\d+\.\d+(?:[-+].*)?$/.test(version)) return 'v1';
+    if (/^0\.2\.\d+(?:[-+].*)?$/.test(version)) return 'legacy';
+    return 'unsupported';
+}
+async function inspectPackage(directory, name, { declaredVersion, plugAndPlay }) {
+    const base = {
+        name,
+        declaredVersion
+    };
+    if (!declaredVersion) return {
+        ...base,
+        version: undefined,
+        status: 'not-declared'
+    };
+    if (plugAndPlay) return {
+        ...base,
+        version: undefined,
+        status: 'unsupported-resolution'
+    };
+    let manifestPath;
+    try {
+        manifestPath = await resolveApplicationPackage(directory, name);
+    } catch  {
+        return {
+            ...base,
+            version: undefined,
+            status: 'not-resolved'
+        };
+    }
+    let installed;
+    try {
+        installed = installedSchema.parse(JSON.parse(await readFile(manifestPath, 'utf8')));
+        if (installed.name !== name) throw new Error('Package name mismatch');
+    } catch  {
+        throw usageError('invalid_installed_package', `Invalid installed metadata for ${name}.`);
+    }
+    const { version } = installed;
+    const root = path.dirname(manifestPath);
+    const docsPath = path.join(root, 'agent-docs/README.md');
+    let bundled = false;
+    try {
+        const header = (await readFile(docsPath, 'utf8')).split('\n')[0];
+        bundled = header === `# ${name} ${version}: agent references`;
+    } catch (error) {
+        if (error.code !== 'ENOENT') throw error;
+    }
+    const family = versionFamily(version);
+    const docs = bundled ? {
+        kind: 'bundled',
+        path: docsPath,
+        version
+    } : {
+        kind: 'online-fallback',
+        version,
+        // Update the 0.2 URL to its archive as part of stable v1 docs promotion.
+        url: family === 'legacy' ? 'https://edgestore.dev/docs/quick-start' : family === 'v1' ? `${version.includes('-') ? 'https://next.edgestore.dev' : 'https://edgestore.dev'}/docs/agents` : undefined,
+        warning: 'No matching bundled references found. Online guidance may differ from this installed version; inspect installed types before using it.'
+    };
+    return {
+        ...base,
+        status: 'installed',
+        version,
+        root,
+        docs
+    };
+}
+async function resolveApplicationPackage(directory, name) {
+    const boundary = await findWorkspaceRoot(directory) ?? await findGitRoot(directory) ?? directory;
+    let current = directory;
+    while(true){
+        try {
+            // Follow package-manager symlinks, but never fall back to NODE_PATH or
+            // a global CLI's modules when the app has not installed its dependency.
+            return await realpath(path.join(current, 'node_modules', name, 'package.json'));
+        } catch (error) {
+            if (error.code !== 'ENOENT') throw error;
+        }
+        if (current === boundary || path.dirname(current) === current) break;
+        current = path.dirname(current);
+    }
+    throw new Error(`Package not installed in the selected application: ${name}`);
+}
+
+async function agentContextCommand(runtime, flags, input) {
+    await selectWorkspaceContext(runtime, flags, 'read');
+    const application = await inspectApplication(runtime.workspaceCwd);
+    const linked = await runtime.repoConfig.read();
+    const configurations = await configurationStatus(runtime, flags, input.assetFile);
+    const selectionRequired = !flags.cwd && !linked && application.candidateWorkspaces.length > 0;
+    const result = {
+        schemaVersion: 1,
+        cliVersion: input.cliVersion,
+        selectionRequired,
+        application,
+        ...application.compatibility === 'not-installed' ? {
+            referenceFallback: {
+                url: `${/^[^+]*-/.test(input.cliVersion) ? 'https://next.edgestore.dev' : 'https://edgestore.dev'}/docs/agents`,
+                warning: 'Setup guidance follows the CLI release channel; resolve installed package references after installation.'
+            }
+        } : {},
+        project: linked ? {
+            account: linked.config.account,
+            project: linked.config.project,
+            apiUrl: resolveApiUrl(apiOriginForRepoConfig(linked.config), undefined).displayUrl,
+            configPath: linked.path,
+            envFile: linked.config.envFile
+        } : null,
+        agentConfiguration: configurations.map(({ client, skills })=>({
+                client,
+                ...skills
+            })),
+        mcpConfiguration: configurations.map(({ client, mcp })=>({
+                client,
+                ...mcp
+            }))
+    };
+    if (selectionRequired) runtime.exitCode = 2;
+    outputFor(runtime, flags).result(result, [
+        `Application: ${application.directory}`,
+        `Framework: ${application.framework} (${application.role})`,
+        `Package manager: ${application.packageManager}`,
+        ...application.packages.map((pkg)=>`${pkg.name}: ${pkg.version ?? pkg.status}`),
+        ...application.warnings,
+        ...selectionRequired ? [
+            'Select an application workspace with --cwd before implementing.',
+            ...application.candidateWorkspaces.map((pkg)=>pkg.directory)
+        ] : []
+    ].join('\n'));
+}
+
+async function agentAssetsCommand(runtime, flags, input) {
+    const options = await agentOptions(runtime, flags, input);
+    const bundle = await loadSkillBundle(input.assetFile);
+    const skills = await planSkills(options, bundle, input.action);
+    const mcp = input.skillsOnly ? undefined : await planMcp(options, input.action === 'status' ? 'status' : 'setup');
+    const changes = [
+        ...skills.changes,
+        ...mcp?.changes ?? []
+    ];
+    if (changes.length && !input.dryRun) {
+        if (!input.yes) {
+            if (!isInteractive(runtime, flags)) throw usageError('confirmation_required', 'Use --yes to apply changes or --dry-run to preview them.');
+            if (!await runtime.prompts.confirm(`Apply ${input.skillsOnly ? 'skill' : 'skill and MCP'} changes for ${options.client} at ${options.global ? options.home : options.project}?`)) return;
+        }
+        // Both plans are preflighted before any asset or MCP configuration is changed.
+        await applyChanges(changes);
+    }
+    const current = !input.dryRun && changes.length ? await planSkills(options, bundle, 'status') : skills;
+    const connection = mcp && !input.dryRun && changes.length ? await planMcp(options, 'status') : mcp;
+    const result = {
+        schemaVersion: 1,
+        client: options.client,
+        scope: options.global ? 'global' : 'project',
+        action: input.action,
+        dryRun: Boolean(input.dryRun),
+        skills: current.result,
+        mcp: connection?.result ?? {
+            status: 'not-inspected',
+            reason: 'skills-only'
+        },
+        changes: changes.map(({ file, before, after })=>({
+                file,
+                action: after === undefined ? 'remove' : before === undefined ? 'create' : 'update',
+                applied: !input.dryRun
+            }))
+    };
+    outputFor(runtime, flags).result(result, [
+        `${options.client}: skill ${current.result.status}`,
+        current.result.directory,
+        `Bundled revision: ${bundle.revision}`,
+        ...changes.map(({ file })=>`${input.dryRun ? 'Would change' : 'Changed'}: ${file}`),
+        ...current.result.otherSources.map((file)=>`Skill found at: ${file}`),
+        ...connection?.result.warnings ?? [],
+        ...current.result.status === 'update-available' ? [
+            'Run edgestore agent update to install the skill from this CLI.'
+        ] : [],
+        ...!input.dryRun && skills.changes.length ? [
+            'Restart your client or open a new task to load the skill.'
+        ] : [],
+        ...!input.dryRun && mcp?.changes.length ? [
+            'Open your client to connect EdgeStore.'
+        ] : []
+    ].join('\n'));
+}
+
+async function loginCommand(runtime, flags, options) {
+    if (options.device && options.token) {
+        throw usageError('conflicting_login_modes', '--device and --token cannot be used together.');
+    }
+    const machineOutputFlag = flags.json ? '--json' : flags.plain ? '--plain' : undefined;
+    if (!options.token && machineOutputFlag) {
+        throw usageError('interactive_input_disabled', `OAuth login is interactive and cannot be used with ${machineOutputFlag}.`, [
+            'edgestore login',
+            'edgestore login --device'
+        ]);
+    }
+    if (options.device) return await oauthLogin(runtime, flags, 'device');
+    if (!options.token) return await oauthLogin(runtime, flags, 'browser');
+    if (machineOutputFlag && runtime.io.inputIsTty) {
+        throw usageError('interactive_input_disabled', `Interactive token input is disabled with ${machineOutputFlag}.`, [
+            `printf %s "$EDGESTORE_TOKEN" | edgestore login --token ${machineOutputFlag}`
+        ]);
+    }
+    const token = await runtime.prompts.readToken(runtime.io.stdin, runtime.io.inputIsTty);
+    const apiUrl = apiUrlFor(runtime, flags);
+    const sdk = runtime.sdkFactory({
+        token,
+        baseUrl: apiUrl.sdkBaseUrl
+    });
+    const identity = await sdk.management.whoami({
+        signal: runtime.signal
+    });
+    const environmentTokenActive = hasEnvironmentToken(runtime);
+    await runtime.credentials.set(apiUrl.displayUrl, token);
+    if (!environmentTokenActive) {
+        await updateActiveAccountAfterLogin(runtime, flags, identity.actor);
+    }
+    const output = outputFor(runtime, flags);
+    output.result(loginResult(identity.actor, environmentTokenActive), `Logged in as ${actorLabel(identity.actor)}.`, actorLabel(identity.actor));
+    warnWhenStoredLoginIsInactive(output, environmentTokenActive);
+}
+async function logoutCommand(runtime, flags) {
+    const apiOrigin = apiUrlFor(runtime, flags).displayUrl;
+    const output = outputFor(runtime, flags);
+    const stored = await runtime.credentials.get(apiOrigin);
+    let oauthCredential;
+    try {
+        oauthCredential = parseStoredOAuthCredential(stored);
+    } catch  {
+        output.warning('The stored OAuth login is invalid. Skipping remote revocation.');
+    }
+    let oauthRevoked;
+    let revocationFailure;
+    if (oauthCredential) {
+        try {
+            await runtime.oauth.revoke(oauthCredential, runtime.signal);
+            oauthRevoked = true;
+        } catch (error) {
+            if (runtime.signal.aborted) throw error;
+            oauthRevoked = false;
+            revocationFailure = normalizeError(error);
+            output.warning('The OAuth grant could not be revoked remotely. The login will still be removed locally.');
+        }
+    }
+    let deleted;
+    try {
+        deleted = await runtime.credentials.delete(apiOrigin);
+    } catch (error) {
+        const deletionFailure = normalizeError(error);
+        if (oauthRevoked) {
+            throw new CliError('logout_partial_failure', 'The OAuth grant was revoked, but the stored login could not be removed.', {
+                details: {
+                    status: 'partial',
+                    oauthGrant: {
+                        status: 'revoked'
+                    },
+                    localCredential: {
+                        status: 'delete_failed',
+                        cause: errorDetails$2(deletionFailure)
+                    }
+                },
+                requestId: deletionFailure.options.requestId,
+                suggestions: [
+                    renderCliCommand(flags, [
+                        'logout'
+                    ])
+                ],
+                exitCode: deletionFailure.exitCode
+            });
+        }
+        if (revocationFailure) {
+            throw new CliError('logout_failed', 'The OAuth grant could not be revoked and the stored login could not be removed.', {
+                details: {
+                    status: 'failed',
+                    oauthGrant: {
+                        status: 'revocation_failed',
+                        cause: errorDetails$2(revocationFailure)
+                    },
+                    localCredential: {
+                        status: 'delete_failed',
+                        cause: errorDetails$2(deletionFailure)
+                    }
+                },
                 requestId: deletionFailure.options.requestId ?? revocationFailure.options.requestId,
                 suggestions: [
                     renderCliCommand(flags, [
@@ -1947,10 +3006,9 @@ async function projectShowCommand(runtime, flags, projectRef) {
     ].join('\n'), project.basePath);
 }
 async function projectCreateCommand(runtime, flags, options) {
-    if (flags.plain && !options.withoutKey) {
-        throw usageError('one_time_secret_delivery_required', 'Plain output cannot deliver the initial project key.', [
-            'Use --without-key with --plain.',
-            'Use human or --json output to receive the one-time key.'
+    if (!isInteractive(runtime, flags) && !options.withoutKey) {
+        throw usageError('one_time_secret_delivery_required', 'Automated project creation requires --without-key.', [
+            'Create the project with --without-key, then use project key create with --output to deliver a protected key.'
         ]);
     }
     const account = await activeAccount(runtime, flags, options.account);
@@ -1962,14 +3020,16 @@ async function projectCreateCommand(runtime, flags, options) {
         allowOverage: Boolean(options.allowOverage),
         signal: runtime.signal
     });
-    const keyLines = result.projectKey ? [
+    const keyLines = isInteractive(runtime, flags) && result.projectKey ? [
         '',
         `EDGE_STORE_ACCESS_KEY=${result.projectKey.key.accessKey}`,
         `EDGE_STORE_SECRET_KEY=${result.projectKey.secretKey}`,
         '',
         'Save this secret now. You will not be able to view it again.'
     ] : [];
-    outputFor(runtime, flags).result(result, [
+    outputFor(runtime, flags).result({
+        project: result.project
+    }, [
         `Created project "${result.project.name}" (${result.project.basePath}).`,
         ...keyLines,
         '',
@@ -2602,21 +3662,276 @@ function findClosingQuote(value, quote) {
     return -1;
 }
 
-async function doctorCommand(runtime, flags, version) {
+async function localApplicationChecks(directory) {
+    const checks = [];
+    let application;
+    try {
+        application = await inspectApplication(directory);
+    } catch  {
+        return [
+            {
+                name: 'Application',
+                status: 'skip',
+                detail: 'No readable package manifest; select an application with --cwd.'
+            }
+        ];
+    }
+    checks.push({
+        name: 'Application',
+        status: application.framework === 'unknown' ? 'skip' : 'pass',
+        detail: `${application.framework} (${application.role})`
+    });
+    checks.push({
+        name: 'Package compatibility',
+        status: [
+            'mixed',
+            'unsupported'
+        ].includes(application.compatibility) ? 'fail' : application.compatibility === 'v1' ? 'pass' : 'warn',
+        detail: application.compatibility === 'legacy' ? 'Installed 0.2 packages: choose maintenance or migration explicitly.' : `${application.compatibility}; API authority is each installed package's references.`
+    });
+    for (const pkg of application.packages){
+        if (pkg.status === 'unsupported-resolution') checks.push({
+            name: pkg.name,
+            status: 'warn',
+            detail: "Yarn Plug'n'Play resolution is unsupported; installed versions and references could not be inspected."
+        });
+        if (pkg.status === 'not-resolved') checks.push({
+            name: pkg.name,
+            status: 'warn',
+            detail: 'Declared but not resolved; install dependencies in the selected workspace.'
+        });
+    }
+    for (const file of application.environmentFiles.filter((file)=>!/\.(example|sample|template)$/.test(file))){
+        try {
+            await validatePath(file, directory);
+            if ((await stat(file)).size > 128_000) throw new Error();
+            const contents = await readFile(file, 'utf8');
+            const exposed = [
+                ...contents.matchAll(/^(?:export\s+)?((?:VITE_|NEXT_PUBLIC_|PUBLIC_)\w*EDGE_?STORE\w*(?:SECRET|ACCESS)_KEY)\s*=/gm)
+            ].some((match)=>Boolean(dotenvValue(contents, match[1])));
+            const backendKeys = Boolean(dotenvValue(contents, 'EDGE_STORE_SECRET_KEY') || dotenvValue(contents, 'EDGE_STORE_ACCESS_KEY'));
+            if (exposed || backendKeys && application.role === 'frontend') {
+                checks.push({
+                    name: 'Environment boundary',
+                    status: 'fail',
+                    detail: `${path.basename(file)} contains project credentials in a frontend destination. Move them to the backend and rotate any exposed secret.`
+                });
+            }
+        } catch  {
+            checks.push({
+                name: 'Environment inspection',
+                status: 'skip',
+                detail: `${path.basename(file)} was not safely readable.`
+            });
+        }
+    }
+    const sources = await readSources(directory);
+    let adapter = false;
+    let provider = false;
+    let parsedFiles = 0;
+    for (const source of sources.files){
+        const facts = inspectSource(source.text, application.role === 'frontend');
+        if (!facts) continue;
+        parsedFiles++;
+        adapter ||= facts.adapter;
+        provider ||= facts.provider;
+        for (const detail of facts.warnings)checks.push({
+            name: `Source: ${source.name}`,
+            status: 'warn',
+            detail
+        });
+    }
+    checks.push({
+        name: 'Source inspection',
+        status: 'skip',
+        detail: `Parsed ${parsedFiles} files within a 200-file/2MB bound; ${sources.skipped || parsedFiles !== sources.files.length ? 'some files were skipped. ' : ''}Static observations do not prove route mounting, provider ancestry, or runtime behavior.`
+    });
+    if (application.role === 'backend' || application.role === 'fullstack') {
+        checks.push({
+            name: 'Server adapter',
+            status: 'skip',
+            detail: adapter ? 'An adapter import was found; verify its route mounts at the client endpoint.' : 'No direct adapter import found; inspect custom/re-exported routes using installed adapter references.'
+        });
+    }
+    if (application.role === 'frontend' || application.role === 'fullstack') {
+        checks.push({
+            name: 'React provider',
+            status: 'skip',
+            detail: provider ? 'EdgeStoreProvider JSX was found; verify it wraps the upload UI.' : 'No directly named EdgeStoreProvider JSX found; inspect custom wrappers and provider aliases.'
+        });
+    }
+    if (application.framework === 'hono') checks.push({
+        name: 'Environment loading',
+        status: 'skip',
+        detail: 'Hono does not itself establish the Node env-file loader. Check the actual start script loads the selected backend env file.'
+    });
+    checks.push({
+        name: 'Remote bucket mapping',
+        status: 'skip',
+        detail: 'Router/provider mapping was not executed or inferred. Compare actual bucket names during the application upload test.'
+    });
+    return checks;
+}
+function inspectSource(source, frontend) {
+    let ast;
+    try {
+        ast = parse$1(source, {
+            sourceType: 'unambiguous',
+            plugins: [
+                'typescript',
+                'jsx'
+            ],
+            attachComment: false
+        });
+    } catch  {
+        return undefined;
+    }
+    const warnings = new Set();
+    let adapter = false;
+    let provider = false;
+    const corsNames = new Set();
+    const handlers = new Set();
+    const clientFile = frontend || ast.program.directives.some((directive)=>directive.value.value === 'use client');
+    for (const statement of ast.program.body){
+        if (statement.type !== 'ImportDeclaration') continue;
+        const from = statement.source.value;
+        const typeOnly = statement.importKind === 'type' || statement.specifiers.length > 0 && statement.specifiers.every((specifier)=>specifier.type === 'ImportSpecifier' && specifier.importKind === 'type');
+        if (from.startsWith('@edgestore/server/adapters/') && !typeOnly) {
+            adapter = true;
+            for (const specifier of statement.specifiers)handlers.add(specifier.local.name);
+        }
+        if (from === 'hono/cors') {
+            for (const specifier of statement.specifiers)corsNames.add(specifier.local.name);
+        }
+        if (clientFile && !typeOnly && (from.startsWith('@edgestore/server') || statement.specifiers.some((specifier)=>specifier.type === 'ImportSpecifier' && isIdentifier(specifier.imported, {
+                name: 'EdgeStoreRouter'
+            }) && specifier.importKind !== 'type'))) {
+            warnings.add('Possible server runtime import in a client module. Use an import type for the backend router contract; do not bundle server modules.');
+        }
+    }
+    traverseFast(ast, (node)=>{
+        if (node.type === 'JSXOpeningElement' && node.name.type === 'JSXIdentifier' && node.name.name === 'EdgeStoreProvider') provider = true;
+        if (node.type !== 'CallExpression' || !isIdentifier(node.callee) || node.arguments[0]?.type !== 'ObjectExpression') return;
+        const argument = node.arguments[0];
+        if (handlers.has(node.callee.name) && property(argument, 'router') && !property(argument, 'edgestore')) {
+            warnings.add('Direct handler router option resembles 0.2 wiring. Check the installed version before maintaining or migrating it.');
+        }
+        if (corsNames.has(node.callee.name)) {
+            const origin = property(argument, 'origin');
+            const credentials = property(argument, 'credentials');
+            const reflects = origin?.type === 'ArrowFunctionExpression' && origin.params.length === 1 && isIdentifier(origin.params[0]) && isIdentifier(origin.body, {
+                name: origin.params[0].name
+            });
+            if (credentials?.type === 'BooleanLiteral' && credentials.value && (isStringLiteral(origin, {
+                value: '*'
+            }) || reflects)) warnings.add('Credentialed CORS uses a wildcard or reflected origin. Configure an explicit trusted frontend origin for the EdgeStore route.');
+        }
+    });
+    return {
+        adapter,
+        provider,
+        warnings: [
+            ...warnings
+        ]
+    };
+}
+function property(object, name) {
+    const member = object.properties.find((entry)=>isObjectProperty(entry) && !entry.computed && (isIdentifier(entry.key, {
+            name
+        }) || isStringLiteral(entry.key, {
+            value: name
+        })));
+    return isObjectProperty(member) ? member.value : undefined;
+}
+async function readSources(directory) {
+    const files = [];
+    let bytes = 0;
+    let skipped = false;
+    let inspectedEntries = 0;
+    const queue = [
+        directory
+    ];
+    const ignored = new Set([
+        'node_modules',
+        'dist',
+        'build',
+        'coverage',
+        'public',
+        'test',
+        'tests',
+        '__tests__'
+    ]);
+    while(queue.length && files.length < 200 && bytes < 2_000_000 && inspectedEntries < 2_000){
+        const current = queue.shift();
+        const entries = await readdir(current, {
+            withFileTypes: true
+        }).catch(()=>[]);
+        for (const entry of entries.sort((a, b)=>a.name.localeCompare(b.name))){
+            if (++inspectedEntries > 2_000) {
+                skipped = true;
+                break;
+            }
+            if (entry.isSymbolicLink() || entry.name.startsWith('.') || ignored.has(entry.name)) continue;
+            const file = path.join(current, entry.name);
+            if (entry.isDirectory()) {
+                // Do not inspect another workspace's source under a monorepo root.
+                if (await stat(path.join(file, 'package.json')).then(()=>true, ()=>false)) continue;
+                if (path.relative(directory, file).split(path.sep).length < 10) queue.push(file);
+                continue;
+            }
+            if (!/\.[cm]?[jt]sx?$/.test(entry.name) || /\.(test|spec)\./.test(entry.name) || entry.name.endsWith('.d.ts')) continue;
+            if (files.length >= 200) {
+                skipped = true;
+                break;
+            }
+            try {
+                const size = (await stat(file)).size;
+                if (size > 128_000 || bytes + size > 2_000_000) {
+                    skipped = true;
+                    continue;
+                }
+                await validatePath(file, directory);
+                files.push({
+                    name: path.relative(directory, file),
+                    text: await readFile(file, 'utf8')
+                });
+                bytes += size;
+            } catch  {
+                skipped = true;
+            }
+        }
+    }
+    return {
+        files,
+        skipped: skipped || queue.length > 0
+    };
+}
+
+async function doctorCommand(runtime, flags, options) {
     await selectWorkspaceContext(runtime, flags, 'read');
     const checks = [
         {
             name: 'CLI',
             status: 'pass',
-            detail: version
+            detail: options.version
         }
     ];
+    checks.push(...await localApplicationChecks(runtime.workspaceCwd));
     const apiUrl = apiUrlFor(runtime, flags);
     const globalConfig = await checkGlobalConfig(runtime, checks);
     const activeAccount = activeAccountFor(globalConfig, apiUrl.displayUrl);
     const localConfig = await checkLocalConfig(runtime, checks);
-    const linkedApiOrigin = localConfig ? apiOriginForRepoConfig(localConfig.config) : undefined;
+    const linkedApiOrigin = localConfig ? resolveApiUrl(apiOriginForRepoConfig(localConfig.config), undefined).displayUrl : undefined;
     const envKeys = await checkEnvFile(runtime, localConfig, checks);
+    if (options.offline) {
+        checks.push({
+            name: 'Remote checks',
+            status: 'skip',
+            detail: 'Offline: no credential-store access, OAuth, or API requests.'
+        });
+        report(runtime, flags, checks);
+        return;
+    }
     const keychainAvailable = await runtime.credentials.available();
     checks.push({
         name: 'Credential store',
@@ -2626,25 +3941,32 @@ async function doctorCommand(runtime, flags, version) {
     let credential;
     try {
         credential = await resolveCredential(runtime.env.EDGESTORE_TOKEN, runtime.credentials, {
-            apiOrigin: apiUrl.displayUrl,
-            oauth: runtime.oauth,
-            signal: runtime.signal
+            apiOrigin: apiUrl.displayUrl
         });
         checks.push({
             name: 'Credential',
             status: credential ? 'pass' : 'warn',
             detail: credential ? credential.source : 'Not configured'
         });
-    } catch (error) {
+    } catch  {
         rethrowIfAborted(runtime.signal);
         checks.push({
             name: 'Credential',
-            status: 'fail',
-            detail: error instanceof Error ? error.message : 'Could not read credential'
+            status: 'warn',
+            detail: 'No usable credential. Login or refresh explicitly; doctor does not change credentials.'
+        });
+    }
+    if (!credential) {
+        checks.push({
+            name: 'Remote checks',
+            status: 'skip',
+            detail: 'No usable existing credential; no network requests were made.'
         });
+        report(runtime, flags, checks);
+        return;
     }
     const sdk = runtime.sdkFactory({
-        token: credential?.token ?? 'edgestore-doctor',
+        token: credential.token,
         baseUrl: apiUrl.sdkBaseUrl
     });
     try {
@@ -2656,84 +3978,85 @@ async function doctorCommand(runtime, flags, version) {
             status: 'pass',
             detail: apiUrl.displayUrl
         });
-    } catch (error) {
+    } catch  {
         rethrowIfAborted(runtime.signal);
         checks.push({
             name: 'API',
             status: 'fail',
-            detail: error instanceof Error ? error.message : 'Health check failed'
+            detail: 'Health check failed; verify the API endpoint and network.'
+        });
+    }
+    let authenticated = false;
+    try {
+        const identity = await sdk.management.whoami({
+            signal: runtime.signal
+        });
+        authenticated = true;
+        const scopeDetail = 'scopes' in identity.actor ? ` (${identity.actor.scopes.join(', ')})` : '';
+        checks.push({
+            name: 'Authentication',
+            status: 'pass',
+            detail: `${identity.actor.kind}${scopeDetail}`
+        });
+    } catch  {
+        rethrowIfAborted(runtime.signal);
+        checks.push({
+            name: 'Authentication',
+            status: 'fail',
+            detail: 'Credential validation failed; inspect the login and granted scopes.'
         });
     }
-    if (credential) {
-        let authenticated = false;
+    if (authenticated && activeAccount) {
         try {
-            const identity = await sdk.management.whoami({
+            const account = await sdk.management.accounts.get({
+                account: activeAccount,
                 signal: runtime.signal
             });
-            authenticated = true;
-            const scopeDetail = 'scopes' in identity.actor ? ` (${identity.actor.scopes.join(', ')})` : '';
             checks.push({
-                name: 'Authentication',
+                name: 'Active account',
                 status: 'pass',
-                detail: `${identity.actor.kind}${scopeDetail}`
+                detail: `${account.account.displayName} (${account.account.id})`
             });
-        } catch (error) {
+        } catch  {
             rethrowIfAborted(runtime.signal);
             checks.push({
-                name: 'Authentication',
+                name: 'Active account',
                 status: 'fail',
-                detail: error instanceof Error ? error.message : 'Validation failed'
+                detail: 'Account is inaccessible with the current credential.'
             });
         }
-        if (authenticated && activeAccount) {
-            try {
-                const account = await sdk.management.accounts.get({
-                    account: activeAccount,
-                    signal: runtime.signal
-                });
-                checks.push({
-                    name: 'Active account',
-                    status: 'pass',
-                    detail: `${account.account.displayName} (${account.account.id})`
-                });
-            } catch (error) {
-                rethrowIfAborted(runtime.signal);
-                checks.push({
-                    name: 'Active account',
-                    status: 'fail',
-                    detail: error instanceof Error ? error.message : 'Account is inaccessible'
-                });
-            }
-        } else if (authenticated) {
-            checks.push({
-                name: 'Active account',
-                status: 'warn',
-                detail: 'Not selected'
+    } else if (authenticated) {
+        checks.push({
+            name: 'Active account',
+            status: 'warn',
+            detail: 'Not selected'
+        });
+    }
+    if (authenticated && localConfig && linkedApiOrigin !== apiUrl.displayUrl) {
+        checks.push({
+            name: 'Linked project',
+            status: 'fail',
+            detail: `Linked to ${linkedApiOrigin}, current API is ${apiUrl.displayUrl}`
+        });
+    } else if (authenticated && localConfig) {
+        try {
+            await checkLinkedProject(runtime, sdk, {
+                local: localConfig,
+                envKeys,
+                checks
             });
-        }
-        if (authenticated && localConfig && linkedApiOrigin !== apiUrl.displayUrl) {
+        } catch  {
+            rethrowIfAborted(runtime.signal);
             checks.push({
                 name: 'Linked project',
                 status: 'fail',
-                detail: `Linked to ${linkedApiOrigin}, current API is ${apiUrl.displayUrl}`
+                detail: 'Project is inaccessible with the current credential.'
             });
-        } else if (authenticated && localConfig) {
-            try {
-                await checkLinkedProject(runtime, sdk, {
-                    local: localConfig,
-                    envKeys,
-                    checks
-                });
-            } catch (error) {
-                rethrowIfAborted(runtime.signal);
-                checks.push({
-                    name: 'Linked project',
-                    status: 'fail',
-                    detail: error instanceof Error ? error.message : 'Project is inaccessible'
-                });
-            }
         }
     }
+    report(runtime, flags, checks);
+}
+function report(runtime, flags, checks) {
     if (checks.some((check)=>check.status === 'fail')) {
         runtime.exitCode = 1;
     }
@@ -2758,12 +4081,12 @@ async function checkGlobalConfig(runtime, checks) {
             detail: runtime.globalConfig.path
         });
         return config;
-    } catch (error) {
+    } catch  {
         rethrowIfAborted(runtime.signal);
         checks.push({
             name: 'Global config',
             status: 'fail',
-            detail: error instanceof Error ? error.message : 'Could not read config'
+            detail: 'Could not read global config; inspect its format locally.'
         });
         return {
             version: 2,
@@ -2780,22 +4103,32 @@ async function checkLocalConfig(runtime, checks) {
             detail: located?.path ?? 'No linked project'
         });
         return located;
-    } catch (error) {
+    } catch  {
         rethrowIfAborted(runtime.signal);
         checks.push({
             name: 'Local config',
             status: 'fail',
-            detail: error instanceof Error ? error.message : 'Could not read local config'
+            detail: 'Could not read local config; inspect its format locally.'
         });
         return undefined;
     }
 }
 async function checkEnvFile(runtime, localConfig, checks) {
-    const label = localConfig?.config.envFile ?? '.env.local';
+    const existing = (await readdir(runtime.workspaceCwd).catch(()=>[])).filter((file)=>/^\.env(?:\.(?:local|development)(?:\.local)?)?$/.test(file));
+    const label = localConfig?.config.envFile ?? (existing.length === 1 ? existing[0] : '.env.local');
+    if (!localConfig?.config.envFile && existing.length > 1) {
+        checks.push({
+            name: 'Environment selection',
+            status: 'skip',
+            detail: 'Multiple env files exist. Inspect the backend loader; only .env.local key presence is checked here.'
+        });
+    }
     const configRoot = localConfig?.config.envFile ? path.dirname(path.dirname(localConfig.path)) : runtime.workspaceCwd;
     const envPath = path.resolve(configRoot, label);
     let contents = '';
     try {
+        await validatePath(envPath, configRoot);
+        if ((await stat(envPath)).size > 128_000) throw new Error();
         contents = await readFile(envPath, 'utf8');
     } catch (error) {
         rethrowIfAborted(runtime.signal);
@@ -2807,10 +4140,11 @@ async function checkEnvFile(runtime, localConfig, checks) {
                 detail: 'Configured env file not found'
             });
         } else if (code !== 'ENOENT') {
+            const unsafePath = error instanceof CliError && error.code === 'unsafe_agent_path';
             checks.push({
                 name: label,
-                status: 'fail',
-                detail: 'Could not read file'
+                status: unsafePath ? 'skip' : 'fail',
+                detail: unsafePath ? 'Symlinked or out-of-scope env file was not inspected.' : 'Could not read file'
             });
         }
         return {
@@ -3024,313 +4358,58 @@ async function fileDeleteCommand(runtime, flags, input) {
                     notAttemptedReferences,
                     cause: {
                         code: cause.code,
-                        message: cause.message,
-                        ...cause.options.details === undefined ? {} : {
-                            details: cause.options.details
-                        }
-                    }
-                },
-                requestId: cause.options.requestId,
-                exitCode: cause.exitCode
-            });
-        }
-    }
-    const successCount = results.filter((result)=>result.success).length;
-    const failureCount = results.length - successCount;
-    const human = [
-        `Deleted ${successCount} file(s); ${failureCount} failed.`,
-        ...results.filter((result)=>!result.success).map((result)=>`  ${fileReferenceLabel(result.fileRef)}: ${result.error.message}`)
-    ].join('\n');
-    outputFor(runtime, flags).result({
-        results,
-        successCount,
-        failureCount
-    }, human);
-    if (failureCount) runtime.exitCode = 1;
-}
-function renderIncompleteDeletion(input) {
-    return [
-        `File deletion stopped: ${input.cause.message}`,
-        `Completed: ${input.successCount} succeeded, ${input.failureCount} failed.`,
-        ...input.results.map((result)=>`  ${JSON.stringify(result.fileRef)}: ${result.success ? 'deleted' : `failed: ${result.error?.message ?? 'unknown failure'}`}`),
-        `Uncertain (${input.uncertainReferences.length}):`,
-        ...input.uncertainReferences.map((reference)=>`  ${reference}`),
-        `Not attempted (${input.notAttemptedReferences.length}):`,
-        ...input.notAttemptedReferences.map((reference)=>`  ${reference}`)
-    ].join('\n');
-}
-function fileReference(value, bucket) {
-    if (bucket) return {
-        bucketName: bucket,
-        path: value
-    };
-    if (/^https?:\/\//i.test(value)) return {
-        url: value
-    };
-    return {
-        id: value
-    };
-}
-function fileReferenceLabel(reference) {
-    if ('id' in reference) return reference.id;
-    if ('key' in reference) return reference.key;
-    if ('url' in reference) return reference.url;
-    return `${reference.bucketName}/${reference.path}`;
-}
-
-async function detectPackages(cwd, options = {}) {
-    const resolvedCwd = path.resolve(cwd);
-    const workspaceRoot = await findWorkspaceRoot(resolvedCwd);
-    const packagePath = path.join(cwd, 'package.json');
-    let manifest;
-    let contents;
-    try {
-        contents = await readFile(packagePath, 'utf8');
-    } catch (error) {
-        if (!isMissingPathError(error)) {
-            throw new CliError('package_manifest_unreadable', `Could not read package manifest at ${packagePath}.`, {
-                details: {
-                    path: packagePath,
-                    cause: error instanceof Error ? error.message : String(error)
-                }
-            });
-        }
-        return {
-            framework: 'unknown',
-            manager: await detectPackageManager(cwd),
-            missing: []
-        };
-    }
-    try {
-        manifest = JSON.parse(contents);
-    } catch (error) {
-        throw new CliError('invalid_package_manifest', `Invalid package manifest at ${packagePath}.`, {
-            details: {
-                path: packagePath,
-                cause: error instanceof Error ? error.message : String(error)
-            },
-            exitCode: 2
-        });
-    }
-    const dependencies = {
-        ...manifest.dependencies,
-        ...manifest.devDependencies
-    };
-    const framework = dependencies.next ? 'next' : dependencies.react ? 'react' : 'node';
-    const wanted = framework === 'next' || framework === 'react' ? [
-        '@edgestore/server',
-        '@edgestore/react'
-    ] : [
-        '@edgestore/server'
-    ];
-    return {
-        framework,
-        manager: await detectPackageManager(cwd),
-        missing: wanted.filter((name)=>!dependencies[name]),
-        installAtWorkspaceRoot: options.installAtWorkspaceRoot,
-        ...workspaceRoot && workspaceRoot !== resolvedCwd ? {
-            workspace: {
-                root: workspaceRoot,
-                ...manifest.name ? {
-                    packageName: manifest.name
-                } : {}
-            }
-        } : {}
-    };
-}
-async function installPackages(runtime, plan, options) {
-    if (!plan.manager || !plan.missing.length) return {
-        ran: false
-    };
-    const args = installArgs(plan.manager, plan.missing, plan.installAtWorkspaceRoot);
-    const command = renderInstallCommand(plan.manager, args, {
-        plan,
-        packageCwd: options.cwd,
-        invocationCwd: options.invocationCwd
-    });
-    const shouldInstall = options.requested ?? (options.interactive ? await runtime.prompts.confirm(`Install EdgeStore packages with ${plan.manager}?`, true) : false);
-    if (!shouldInstall) return {
-        command,
-        cwd: options.cwd,
-        ran: false
-    };
-    const captured = options.structured ? createOutputCapture() : undefined;
-    try {
-        await runtime.runCommand(plan.manager, args, {
-            cwd: options.cwd,
-            ...captured ? {
-                stdout: captured.stream,
-                stderr: captured.stream
-            } : {}
-        });
-    } catch (error) {
-        const diagnostics = captured?.read().trim();
-        if (diagnostics && !options.json) {
-            runtime.io.stderr.write(`${diagnostics}\n`);
-        }
-        throw new CliError('package_install_failed', error instanceof Error ? error.message : 'Package installation failed.', {
-            ...diagnostics ? {
-                details: {
-                    diagnostics
-                }
-            } : {},
-            suggestions: [
-                command
-            ]
-        });
-    }
-    const diagnostics = captured?.read();
-    if (diagnostics) {
-        runtime.io.stderr.write(diagnostics.endsWith('\n') ? diagnostics : `${diagnostics}\n`);
-    }
-    return {
-        command,
-        cwd: options.cwd,
-        ran: true
-    };
-}
-function renderInstallCommand(manager, args, context) {
-    const { plan, packageCwd, invocationCwd } = context;
-    const workspace = plan.workspace;
-    if (invocationCwd === workspace?.root) {
-        const workspacePath = path.relative(workspace.root, packageCwd).replaceAll(path.sep, '/');
-        if (manager === 'pnpm') {
-            return renderShellCommand([
-                manager,
-                '--filter',
-                `./${workspacePath}`,
-                ...args
-            ]);
-        }
-        if (manager === 'npm') {
-            return renderShellCommand([
-                manager,
-                ...args,
-                '--workspace',
-                workspacePath
-            ]);
-        }
-        if (manager === 'yarn' && workspace.packageName) {
-            return renderShellCommand([
-                manager,
-                'workspace',
-                workspace.packageName,
-                ...args
-            ]);
+                        message: cause.message,
+                        ...cause.options.details === undefined ? {} : {
+                            details: cause.options.details
+                        }
+                    }
+                },
+                requestId: cause.options.requestId,
+                exitCode: cause.exitCode
+            });
         }
     }
-    const relativeCwd = path.relative(invocationCwd, packageCwd) || '.';
-    if (relativeCwd === '.') return renderShellCommand([
-        manager,
-        ...args
-    ]);
-    if (manager === 'npm') {
-        return renderShellCommand([
-            manager,
-            '--prefix',
-            relativeCwd,
-            ...args
-        ]);
-    }
-    if (manager === 'pnpm') {
-        return renderShellCommand([
-            manager,
-            '--dir',
-            relativeCwd,
-            ...args
-        ]);
-    }
-    return renderShellCommand([
-        manager,
-        '--cwd',
-        relativeCwd,
-        ...args
-    ]);
+    const successCount = results.filter((result)=>result.success).length;
+    const failureCount = results.length - successCount;
+    const human = [
+        `Deleted ${successCount} file(s); ${failureCount} failed.`,
+        ...results.filter((result)=>!result.success).map((result)=>`  ${fileReferenceLabel(result.fileRef)}: ${result.error.message}`)
+    ].join('\n');
+    outputFor(runtime, flags).result({
+        results,
+        successCount,
+        failureCount
+    }, human);
+    if (failureCount) runtime.exitCode = 1;
 }
-function packageNextSteps(framework) {
-    if (framework === 'next') {
-        return [
-            'Next steps:',
-            '  Configure an EdgeStore router in your Next.js app.',
-            '  Add the EdgeStore provider to your client layout.'
-        ];
-    }
-    if (framework === 'react') {
-        return [
-            'Next steps:',
-            '  Configure an EdgeStore server endpoint.',
-            '  Add the EdgeStore provider to your React app.'
-        ];
-    }
+function renderIncompleteDeletion(input) {
     return [
-        'Next steps:',
-        '  Configure an EdgeStore router and server endpoint.'
-    ];
+        `File deletion stopped: ${input.cause.message}`,
+        `Completed: ${input.successCount} succeeded, ${input.failureCount} failed.`,
+        ...input.results.map((result)=>`  ${JSON.stringify(result.fileRef)}: ${result.success ? 'deleted' : `failed: ${result.error?.message ?? 'unknown failure'}`}`),
+        `Uncertain (${input.uncertainReferences.length}):`,
+        ...input.uncertainReferences.map((reference)=>`  ${reference}`),
+        `Not attempted (${input.notAttemptedReferences.length}):`,
+        ...input.notAttemptedReferences.map((reference)=>`  ${reference}`)
+    ].join('\n');
 }
-function createOutputCapture(limit = 32_768) {
-    let output = '';
+function fileReference(value, bucket) {
+    if (bucket) return {
+        bucketName: bucket,
+        path: value
+    };
+    if (/^https?:\/\//i.test(value)) return {
+        url: value
+    };
     return {
-        stream: new Writable({
-            write (chunk, _encoding, callback) {
-                output = `${output}${Buffer.from(chunk).toString('utf8')}`.slice(-limit);
-                callback();
-            }
-        }),
-        read: ()=>output
+        id: value
     };
 }
-function isMissingPathError(error) {
-    return error instanceof Error && 'code' in error && (error.code === 'ENOENT' || error.code === 'ENOTDIR');
-}
-async function detectPackageManager(cwd) {
-    const start = path.resolve(cwd);
-    const boundary = await findWorkspaceRoot(start) ?? await findGitRoot(start) ?? start;
-    let directory = start;
-    while(true){
-        for (const strategy of [
-            'packageManager-field',
-            'lockfile',
-            'devEngines-field'
-        ]){
-            const result = await detect({
-                cwd: directory,
-                stopDir: directory,
-                strategies: [
-                    strategy
-                ],
-                packageJsonParser: (contents)=>packageJsonForStrategy(contents, strategy)
-            });
-            if (result?.name === 'pnpm' || result?.name === 'npm' || result?.name === 'yarn' || result?.name === 'bun') {
-                return result.name;
-            }
-        }
-        if (directory === boundary) break;
-        directory = path.dirname(directory);
-    }
-    return 'npm';
-}
-function packageJsonForStrategy(contents, strategy) {
-    const manifest = JSON.parse(contents);
-    if (strategy !== 'packageManager-field') delete manifest.packageManager;
-    if (strategy !== 'devEngines-field') delete manifest.devEngines;
-    return manifest;
-}
-function installArgs(manager, packages, installAtWorkspaceRoot = false) {
-    if (manager === 'npm') return [
-        'install',
-        ...packages
-    ];
-    if (manager === 'pnpm' && installAtWorkspaceRoot) {
-        return [
-            'add',
-            '-w',
-            ...packages
-        ];
-    }
-    return [
-        'add',
-        ...packages
-    ];
+function fileReferenceLabel(reference) {
+    if ('id' in reference) return reference.id;
+    if ('key' in reference) return reference.key;
+    if ('url' in reference) return reference.url;
+    return `${reference.bucketName}/${reference.path}`;
 }
 
 async function deliverEnvSecretWithRollback(input) {
@@ -3579,13 +4658,25 @@ function errorDetails$1(error) {
 const execFileAsync = promisify(execFile);
 async function resolveSecretOutput(runtime, explicitOutput, interactive) {
     if (explicitOutput) return explicitOutput;
-    if (!interactive) return '.env.local';
+    const linked = await runtime.repoConfig.read();
+    if (linked?.config.envFile) return linked.config.envFile;
     const discovered = (await readdir(runtime.workspaceCwd, {
         withFileTypes: true
     })).filter((entry)=>entry.isFile() && entry.name.startsWith('.env') && !/\.(?:example|sample|template)$/i.test(entry.name)).map((entry)=>entry.name).sort();
     if (!discovered.length || discovered.every((name)=>name === '.env.local')) {
         return '.env.local';
     }
+    if (!interactive) {
+        if (discovered.length === 1 && [
+            '.env',
+            '.env.local',
+            '.env.development',
+            '.env.development.local'
+        ].includes(discovered[0])) return discovered[0];
+        throw usageError('secret_output_required', 'Existing environment files require an explicit --output choice.', [
+            'Inspect the backend environment loader and pass --output <file>.'
+        ]);
+    }
     const choices = Array.from(new Set([
         ...discovered,
         '.env.local'
@@ -3606,6 +4697,13 @@ async function protectSecretFile(cwd, output) {
     const boundary = gitRoot ?? packageRoot;
     const repositoryRelative = path.relative(boundary, absolute);
     const packageRelative = path.relative(packageRoot, absolute);
+    const realPackageRoot = await realpath(packageRoot);
+    const realParent = await realpath(path.dirname(absolute));
+    const realRelative = path.relative(realPackageRoot, realParent);
+    if (realRelative === '..' || realRelative.startsWith(`..${path.sep}`) || path.isAbsolute(realRelative)) {
+        throw usageError('secret_output_unprotected', 'Secret output must not escape the selected package through a symlink.');
+    }
+    await rejectSymlink(absolute);
     if (!packageRelative || packageRelative.startsWith('..') || path.isAbsolute(packageRelative)) {
         throw usageError('secret_output_unprotected', `Secret output ${absolute} must be inside ${packageRoot}.`, [
             'Choose an env file inside the selected package.'
@@ -3622,6 +4720,7 @@ async function protectSecretFile(cwd, output) {
         if (await isIgnoredFile(gitRoot, gitPath)) return normalized;
     }
     const gitignorePath = path.join(packageRoot, '.gitignore');
+    await rejectSymlink(gitignorePath);
     let contents = '';
     try {
         contents = await readFile(gitignorePath, 'utf8');
@@ -3645,6 +4744,13 @@ async function protectSecretFile(cwd, output) {
     }
     return normalized;
 }
+async function rejectSymlink(file) {
+    try {
+        if ((await lstat(file)).isSymbolicLink()) throw usageError('secret_output_unprotected', `Refusing to overwrite a symlink at ${file}.`);
+    } catch (error) {
+        if (error.code !== 'ENOENT') throw error;
+    }
+}
 async function isIgnoredFile(root, relative) {
     try {
         await execFileAsync('git', [
@@ -4175,6 +5281,42 @@ function requireInteractive(interactive, message) {
     }
 }
 
+async function mcpCommand(runtime, flags, input) {
+    const { action } = input;
+    const options = await agentOptions(runtime, flags, input);
+    const { client } = options;
+    const plan = await planMcp(options, action);
+    if (plan.changes.length && !input.dryRun) {
+        if (!input.yes) {
+            if (!isInteractive(runtime, flags)) throw usageError('confirmation_required', 'Use --yes to apply changes or --dry-run to preview them.');
+            if (!await runtime.prompts.confirm(`${action === 'remove' ? 'Remove EdgeStore MCP from' : 'Configure EdgeStore MCP in'} ${plan.result.configPath}?`)) return;
+        }
+        await applyChanges(plan.changes);
+    }
+    const current = plan.changes.length && !input.dryRun ? (await planMcp(options, 'status')).result : plan.result;
+    const result = {
+        ...current,
+        action,
+        dryRun: Boolean(input.dryRun),
+        changedFiles: input.dryRun ? [] : plan.changes.map(({ file })=>file),
+        plannedFiles: plan.result.plannedFiles
+    };
+    outputFor(runtime, flags).result(result, [
+        `${client}: ${result.status}`,
+        result.configPath,
+        ...result.warnings,
+        ...input.dryRun ? [
+            'Dry run; no files changed.'
+        ] : [],
+        ...action === 'status' ? [
+            'Connection and sign-in were not checked.'
+        ] : [],
+        ...!input.dryRun && action === 'setup' ? [
+            'Open your client to connect EdgeStore.'
+        ] : []
+    ].join('\n'));
+}
+
 async function memberListCommand(runtime, flags, options) {
     const account = await selectedAccount(runtime, flags);
     if (account.type === 'PERSONAL') {
@@ -4459,7 +5601,7 @@ async function projectKeyListCommand(runtime, flags, project) {
     ], rows) : 'No project keys found.');
 }
 async function projectKeyCreateCommand(runtime, flags, input) {
-    requirePlainSecretDelivery(flags, input);
+    requireSecretDelivery(runtime, flags, input);
     await preflightKeyDelivery(runtime, input);
     const sdk = await sdkFor(runtime, flags);
     const { result, delivered } = await createAndDeliverKey({
@@ -4468,7 +5610,10 @@ async function projectKeyCreateCommand(runtime, flags, input) {
         sdk
     }, input);
     const values = keyValues(result.key.accessKey, result.secretKey);
-    outputFor(runtime, flags).result(result, [
+    outputFor(runtime, flags).result({
+        key: result.key,
+        delivery: delivered
+    }, [
         `Created project key "${result.key.name}".`,
         ...delivered.length ? [
             '',
@@ -4541,7 +5686,7 @@ async function projectKeyRotateCommand(runtime, flags, input) {
     } else if (!input.copy && !input.output) {
         throw usageError('secret_delivery_required', 'Non-interactive rotation requires --copy or --output.');
     }
-    requirePlainSecretDelivery(flags, input);
+    requireSecretDelivery(runtime, flags, input);
     const sdk = await sdkFor(runtime, flags);
     const listed = await sdk.management.projectKeys.list({
         project: input.project,
@@ -4673,7 +5818,10 @@ async function projectKeyRotateCommand(runtime, flags, input) {
         });
     }
     output.result({
-        replacement: result,
+        replacement: {
+            key: result.key,
+            delivery: delivered
+        },
         revokedKeyId: input.keyId
     }, input.yes ? [
         secretMessage,
@@ -4722,10 +5870,11 @@ async function preflightKeyDelivery(runtime, options) {
         'EDGE_STORE_ACCESS_KEY',
         'EDGE_STORE_SECRET_KEY'
     ], options);
+    if (options.output) await protectSecretFile(runtime.cwd, options.output);
 }
-function requirePlainSecretDelivery(flags, options) {
-    if (flags.plain && !options.copy && !options.output) {
-        throw usageError('secret_delivery_required', 'Plain output requires --copy or --output for the one-time key.');
+function requireSecretDelivery(runtime, flags, options) {
+    if (!isInteractive(runtime, flags) && !options.output) {
+        throw usageError('secret_delivery_required', 'Automated project-key commands require --output to deliver the one-time key to a protected env file.');
     }
 }
 function keyValues(accessKey, secretKey) {
@@ -4798,12 +5947,13 @@ async function tokenCreateCommand(runtime, flags, options) {
     if (!options.preset && !options.scope?.length) {
         throw usageError('token_permissions_required', 'Token creation requires --preset or at least one --scope.');
     }
-    if (flags.plain && !options.copy && !options.output) {
-        throw usageError('secret_delivery_required', 'Plain output requires --copy or --output for the one-time token.');
+    if (!isInteractive(runtime, flags) && !options.output) {
+        throw usageError('secret_delivery_required', 'Automated token creation requires --output to deliver the one-time token to a protected env file.');
     }
     await preflightEnvSecret(runtime.cwd, [
         'EDGESTORE_TOKEN'
     ], options);
+    if (options.output) await protectSecretFile(runtime.cwd, options.output);
     const sdk = await sdkFor(runtime, flags);
     const permissions = options.preset ? {
         preset: options.preset
@@ -4848,7 +5998,10 @@ async function tokenCreateCommand(runtime, flags, options) {
             'Use a credential with token:revoke access or revoke the token in the dashboard.'
         ]
     });
-    outputFor(runtime, flags).result(result, [
+    outputFor(runtime, flags).result({
+        token: result.token,
+        delivery: delivered
+    }, [
         `Created ${result.token.kind.toLowerCase()} token "${result.token.name}".`,
         ...delivered.length ? [
             '',
@@ -4883,6 +6036,141 @@ async function tokenRevokeCommand(runtime, flags, input) {
     outputFor(runtime, flags).result(result, `Revoked management token ${input.tokenId}.`, input.tokenId);
 }
 
+const SPINNER_FRAMES = [
+    '◒',
+    '◐',
+    '◓',
+    '◑'
+];
+const BAR_WIDTH = 18;
+class UploadProgressDisplay {
+    live;
+    entries = new Map();
+    colors;
+    timer;
+    frame = 0;
+    constructor(live, color){
+        this.live = live;
+        this.colors = createColors(color);
+    }
+    start(id, fileName, totalBytes) {
+        this.entries.set(id, {
+            fileName,
+            totalBytes,
+            progress: {
+                transferredBytes: 0,
+                totalBytes,
+                percentage: 0,
+                phase: 'preparing'
+            },
+            status: 'active'
+        });
+        this.startTimer();
+        this.render();
+    }
+    update(id, progress) {
+        const entry = this.entries.get(id);
+        if (entry?.status !== 'active' || sameProgress(entry.progress, progress)) return;
+        entry.progress = progress;
+    }
+    succeed(id) {
+        const entry = this.entries.get(id);
+        if (!entry) return;
+        entry.status = 'succeeded';
+        this.afterEntryFinished();
+    }
+    fail(id, canceled) {
+        const entry = this.entries.get(id);
+        if (!entry) return;
+        entry.status = canceled ? 'canceled' : 'failed';
+        this.afterEntryFinished();
+    }
+    close() {
+        this.stopTimer();
+        this.render();
+        this.live.done();
+        this.entries.clear();
+    }
+    startTimer() {
+        if (this.timer) return;
+        this.timer = setInterval(()=>{
+            this.frame = (this.frame + 1) % SPINNER_FRAMES.length;
+            this.render();
+        }, 80);
+        this.timer.unref();
+    }
+    stopTimer() {
+        if (!this.timer) return;
+        clearInterval(this.timer);
+        this.timer = undefined;
+    }
+    afterEntryFinished() {
+        if ([
+            ...this.entries.values()
+        ].every((entry)=>entry.status !== 'active')) {
+            this.stopTimer();
+        }
+        this.render();
+    }
+    render() {
+        if (!this.entries.size) {
+            this.live.clear();
+            return;
+        }
+        const spinner = this.colors.magenta(SPINNER_FRAMES[this.frame] ?? '◒');
+        this.live([
+            ...this.entries.entries()
+        ].sort(([left], [right])=>left - right).map(([, entry])=>renderEntry(entry, spinner, this.colors)).join('\n'));
+    }
+}
+function createUploadProgressDisplay(runtime, flags) {
+    const enabled = flags.progress && !flags.json && !flags.plain && runtime.io.stderrIsTty;
+    if (!enabled) return undefined;
+    return new UploadProgressDisplay(createLogUpdate(runtime.io.stderr, {
+        showCursor: true,
+        defaultWidth: 80
+    }), flags.color && runtime.env.NO_COLOR === undefined);
+}
+function renderEntry(entry, spinner, colors) {
+    if (entry.status === 'succeeded') {
+        return `${colors.green('◆')} ${entry.fileName} ${colors.green('uploaded')} · ${formatBytes(entry.totalBytes)}`;
+    }
+    if (entry.status !== 'active') {
+        return `${colors.red('■')} ${entry.fileName} ${colors.red(entry.status)}`;
+    }
+    const { progress } = entry;
+    const percentage = Math.max(0, Math.min(100, progress.percentage));
+    const completed = Math.round(percentage / 100 * BAR_WIDTH);
+    const bar = `${colors.magenta('━'.repeat(completed))}${colors.dim('─'.repeat(BAR_WIDTH - completed))}`;
+    const transfer = `${formatBytes(progress.transferredBytes)} / ${formatBytes(progress.totalBytes)}`;
+    return `${spinner} ${entry.fileName}  ${bar} ${formatPercentage(percentage)} · ${transfer} · ${progress.phase}`;
+}
+function sameProgress(left, right) {
+    return left.transferredBytes === right.transferredBytes && left.totalBytes === right.totalBytes && left.percentage === right.percentage && left.phase === right.phase;
+}
+function formatPercentage(percentage) {
+    return `${Number(percentage.toFixed(2))}%`;
+}
+function formatBytes(bytes) {
+    if (bytes < 1024) return `${bytes} B`;
+    const units = [
+        'KB',
+        'MB',
+        'GB',
+        'TB'
+    ];
+    let value = bytes / 1024;
+    let unit = units[0] ?? 'KB';
+    for (const candidate of units.slice(1)){
+        if (value < 1024) break;
+        value /= 1024;
+        unit = candidate;
+    }
+    const precision = value >= 10 ? 0 : 1;
+    return `${Number(value.toFixed(precision))} ${unit}`;
+}
+
+const FILE_UPLOAD_CONCURRENCY = 3;
 async function fileUploadCommand(runtime, flags, input) {
     if (flags.plain) {
         throw usageError('plain_output_unavailable', 'File upload does not have a single plain-text result.', [
@@ -4904,73 +6192,64 @@ async function fileUploadCommand(runtime, flags, input) {
     if (localFiles.length > 1 && input.path && !input.path.endsWith('/')) {
         throw usageError('upload_path_not_folder', '--path must end in / when uploading multiple files.');
     }
+    validateUniqueUploadDestinations(localFiles, {
+        destinationPath: input.path,
+        keepName: input.keepName
+    });
     const project = await resolvedProjectRef(runtime, flags, input.project);
     const sdk = await sdkFor(runtime, flags);
-    const results = [];
-    for (const [index, localFile] of localFiles.entries()){
-        try {
-            const fileName = path.basename(localFile);
-            const mimeType = mimeTypeFor(fileName);
-            const destination = resolveUploadDestination(input.path, {
-                fileName,
-                keepName: input.keepName
-            });
-            const source = await openAsBlob(localFile, mimeType ? {
-                type: mimeType
-            } : undefined);
+    const progressDisplay = createUploadProgressDisplay(runtime, flags);
+    let outcomes;
+    try {
+        const upload = async (localFile, index)=>{
             try {
-                const completed = await sdk.management.uploads.upload({
-                    project,
-                    bucket: input.bucket,
-                    source,
-                    signedReadUrl: {},
-                    ...destination.fileName ? {
-                        fileName: destination.fileName
-                    } : {},
-                    ...destination.path ? {
-                        path: destination.path
-                    } : {},
-                    mimeType,
-                    signal: runtime.signal,
-                    onProgress: (progress)=>reportProgress(runtime, flags, {
-                            fileName,
-                            percentage: progress.percentage
-                        })
-                });
-                results.push({
-                    localPath: localFile,
-                    ...completed
-                });
+                return {
+                    status: 'completed',
+                    result: await uploadLocalFile({
+                        runtime,
+                        flags,
+                        sdk,
+                        progressDisplay,
+                        index,
+                        localFile,
+                        project,
+                        bucket: input.bucket,
+                        destinationPath: input.path,
+                        keepName: input.keepName
+                    })
+                };
             } catch (error) {
-                throw normalizeUploadError(error, {
-                    runtime,
-                    flags,
-                    project
-                });
+                return {
+                    status: 'failed',
+                    localPath: localFile,
+                    cause: normalizeError(error)
+                };
             }
-        } catch (error) {
-            if (localFiles.length === 1) throw error;
-            const cause = normalizeError(error);
-            const notAttemptedPaths = localFiles.slice(index + 1);
-            throw new CliError('file_upload_incomplete', [
-                `Upload batch stopped while processing ${localFile}: ${cause.message}`,
-                `Completed (${results.length}):`,
-                ...results.map((result)=>`  ${result.localPath} -> ${result.signedReadUrl?.signedUrl ?? result.file.url} (${result.file.id})`),
-                `Interrupted: ${localFile}`,
-                `Not attempted (${notAttemptedPaths.length}):`,
-                ...notAttemptedPaths.map((file)=>`  ${file}`)
-            ].join('\n'), {
-                details: {
-                    completed: results,
-                    interruptedPath: localFile,
-                    notAttemptedPaths,
-                    cause: errorDetails(cause)
-                },
-                requestId: cause.options.requestId,
-                suggestions: cause.options.suggestions,
-                exitCode: cause.exitCode
-            });
-        }
+        };
+        outcomes = localFiles.length === 1 ? [
+            await upload(localFiles[0], 0)
+        ] : await mapConcurrent(localFiles, upload, {
+            concurrency: FILE_UPLOAD_CONCURRENCY,
+            signal: runtime.signal
+        });
+    } finally{
+        progressDisplay?.close();
+    }
+    const results = outcomes.flatMap((outcome)=>outcome?.status === 'completed' ? [
+            outcome.result
+        ] : []);
+    const failures = outcomes.flatMap((outcome)=>outcome?.status === 'failed' ? [
+            outcome
+        ] : []);
+    const notAttemptedPaths = localFiles.filter((_, index)=>!outcomes[index]);
+    if (failures.length || notAttemptedPaths.length) {
+        if (localFiles.length === 1 && failures[0]) throw failures[0].cause;
+        if (runtime.signal.aborted && !failures.length) throw interruptedError();
+        throw batchUploadError({
+            results,
+            failures,
+            notAttemptedPaths
+        });
     }
     const human = results.map((result)=>{
         const readUrl = result.signedReadUrl?.signedUrl ?? result.file.url;
@@ -4980,6 +6259,123 @@ async function fileUploadCommand(runtime, flags, input) {
         uploads: results
     }, human);
 }
+async function uploadLocalFile(input) {
+    const { progressDisplay } = input;
+    const fileName = path.basename(input.localFile);
+    const mimeType = mimeTypeFor(fileName);
+    const destination = resolveUploadDestination(input.destinationPath, {
+        fileName,
+        keepName: input.keepName
+    });
+    const source = await openAsBlob(input.localFile, mimeType ? {
+        type: mimeType
+    } : undefined);
+    progressDisplay?.start(input.index, fileName, source.size);
+    try {
+        const completed = await input.sdk.management.uploads.upload({
+            project: input.project,
+            bucket: input.bucket,
+            source,
+            signedReadUrl: {},
+            ...destination.fileName ? {
+                fileName: destination.fileName
+            } : {},
+            ...destination.path ? {
+                path: destination.path
+            } : {},
+            mimeType,
+            signal: input.runtime.signal,
+            ...progressDisplay ? {
+                onProgress: (progress)=>progressDisplay.update(input.index, progress)
+            } : {}
+        });
+        progressDisplay?.succeed(input.index);
+        return {
+            localPath: input.localFile,
+            ...completed
+        };
+    } catch (error) {
+        progressDisplay?.fail(input.index, input.runtime.signal.aborted);
+        throw normalizeUploadError(error, {
+            runtime: input.runtime,
+            flags: input.flags,
+            project: input.project
+        });
+    }
+}
+async function mapConcurrent(values, mapper, options) {
+    const results = Array(values.length);
+    let nextIndex = 0;
+    const workers = Array.from({
+        length: Math.min(options.concurrency, values.length)
+    }, async ()=>{
+        while(!options.signal.aborted){
+            const index = nextIndex++;
+            if (index >= values.length) return;
+            results[index] = await mapper(values[index], index);
+        }
+    });
+    await Promise.all(workers);
+    return results;
+}
+function batchUploadError(input) {
+    const firstFailure = input.failures[0]?.cause;
+    const suggestions = Array.from(new Set(input.failures.flatMap((failure)=>failure.cause.options.suggestions ?? [])));
+    const lines = [
+        `Upload batch finished with ${input.failures.length} failure${input.failures.length === 1 ? '' : 's'}.`,
+        `Completed (${input.results.length}):`,
+        ...input.results.map((result)=>`  ${result.localPath} -> ${result.signedReadUrl?.signedUrl ?? result.file.url} (${result.file.id})`),
+        `Failed (${input.failures.length}):`,
+        ...input.failures.map((failure)=>`  ${failure.localPath}: ${failure.cause.message}`),
+        ...input.notAttemptedPaths.length ? [
+            `Not attempted (${input.notAttemptedPaths.length}):`,
+            ...input.notAttemptedPaths.map((file)=>`  ${file}`)
+        ] : []
+    ];
+    return new CliError('file_upload_incomplete', lines.join('\n'), {
+        details: {
+            completed: input.results,
+            failures: input.failures.map((failure)=>({
+                    localPath: failure.localPath,
+                    cause: errorDetails(failure.cause)
+                })),
+            notAttemptedPaths: input.notAttemptedPaths
+        },
+        requestId: firstFailure?.options.requestId,
+        ...suggestions.length ? {
+            suggestions
+        } : {},
+        exitCode: firstFailure?.exitCode
+    });
+}
+function validateUniqueUploadDestinations(localFiles, options) {
+    const filesByDestination = new Map();
+    for (const localFile of localFiles){
+        const destination = resolveUploadDestination(options.destinationPath, {
+            fileName: path.basename(localFile),
+            keepName: options.keepName
+        });
+        if (!destination.fileName) continue;
+        const remotePath = path.posix.join(destination.path ?? '', destination.fileName);
+        const files = filesByDestination.get(remotePath) ?? [];
+        files.push(localFile);
+        filesByDestination.set(remotePath, files);
+    }
+    const conflicts = [
+        ...filesByDestination.entries()
+    ].filter(([, files])=>files.length > 1);
+    if (!conflicts.length) return;
+    throw usageError('upload_destination_conflict', [
+        'Multiple files resolve to the same upload destination:',
+        ...conflicts.flatMap(([remotePath, files])=>[
+                `  ${remotePath}`,
+                ...files.map((file)=>`    ${file}`)
+            ])
+    ].join('\n'), [
+        'Rename the local files so each destination is unique.',
+        'Omit --keep-name to let EdgeStore generate unique file names.'
+    ]);
+}
 function resolveUploadDestination(destinationPath, input) {
     if (!destinationPath) {
         return input.keepName ? {
@@ -5045,11 +6441,6 @@ function interruptedError() {
 function isFileBlobMutation(error) {
     return error instanceof DOMException && error.name === 'NotReadableError';
 }
-function reportProgress(runtime, flags, progress) {
-    if (flags.progress && !flags.json && runtime.io.outputIsTty) {
-        runtime.io.stderr.write(`${progress.fileName}: uploading ${progress.percentage}%\n`);
-    }
-}
 async function fileUploadStatusCommand(runtime, flags, input) {
     const sdk = await sdkFor(runtime, flags);
     const result = await sdk.management.uploads.get({
@@ -5209,9 +6600,52 @@ Common workflows:
     program.command('whoami').description('Show the current identity and context').action(async ()=>{
         await whoamiCommand(runtime, globalFlags(program));
     });
-    program.command('doctor').description('Check local configuration and API connectivity').action(async ()=>{
-        await doctorCommand(runtime, globalFlags(program), version);
+    program.command('doctor').description('Check local configuration and API connectivity').option('--offline', 'inspect locally without credentials, OAuth, or API requests').action(async (options)=>{
+        await doctorCommand(runtime, globalFlags(program), {
+            version,
+            offline: options.offline
+        });
+    });
+    const agent = program.command('agent').description('Manage coding-agent integrations');
+    const assetFile = fileURLToPath(new URL('../agent-assets/skills.json', import.meta.url));
+    agent.command('context').description('Show application versions and local documentation paths').action(async ()=>{
+        await agentContextCommand(runtime, globalFlags(program), {
+            cliVersion: version,
+            assetFile
+        });
     });
+    const agentDescriptions = {
+        setup: 'Install the EdgeStore skill and configure MCP',
+        update: 'Update the skill from this CLI and configure MCP',
+        status: 'Show installed skill and MCP configuration'
+    };
+    for (const action of [
+        'setup',
+        'update',
+        'status'
+    ]){
+        agent.command(action).description(agentDescriptions[action]).option('--client <client>', 'codex, claude, or cursor').option('--global', 'use user-level skill and MCP configuration').option('--skills-only', 'manage only the skill').option('--dry-run', 'preview changes without writing').option('--yes', 'skip confirmation prompts').action(async (options)=>agentAssetsCommand(runtime, globalFlags(program), {
+                ...options,
+                action,
+                assetFile
+            }));
+    }
+    const mcp = program.command('mcp').description('Manage the EdgeStore MCP configuration');
+    const mcpDescriptions = {
+        setup: 'Configure the EdgeStore MCP connection',
+        status: 'Show the saved MCP configuration, not connection status',
+        remove: 'Remove the EdgeStore MCP connection'
+    };
+    for (const action of [
+        'setup',
+        'status',
+        'remove'
+    ]){
+        mcp.command(action).description(mcpDescriptions[action]).option('--client <client>', 'codex, claude, or cursor').option('--global', 'use the user-level client configuration').option('--dry-run', 'preview changes without writing').option('--yes', 'skip confirmation prompts').action(async (options)=>mcpCommand(runtime, globalFlags(program), {
+                ...options,
+                action
+            }));
+    }
     program.command('init').description('Configure EdgeStore for the current project').option('--new', 'create a new project').option('--link <project>', 'link an existing project').option('--name <name>', 'new project name').option('--account <account-id>', 'override the active account').option('--create-key', 'create a new local project key').option('--without-key', 'do not create a project key').option('--output <file>', 'write project keys to an env file').option('--update', 'replace existing values in the output file').option('--bucket <bucket>', 'create a bucket').option('--bucket-type <type>', 'bucket type: file or image').option('--public', 'make the new bucket public').option('--protected', 'make the new bucket protected').option('--install', 'install detected EdgeStore packages').option('--allow-overage', 'allow billable project overage').addHelpText('after', `
 Examples:
   edgestore init --new --name "Marketing Site" --output .env.local