expxagents 0.20.1 → 0.21.1

package/dist/cli/src/commands/__tests__/outdated.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/cli/src/commands/__tests__/outdated.test.js

@@ -0,0 +1,76 @@
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import { mkdirSync, writeFileSync, rmSync, mkdtempSync } from 'node:fs';
+import { join } from 'node:path';
+import { tmpdir } from 'node:os';
+import { scanInstalledSquads } from '../outdated.js';
+describe('scanInstalledSquads', () => {
+    let tempDir;
+    beforeEach(() => {
+        tempDir = mkdtempSync(join(tmpdir(), 'squads-test-'));
+    });
+    afterEach(() => {
+        rmSync(tempDir, { recursive: true, force: true });
+    });
+    it('returns empty array when directory does not exist', () => {
+        const result = scanInstalledSquads('/nonexistent/path');
+        expect(result).toEqual([]);
+    });
+    it('returns empty array when no @scope directories exist', () => {
+        mkdirSync(join(tempDir, 'local-squad'), { recursive: true });
+        writeFileSync(join(tempDir, 'local-squad', 'squad.yaml'), 'squad:\n  version: "1.0.0"');
+        const result = scanInstalledSquads(tempDir);
+        expect(result).toEqual([]);
+    });
+    it('finds squads under @scope directories', () => {
+        const squadDir = join(tempDir, '@thulio', 'brand-squad');
+        mkdirSync(squadDir, { recursive: true });
+        writeFileSync(join(squadDir, 'squad.yaml'), 'squad:\n  code: brand-squad\n  version: "1.2.0"');
+        const result = scanInstalledSquads(tempDir);
+        expect(result).toEqual([
+            { fullName: '@thulio/brand-squad', currentVersion: '1.2.0' },
+        ]);
+    });
+    it('skips squads without squad.yaml', () => {
+        const squadDir = join(tempDir, '@thulio', 'no-yaml');
+        mkdirSync(squadDir, { recursive: true });
+        const result = scanInstalledSquads(tempDir);
+        expect(result).toEqual([]);
+    });
+    it('skips squads with invalid yaml', () => {
+        const squadDir = join(tempDir, '@thulio', 'bad-yaml');
+        mkdirSync(squadDir, { recursive: true });
+        writeFileSync(join(squadDir, 'squad.yaml'), '}{invalid');
+        const result = scanInstalledSquads(tempDir);
+        expect(result).toEqual([]);
+    });
+    it('skips squads without version field', () => {
+        const squadDir = join(tempDir, '@thulio', 'no-version');
+        mkdirSync(squadDir, { recursive: true });
+        writeFileSync(join(squadDir, 'squad.yaml'), 'squad:\n  code: no-version');
+        const result = scanInstalledSquads(tempDir);
+        expect(result).toEqual([]);
+    });
+    it('finds squads with nested tarball structure (@scope/name/name/squad.yaml)', () => {
+        const nestedDir = join(tempDir, '@community', 'copy-squad', 'copy-squad');
+        mkdirSync(nestedDir, { recursive: true });
+        writeFileSync(join(nestedDir, 'squad.yaml'), 'squad:\n  code: copy-squad\n  version: "2.0.0"');
+        const result = scanInstalledSquads(tempDir);
+        expect(result).toEqual([
+            { fullName: '@community/copy-squad', currentVersion: '2.0.0' },
+        ]);
+    });
+    it('finds multiple squads across scopes', () => {
+        const squad1 = join(tempDir, '@thulio', 'squad-a');
+        const squad2 = join(tempDir, '@community', 'squad-b');
+        mkdirSync(squad1, { recursive: true });
+        mkdirSync(squad2, { recursive: true });
+        writeFileSync(join(squad1, 'squad.yaml'), 'squad:\n  version: "1.0.0"');
+        writeFileSync(join(squad2, 'squad.yaml'), 'squad:\n  version: "2.0.0"');
+        const result = scanInstalledSquads(tempDir);
+        expect(result).toHaveLength(2);
+        expect(result).toEqual(expect.arrayContaining([
+            { fullName: '@thulio/squad-a', currentVersion: '1.0.0' },
+            { fullName: '@community/squad-b', currentVersion: '2.0.0' },
+        ]));
+    });
+});

package/dist/cli/src/commands/create.js

@@ -2,6 +2,7 @@ import { spawn } from 'child_process';
 import path from 'path';
 import fs from 'fs';
 import { getCoreAsset } from '../utils/config.js';
