squads-cli 0.4.9 → 0.4.10

package/README.md

@@ -765,6 +765,44 @@ squads workers                       Show active workers
   -v, --verbose                      More details
   -k, --kill <pid>                   Kill process
 
+squads context                       Business context for alignment
+  -s, --squad <squad>                Focus on specific squad
+  -t, --topic <topic>                Search memory for relevant context
+  -v, --verbose                      Show additional details
+  --json                             JSON output
+
+squads history                       Recent agent execution history
+  -d, --days <n>                     Days to look back (default: 7)
+  -s, --squad <squad>                Filter by squad
+  -v, --verbose                      Show cost and token details
+  -j, --json                         JSON output
+
+squads health                        Quick infrastructure health check
+  -v, --verbose                      Show logs for failures
+  --json                             JSON output
+
+squads watch <command> [args]        Live refresh any command (like Unix watch)
+  -n, --interval <seconds>           Refresh interval (default: 2)
+
+squads live                          Live TUI dashboard (like htop)
+  -r, --refresh <ms>                 Refresh rate (default: 1000)
+
+squads top                           Live process table (like Unix top)
+
+squads version                       Show version information
+
+squads env show <squad>              Squad execution environment (MCP, model, budget)
+  --json                             JSON output
+squads env list                      List all squad environments
+  --json                             JSON output
+
+squads cost                          Cost summary (today, week, by squad)
+  -s, --squad <squad>                Filter to specific squad
+  --json                             JSON output
+
+squads budget <squad>                Check budget status for a squad
+  --json                             JSON output
+
 squads issues                        GitHub issues
   -o, --org <org>                    Organization (default: agents-squads)
   -r, --repos <repos>                Comma-separated repos

package/dist/cli.js

