@bradygaster/squad-cli 0.8.5 → 0.8.17-preview

package/dist/cli-entry.js

@@ -1,4 +1,14 @@
 #!/usr/bin/env node
+process.env.NODE_NO_WARNINGS = '1';
+// Suppress Node.js experimental feature warnings (e.g., SQLite) from end users
+const originalEmitWarning = process.emitWarning;
+process.emitWarning = (warning, ...args) => {
+    if (typeof warning === 'string' && warning.includes('ExperimentalWarning'))
+        return;
+    if (warning?.name === 'ExperimentalWarning')
+        return;
+    return originalEmitWarning.call(process, warning, ...args);
+};
 /**
  * Squad CLI — entry point for command-line invocation.
  * Separated from src/index.ts so library consumers can import
@@ -6,6 +16,25 @@
  *
  * SDK library exports live in src/index.ts (dist/index.js).
  */
+// Load .env file if present (dev mode)
+import { existsSync, readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+const envPath = resolve(process.cwd(), '.env');
+if (existsSync(envPath)) {
+    for (const line of readFileSync(envPath, 'utf8').split('\n')) {
+        const trimmed = line.trim();
+        if (!trimmed || trimmed.startsWith('#'))
+            continue;
+        const eq = trimmed.indexOf('=');
+        if (eq > 0) {
+            const key = trimmed.slice(0, eq).trim();
+            const val = trimmed.slice(eq + 1).trim();
+            if (!process.env[key])
+                process.env[key] = val;
+        }
+    }
+}
 import fs from 'node:fs';
 import path from 'node:path';
 import { fatal, SquadError } from './cli/core/errors.js';
@@ -13,73 +42,631 @@ import { BOLD, RESET, DIM, RED } from './cli/core/output.js';
 import { runInit } from './cli/core/init.js';
 import { resolveSquad, resolveGlobalSquadPath } from '@bradygaster/squad-sdk';
 import { runShell } from './cli/shell/index.js';
+import { loadWelcomeData } from './cli/shell/lifecycle.js';
 // Keep VERSION in index.ts (public API); import it here via re-export
 import { VERSION } from '@bradygaster/squad-sdk';
+/** Debug logger — writes to stderr only when SQUAD_DEBUG=1. */
+function debugLog(...args) {
+    if (process.env['SQUAD_DEBUG'] === '1') {
+        console.error('[SQUAD_DEBUG]', ...args);
+    }
+}
+/** Check if --help or -h appears in args after the subcommand. */
+function hasHelpFlag(args) {
+    return args.slice(1).includes('--help') || args.slice(1).includes('-h');
+}
+/** Commands that skip the auto-link check (non-interactive or utility). */
+const SKIP_AUTO_LINK_CMDS = new Set([
+    '--version', '-v', 'version',
+    '--help', '-h', 'help',
+    'export', 'import', 'doctor', 'heartbeat',
+    'scrub-emails', '--preview', '--dry-run',
+]);
+/**
+ * Dev convenience: when running from source (-preview), check if the CLI
+ * is globally linked and offer to link it if not.
+ */
+async function checkAutoLink(cmd, args) {
+    try {
+        if (!VERSION.includes('-preview'))
+            return;
+        if (cmd && SKIP_AUTO_LINK_CMDS.has(cmd))
+            return;
+        if (args.includes('--preview') || args.includes('--dry-run'))
+            return;
+        if (args.includes('--help') || args.includes('-h'))
+            return;
+        if (!process.stdin.isTTY)
+            return;
+        const { homedir } = await import('node:os');
+        const home = homedir();
+        const squadDir = path.join(home, '.squad');
+        const markerPath = path.join(squadDir, '.no-auto-link');
+        if (fs.existsSync(markerPath))
+            return;
+        // Locate this package and the monorepo root
+        const thisFile = fileURLToPath(import.meta.url);
+        const packageDir = path.resolve(path.dirname(thisFile), '..');
+        const repoRoot = path.resolve(packageDir, '..', '..');
+        // Check if already globally linked
+        const { execSync } = await import('node:child_process');
+        let alreadyLinked = false;
+        let output = '';
+        try {
+            output = execSync('npm ls -g @bradygaster/squad-cli --json', {
+                encoding: 'utf8',
+                stdio: ['pipe', 'pipe', 'pipe'],
+            });
+        }
+        catch (e) {
+            const err = e;
+            output = err.stdout ?? '';
+        }
+        if (output) {
+            try {
+                const parsed = JSON.parse(output);
+                const dep = parsed?.dependencies?.['@bradygaster/squad-cli'];
+                if (dep?.link === true) {
+                    alreadyLinked = true;
+                }
+                else if (typeof dep?.resolved === 'string' && dep.resolved.startsWith('file:')) {
+                    try {
+                        const resolvedPath = fileURLToPath(new URL(dep.resolved));
+                        alreadyLinked = path.resolve(resolvedPath) === path.resolve(packageDir);
+                    }
+                    catch {
+                        // URL parsing failed — skip
+                    }
+                }
+            }
+            catch {
+                // JSON parse failed
+            }
+        }
+        if (alreadyLinked)
+            return;
+        // Prompt the user
+        console.log(`\n📦 You're running Squad from source (${VERSION}).`);
+        console.log(`   Run 'npm link -w packages/squad-cli' to make 'squad' use your local build?`);
+        const { createInterface } = await import('node:readline');
+        const rl = createInterface({ input: process.stdin, output: process.stdout });
+        const answer = await new Promise((resolve) => {
+            rl.question('\n[Y/n] ', (ans) => {
+                rl.close();
+                resolve(ans.trim().toLowerCase());
+            });
+        });
+        if (answer === '' || answer === 'y' || answer === 'yes') {
+            console.log('Linking...');
+            try {
+                execSync('npm link -w packages/squad-cli', {
+                    cwd: repoRoot,
+                    encoding: 'utf8',
+                    stdio: ['pipe', 'pipe', 'pipe'],
+                });
+                console.log('✓ Linked successfully. The "squad" command now uses your local build.\n');
+            }
+            catch (linkErr) {
+                debugLog('npm link failed:', linkErr);
+                console.log('Link failed — you can run it manually: npm link -w packages/squad-cli\n');
+            }
+        }
+        else {
+            if (!fs.existsSync(squadDir)) {
+                fs.mkdirSync(squadDir, { recursive: true });
+            }
+            fs.writeFileSync(markerPath, '# Created by squad CLI. Delete this file to be prompted again.\n');
+            console.log("Got it — won't ask again. Run 'npm link -w packages/squad-cli' manually anytime.\n");
+        }
+    }
+    catch (err) {
+        debugLog('Auto-link check failed, skipping:', err);
+    }
+}
+/** Per-command help text. Returns undefined for unknown commands. */
+function getCommandHelp(cmd) {
+    const help = {
+        init: `
+${BOLD}squad init${RESET} — Initialize Squad
+
+${BOLD}USAGE${RESET}
+  squad init [prompt] [--file <path>] [--global] [--mode remote <path>]
+
+${BOLD}DESCRIPTION${RESET}
+  Creates the .squad/ directory structure in your project or personal directory.
+  Detects your project type and scaffolds appropriate workflows and templates.
+  If a prompt is provided, stores it so the REPL can auto-cast your team.
+
+${BOLD}OPTIONS${RESET}
+  prompt                A project description (quoted string) for team casting
+  --file <path>         Read the project description from a file
+  --global              Create personal squad at ~/.squad/
+  --mode remote <path>  Link to a remote team root (dual-root mode)
+
+${BOLD}EXAMPLES${RESET}
+  ${DIM}# Initialize and describe your project for auto-casting${RESET}
+  squad init "Build a snake game in HTML and JavaScript"
+
+  ${DIM}# Initialize with a spec file${RESET}
+  squad init --file ./PROJECT.md
+
+  ${DIM}# Initialize without a prompt (cast later interactively)${RESET}
+  squad init
+
+  ${DIM}# Create personal squad${RESET}
+  squad init --global
+
+  ${DIM}# Link to shared team in parent directory${RESET}
+  squad init --mode remote ../team-repo
+`,
+        upgrade: `
+${BOLD}squad upgrade${RESET} — Update Squad Files
+
+${BOLD}USAGE${RESET}
+  squad upgrade [--global] [--migrate-directory]
+
+${BOLD}DESCRIPTION${RESET}
+  Updates Squad-owned files to the latest version. Your team state
+  (team.md, decisions.md, agent history) is never modified.
+
+${BOLD}OPTIONS${RESET}
+  --global              Upgrade personal squad at ~/.squad/
+  --migrate-directory   Rename .ai-team/ to .squad/ (legacy migration)
+
+${BOLD}EXAMPLES${RESET}
+  ${DIM}# Upgrade current repo's Squad files${RESET}
+  squad upgrade
+
+  ${DIM}# Upgrade personal squad${RESET}
+  squad upgrade --global
+
+  ${DIM}# Migrate from legacy .ai-team/ directory${RESET}
+  squad upgrade --migrate-directory
+`,
+        status: `
+${BOLD}squad status${RESET} — Show Active Squad
+
+${BOLD}USAGE${RESET}
+  squad status
+
+${BOLD}DESCRIPTION${RESET}
+  Displays which squad is currently active and where it's located.
+  Shows repo squad, personal squad path, and resolution order.
+
+${BOLD}EXAMPLES${RESET}
+  ${DIM}# Check active squad${RESET}
+  squad status
+`,
+        triage: `
+${BOLD}squad triage${RESET} — Auto-Triage Issues
+
+${BOLD}USAGE${RESET}
+  squad triage [--interval <minutes>]
+  squad watch [--interval <minutes>]    ${DIM}(alias)${RESET}
+
+${BOLD}DESCRIPTION${RESET}
+  Ralph's work monitor. Continuously polls GitHub issues and automatically
+  assigns them to the right team member based on content and expertise.
+
+${BOLD}OPTIONS${RESET}
+  --interval <minutes>    Polling frequency (default: 10)
+
+${BOLD}EXAMPLES${RESET}
+  ${DIM}# Start triage with default 10-minute interval${RESET}
+  squad triage
+
+  ${DIM}# Poll every 5 minutes${RESET}
+  squad triage --interval 5
+`,
+        copilot: `
+${BOLD}squad copilot${RESET} — Manage Copilot Coding Agent
+
+${BOLD}USAGE${RESET}
+  squad copilot [--off] [--auto-assign]
+
+${BOLD}DESCRIPTION${RESET}
+  Add or remove the GitHub Copilot coding agent (@copilot) from your team.
+  When enabled, @copilot can pick up issues labeled 'squad:copilot'.
+
+${BOLD}OPTIONS${RESET}
+  --off            Remove @copilot from the team
+  --auto-assign    Enable automatic issue assignment for @copilot
+
+${BOLD}EXAMPLES${RESET}
+  ${DIM}# Add @copilot to the team${RESET}
+  squad copilot
+
+  ${DIM}# Add @copilot with auto-assignment enabled${RESET}
+  squad copilot --auto-assign
+
+  ${DIM}# Remove @copilot from the team${RESET}
+  squad copilot --off
+`,
+        plugin: `
+${BOLD}squad plugin${RESET} — Manage Plugin Marketplaces
+
+${BOLD}USAGE${RESET}
+  squad plugin marketplace add <owner/repo>
+  squad plugin marketplace remove <name>
+  squad plugin marketplace list
+  squad plugin marketplace browse <name>
+
+${BOLD}DESCRIPTION${RESET}
+  Manage plugin marketplaces — registries of Squad extensions, skills,
+  and agent templates.
+
+${BOLD}EXAMPLES${RESET}
+  ${DIM}# Add official Squad plugins marketplace${RESET}
+  squad plugin marketplace add bradygaster/squad-plugins
+
+  ${DIM}# List all registered marketplaces${RESET}
+  squad plugin marketplace list
+`,
+        export: `
+${BOLD}squad export${RESET} — Export Squad to JSON
+
+${BOLD}USAGE${RESET}
+  squad export [--out <path>]
+
+${BOLD}DESCRIPTION${RESET}
+  Creates a portable JSON snapshot of your entire squad — casting state,
+  agent charters, accumulated history, and skills.
+
+${BOLD}OPTIONS${RESET}
+  --out <path>    Custom output path (default: squad-export.json)
+
+${BOLD}EXAMPLES${RESET}
+  ${DIM}# Export to default file${RESET}
+  squad export
+
+  ${DIM}# Export to custom location${RESET}
+  squad export --out ./backups/team-backup.json
+`,
+        import: `
+${BOLD}squad import${RESET} — Import Squad from JSON
+
+${BOLD}USAGE${RESET}
+  squad import <file> [--force]
+
+${BOLD}DESCRIPTION${RESET}
+  Restores a squad from a JSON export file. Creates .squad/ directory
+  and populates it with casting state, agents, skills, and history.
+
+${BOLD}OPTIONS${RESET}
+  --force    Overwrite existing squad (archives old .squad/ first)
+
+${BOLD}EXAMPLES${RESET}
+  ${DIM}# Import into current directory${RESET}
+  squad import squad-export.json
+
+  ${DIM}# Import and overwrite existing squad${RESET}
+  squad import squad-export.json --force
+`,
+        'scrub-emails': `
+${BOLD}squad scrub-emails${RESET} — Remove Email Addresses
+
+${BOLD}USAGE${RESET}
+  squad scrub-emails [directory]
+
+${BOLD}DESCRIPTION${RESET}
+  Removes email addresses (PII) from Squad state files. Useful before
+  committing to public repos or sharing exports.
+
+${BOLD}OPTIONS${RESET}
+  [directory]    Target directory (default: .squad)
+
+${BOLD}EXAMPLES${RESET}
+  ${DIM}# Scrub current squad${RESET}
+  squad scrub-emails .squad
+
+  ${DIM}# Scrub legacy .ai-team directory${RESET}
+  squad scrub-emails
+`,
+        doctor: `
+${BOLD}squad doctor${RESET} — Validate Squad Setup
+
+${BOLD}USAGE${RESET}
+  squad doctor
+
+${BOLD}DESCRIPTION${RESET}
+  Runs a 9-check diagnostic on your squad setup. Reports health of
+  expected files, conventions, and directory structure.
+
+${BOLD}EXAMPLES${RESET}
+  ${DIM}# Check current squad setup${RESET}
+  squad doctor
+`,
+        link: `
+${BOLD}squad link${RESET} — Link to Remote Team
+
+${BOLD}USAGE${RESET}
+  squad link <team-repo-path>
+
+${BOLD}DESCRIPTION${RESET}
+  Links the current project to a remote team root. Enables dual-root mode
+  where project-specific state lives in .squad/ and team identity lives
+  in a shared location.
+
+${BOLD}EXAMPLES${RESET}
+  ${DIM}# Link to parent directory's team${RESET}
+  squad link ../team-repo
+
+  ${DIM}# Link to absolute path${RESET}
+  squad link /Users/org/shared-squad
+`,
+        aspire: `
+${BOLD}squad aspire${RESET} — Launch Aspire Dashboard
+
+${BOLD}USAGE${RESET}
+  squad aspire [--docker] [--port <number>]
+
+${BOLD}DESCRIPTION${RESET}
+  Launches the .NET Aspire dashboard for observability. Squad exports
+  OpenTelemetry traces and metrics to the dashboard for real-time visibility.
+
+${BOLD}OPTIONS${RESET}
+  --docker         Force Docker mode
+  --port <number>  OTLP port (default: 4317)
+
+${BOLD}EXAMPLES${RESET}
+  ${DIM}# Launch Aspire dashboard (auto-detect runtime)${RESET}
+  squad aspire
+
+  ${DIM}# Force Docker mode${RESET}
+  squad aspire --docker
+`,
+        upstream: `
+${BOLD}squad upstream${RESET} — Manage Upstream Squad Sources
+
+${BOLD}USAGE${RESET}
+  squad upstream add <source> [--name <name>] [--ref <branch>]
+  squad upstream remove <name>
+  squad upstream list
+  squad upstream sync [name]
+
+${BOLD}DESCRIPTION${RESET}
+  Manage upstream Squad sources — external configurations from local
+  directories, git repositories, or export files that can be synced
+  into your squad.
+
+${BOLD}OPTIONS${RESET}
+  add <source>          Add an upstream (path, git URL, or .json export)
+    --name <name>       Custom name (auto-derived if omitted)
+    --ref <branch>      Git branch/tag (default: main)
+  remove <name>         Remove an upstream by name
+  list                  Show all configured upstreams
+  sync [name]           Sync all or a specific upstream
+
+${BOLD}EXAMPLES${RESET}
+  ${DIM}# Add a git upstream${RESET}
+  squad upstream add https://github.com/org/squad-config.git
+
+  ${DIM}# Add a local upstream with custom name${RESET}
+  squad upstream add ../shared-squad --name shared
+
+  ${DIM}# Sync all upstreams${RESET}
+  squad upstream sync
+`,
+        nap: `
+${BOLD}squad nap${RESET} — Context Hygiene
+
+${BOLD}USAGE${RESET}
+  squad nap [--deep] [--dry-run]
+
+${BOLD}DESCRIPTION${RESET}
+  Compresses agent histories, prunes old logs, archives stale decisions,
+  and cleans up orphaned inbox files. Shows before/after stats with
+  estimated token savings.
+
+${BOLD}OPTIONS${RESET}
+  --deep      Aggressive mode — tighter history compression
+  --dry-run   Show what would change without modifying files
+
+${BOLD}EXAMPLES${RESET}
+  ${DIM}# Run a standard nap${RESET}
+  squad nap
+
+  ${DIM}# Preview changes without modifying files${RESET}
+  squad nap --dry-run
+
+  ${DIM}# Deep clean for maximum compression${RESET}
+  squad nap --deep
+`,
+        shell: `
+${BOLD}squad shell${RESET} — Launch Interactive Shell
+
+${BOLD}USAGE${RESET}
+  squad shell [--preview] [--timeout <seconds>]
+
+${BOLD}DESCRIPTION${RESET}
+  Starts the interactive Squad REPL. Messages are routed to the
+  right agent automatically based on content and team expertise.
+
+${BOLD}OPTIONS${RESET}
+  --preview              Show team summary without launching shell
+  --timeout <seconds>    Set REPL inactivity timeout (default: 600)
+
+${BOLD}EXAMPLES${RESET}
+  ${DIM}# Start interactive shell${RESET}
+  squad shell
+
+  ${DIM}# Preview team before launching${RESET}
+  squad shell --preview
+`,
+    };
+    // Handle aliases
+    const aliases = {
+        watch: 'triage',
+        loop: 'triage',
+        hire: 'init',
+        heartbeat: 'doctor',
+    };
+    const key = aliases[cmd] ?? cmd;
+    return help[key];
+}
 async function main() {
     const args = process.argv.slice(2);
     const hasGlobal = args.includes('--global');
-    const cmd = args[0];
-    // --version / -v
-    if (cmd === '--version' || cmd === '-v') {
-        console.log(`squad ${VERSION}`);
+    const rawCmd = args[0];
+    const cmd = rawCmd?.trim() || undefined;
+    // --timeout <seconds> → set SQUAD_REPL_TIMEOUT env var for shell
+    const timeoutIdx = args.indexOf('--timeout');
+    if (timeoutIdx >= 0 && args[timeoutIdx + 1]) {
+        process.env['SQUAD_REPL_TIMEOUT'] = args[timeoutIdx + 1];
+    }
+    // Dev convenience: offer to npm-link when running from source
+    await checkAutoLink(cmd, args);
+    // Empty or whitespace-only args should show help, not launch shell
+    if (rawCmd !== undefined && !cmd) {
+        console.log(`\n${BOLD}squad${RESET} v${VERSION}`);
+        console.log(`Your AI agent team\n`);
+        console.log(`Usage: squad [command] [options]`);
+        console.log(`\nRun 'squad help' for full command list.\n`);
+        return;
+    }
+    // --version / -v / version — canonical format: bare semver
+    if (cmd === '--version' || cmd === '-v' || cmd === 'version') {
+        console.log(VERSION);
         return;
     }
     // --help / -h / help
     if (cmd === '--help' || cmd === '-h' || cmd === 'help') {
-        console.log(`\n${BOLD}squad${RESET} v${VERSION} — Add an AI agent team to any project\n`);
+        console.log(`\n${BOLD}squad${RESET} v${VERSION}`);
+        console.log(`Your AI agent team\n`);
+        console.log(`${BOLD}Just type — squad routes your message to the right agent automatically${RESET}`);
+        console.log(`  squad                  Start interactive shell`);
+        console.log(`  squad --global         Use your personal squad\n`);
         console.log(`Usage: squad [command] [options]\n`);
-        console.log(`Commands:`);
-        console.log(`  ${BOLD}(default)${RESET}  Launch interactive shell (no args)`);
-        console.log(`             Flags: --global (init in personal squad directory)`);
-        console.log(`  ${BOLD}init${RESET}       Initialize Squad (skip files that already exist)`);
-        console.log(`             Flags: --global (init in personal squad directory)`);
-        console.log(`             --mode remote <path> (init linked to a remote team root)`);
-        console.log(`  ${BOLD}upgrade${RESET}    Update Squad-owned files to latest version`);
-        console.log(`             Overwrites: squad.agent.md, templates dir (.squad-templates/ or .ai-team-templates/)`);
-        console.log(`             Never touches: .squad/ or .ai-team/ (your team state)`);
-        console.log(`             Flags: --global (upgrade personal squad), --migrate-directory (rename .ai-team/ → .squad/)`);
-        console.log(`  ${BOLD}status${RESET}     Show which squad is active and why`);
-        console.log(`  ${BOLD}triage${RESET}     Scan for work and categorize issues`);
-        console.log(`             Usage: triage [--interval <minutes>]`);
-        console.log(`             Default: checks every 10 minutes (Ctrl+C to stop)`);
-        console.log(`  ${BOLD}loop${RESET}       Continuous work loop (Ralph mode)`);
-        console.log(`             Usage: loop [--filter <label>] [--interval <minutes>]`);
-        console.log(`             Default: checks every 10 minutes (Ctrl+C to stop)`);
-        console.log(`  ${BOLD}hire${RESET}       Team creation wizard`);
-        console.log(`             Usage: hire [--name <name>] [--role <role>]`);
-        console.log(`  ${BOLD}copilot${RESET}    Add/remove the Copilot coding agent (@copilot)`);
-        console.log(`             Usage: copilot [--off] [--auto-assign]`);
-        console.log(`  ${BOLD}plugin${RESET}     Manage plugin marketplaces`);
-        console.log(`             Usage: plugin marketplace add|remove|list|browse`);
-        console.log(`  ${BOLD}export${RESET}     Export squad to a portable JSON snapshot`);
-        console.log(`             Default: squad-export.json (use --out <path> to override)`);
-        console.log(`  ${BOLD}import${RESET}     Import squad from an export file`);
-        console.log(`             Usage: import <file> [--force]`);
-        console.log(`  ${BOLD}scrub-emails${RESET}  Remove email addresses from Squad state files`);
-        console.log(`             Usage: scrub-emails [directory] (default: .ai-team/)`);
-        console.log(`  ${BOLD}doctor${RESET}     Validate squad setup integrity (diagnostic)`);
-        console.log(`  ${BOLD}link${RESET}       Link project to a remote team root`);
-        console.log(`             Usage: link <team-repo-path>`);
-        console.log(`  ${BOLD}aspire${RESET}     Launch Aspire dashboard for Squad observability`);
-        console.log(`             Flags: --docker (force Docker), --port <number> (OTLP port)`);
-        console.log(`  ${BOLD}help${RESET}       Show this help message`);
-        console.log(`\nFlags:`);
-        console.log(`  ${BOLD}--version, -v${RESET}  Print version`);
-        console.log(`  ${BOLD}--help, -h${RESET}     Show help`);
-        console.log(`  ${BOLD}--global${RESET}       Use personal (global) squad path (for init, upgrade)`);
+        console.log(`${BOLD}Getting Started${RESET}`);
+        console.log(`  ${BOLD}init${RESET}           Create .squad/ in this repo ${DIM}(alias: hire)${RESET}`);
+        console.log(`                 --global             Create personal squad directory`);
+        console.log(`                 --mode remote <path>  Link to a remote team root`);
+        console.log(`  ${BOLD}upgrade${RESET}        Update Squad files to latest`);
+        console.log(`                 --global             Upgrade personal squad`);
+        console.log(`                 --migrate-directory  Rename .ai-team/ → .squad/`);
+        console.log(`  ${BOLD}status${RESET}         Show which squad is active`);
+        console.log(`  ${BOLD}doctor${RESET}         Check your setup ${DIM}(alias: heartbeat)${RESET}`);
+        console.log(`\n${BOLD}Development${RESET}`);
+        console.log(`  ${BOLD}shell${RESET}          Launch interactive shell`);
+        console.log(`\n${BOLD}Team Management${RESET}`);
+        console.log(`  ${BOLD}triage${RESET}         Watch issues and auto-triage ${DIM}(alias: watch, loop)${RESET}`);
+        console.log(`                 --interval <minutes>  Polling frequency (default: 10)`);
+        console.log(`  ${BOLD}copilot${RESET}        Add/remove GitHub Copilot agent`);
+        console.log(`                 --off                Remove @copilot`);
+        console.log(`                 --auto-assign        Enable auto-assignment`);
+        console.log(`  ${BOLD}link${RESET}           Connect to a remote team`);
+        console.log(`                 <team-repo-path>`);
+        console.log(`  ${BOLD}upstream${RESET}       Manage upstream Squad sources`);
+        console.log(`                 add|remove|list|sync`);
+        console.log(`\n${BOLD}Utilities${RESET}`);
+        console.log(`  ${BOLD}nap${RESET}            Context hygiene — compress, prune, archive`);
+        console.log(`                 --deep               Aggressive compression`);
+        console.log(`                 --dry-run            Preview without changes`);
+        console.log(`  ${BOLD}export${RESET}         Save squad to JSON`);
+        console.log(`                 --out <path>         Output path (default: squad-export.json)`);
+        console.log(`  ${BOLD}import${RESET}         Load squad from JSON`);
+        console.log(`                 <file> [--force]`);
+        console.log(`  ${BOLD}plugin${RESET}         Manage plugins`);
+        console.log(`                 marketplace add|remove|list|browse`);
+        console.log(`  ${BOLD}aspire${RESET}         Open Aspire dashboard`);
+        console.log(`                 --docker             Force Docker mode`);
+        console.log(`                 --port <number>      OTLP port (default: 4317)`);
+        console.log(`  ${BOLD}scrub-emails${RESET}   Remove email addresses from squad state`);
+        console.log(`                 [directory]          Target directory (default: .squad/)`);
+        console.log(`\n${BOLD}Flags${RESET}`);
+        console.log(`  --version, -v            Print version`);
+        console.log(`  --help, -h               Show this help`);
+        console.log(`  --preview                Show team summary without launching shell`);
+        console.log(`  --global                 Use personal squad path`);
+        console.log(`  --timeout <seconds>      Set REPL inactivity timeout (default: 600)`);
+        console.log(`\n${BOLD}Examples${RESET}`);
+        console.log(`  ${DIM}$ squad init${RESET}                          Set up a squad in this repo`);
+        console.log(`  ${DIM}$ squad triage --interval 5${RESET}           Poll issues every 5 minutes`);
+        console.log(`  ${DIM}$ squad export --out ./backups/team.json${RESET}`);
+        console.log(`                                        Save squad snapshot`);
+        console.log(`  ${DIM}$ squad copilot --auto-assign${RESET}         Add @copilot with auto-assignment`);
+        console.log(`  ${DIM}$ squad doctor${RESET}                        Diagnose setup issues`);
         console.log(`\nInstallation:`);
-        console.log(`  npm install --save-dev @bradygaster/squad-cli`);
+        console.log(`  npm i --save-dev @bradygaster/squad-cli`);
         console.log(`\nInsider channel:`);
-        console.log(`  npm install --save-dev @bradygaster/squad-cli@insider\n`);
+        console.log(`  npm i --save-dev @bradygaster/squad-cli@insider`);
+        console.log(`\nRun 'squad <command> --help' for details.\n`);
         return;
     }
-    // No args → launch interactive shell
+    // --preview / --dry-run — show team summary without launching the interactive shell
+    if (cmd === '--preview' || cmd === '--dry-run' || (!cmd && args.includes('--preview')) || (cmd === 'shell' && args.includes('--preview'))) {
+        const squadDir = resolveSquad(process.cwd());
+        const globalPath = resolveGlobalSquadPath();
+        const globalSquadDir = path.join(globalPath, '.squad');
+        const teamRoot = squadDir ? path.dirname(squadDir) : fs.existsSync(globalSquadDir) ? globalPath : null;
+        if (!teamRoot) {
+            console.log(`${RED}✗${RESET} No squad found. Run 'squad init' first.`);
+            process.exit(1);
+        }
+        const data = loadWelcomeData(teamRoot);
+        if (!data) {
+            console.log(`${RED}✗${RESET} Could not read team configuration.`);
+            process.exit(1);
+        }
+        console.log(`\n${BOLD}Squad Preview${RESET}`);
+        console.log(`${'─'.repeat(40)}`);
+        console.log(`  Team:   ${data.projectName}`);
+        console.log(`  Agents: ${data.agents.length}`);
+        if (data.description)
+            console.log(`  About:  ${data.description}`);
+        if (data.focus)
+            console.log(`  Focus:  ${data.focus}`);
+        console.log(`\n${BOLD}Agents${RESET}`);
+        for (const a of data.agents) {
+            console.log(`  ${a.emoji} ${BOLD}${a.name}${RESET} — ${a.role}`);
+        }
+        console.log(`\n${BOLD}Shell Commands${RESET}`);
+        console.log(`  /status    — Check your team & what's happening`);
+        console.log(`  /history   — See recent messages`);
+        console.log(`  /agents    — List all team members`);
+        console.log(`  /sessions  — List saved sessions`);
+        console.log(`  /resume    — Restore a past session`);
+        console.log(`  /clear     — Clear the screen`);
+        console.log(`  /quit      — Exit`);
+        console.log(`\n${DIM}Run 'squad' to start the interactive shell.${RESET}\n`);
+        return;
+    }
+    // No args → check if .squad/ exists
     if (!cmd) {
-        await runShell();
+        const squadPath = resolveSquad(process.cwd());
+        const globalPath = resolveGlobalSquadPath();
+        const globalSquadDir = path.join(globalPath, '.squad');
+        const hasSquad = squadPath || fs.existsSync(globalSquadDir);
+        if (hasSquad) {
+            // Squad exists, launch shell
+            await runShell();
+        }
+        else {
+            // First run — no squad found. Welcome the user.
+            console.log(`\n${BOLD}Welcome to Squad${RESET} v${VERSION}`);
+            console.log(`Your AI agent team\n`);
+            console.log(`Squad adds a team of AI agents to your project. Each agent`);
+            console.log(`has a role — architect, tester, security reviewer — and they`);
+            console.log(`collaborate to help you build, review, and ship code.\n`);
+            console.log(`${BOLD}Get started:${RESET}`);
+            console.log(`  ${BOLD}squad init${RESET}             Set up a squad in this repo`);
+            console.log(`  ${BOLD}squad init --global${RESET}    Create a personal squad\n`);
+            console.log(`${DIM}After init, just run ${BOLD}squad${RESET}${DIM} to start talking to your team.${RESET}`);
+            console.log(`${DIM}Run ${BOLD}squad help${RESET}${DIM} for all commands.${RESET}\n`);
+        }
         return;
     }
+    // Per-command --help/-h: intercept before dispatching (fixes #511, #512)
+    if (hasHelpFlag(args)) {
+        const helpText = getCommandHelp(cmd);
+        if (helpText) {
+            console.log(helpText);
+            return;
+        }
+    }
     // Route subcommands
-    if (cmd === 'init') {
+    // hire → alias for init (#501)
+    if (cmd === 'init' || cmd === 'hire') {
         const modeIdx = args.indexOf('--mode');
         const mode = (modeIdx !== -1 && args[modeIdx + 1]) ? args[modeIdx + 1] : 'local';
         const dest = hasGlobal ? resolveGlobalSquadPath() : process.cwd();
@@ -88,18 +675,35 @@ async function main() {
             // teamRoot can be provided as the next positional arg after --mode remote
             const teamRootArg = args.find((a, i) => i > 0 && a !== '--mode' && a !== 'remote' && a !== '--global' && a !== 'init');
             if (!teamRootArg) {
-                fatal('--mode remote requires a team root path. Usage: squad init --mode remote <team-root-path>');
+                fatal('squad init --mode remote <team-root-path>');
             }
             writeRemoteConfig(dest, teamRootArg);
         }
-        await runInit(dest);
+        // Extract project prompt: squad init "Build a snake game" or squad init --file ./spec.txt
+        let initPrompt;
+        const fileIdx = args.indexOf('--file');
+        if (fileIdx !== -1 && args[fileIdx + 1]) {
+            const filePath = resolve(args[fileIdx + 1]);
+            if (!existsSync(filePath)) {
+                fatal(`Prompt file not found: ${filePath}`);
+            }
+            initPrompt = readFileSync(filePath, 'utf-8').trim();
+        }
+        else {
+            // Look for a positional string arg (not a flag, not 'init'/'hire')
+            const skipSet = new Set(['init', 'hire', '--global', '--mode', mode]);
+            const positional = args.find((a, i) => i > 0 && !a.startsWith('--') && !skipSet.has(a));
+            if (positional)
+                initPrompt = positional;
+        }
+        await runInit(dest, { prompt: initPrompt });
         return;
     }
     if (cmd === 'link') {
         const { runLink } = await import('./cli/commands/link.js');
         const linkTarget = args[1];
         if (!linkTarget) {
-            fatal('Usage: squad link <team-repo-path>');
+            fatal('Run: squad link <team-repo-path>');
         }
         runLink(process.cwd(), linkTarget);
         return;
@@ -108,7 +712,6 @@ async function main() {
         const { runUpgrade } = await import('./cli/core/upgrade.js');
         const { migrateDirectory } = await import('./cli/core/migrate-directory.js');
         const migrateDir = args.includes('--migrate-directory');
-        const selfUpgrade = args.includes('--self');
         const dest = hasGlobal ? resolveGlobalSquadPath() : process.cwd();
         // Handle --migrate-directory flag
         if (migrateDir) {
@@ -118,40 +721,26 @@ async function main() {
         // Run upgrade
         await runUpgrade(dest, {
             migrateDirectory: migrateDir,
-            self: selfUpgrade
         });
         return;
     }
-    if (cmd === 'triage' || cmd === 'watch') {
-        console.log('🕵️ Squad triage — scanning for work... (full implementation pending)');
+    if (cmd === 'nap') {
+        const { runNap, formatNapReport } = await import('./cli/core/nap.js');
+        const squadDir = path.join(hasGlobal ? resolveGlobalSquadPath() : process.cwd(), '.squad');
+        const deep = args.includes('--deep');
+        const dryRun = args.includes('--dry-run');
+        const result = await runNap({ squadDir, deep, dryRun });
+        console.log(formatNapReport(result, !!process.env['NO_COLOR']));
         return;
     }
-    if (cmd === 'loop') {
-        const filterIdx = args.indexOf('--filter');
-        const filter = (filterIdx !== -1 && args[filterIdx + 1]) ? args[filterIdx + 1] : undefined;
+    // loop → alias for triage (#509)
+    if (cmd === 'triage' || cmd === 'watch' || cmd === 'loop') {
+        const { runWatch } = await import('./cli/commands/watch.js');
         const intervalIdx = args.indexOf('--interval');
         const intervalMinutes = (intervalIdx !== -1 && args[intervalIdx + 1])
             ? parseInt(args[intervalIdx + 1], 10)
             : 10;
-        console.log(`🔄 Squad loop starting... (full implementation pending)`);
-        if (filter) {
-            console.log(`   Filter: ${filter}`);
-        }
-        console.log(`   Interval: ${intervalMinutes} minutes`);
-        return;
-    }
-    if (cmd === 'hire') {
-        const nameIdx = args.indexOf('--name');
-        const name = (nameIdx !== -1 && args[nameIdx + 1]) ? args[nameIdx + 1] : undefined;
-        const roleIdx = args.indexOf('--role');
-        const role = (roleIdx !== -1 && args[roleIdx + 1]) ? args[roleIdx + 1] : undefined;
-        console.log('👋 Squad hire — team creation wizard starting... (full implementation pending)');
-        if (name) {
-            console.log(`   Name: ${name}`);
-        }
-        if (role) {
-            console.log(`   Role: ${role}`);
-        }
+        await runWatch(process.cwd(), intervalMinutes);
         return;
     }
     if (cmd === 'export') {
@@ -165,7 +754,7 @@ async function main() {
         const { runImport } = await import('./cli/commands/import.js');
         const importFile = args[1];
         if (!importFile) {
-            fatal('Usage: squad import <file> [--force]');
+            fatal('Run: squad import <file> [--force]');
         }
         const hasForce = args.includes('--force');
         await runImport(process.cwd(), importFile, hasForce);
@@ -185,13 +774,13 @@ async function main() {
     }
     if (cmd === 'scrub-emails') {
         const { scrubEmails } = await import('./cli/core/email-scrub.js');
-        const targetDir = args[1] || '.ai-team';
+        const targetDir = args[1] || '.squad';
         const count = await scrubEmails(targetDir);
         if (count > 0) {
-            console.log(`Scrubbed ${count} email address(es).`);
+            console.log(`Scrubbed ${count} email${count !== 1 ? 's' : ''}.`);
         }
         else {
-            console.log('No email addresses found.');
+            console.log('No emails found.');
         }
         return;
     }
@@ -203,7 +792,13 @@ async function main() {
         await runAspire({ docker: useDocker, port });
         return;
     }
-    if (cmd === 'doctor') {
+    if (cmd === 'upstream') {
+        const { upstreamCommand } = await import('./cli/commands/upstream.js');
+        await upstreamCommand(args.slice(1));
+        return;
+    }
+    // heartbeat → alias for doctor (#503)
+    if (cmd === 'doctor' || cmd === 'heartbeat') {
         const { doctorCommand } = await import('./cli/commands/doctor.js');
         await doctorCommand(process.cwd());
         return;
@@ -215,36 +810,46 @@ async function main() {
         const globalExists = fs.existsSync(globalSquadDir);
         console.log(`\n${BOLD}Squad Status${RESET}\n`);
         if (repoSquad) {
-            console.log(`  Active squad: ${BOLD}repo${RESET}`);
-            console.log(`  Path:         ${repoSquad}`);
-            console.log(`  Reason:       Found .squad/ in repository tree`);
+            console.log(`  Here:  ${BOLD}repo${RESET} (in .squad/)`);
+            console.log(`  Path:  ${repoSquad}`);
         }
         else if (globalExists) {
-            console.log(`  Active squad: ${BOLD}personal (global)${RESET}`);
-            console.log(`  Path:         ${globalSquadDir}`);
-            console.log(`  Reason:       No repo .squad/ found; personal squad exists at global path`);
+            console.log(`  Here:  ${BOLD}personal${RESET} (global)`);
+            console.log(`  Path:  ${globalSquadDir}`);
         }
         else {
-            console.log(`  Active squad: ${DIM}none${RESET}`);
-            console.log(`  Reason:       No .squad/ found in repo tree or at global path`);
+            console.log(`  Here:  ${DIM}none${RESET}`);
+            console.log(`  Hint:  Run 'squad init' to get started`);
         }
         console.log();
-        console.log(`  ${DIM}Repo resolution:   ${repoSquad ?? 'not found'}${RESET}`);
-        console.log(`  ${DIM}Global path:       ${globalPath}${RESET}`);
-        console.log(`  ${DIM}Global squad:      ${globalExists ? globalSquadDir : 'not initialized'}${RESET}`);
+        console.log(`  ${DIM}Repo squad:   ${repoSquad ?? 'not found'}${RESET}`);
+        console.log(`  ${DIM}Global:       ${globalPath}${RESET}`);
         console.log();
         return;
     }
+    // shell → explicit REPL launch (#507)
+    if (cmd === 'shell') {
+        await runShell();
+        return;
+    }
     // Unknown command
-    fatal(`Unknown command: ${cmd}\n       Run 'squad help' for usage information.`);
+    fatal(`Unknown command: ${cmd}. Run 'squad help' for commands.`);
 }
 main().catch(err => {
+    debugLog('Fatal CLI error:', err);
     if (err instanceof SquadError) {
         console.error(`${RED}✗${RESET} ${err.message}`);
     }
     else {
-        console.error(err);
+        const msg = err instanceof Error ? err.message : String(err);
+        const friendly = msg.replace(/^Error:\s*/i, '');
+        console.error(`${RED}✗${RESET} ${friendly}`);
+        // Show stack trace only when SQUAD_DEBUG is enabled
+        if (process.env['SQUAD_DEBUG'] === '1' && err instanceof Error && err.stack) {
+            console.error(`\n${DIM}${err.stack}${RESET}`);
+        }
     }
+    console.error(`\n${DIM}Tip: Run 'squad doctor' for help. Set SQUAD_DEBUG=1 for details.${RESET}`);
     process.exit(1);
 });
 //# sourceMappingURL=cli-entry.js.map