+import { getCommandPrefix } from '../utils/command-prefix.js';
 export async function createCommand(description) {
     const cwd = process.cwd();
     const architectPath = getCoreAsset('solution-architect.agent.md');
@@ -46,7 +47,7 @@ export async function createCommand(description) {
     });
     child.on('exit', (code) => {
         if (code === 0) {
-            console.log('\nSquad created! Run `expxagents list` to see it.');
+            console.log(`\nSquad created! Run \`${getCommandPrefix()} list\` to see it.`);
         }
         else {
             console.error(`\nArchitect exited with code ${code}`);

package/dist/cli/src/commands/doctor.js

@@ -2,8 +2,10 @@ import fs from 'fs';
 import path from 'path';
 import { execSync } from 'child_process';
 import { getAssetsDir } from '../utils/config.js';
+import { getCommandPrefix } from '../utils/command-prefix.js';
 export async function doctorCommand() {
     const cwd = process.cwd();
+    const cmd = getCommandPrefix();
     const checks = [];
     // Node.js version
     const nodeVersion = process.version;
@@ -44,7 +46,7 @@ export async function doctorCommand() {
         checks.push({
             name: 'MCP integrations',
             status: 'warn',
-            message: 'No MCPs configured. Run: expxagents mcp setup <id>',
+            message: `No MCPs configured. Run: ${cmd} mcp setup <id>`,
         });
     }
     // Project structure
@@ -54,7 +56,7 @@ export async function doctorCommand() {
         checks.push({
             name: `Directory: ${dir}`,
             status: exists ? 'ok' : 'warn',
-            message: exists ? 'exists' : 'missing — run `expxagents init`',
+            message: exists ? 'exists' : `missing — run \`${cmd} init\``,
         });
     }
     // .env file
@@ -62,7 +64,7 @@ export async function doctorCommand() {
     checks.push({
         name: '.env file',
         status: envExists ? 'ok' : 'warn',
-        message: envExists ? 'exists' : 'missing — run `expxagents init`',
+        message: envExists ? 'exists' : `missing — run \`${cmd} init\``,
     });
     // Company profile
     const companyPath = path.join(cwd, '_expxagents', '_memory', 'company.md');
@@ -72,7 +74,7 @@ export async function doctorCommand() {
         checks.push({
             name: 'Company profile',
             status: configured ? 'ok' : 'warn',
-            message: configured ? 'configured' : 'not configured — run `expxagents onboarding`',
+            message: configured ? 'configured' : `not configured — run \`${cmd} onboarding\``,
         });
     }
     // Squads count

package/dist/cli/src/commands/init.js

@@ -3,6 +3,8 @@ import path from 'path';
 import crypto from 'crypto';
 import { execSync } from 'child_process';
 import { getTemplateDir, getAssetsDir } from '../utils/config.js';
+import { tryGlobalInstall } from '../utils/global-install.js';
+import { getVersion } from '../utils/version.js';
 function getDefaultTemplate(file) {
     if (file === 'company.md') {
         return `<!-- NOT CONFIGURED -->
@@ -408,6 +410,13 @@ BRIDGE_TIMEOUT_MS=300000
         fs.writeFileSync(gitignorePath, gitignoreEntries.join('\n') + '\n', 'utf-8');
         console.log('  Created .gitignore');
     }
+    // Try global install
+    const version = getVersion();
+    const globalInstalled = tryGlobalInstall(version);
+    const prefix = globalInstalled ? 'expxagents' : 'npx expxagents';
+    if (globalInstalled) {
+        console.log('\n  ✓ CLI installed globally');
+    }
     // MCP Setup
     const mcpsDir = path.resolve('mcps');
     if (fs.existsSync(mcpsDir)) {
@@ -438,7 +447,7 @@ BRIDGE_TIMEOUT_MS=300000
                 }
             }
         }
-        console.log('\n  Run: expxagents mcp setup <id> to configure additional MCPs\n');
+        console.log(`\n  Run: ${prefix} mcp setup <id> to configure additional MCPs\n`);
     }
     // Install Python dependencies
     const pythonDeps = ['aiohttp', 'aiofiles', 'python-dotenv'];
@@ -461,7 +470,7 @@ BRIDGE_TIMEOUT_MS=300000
         console.log('\nUpdate complete! Assets refreshed to latest version.');
     }
     else {
-        console.log('\nProject initialized! Run `expxagents onboarding` to configure your profile.');
+        console.log(`\nProject initialized! Run \`${prefix} onboarding\` to configure your profile.`);
         console.log('Use /expxagents in Claude Code to get started.');
     }
 }

package/dist/cli/src/commands/install.js

@@ -1,5 +1,6 @@
 import fs from 'fs';
 import path from 'path';
+import { getCommandPrefix } from '../utils/command-prefix.js';
 const SKILL_CATALOG = {
     'web-search': {
         description: 'Web search capability (built-in)',
@@ -34,6 +35,7 @@ const SKILL_CATALOG = {
 };
 export async function installCommand(skillName) {
     const cwd = process.cwd();
+    const cmd = getCommandPrefix();
     const skillsDir = path.join(cwd, 'skills');
     if (!skillName) {
         console.log('\n  Available skills:\n');
@@ -41,13 +43,13 @@ export async function installCommand(skillName) {
             const installed = fs.existsSync(path.join(skillsDir, name));
             console.log(`  ${installed ? '[installed]' : '          '} ${name} — ${info.description}`);
         }
-        console.log('\n  Usage: expxagents install <skill-name>\n');
+        console.log(`\n  Usage: ${cmd} install <skill-name>\n`);
         return;
     }
     const skill = SKILL_CATALOG[skillName];
     if (!skill) {
         console.error(`  Skill "${skillName}" not found in catalog.`);
-        console.log('  Run `expxagents install` to see available skills.');
+        console.log(`  Run \`${cmd} install\` to see available skills.`);
         process.exit(1);
     }
     const skillDir = path.join(skillsDir, skillName);

package/dist/cli/src/commands/list.js

@@ -3,6 +3,7 @@ import path from 'path';
 import yaml from 'js-yaml';
 import { loadSkills } from '../../../core/skills-loader.js';
 import { readState } from '../../../core/state-manager.js';
+import { getCommandPrefix } from '../utils/command-prefix.js';
 function walkSquads(squadsDir) {
     if (!fs.existsSync(squadsDir))
         return [];
@@ -70,6 +71,7 @@ function capitalize(s) {
 }
 export async function listCommand() {
     const cwd = process.cwd();
+    const cmd = getCommandPrefix();
     const squadsDir = path.join(cwd, 'squads');
     const skillsDir = path.join(cwd, 'skills');
     console.log('Squads:');
@@ -77,7 +79,7 @@ export async function listCommand() {
     if (fs.existsSync(squadsDir)) {
         const allSquads = walkSquads(squadsDir);
         if (allSquads.length === 0) {
-            console.log('  No squads found. Run `expxagents create` to create one.\n');
+            console.log(`  No squads found. Run \`${cmd} create\` to create one.\n`);
         }
         else {
             const hierarchical = allSquads
@@ -113,14 +115,14 @@ export async function listCommand() {
         }
     }
     else {
-        console.log('  No squads directory. Run `expxagents init` first.\n');
+        console.log(`  No squads directory. Run \`${cmd} init\` first.\n`);
     }
     // List skills (unchanged)
     console.log('Skills:');
     console.log('-------');
     const skills = loadSkills(skillsDir);
     if (skills.length === 0) {
-        console.log('  No skills installed. Run `expxagents install <skill>` to add one.');
+        console.log(`  No skills installed. Run \`${cmd} install <skill>\` to add one.`);
     }
     else {
         for (const skill of skills) {

package/dist/cli/src/commands/mcp.js

@@ -7,6 +7,7 @@ import { detectMcp, detectExtension, resolvePlatformBinary } from '../mcp/detect
 import { writeMcpConfig, removeMcpConfig } from '../mcp/setup.js';
 import { getConfiguredMcpIds } from '../mcp/validate.js';
 import { getAssetsDir } from '../utils/config.js';
+import { getCommandPrefix } from '../utils/command-prefix.js';
 function getMcpsDir() {
     const local = path.resolve('mcps');
     if (fs.existsSync(local))
@@ -54,7 +55,7 @@ export function mcpCommand() {
             }
             console.log('');
         }
-        console.log('Run: expxagents mcp setup <id> to configure\n');
+        console.log(`Run: ${getCommandPrefix()} mcp setup <id> to configure\n`);
     });
     mcp
         .command('setup <ids...>')

package/dist/cli/src/commands/onboarding.js

@@ -1,6 +1,7 @@
 import fs from 'fs';
 import path from 'path';
 import readline from 'readline';
+import { getCommandPrefix } from '../utils/command-prefix.js';
 function ask(rl, question) {
     return new Promise(resolve => rl.question(question, resolve));
 }
@@ -8,8 +9,9 @@ export async function onboardingCommand() {
     const cwd = process.cwd();
     const companyPath = path.join(cwd, '_expxagents', '_memory', 'company.md');
     const prefsPath = path.join(cwd, '_expxagents', '_memory', 'preferences.md');
+    const cmd = getCommandPrefix();
     if (!fs.existsSync(path.dirname(companyPath))) {
-        console.error('Project not initialized. Run `expxagents init` first.');
+        console.error(`Project not initialized. Run \`${cmd} init\` first.`);
         process.exit(1);
     }
     const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
@@ -31,7 +33,7 @@ export async function onboardingCommand() {
         const companyContent = `# Company Profile\n\n## Company\n- **Name:** ${companyName}\n- **Website:** ${companyUrl}\n- **Sector:** ${sector}\n- **Description:** ${description}\n\n## Target Audience\n- **Primary:** ${audience}\n\n## Tone of Voice\n- **Style:** ${toneStyle}\n`;
         fs.writeFileSync(companyPath, companyContent, 'utf-8');
         console.log('\n  Profile saved! You can edit it anytime at _expxagents/_memory/company.md');
-        console.log('  Run `expxagents create` to design your first squad.\n');
+        console.log(`  Run \`${cmd} create\` to design your first squad.\n`);
     }
     finally {
         rl.close();

package/dist/cli/src/commands/outdated.d.ts

@@ -0,0 +1,14 @@
+import { Command } from 'commander';
+import { RegistryClient } from '@expxagents/registry-client';
+export interface InstalledSquad {
+    fullName: string;
+    currentVersion: string;
+}
+export declare function scanInstalledSquads(squadsDir: string): InstalledSquad[];
+export interface OutdatedResult {
+    fullName: string;
+    current: string;
+    latest: string;
+}
+export declare function checkOutdated(client: RegistryClient, squads: InstalledSquad[]): Promise<OutdatedResult[]>;
+export declare const outdatedCommand: Command;

package/dist/cli/src/commands/outdated.js

@@ -0,0 +1,88 @@
+import { Command } from 'commander';
+import { resolve, join } from 'node:path';
+import { readdirSync, readFileSync, existsSync } from 'node:fs';
+import { RegistryClient, readCredentials } from '@expxagents/registry-client';
+import { load as loadYaml } from 'js-yaml';
+import { getCommandPrefix } from '../utils/command-prefix.js';
+export function scanInstalledSquads(squadsDir) {
+    const installed = [];
+    if (!existsSync(squadsDir))
+        return installed;
+    for (const entry of readdirSync(squadsDir, { withFileTypes: true })) {
+        if (!entry.isDirectory() || !entry.name.startsWith('@'))
+            continue;
+        const scope = entry.name.slice(1); // remove @
+        const scopeDir = join(squadsDir, entry.name);
+        for (const squadEntry of readdirSync(scopeDir, { withFileTypes: true })) {
+            if (!squadEntry.isDirectory())
+                continue;
+            // Tarball may extract as @scope/name/squad.yaml or @scope/name/name/squad.yaml
+            const directPath = join(scopeDir, squadEntry.name, 'squad.yaml');
+            const nestedPath = join(scopeDir, squadEntry.name, squadEntry.name, 'squad.yaml');
+            const yamlPath = existsSync(directPath) ? directPath : existsSync(nestedPath) ? nestedPath : null;
+            if (!yamlPath)
+                continue;
+            try {
+                const raw = readFileSync(yamlPath, 'utf-8');
+                const parsed = loadYaml(raw);
+                const version = parsed?.squad?.version ?? parsed?.version;
+                if (version) {
+                    installed.push({
+                        fullName: `@${scope}/${squadEntry.name}`,
+                        currentVersion: String(version),
+                    });
+                }
+            }
+            catch {
+                // Skip squads with invalid yaml
+            }
+        }
+    }
+    return installed;
+}
+export async function checkOutdated(client, squads) {
+    const outdated = [];
+    for (const squad of squads) {
+        try {
+            const meta = await client.getSquad(squad.fullName);
+            if (meta.latestVersion && meta.latestVersion !== squad.currentVersion) {
+                outdated.push({
+                    fullName: squad.fullName,
+                    current: squad.currentVersion,
+                    latest: meta.latestVersion,
+                });
+            }
+        }
+        catch {
+            // Squad not found on registry — skip (local-only squad)
+        }
+    }
+    return outdated;
+}
+export const outdatedCommand = new Command('outdated')
+    .description('Check installed squads for available updates')
+    .option('--dir <dir>', 'Squads directory', './squads')
+    .action(async (options) => {
+    const squadsDir = resolve(options.dir);
+    const installed = scanInstalledSquads(squadsDir);
+    if (installed.length === 0) {
+        console.log('No registry squads installed.');
+        return;
+    }
+    const creds = readCredentials();
+    const client = new RegistryClient({
+        registryUrl: creds?.registryUrl || 'https://expxagents-marketplace-production.up.railway.app',
+        apiKey: creds?.apiKey,
+    });
+    console.log(`Checking ${installed.length} squad(s)...\n`);
+    const outdated = await checkOutdated(client, installed);
+    if (outdated.length === 0) {
+        console.log('All squads are up to date.');
+        return;
+    }
+    console.log('Updates available:\n');
+    for (const o of outdated) {
+        console.log(`  ${o.fullName}  ${o.current} \u2192 ${o.latest}`);
+    }
+    console.log(`\nRun \`${getCommandPrefix()} update\` to update all.`);
+});

package/dist/cli/src/commands/publish.js

@@ -1,6 +1,7 @@
 import { Command } from 'commander';
 import { resolve } from 'node:path';
 import { RegistryClient, readCredentials } from '@expxagents/registry-client';
+import { getCommandPrefix } from '../utils/command-prefix.js';
 export const publishCommand = new Command('publish')
     .description('Publish a squad to the registry')
     .argument('[dir]', 'Squad directory', '.')
@@ -8,7 +9,7 @@ export const publishCommand = new Command('publish')
     .action(async (dir, options) => {
     const creds = readCredentials();
     if (!creds) {
-        console.error('Not logged in. Run: expxagents login');
+        console.error(`Not logged in. Run: ${getCommandPrefix()} login`);
         process.exit(1);
     }
     const squadDir = resolve(dir);

package/dist/cli/src/commands/reorganize.js

@@ -2,6 +2,7 @@ import fs from 'fs';
 import path from 'path';
 import * as readline from 'readline';
 import yaml from 'js-yaml';
+import { getCommandPrefix } from '../utils/command-prefix.js';
 // Walk squadsDir recursively, return all squad summaries
 function discoverAllSquads(squadsDir) {
     const result = [];
@@ -214,7 +215,7 @@ export async function reorganizeCommand() {
     const cwd = process.cwd();
     const squadsDir = path.join(cwd, 'squads');
     if (!fs.existsSync(squadsDir)) {
-        console.error('No squads directory found. Run `expxagents init` first.');
+        console.error(`No squads directory found. Run \`${getCommandPrefix()} init\` first.`);
         process.exit(1);
     }
     console.log('Escaneando squads...\n');

package/dist/cli/src/commands/run.js

@@ -5,6 +5,7 @@ import { loadSquad, findSquadDir } from '../../../core/squad-loader.js';
 import { createInitialState, readState, writeState, updateAgentStatus, updateStep, setHandoff, setSquadStatus, HANDOFF_DELAY_MS, } from '../../../core/state-manager.js';
 import { loadSkills } from '../../../core/skills-loader.js';
 import { getCoreAsset } from '../utils/config.js';
+import { getCommandPrefix } from '../utils/command-prefix.js';
 import { runWithProvider } from '../runners/provider-runner.js';
 import { estimateCost, formatCost } from '../runners/cost-tracker.js';
 function delay(ms) {
@@ -135,8 +136,9 @@ export async function runCommand(name) {
     const squadsDir = path.join(cwd, 'squads');
     const squadDir = findSquadDir(squadsDir, name);
     const skillsDir = path.join(cwd, 'skills');
+    const cmd = getCommandPrefix();
     if (!squadDir) {
-        console.error(`Squad "${name}" not found. Run \`expxagents list\` to see available squads.`);
+        console.error(`Squad "${name}" not found. Run \`${cmd} list\` to see available squads.`);
         process.exit(1);
     }
     let config;
@@ -155,7 +157,7 @@ export async function runCommand(name) {
     }
     const existingState = readState(squadDir);
     if (existingState && existingState.status === 'running') {
-        console.error(`Squad "${name}" is already running. Use \`expxagents stop ${name}\` first.`);
+        console.error(`Squad "${name}" is already running. Use \`${cmd} stop ${name}\` first.`);
         process.exit(1);
     }
     const outputDir = getNextVersionDir(squadDir);

package/dist/cli/src/commands/sync-templates.js

@@ -1,6 +1,7 @@
 import fs from 'fs';
 import path from 'path';
 import { findSquadDir, loadSquad } from '../../../core/squad-loader.js';
+import { getCommandPrefix } from '../utils/command-prefix.js';
 /**
  * Find all .pen files in a squad's templates/ directory.
  */
@@ -65,7 +66,7 @@ export async function syncTemplatesCommand(squadFilter) {
     const cwd = process.cwd();
     const squadsDir = path.join(cwd, 'squads');
     if (!fs.existsSync(squadsDir)) {
-        console.error('No squads/ directory found. Run `expxagents init` first.');
+        console.error(`No squads/ directory found. Run \`${getCommandPrefix()} init\` first.`);
         process.exit(1);
     }
     let squadDirs;

package/dist/cli/src/commands/update.d.ts

@@ -0,0 +1,2 @@
+import { Command } from 'commander';
+export declare const updateCommand: Command;

package/dist/cli/src/commands/update.js

@@ -0,0 +1,81 @@
+import { Command } from 'commander';
+import { resolve } from 'node:path';
+import { createInterface } from 'node:readline';
+import { RegistryClient, readCredentials } from '@expxagents/registry-client';
+import { scanInstalledSquads, checkOutdated } from './outdated.js';
+function confirm(question) {
+    const rl = createInterface({ input: process.stdin, output: process.stdout });
+    return new Promise((res) => {
+        rl.question(question, (answer) => {
+            rl.close();
+            res(answer.toLowerCase() === 'y' || answer.toLowerCase() === 'yes');
+        });
+    });
+}
+async function updateSquads(client, squads, targetDir) {
+    for (const squad of squads) {
+        try {
+            console.log(`  Updating ${squad.fullName} ${squad.current} \u2192 ${squad.latest}...`);
+            const result = await client.installWithDeps(squad.fullName, squad.latest, targetDir);
+            console.log(`  \u2713 ${result.root}`);
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            console.error(`  \u2717 ${squad.fullName}: ${message}`);
+        }
+    }
+}
+export const updateCommand = new Command('update')
+    .description('Update installed squads to their latest versions')
+    .argument('[squad]', 'Specific squad to update (@scope/name)')
+    .option('--dir <dir>', 'Squads directory', './squads')
+    .option('--yes', 'Skip confirmation prompt')
+    .action(async (squad, options) => {
+    const squadsDir = resolve(options.dir);
+    const creds = readCredentials();
+    const client = new RegistryClient({
+        registryUrl: creds?.registryUrl || 'https://expxagents-marketplace-production.up.railway.app',
+        apiKey: creds?.apiKey,
+    });
+    // If specific squad provided, update just that one
+    if (squad) {
+        try {
+            console.log(`Updating ${squad}...`);
+            const result = await client.installWithDeps(squad, 'latest', squadsDir);
+            console.log(`\u2713 Updated ${result.root}`);
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            console.error(`\u2717 Update failed: ${message}`);
+            process.exit(1);
+        }
+        return;
+    }
+    // Otherwise: scan all, check for updates, confirm, update
+    const installed = scanInstalledSquads(squadsDir);
+    if (installed.length === 0) {
+        console.log('No registry squads installed.');
+        return;
+    }
+    console.log(`Checking ${installed.length} squad(s)...\n`);
+    const outdated = await checkOutdated(client, installed);
+    if (outdated.length === 0) {
+        console.log('All squads are up to date.');
+        return;
+    }
+    console.log('Updates available:\n');
+    for (const o of outdated) {
+        console.log(`  ${o.fullName}  ${o.current} \u2192 ${o.latest}`);
+    }
+    console.log('');
+    if (!options.yes) {
+        const ok = await confirm(`Update ${outdated.length} squad(s)? (y/N) `);
+        if (!ok) {
+            console.log('Cancelled.');
+            return;
+        }
+    }
+    console.log('');
+    await updateSquads(client, outdated, squadsDir);
+    console.log('\nDone.');
+});

package/dist/cli/src/commands/whoami.js

@@ -1,11 +1,12 @@
 import { Command } from 'commander';
 import { RegistryClient, readCredentials } from '@expxagents/registry-client';
+import { getCommandPrefix } from '../utils/command-prefix.js';
 export const whoamiCommand = new Command('whoami')
     .description('Show current registry identity')
     .action(async () => {
     const creds = readCredentials();
     if (!creds) {
-        console.error('Not logged in. Run: expxagents login');
+        console.error(`Not logged in. Run: ${getCommandPrefix()} login`);
         process.exit(1);
     }
     const client = new RegistryClient({ registryUrl: creds.registryUrl, apiKey: creds.apiKey });
@@ -17,7 +18,7 @@ export const whoamiCommand = new Command('whoami')
         console.log(`  Registry: ${creds.registryUrl}`);
     }
     catch {
-        console.error('\u2717 Invalid credentials. Run: expxagents login');
+        console.error(`\u2717 Invalid credentials. Run: ${getCommandPrefix()} login`);
         process.exit(1);
     }
 });

package/dist/cli/src/index.js

@@ -1,4 +1,3 @@
-import fs from 'fs';
 import { Command } from 'commander';
 import { initCommand } from './commands/init.js';
 import { createCommand } from './commands/create.js';
@@ -25,17 +24,9 @@ import { publishCommand } from './commands/publish.js';
 import { registryInstallCommand } from './commands/registry-install.js';
 import { searchCommand } from './commands/search.js';
 import { infoCommand } from './commands/info.js';
-import { findPackageRoot } from './utils/config.js';
-function getVersion() {
-    try {
-        const pkgPath = `${findPackageRoot()}/package.json`;
-        const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf-8'));
-        return pkg.version ?? '0.0.0';
-    }
-    catch {
-        return '0.0.0';
-    }
-}
+import { outdatedCommand } from './commands/outdated.js';
+import { updateCommand } from './commands/update.js';
+import { getVersion } from './utils/version.js';
 const program = new Command();
 program
     .name('expxagents')
@@ -121,4 +112,6 @@ program.addCommand(publishCommand);
 program.addCommand(registryInstallCommand);
 program.addCommand(searchCommand);
 program.addCommand(infoCommand);
+program.addCommand(outdatedCommand);
+program.addCommand(updateCommand);
 program.parse();

package/dist/cli/src/mcp/validate.js

@@ -1,5 +1,6 @@
 import fs from 'fs';
 import path from 'path';
+import { getCommandPrefix } from '../utils/command-prefix.js';
 export function getConfiguredMcpIds(projectDir) {
     const mcpPath = path.join(projectDir, '.mcp.json');
     if (!fs.existsSync(mcpPath))
@@ -18,6 +19,6 @@ export function validateSquadMcps(squadMcps, configuredMcps) {
     const missing = squadMcps.filter(m => !configuredMcps.includes(m));
     if (missing.length > 0) {
         throw new Error(`Squad requires MCPs not configured: ${missing.join(', ')}.\n` +
-            `Run: expxagents mcp setup ${missing.join(' ')}`);
+            `Run: ${getCommandPrefix()} mcp setup ${missing.join(' ')}`);
     }
 }

package/dist/cli/src/utils/__tests__/command-prefix.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/cli/src/utils/__tests__/command-prefix.test.js

@@ -0,0 +1,35 @@
+import { describe, it, expect, afterEach } from 'vitest';
+import { getCommandPrefix } from '../command-prefix.js';
+describe('getCommandPrefix', () => {
+    const originalArgv = process.argv;
+    const originalEnv = { ...process.env };
+    afterEach(() => {
+        process.argv = originalArgv;
+        process.env = originalEnv;
+    });
+    it('returns "npx expxagents" when npm_execpath contains npx', () => {
+        process.env.npm_execpath = '/usr/local/lib/node_modules/npm/bin/npx-cli.js';
+        process.argv = [process.argv[0], '/usr/local/bin/expxagents'];
+        expect(getCommandPrefix()).toBe('npx expxagents');
+    });
+    it('returns "npx expxagents" when argv[1] contains _npx (fallback)', () => {
+        delete process.env.npm_execpath;
+        process.argv = [process.argv[0], '/home/user/.npm/_npx/abc123/bin/expxagents.js'];
+        expect(getCommandPrefix()).toBe('npx expxagents');
+    });
+    it('returns "expxagents" for global install on Unix', () => {
+        delete process.env.npm_execpath;
+        process.argv = [process.argv[0], '/usr/local/bin/expxagents'];
+        expect(getCommandPrefix()).toBe('expxagents');
+    });
+    it('returns "expxagents" for global install on Windows', () => {
+        delete process.env.npm_execpath;
+        process.argv = [process.argv[0], 'C:\\Users\\X\\AppData\\Roaming\\npm\\expxagents'];
+        expect(getCommandPrefix()).toBe('expxagents');
+    });
+    it('returns "expxagents" when both env and argv are empty', () => {
+        delete process.env.npm_execpath;
+        process.argv = [process.argv[0], ''];
+        expect(getCommandPrefix()).toBe('expxagents');
+    });
+});

package/dist/cli/src/utils/__tests__/global-install.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/cli/src/utils/__tests__/global-install.test.js

@@ -0,0 +1,25 @@
+import { describe, it, expect, vi, afterEach } from 'vitest';
+import { execSync } from 'child_process';
+import { tryGlobalInstall } from '../global-install.js';
+vi.mock('child_process', () => ({
+    execSync: vi.fn(),
+}));
+const mockExecSync = vi.mocked(execSync);
+afterEach(() => {
+    vi.restoreAllMocks();
+});
+describe('tryGlobalInstall', () => {
+    it('returns true when npm install -g succeeds', () => {
+        mockExecSync.mockReturnValue(Buffer.from(''));
+        expect(tryGlobalInstall('0.20.1')).toBe(true);
+        expect(mockExecSync).toHaveBeenCalledWith('npm install -g expxagents@0.20.1', { stdio: 'pipe', timeout: 60000 });
+    });
+    it('returns false when npm install -g fails', () => {
+        mockExecSync.mockImplementation(() => { throw new Error('EACCES'); });
+        expect(tryGlobalInstall('0.20.1')).toBe(false);
+    });
+    it('never throws', () => {
+        mockExecSync.mockImplementation(() => { throw new Error('network error'); });
+        expect(() => tryGlobalInstall('1.0.0')).not.toThrow();
+    });
+});

package/dist/cli/src/utils/command-prefix.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Detects whether the CLI is running globally or via npx.
+ * Returns 'expxagents' for global, 'npx expxagents' for npx.
+ */
+export declare function getCommandPrefix(): string;

package/dist/cli/src/utils/command-prefix.js

@@ -0,0 +1,15 @@
+/**
+ * Detects whether the CLI is running globally or via npx.
+ * Returns 'expxagents' for global, 'npx expxagents' for npx.
+ */
+export function getCommandPrefix() {
+    const npmExecPath = process.env.npm_execpath ?? '';
+    if (npmExecPath.includes('npx')) {
+        return 'npx expxagents';
+    }
+    const execPath = process.argv[1] ?? '';
+    if (execPath.includes('_npx')) {
+        return 'npx expxagents';
+    }
+    return 'expxagents';
+}

package/dist/cli/src/utils/ensure-server.js

@@ -1,7 +1,53 @@
-import { spawn } from 'child_process';
+import { execSync, spawn } from 'child_process';
 import fs from 'fs';
 import path from 'path';
 import { resolveServerPaths } from './server-paths.js';
+const MAX_HEALTH_CHECK_ATTEMPTS = 30;
+const HEALTH_CHECK_INTERVAL_MS = 500;
+/**
+ * Kill the process listening on the given port (cross-platform).
+ */
+function killProcessOnPort(port) {
+    if (process.platform === 'win32') {
+        // Find PID using netstat, then kill it
+        try {
+            const output = execSync(`netstat -ano | findstr :${port} | findstr LISTENING`, {
+                encoding: 'utf-8',
+                stdio: ['pipe', 'pipe', 'ignore'],
+            });
+            const pids = new Set(output
+                .split('\n')
+                .map((line) => line.trim().split(/\s+/).pop())
+                .filter((pid) => !!pid && pid !== '0'));
+            for (const pid of pids) {
+                execSync(`taskkill /PID ${pid} /F`, { stdio: 'ignore' });
+            }
+        }
+        catch {
+            throw new Error(`Could not stop existing server on port ${port}`);
+        }
+    }
+    else {
+        execSync(`lsof -ti:${port} | xargs kill -9`, { stdio: 'ignore' });
+    }
+}
+/**
+ * Poll the health endpoint until the server responds OK or max attempts reached.
+ */
+async function waitForHealthy(port) {
+    for (let i = 0; i < MAX_HEALTH_CHECK_ATTEMPTS; i++) {
+        try {
+            const res = await fetch(`http://localhost:${port}/api/health`);
+            if (res.ok)
+                return true;
+        }
+        catch {
+            // Server not ready yet
+        }
+        await new Promise((resolve) => setTimeout(resolve, HEALTH_CHECK_INTERVAL_MS));
+    }
+    return false;
+}
 /**
  * Ensure the production server is running on the given port.
  * If a dev server is detected (health OK but no dashboard), it is killed and replaced.
@@ -32,8 +78,7 @@ export async function ensureProductionServer(port) {
         // Server is running but not serving dashboard (dev mode) — kill it
         console.log('Detected dev server on port ' + port + ', restarting in production mode...');
         try {
-            const { execSync } = await import('child_process');
-            execSync(`lsof -ti:${port} | xargs kill -9`, { stdio: 'ignore' });
+            killProcessOnPort(port);
             // Wait for port to free up
             await new Promise((resolve) => setTimeout(resolve, 1000));
         }
@@ -71,6 +116,11 @@ export async function ensureProductionServer(port) {
         console.error(`Failed to start server: ${err.message}`);
         process.exit(1);
     });
-    // Wait for server to start
-    await new Promise((resolve) => setTimeout(resolve, 2000));
+    // Poll health endpoint until server is ready (up to 15 seconds)
+    const healthy = await waitForHealthy(port);
+    if (!healthy) {
+        console.error(`Server failed to start on port ${port} within ${(MAX_HEALTH_CHECK_ATTEMPTS * HEALTH_CHECK_INTERVAL_MS) / 1000} seconds.`);
+        console.error('Check the server logs above for errors.');
+        process.exit(1);
+    }
 }

package/dist/cli/src/utils/global-install.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Attempts to install expxagents globally via npm.
+ * Returns true if successful, false otherwise.
+ * Never throws — failures are silent.
+ */
+export declare function tryGlobalInstall(version: string): boolean;

package/dist/cli/src/utils/global-install.js

@@ -0,0 +1,15 @@
+import { execSync } from 'child_process';
+/**
+ * Attempts to install expxagents globally via npm.
+ * Returns true if successful, false otherwise.
+ * Never throws — failures are silent.
+ */
+export function tryGlobalInstall(version) {
+    try {
+        execSync(`npm install -g expxagents@${version}`, { stdio: 'pipe', timeout: 60000 });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}

package/dist/cli/src/utils/version.d.ts

@@ -0,0 +1 @@
+export declare function getVersion(): string;

package/dist/cli/src/utils/version.js

@@ -0,0 +1,12 @@
+import fs from 'fs';
+import { findPackageRoot } from './config.js';
+export function getVersion() {
+    try {
+        const pkgPath = `${findPackageRoot()}/package.json`;
+        const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf-8'));
+        return pkg.version ?? '0.0.0';
+    }
+    catch {
+        return '0.0.0';
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "expxagents",
-  "version": "0.20.1",
+  "version": "0.21.1",
   "description": "Multi-agent orchestration platform for AI squads",
   "author": "ExpxAgents",
   "license": "MIT",