@@ -388,7 +388,7 @@ function getActivitySparkline(basePath, days = 7) {
 // src/lib/telemetry.ts
 import { existsSync as existsSync2, readFileSync, writeFileSync, mkdirSync } from "fs";
 import { join as join2 } from "path";
-import { homedir } from "os";
+import { homedir, platform, release } from "os";
 import { randomUUID } from "crypto";
 var TELEMETRY_DIR = join2(homedir(), ".squads-cli");
 var CONFIG_PATH = join2(TELEMETRY_DIR, "telemetry.json");
@@ -400,6 +400,20 @@ var TELEMETRY_ENDPOINT = Buffer.from(
 var TELEMETRY_KEY = Buffer.from("c3FfdGVsX3YxXzdmOGE5YjJjM2Q0ZTVmNmE=", "base64").toString();
 var eventQueue = [];
 var flushScheduled = false;
+var cachedSystemContext = null;
+function getSystemContext() {
+  if (cachedSystemContext) return cachedSystemContext;
+  cachedSystemContext = {
+    os: platform(),
+    // darwin, linux, win32
+    osVersion: release(),
+    nodeVersion: process.version,
+    shell: process.env.SHELL?.split("/").pop() || process.env.ComSpec?.split("\\").pop(),
+    terminal: process.env.TERM_PROGRAM || void 0,
+    ci: process.env.CI === "true" ? "true" : void 0
+  };
+  return cachedSystemContext;
+}
 function ensureDir() {
   if (!existsSync2(TELEMETRY_DIR)) {
     mkdirSync(TELEMETRY_DIR, { recursive: true });
@@ -440,6 +454,7 @@ async function track(event, properties) {
     timestamp: (/* @__PURE__ */ new Date()).toISOString(),
     properties: {
       ...properties,
+      ...getSystemContext(),
       anonymousId: config2.anonymousId,
       cliVersion: process.env.npm_package_version || "unknown"
     }
@@ -837,8 +852,9 @@ async function initCommand(options) {
     }
   }
   console.log();
-  if (hasMissingRequired) {
+  if (hasMissingRequired && !options.force) {
     console.log(chalk.yellow("  Install missing tools to continue, then run squads init again."));
+    console.log(chalk.dim("  Or use --force to skip requirement checks."));
     console.log();
     track(Events.CLI_INIT, {
       success: false,
@@ -867,8 +883,11 @@ async function initCommand(options) {
       ".agents/squads",
       ".agents/squads/demo",
       ".agents/memory",
+      ".agents/memory/getting-started",
       ".agents/outputs",
-      ".claude"
+      ".claude",
+      ".claude/skills",
+      ".claude/skills/squads-workflow"
     ];
     for (const dir of dirs) {
       await fs.mkdir(path.join(cwd, dir), { recursive: true });
@@ -969,6 +988,139 @@ Markdown report saved to .agents/outputs/demo/project-analysis.md
       path.join(cwd, ".agents/squads/demo/analyzer.md"),
       analyzerAgent
     );
+    const squadsWorkflowSkill = `# Squads Workflow
+
+Use this skill when working with squads-cli to maintain persistent memory, track goals, and coordinate work.
+
+## Session Start
+
+At session start, you'll see \`squads status\` output automatically. For complex tasks, run:
+
+\`\`\`bash
+squads context                # Get business context, goals, decisions
+squads memory query "<topic>" # Check what we already know
+\`\`\`
+
+**Skip context loading for simple tasks** (typo fixes, quick questions).
+
+## Core Commands
+
+\`\`\`bash
+# Context & Status
+squads context                # Business context for alignment
+squads status                 # Squad overview
+squads dash                   # Full dashboard
+
+# Memory
+squads memory query "<topic>" # Search memory
+squads memory show <squad>    # Squad's full memory
+
+# Goals
+squads goal list              # All active goals
+squads goal set <squad> "X"   # Add a goal
+
+# Running Agents
+squads run <squad>            # Run all agents in squad
+squads run <squad>/<agent>    # Run specific agent
+squads list                   # List all agents
+\`\`\`
+
+## Workflow
+
+### Before Research
+Always check memory first to avoid re-researching:
+\`\`\`bash
+squads memory query "topic"
+\`\`\`
+
+### After Work
+Update memory with what you learned by editing:
+\`.agents/memory/<squad>/<agent>/state.md\`
+
+### Commits
+Include goal attribution when relevant:
+\`\`\`
+feat: add user auth [goal:engineering/1]
+\`\`\`
+
+## Agent Execution
+
+When a task could be automated:
+1. Check if agent exists: \`squads list | grep <keyword>\`
+2. If yes: \`squads run <squad>/<agent>\`
+3. If no: Create agent in \`.agents/squads/<squad>/<name>.md\`
+
+## Memory Locations
+
+- \`.agents/memory/<squad>/<agent>/state.md\` - Current knowledge
+- \`.agents/memory/<squad>/<agent>/learnings.md\` - Insights over time
+
+## Key Principle
+
+**Memory is your cross-session brain.** Without it, every session starts fresh. With it, you build on previous work.
+`;
+    await fs.writeFile(
+      path.join(cwd, ".claude/skills/squads-workflow/instruction.md"),
+      squadsWorkflowSkill
+    );
+    const seedMemory = `# Getting Started with Squads
+
+## What You've Set Up
+
+- **Demo squad** ready to run (\`squads run demo\`)
+- **Memory system** for persistent context
+- **Hooks** that sync status and memory automatically
+
+## Next Steps
+
+1. Run the demo: \`squads run demo\`
+2. Check the dashboard: \`squads dash\`
+3. Create your first real squad in \`.agents/squads/\`
+
+## Tips
+
+- Check memory before researching: \`squads memory query "<topic>"\`
+- Use \`squads context\` for business alignment on complex tasks
+- Agents are reusable - if you do something twice, make it an agent
+`;
+    await fs.writeFile(
+      path.join(cwd, ".agents/memory/getting-started/state.md"),
+      seedMemory
+    );
+    const businessBrief = `# Business Brief
+
+## #1 Priority
+
+**[Define your top priority here]**
+
+## Runway
+
+**Pressure**: LOW | MEDIUM | HIGH
+
+## Current Focus
+
+1. **[Focus area 1]** - Description
+2. **[Focus area 2]** - Description
+3. **[Focus area 3]** - Description
+
+## Blockers
+
+- None currently (or list blockers)
+
+## Decision Framework
+
+1. Does this drive the #1 priority?
+2. Is there a simpler approach?
+3. What's the opportunity cost?
+
+---
+
+*This file is read by \`squads context\` to provide business alignment.*
+`;
+    await fs.writeFile(
+      path.join(cwd, ".agents/BUSINESS_BRIEF.md"),
+      businessBrief
+    );
     const claudeSettings = {
       hooks: {
         SessionStart: [
@@ -1023,12 +1175,22 @@ Each **squad** is a team of **agents** (markdown prompts) that execute via Claud
 
 ## For Claude (READ THIS)
 
-When helping users with squad-related tasks:
+**Skill available**: Use \`/squads-workflow\` for detailed workflow guidance.
+
+### Session Start
+
+You'll see \`squads status\` automatically. For complex tasks, also run:
+\`\`\`bash
+squads context                # Business context, goals, decisions
+squads memory query "<topic>" # What we already know
+\`\`\`
+
+**Skip for simple tasks** (typo fixes, quick questions).
 
-### Check Context First
+### Before Research
+Always check memory first:
 \`\`\`bash
-squads status              # What squads exist?
-squads memory query "X"    # What do we know about X?
+squads memory query "<topic>"
 \`\`\`
 
 ### Creating Agents
@@ -1071,10 +1233,12 @@ squads goal set <squad> "X"  # Add a goal
 | "What's the status?" | Run \`squads dash\` or \`squads status\` |
 | "Run the X agent" | \`squads run <squad>/x\` |
 | "Check memory" | \`squads memory query "<topic>"\` |
+| "Get context" | \`squads context\` |
 
 ## Quick Reference
 
 \`\`\`bash
+squads context         # Business context for alignment
 squads status          # Overview
 squads dash            # Full dashboard
 squads run demo        # Try demo squad
@@ -1137,9 +1301,12 @@ squads goal list       # View goals
   console.log(chalk.green.bold("  \u2713 Squads initialized!"));
   console.log();
   console.log(chalk.dim("  Created:"));
-  console.log(chalk.dim("  \u2022 .agents/squads/demo/  - Demo squad with 2 agents"));
-  console.log(chalk.dim("  \u2022 .claude/settings.json - Claude Code hooks"));
-  console.log(chalk.dim("  \u2022 CLAUDE.md             - Agent instructions"));
+  console.log(chalk.dim("  \u2022 .agents/squads/demo/     - Demo squad with 2 agents"));
+  console.log(chalk.dim("  \u2022 .agents/BUSINESS_BRIEF   - Business context template"));
+  console.log(chalk.dim("  \u2022 .agents/memory/          - Seed memory"));
+  console.log(chalk.dim("  \u2022 .claude/settings.json    - Claude Code hooks"));
+  console.log(chalk.dim("  \u2022 .claude/skills/          - Squads workflow skill"));
+  console.log(chalk.dim("  \u2022 CLAUDE.md                - Agent instructions"));
   console.log();
   const email = await promptEmail();
   if (email) {
@@ -1533,11 +1700,11 @@ function validateMcpServer(server, allow, deny) {
   }
   return null;
 }
-function validateExecution(context2, request) {
+function validateExecution(context, request) {
   const violations = [];
   if (request.bashCommands) {
     for (const cmd of request.bashCommands) {
-      const violation = validateBashCommand(cmd, context2.permissions.bash);
+      const violation = validateBashCommand(cmd, context.permissions.bash);
       if (violation) {
         violations.push(violation);
       }
@@ -1545,7 +1712,7 @@ function validateExecution(context2, request) {
   }
   if (request.writePaths) {
     for (const path3 of request.writePaths) {
-      const violation = validateFilePath(path3, context2.permissions.write, "write");
+      const violation = validateFilePath(path3, context.permissions.write, "write");
       if (violation) {
         violations.push(violation);
       }
@@ -1553,7 +1720,7 @@ function validateExecution(context2, request) {
   }
   if (request.readPaths) {
     for (const path3 of request.readPaths) {
-      const violation = validateFilePath(path3, context2.permissions.read, "read");
+      const violation = validateFilePath(path3, context.permissions.read, "read");
       if (violation) {
         violations.push(violation);
       }
@@ -1563,8 +1730,8 @@ function validateExecution(context2, request) {
     for (const server of request.mcpServers) {
       const violation = validateMcpServer(
         server,
-        context2.permissions.mcp.allow,
-        context2.permissions.mcp.deny
+        context.permissions.mcp.allow,
+        context.permissions.mcp.deny
       );
       if (violation) {
         violations.push(violation);
@@ -1572,11 +1739,11 @@ function validateExecution(context2, request) {
     }
   }
   const hasErrors = violations.some((v) => v.severity === "error");
-  const allowed = context2.permissions.mode !== "strict" || !hasErrors;
+  const allowed = context.permissions.mode !== "strict" || !hasErrors;
   return {
     allowed,
     violations,
-    mode: context2.permissions.mode
+    mode: context.permissions.mode
   };
 }
 function formatViolations(result) {
@@ -1639,16 +1806,16 @@ function parsePermissionsYaml(content) {
   return Object.keys(permissions).length > 0 ? permissions : null;
 }
 function buildContextFromSquad(squadName, squadContent, agentName) {
-  const context2 = getDefaultContext(squadName, agentName);
+  const context = getDefaultContext(squadName, agentName);
   const parsed = parsePermissionsYaml(squadContent);
   if (parsed) {
-    if (parsed.mode) context2.permissions.mode = parsed.mode;
-    if (parsed.bash) context2.permissions.bash = parsed.bash;
-    if (parsed.write) context2.permissions.write = parsed.write;
-    if (parsed.read) context2.permissions.read = parsed.read;
-    if (parsed.mcp) context2.permissions.mcp = parsed.mcp;
+    if (parsed.mode) context.permissions.mode = parsed.mode;
+    if (parsed.bash) context.permissions.bash = parsed.bash;
+    if (parsed.write) context.permissions.write = parsed.write;
+    if (parsed.read) context.permissions.read = parsed.read;
+    if (parsed.mcp) context.permissions.mcp = parsed.mcp;
   }
-  return context2;
+  return context;
 }
 
 // src/commands/run.ts
@@ -8705,9 +8872,9 @@ async function permissionsShowCommand(squadName) {
   }
   const squadFilePath = join18(squadsDir, squadName, "SQUAD.md");
   const squadContent = readFileSync14(squadFilePath, "utf-8");
-  const context2 = buildContextFromSquad(squadName, squadContent);
+  const context = buildContextFromSquad(squadName, squadContent);
   const defaults = getDefaultContext(squadName);
-  const isDefault = JSON.stringify(context2.permissions) === JSON.stringify(defaults.permissions);
+  const isDefault = JSON.stringify(context.permissions) === JSON.stringify(defaults.permissions);
   writeLine(`  ${bold}Squad:${RESET} ${squadName}`);
   if (squad.mission) {
     writeLine(`  ${colors.dim}${squad.mission}${RESET}`);
@@ -8718,47 +8885,47 @@ async function permissionsShowCommand(squadName) {
     writeLine(`  ${colors.dim}Add a permissions block to SQUAD.md to restrict access.${RESET}`);
     writeLine();
   }
-  writeLine(`  ${bold}Mode:${RESET} ${formatMode(context2.permissions.mode)}`);
+  writeLine(`  ${bold}Mode:${RESET} ${formatMode(context.permissions.mode)}`);
   writeLine();
   writeLine(`  ${bold}Bash Commands:${RESET}`);
-  if (context2.permissions.bash.includes("*")) {
+  if (context.permissions.bash.includes("*")) {
     writeLine(`    ${colors.dim}All commands allowed (*)${RESET}`);
   } else {
-    for (const cmd of context2.permissions.bash) {
+    for (const cmd of context.permissions.bash) {
       writeLine(`    ${icons.active} ${cmd}`);
     }
   }
   writeLine();
   writeLine(`  ${bold}Write Paths:${RESET}`);
-  if (context2.permissions.write.includes("**") || context2.permissions.write.includes("*")) {
+  if (context.permissions.write.includes("**") || context.permissions.write.includes("*")) {
     writeLine(`    ${colors.dim}All paths writable (**)${RESET}`);
   } else {
-    for (const path3 of context2.permissions.write) {
+    for (const path3 of context.permissions.write) {
       writeLine(`    ${icons.active} ${path3}`);
     }
   }
   writeLine();
   writeLine(`  ${bold}Read Paths:${RESET}`);
-  if (context2.permissions.read.includes("**") || context2.permissions.read.includes("*")) {
+  if (context.permissions.read.includes("**") || context.permissions.read.includes("*")) {
     writeLine(`    ${colors.dim}All paths readable (**)${RESET}`);
   } else {
-    for (const path3 of context2.permissions.read) {
+    for (const path3 of context.permissions.read) {
       writeLine(`    ${icons.active} ${path3}`);
     }
   }
   writeLine();
   writeLine(`  ${bold}MCP Servers:${RESET}`);
-  if (context2.permissions.mcp.allow.includes("*")) {
+  if (context.permissions.mcp.allow.includes("*")) {
     writeLine(`    ${colors.dim}All servers allowed (*)${RESET}`);
   } else {
     writeLine(`    ${colors.green}Allow:${RESET}`);
-    for (const server of context2.permissions.mcp.allow) {
+    for (const server of context.permissions.mcp.allow) {
       writeLine(`      ${icons.success} ${server}`);
     }
   }
-  if (context2.permissions.mcp.deny.length > 0) {
+  if (context.permissions.mcp.deny.length > 0) {
     writeLine(`    ${colors.red}Deny:${RESET}`);
-    for (const server of context2.permissions.mcp.deny) {
+    for (const server of context.permissions.mcp.deny) {
       writeLine(`      ${icons.error} ${server}`);
     }
   }
@@ -8800,7 +8967,7 @@ async function permissionsCheckCommand(squadName, options) {
   }
   const squadFilePath = join18(squadsDir, squadName, "SQUAD.md");
   const squadContent = readFileSync14(squadFilePath, "utf-8");
-  const context2 = buildContextFromSquad(squadName, squadContent, options.agent);
+  const context = buildContextFromSquad(squadName, squadContent, options.agent);
   const request = {
     mcpServers: options.mcp,
     bashCommands: options.bash,
@@ -8817,7 +8984,7 @@ async function permissionsCheckCommand(squadName, options) {
     writeLine();
     return;
   }
-  const result = validateExecution(context2, request);
+  const result = validateExecution(context, request);
   if (result.violations.length === 0) {
     writeLine(`  ${icons.success} ${colors.green}All permissions valid${RESET}`);
     writeLine();
@@ -9612,6 +9779,7 @@ function launchAgent(target, projectRoot, sessionId, logFile) {
   const sessionName = `squads-tonight-${sessionId}`;
   const claudeCmd = [
     `cd '${projectRoot}'`,
+    `unset ANTHROPIC_API_KEY`,
     `echo "=== Tonight Session: ${target} ===" >> '${logFile}'`,
     `echo "Started: $(date)" >> '${logFile}'`,
     `claude --dangerously-skip-permissions -p 'You are running as part of an overnight autonomous session. Execute your tasks efficiently. If you encounter errors, document them clearly and move on. Do not ask for user input.' -- "Run squad: ${target}" 2>&1 | tee -a '${logFile}'`,
@@ -9935,14 +10103,24 @@ program.name("squads").description("A CLI for humans and agents").version(versio
   }
   await statusCommand(void 0, {});
 });
-program.command("init").description("Initialize a new squad project").option("-t, --template <template>", "Project template", "default").option("--skip-infra", "Skip infrastructure setup prompt").action(initCommand);
-program.command("run <target>").description("Run a squad or agent").option("-v, --verbose", "Verbose output").option("-d, --dry-run", "Show what would be run without executing").option("-e, --execute", "Execute agent via Claude CLI (requires claude installed)").option("-a, --agent <agent>", "Run specific agent within squad").option("-t, --timeout <minutes>", "Execution timeout in minutes (default: 30)", "30").option("-p, --parallel", "Run all agents in parallel (N tmux sessions)").option("-l, --lead", "Lead mode: single orchestrator using Task tool for parallelization").option("-f, --foreground", "Run in foreground (no tmux, blocks terminal)").option("--use-api", "Use API credits instead of subscription").option("--effort <level>", "Effort level: high, medium, low (default: from SQUAD.md or high)").option("--skills <skills...>", "Skills to load (skill IDs or local paths)").action((target, options) => runCommand(target, { ...options, timeout: parseInt(options.timeout, 10) }));
-program.command("list").description("List agents and squads").option("-s, --squads", "List squads only").option("-a, --agents", "List agents only").action(listCommand);
+program.command("init").description("Initialize a new squad project").option("-t, --template <template>", "Project template", "default").option("--skip-infra", "Skip infrastructure setup prompt").option("--force", "Skip requirement checks (for CI/testing)").action(initCommand);
+program.command("run <target>").description("Run a squad or agent").option("-v, --verbose", "Verbose output").option("-d, --dry-run", "Show what would be run without executing").option("-e, --execute", "Execute agent via Claude CLI (requires claude installed)").option("-a, --agent <agent>", "Run specific agent within squad").option("-t, --timeout <minutes>", "Execution timeout in minutes (default: 30)", "30").option("-p, --parallel", "Run all agents in parallel (N tmux sessions)").option("-l, --lead", "Lead mode: single orchestrator using Task tool for parallelization").option("-f, --foreground", "Run in foreground (no tmux, blocks terminal)").option("--use-api", "Use API credits instead of subscription").option("--effort <level>", "Effort level: high, medium, low (default: from SQUAD.md or high)").option("--skills <skills...>", "Skills to load (skill IDs or local paths)").addHelpText("after", `
+Examples:
+  $ squads run engineering              Run whole squad (shows agent list)
+  $ squads run engineering/code-review  Run specific agent (slash notation)
+  $ squads run engineering -a code-review  Same as above (flag notation)
+  $ squads run engineering --dry-run    Preview what would run
+  $ squads run engineering --execute    Execute via Claude CLI
+  $ squads run engineering --parallel   Run all agents in parallel (tmux)
+  $ squads run engineering --lead       Single orchestrator with Task tool
+  $ squads run engineering -f           Run in foreground (blocks terminal)
+`).action((target, options) => runCommand(target, { ...options, timeout: parseInt(options.timeout, 10) }));
+program.command("list").description("List agents and squads").option("-s, --squads", "List squads only").option("-a, --agents", "List agents only").option("-v, --verbose", "Show additional details").action(listCommand);
 program.command("status [squad]").description("Show squad status and state").option("-v, --verbose", "Show detailed status").action(statusCommand);
 program.command("dashboard").alias("dash").description("Show comprehensive goals and metrics dashboard").option("-v, --verbose", "Show additional details").option("-c, --ceo", "Executive summary with priorities and blockers").option("-f, --full", "Include GitHub PR/issue stats (slower, ~30s)").action((options) => dashboardCommand({ ...options, fast: !options.full }));
-var context = program.command("context").description("View and manage squad execution context");
-context.command("show <squad>").description("Show context for a squad (MCP, skills, model, budget)").option("--json", "Output as JSON").action(contextShowCommand);
-context.command("list").description("List context for all squads").option("--json", "Output as JSON").action(contextListCommand);
+var env = program.command("env").description("View squad execution environment (MCP, skills, model, budget)");
+env.command("show <squad>").description("Show execution environment for a squad").option("--json", "Output as JSON").action(contextShowCommand);
+env.command("list").description("List execution environment for all squads").option("--json", "Output as JSON").action(contextListCommand);
 program.command("cost").description("Show cost summary (today, week, by squad)").option("-s, --squad <squad>", "Filter to specific squad").option("--json", "Output as JSON").action(costCommand);
 program.command("budget").description("Check budget status for a squad").argument("<squad>", "Squad to check").option("--json", "Output as JSON").action(budgetCheckCommand);
 var exec2 = program.command("exec").description("View execution history and statistics");
@@ -9958,7 +10136,7 @@ progress.command("start <squad> <description>").description("Register a new acti
 progress.command("complete <taskId>").description("Mark a task as completed").option("-f, --failed", "Mark as failed instead").action(progressCompleteCommand);
 program.command("results [squad]").description("Show squad results: git activity + KPI goals vs actuals").option("-d, --days <days>", "Days to look back", "7").option("-v, --verbose", "Show detailed KPIs per goal").action((squad, options) => resultsCommand({ ...options, squad }));
 program.command("history").description("Show recent agent execution history").option("-d, --days <days>", "Days to look back", "7").option("-s, --squad <squad>", "Filter by squad").option("-v, --verbose", "Show cost and token details").option("-j, --json", "Output as JSON").action((options) => historyCommand(options));
-program.command("context-feed").alias("feed").description("Context feed for agents: goals, memory, costs, activity").option("-s, --squad <squad>", "Focus on specific squad").option("-t, --topic <topic>", "Search memory for relevant context").option("-a, --agent", "Output JSON for agent consumption").option("-j, --json", "Output as JSON (alias for --agent)").option("-v, --verbose", "Show additional details").action((options) => contextFeedCommand(options));
+program.command("context").alias("feed").description("Get business context for alignment: goals, memory, costs, activity").option("-s, --squad <squad>", "Focus on specific squad").option("-t, --topic <topic>", "Search memory for relevant context").option("-a, --agent", "Output JSON for agent consumption").option("-j, --json", "Output as JSON (alias for --agent)").option("-v, --verbose", "Show additional details").action((options) => contextFeedCommand(options));
 program.command("workers").description("Show active workers: Claude sessions, tasks, dev servers").option("-v, --verbose", "Show more details").option("-k, --kill <pid>", "Kill a process by PID").action(workersCommand);
 program.command("health").description("Quick health check for all infrastructure services").option("-v, --verbose", "Show optional services").action((options) => healthCommand(options));
 program.command("watch <command> [args...]").description("Live refresh any squads command (like Unix watch)").option("-n, --interval <seconds>", "Refresh interval in seconds", "2").option("--no-clear", "Don't clear screen between refreshes").action((command, args, options) => watchCommand(command, args, {
@@ -9967,7 +10145,14 @@ program.command("watch <command> [args...]").description("Live refresh any squad
 }));
 program.command("live").description("Live TUI dashboard with real-time metrics (like htop)").option("-m, --minimal", "Minimal view").option("-f, --focus <panel>", "Focus on specific panel (agents, cost, activity, memory)").action((options) => liveCommand(options));
 program.command("top").description("Live process table (like Unix top) - numbers update in place").action(() => topCommand());
-var memory = program.command("memory").description("Query and manage squad memory").action(() => {
+var memory = program.command("memory").description("Query and manage squad memory").addHelpText("after", `
+Examples:
+  $ squads memory query "pricing"     Search all memory for "pricing"
+  $ squads memory show engineering    View engineering squad's memory
+  $ squads memory update research "Found: MCP adoption at 15%"
+  $ squads memory list                List all memory entries
+  $ squads memory sync --push         Sync and push to git
+`).action(() => {
   memory.outputHelp();
 });
 memory.command("query <query>").description("Search across all squad memory").option("-s, --squad <squad>", "Limit search to specific squad").option("-a, --agent <agent>", "Limit search to specific agent").action(memoryQueryCommand);