atris 3.15.14 → 3.15.22

package/bin/atris.js

@@ -26,7 +26,13 @@ try {
 }
 
 // Update check utility
-const { checkForUpdates, showUpdateNotification, autoUpdate } = require('../utils/update-check');
+const {
+  checkForUpdates,
+  showUpdateNotification,
+  autoUpdate,
+  inspectInstallGitState,
+  formatInstallGitWarning,
+} = require('../utils/update-check');
 
 // State detection for smart default
 const { detectWorkspaceState, loadContext } = require('../lib/state-detection');
@@ -62,10 +68,18 @@ const fetchMyAgents = (token) => _fetchMyAgents(token, apiRequestJson);
 const displayAccountSummary = () => _displayAccountSummary(apiRequestJson);
 
 // Run update check in background (non-blocking)
-// Skip for 'version' and 'update' commands to avoid redundant messages
+// Skip for 'version', 'update', and help commands to avoid redundant messages or help side effects.
 let updateCheckPromise = null;
-const skipUpdateCheck = Boolean(process.env.ATRIS_SKIP_UPDATE_CHECK || process.env.NO_UPDATE_NOTIFIER);
-if (!skipUpdateCheck && (!process.argv[2] || (process.argv[2] && !['version', 'update', 'help'].includes(process.argv[2])))) {
+const updateCommand = process.argv[2];
+const updateArgs = process.argv.slice(3);
+const helpRequested = updateCommand === 'help'
+  || updateCommand === '--help'
+  || updateCommand === '-h'
+  || updateArgs.includes('--help')
+  || updateArgs.includes('-h')
+  || updateArgs[0] === 'help';
+const skipUpdateCheck = Boolean(process.env.ATRIS_SKIP_UPDATE_CHECK || process.env.NO_UPDATE_NOTIFIER || helpRequested);
+if (!skipUpdateCheck && (!updateCommand || (updateCommand && !['version', 'update'].includes(updateCommand)))) {
   updateCheckPromise = checkForUpdates()
     .then((updateInfo) => {
       // Show notification if update available (after command completes)
@@ -103,6 +117,15 @@ const isBusinessSyncSafetyCommand = command === 'sync'
     || firstCommandArg === 'resolve'
   );
 
+// Keep APP.md app-pack operations independent from the heavier workspace boot
+// path so `atris apps --json` stays machine-readable for agents.
+if (command === 'apps') {
+  const subcommand = process.argv[3];
+  const args = process.argv.slice(4);
+  require('../commands/apps').appsCommand(subcommand, ...args);
+  process.exit(0);
+}
+
 // Auto-sync skills only for commands that modify workspace state
 if (['init', 'update', 'upgrade'].includes(command) || (command === 'sync' && !isBusinessSyncSafetyCommand)) {
   try {
@@ -116,10 +139,68 @@ if (['init', 'update', 'upgrade'].includes(command) || (command === 'sync' && !i
   }
 }
 
+/**
+ * Load active missions from .atris/state/missions.jsonl (append-only event log).
+ * Walks lines in reverse, deduping by mission id, returns missions whose latest
+ * record has status in {ready, running, planning} sorted newest-first.
+ *
+ * Each mission: { id, owner, objective, status, verifier, verifier_passed, next_action, lane }.
+ *
+ * Returns [] if file missing or malformed — never throws.
+ */
+function loadActiveMissions(workspaceDir) {
+  try {
+    const file = path.join(workspaceDir, '.atris', 'state', 'missions.jsonl');
+    if (!fs.existsSync(file)) return [];
+    const lines = fs.readFileSync(file, 'utf8').split('\n').filter(Boolean);
+    const seen = new Map(); // id -> mission record
+    for (let i = lines.length - 1; i >= 0; i--) {
+      let rec;
+      try { rec = JSON.parse(lines[i]); } catch { continue; }
+      const id = rec.id || rec.mission_id;
+      if (!id || seen.has(id)) continue;
+      seen.set(id, rec);
+    }
+    const live = [];
+    for (const m of seen.values()) {
+      const status = m.status;
+      if (!['ready', 'running', 'planning'].includes(status)) continue;
+      live.push({
+        id: m.id || m.mission_id,
+        owner: m.owner || '?',
+        objective: m.objective || '',
+        status,
+        verifier: m.verifier || null,
+        verifier_passed: (m.verifier_result && m.verifier_result.passed) === true,
+        next_action: m.next_action || '',
+        lane: m.lane || null,
+      });
+    }
+    // Most recently started first (rough — relies on insertion order from reversed walk)
+    return live;
+  } catch {
+    return [];
+  }
+}
+
+function showSearchHelp() {
+  console.log('Usage: atris search <keyword>');
+  console.log('Example: atris search auth');
+}
+
 function searchJournal(keyword) {
   if (!keyword) {
-    console.log('Usage: atris search <keyword>');
-    console.log('Example: atris search auth');
+    showSearchHelp();
+    process.exit(1);
+  }
+
+  if (keyword === '--help' || keyword === '-h') {
+    showSearchHelp();
+    process.exit(0);
+  }
+
+  if (process.argv.slice(4).includes('--help') || process.argv.slice(4).includes('-h')) {
+    showSearchHelp();
     process.exit(1);
   }
 
@@ -253,14 +334,17 @@ function showHelp() {
   console.log('  now        - Show atris/now.md, the current operating truth');
   console.log('  activate   - Load Atris context');
   console.log('  status     - See local work and completions (`atris status <business>` for remote)');
+  console.log('  xp         - Show Career XP and contribution graph');
   console.log('  analytics  - Show recent productivity from journals');
   console.log('  search     - Search journal history (atris search <keyword>)');
   console.log('  clean      - Housekeeping (stale tasks, archive journals, broken refs)');
   console.log('  verify     - Validate work is done (tests, MAP.md, changes)');
   console.log('  task       - Local agent task plane (atomic claims, TODO import)');
+  console.log('  mission    - Goal + loop + member owner + verifier + receipt');
   console.log('  release    - Tag release, bump version, create GitHub release, draft /launch');
   console.log('  learn      - Project learnings (patterns, pitfalls, preferences)');
   console.log('  brain      - Compile MAP/TODO/wiki/state into a loadable agent brain');
+  console.log('  lesson     - Append a one-line lesson to atris/lessons.md');
   console.log('  ingest     - Local-first wiki ingest into atris/wiki/');
   console.log('  query      - Local-first wiki query against atris/wiki/');
   console.log('  lint       - Local-first wiki lint for atris/wiki/');
@@ -269,6 +353,7 @@ function showHelp() {
   console.log('Optional helpers:');
   console.log('  brainstorm - Explore ideas conversationally before planning');
   console.log('  autopilot  - Guided loop that can clarify TODOs and run plan → do → review');
+  console.log('  worktree   - Isolated Git worktrees plus guarded ship/merge for parallel agents');
   console.log('  visualize  - Generate a Slack/deck-ready visual from a prompt');
   console.log('');
   console.log('Experiments:');
@@ -319,7 +404,7 @@ function showHelp() {
   console.log('  console    - Start/attach always-on coding console (tmux daemon)');
   console.log('  soul       - Show, snapshot, or fork workspace identity');
   console.log('  fleet      - Inspect local fleet status');
-  console.log('  agent      - Select which Atris agent to use');
+  console.log('  agent      - Select cloud agent, or run `agent doctor` for local CLI wiring');
   console.log('  chat       - Chat with the selected Atris agent');
   console.log('  login      - Sign in or add another account');
   console.log('  logout     - Sign out of current account');
@@ -333,7 +418,7 @@ function showHelp() {
   console.log('  calendar   - Calendar commands (today, week)');
   console.log('  twitter    - Twitter commands (post)');
   console.log('  slack      - Slack commands (channels)');
-  console.log('  imessage   - Local Mac iMessage commands (doctor, recent)');
+  console.log('  imessage   - Local Mac iMessage commands (doctor, lookup, recent, send)');
   console.log('  integrations - Show integration status');
   console.log('');
   console.log('Skills:');
@@ -418,6 +503,216 @@ function showReviewHelp() {
   console.log('');
 }
 
+function showStatusHelp() {
+  console.log('');
+  console.log('Usage: atris status [--quick] [--json] [--verbose]');
+  console.log('');
+  console.log('Description:');
+  console.log('  Show the local Atris workspace task, inbox, completion, lesson, and team status.');
+  console.log('');
+  console.log('Options:');
+  console.log('  --quick, -q    Print one compact status line.');
+  console.log('  --json         Print machine-readable workspace status.');
+  console.log('  --verbose, -v  Print the legacy visual task board.');
+  console.log('  --help, -h     Show this help.');
+  console.log('');
+}
+
+function showAnalyticsHelp() {
+  console.log('');
+  console.log('Usage: atris analytics');
+  console.log('');
+  console.log('Description:');
+  console.log('  Summarize local journal completions, inbox trend, and activity patterns.');
+  console.log('');
+  console.log('Options:');
+  console.log('  --help, -h   Show this help.');
+  console.log('');
+}
+
+function showActivateHelp() {
+  console.log('');
+  console.log('Usage: atris activate');
+  console.log('');
+  console.log('Description:');
+  console.log('  Load workspace context, recent completions, TODO, MAP, journal, and wiki status.');
+  console.log('');
+  console.log('Options:');
+  console.log('  --help, -h   Show this help.');
+  console.log('');
+}
+
+function showNextHelp(commandName = 'next') {
+  console.log('');
+  console.log(`Usage: atris ${commandName} [request]`);
+  console.log('');
+  console.log('Description:');
+  console.log('  Auto-advance to the next workflow step, or route a request through the Atris entry.');
+  console.log('');
+  console.log('Options:');
+  console.log('  --help, -h   Show this help.');
+  console.log('');
+}
+
+function showVerifyHelp() {
+  console.log('');
+  console.log('Usage: atris verify [task]');
+  console.log('Usage: atris verify <feature-slug> --section <name>');
+  console.log('');
+  console.log('Description:');
+  console.log('  Validate workspace health, a specific task, or a feature rubric section.');
+  console.log('');
+  console.log('Options:');
+  console.log('  --section <name>  Run a fenced bash check from atris/features/<slug>/validate.md.');
+  console.log('  --help, -h        Show this help.');
+  console.log('');
+}
+
+function showUpdateHelp(commandName = 'update') {
+  console.log('');
+  console.log(`Usage: atris ${commandName} [--all] [--dry-run] [--force]`);
+  console.log('');
+  console.log('Description:');
+  console.log('  Sync Atris workspace files from the installed CLI templates.');
+  console.log('');
+  console.log('Options:');
+  console.log('  --all        Update Atris files across projects under the current tree.');
+  console.log('  --dry-run    Preview update work without writing files.');
+  console.log('  --force      Overwrite existing template files where supported.');
+  console.log('  --help, -h       Show this help.');
+  console.log('');
+}
+
+function showUpgradeHelp() {
+  console.log('');
+  console.log('Usage: atris upgrade');
+  console.log('');
+  console.log('Description:');
+  console.log('  Check npm for the latest Atris CLI and install it globally if newer.');
+  console.log('');
+  console.log('Options:');
+  console.log('  --help, -h       Show this help.');
+  console.log('');
+}
+
+function showReleaseHelp() {
+  console.log('');
+  console.log('Usage: atris release [--dry-run]');
+  console.log('');
+  console.log('Description:');
+  console.log('  Draft or publish a release from local git history.');
+  console.log('');
+  console.log('Options:');
+  console.log('  --dry-run    Print the planned release without committing, tagging, or pushing.');
+  console.log('  --help, -h   Show this help.');
+  console.log('');
+}
+
+function showAuthHelp(commandName) {
+  const usage = {
+    login: 'Usage: atris login [--token <token>] [--force]',
+    logout: 'Usage: atris logout',
+    whoami: 'Usage: atris whoami',
+    switch: 'Usage: atris switch [account] [--global]',
+    use: 'Usage: atris use [account]',
+    accounts: 'Usage: atris accounts [add|remove <account>|remove --all]',
+  }[commandName] || 'Usage: atris login|logout|whoami';
+  console.log('');
+  console.log(usage);
+  console.log('');
+  console.log('Description:');
+  if (commandName === 'login') {
+    console.log('  Sign in with browser OAuth or a pasted API token.');
+  } else if (commandName === 'logout') {
+    console.log('  Sign out of the current Atris account.');
+  } else if (commandName === 'whoami') {
+    console.log('  Show the active Atris account.');
+  } else if (commandName === 'switch') {
+    console.log('  Switch the active account globally or for this terminal session.');
+  } else if (commandName === 'use') {
+    console.log('  Print an ATRIS_PROFILE export for per-terminal account use.');
+  } else if (commandName === 'accounts') {
+    console.log('  List, add, or remove saved Atris accounts.');
+  }
+  console.log('');
+  console.log('Options:');
+  if (commandName === 'login') {
+    console.log('  --token <token>  Save an API token without prompting.');
+    console.log('  --force, -f      Re-run login even if credentials already exist.');
+  } else if (commandName === 'switch') {
+    console.log('  --global, -g     Switch the account for all terminals.');
+  }
+  console.log('  --help, -h       Show this help.');
+  console.log('');
+}
+
+function showIntegrationsHelp() {
+  console.log('');
+  console.log('Usage: atris integrations');
+  console.log('');
+  console.log('Description:');
+  console.log('  Show connection status for Gmail, Calendar, Slack, Twitter, GitHub, and iMessage.');
+  console.log('');
+  console.log('Options:');
+  console.log('  --help, -h       Show this help.');
+  console.log('');
+}
+
+function showSetupHelp() {
+  console.log('');
+  console.log('Usage: atris setup');
+  console.log('');
+  console.log('Description:');
+  console.log('  Guided first-time setup: checks Node.js, login, businesses, and pull.');
+  console.log('');
+  console.log('Options:');
+  console.log('  --help, -h   Show this help.');
+  console.log('');
+}
+
+function showServeHelp() {
+  console.log('');
+  console.log('Usage: atris serve [--agent <agent_id>] [--allow-bash]');
+  console.log('');
+  console.log('Description:');
+  console.log('  Start the local AI Computer bridge for the current directory.');
+  console.log('');
+  console.log('Options:');
+  console.log('  --agent <agent_id>  Bind the session to a specific cloud agent.');
+  console.log('  --allow-bash        Allow remote bash operations in this directory.');
+  console.log('  --help, -h          Show this help.');
+  console.log('');
+}
+
+function showLoopHelp() {
+  console.log('');
+  console.log('Usage: atris loop [--dry-run] [--json] [--limit=N]');
+  console.log('');
+  console.log('Description:');
+  console.log('  Inspect wiki upkeep state and optionally refresh wiki status/log files.');
+  console.log('');
+  console.log('Options:');
+  console.log('  --dry-run    Preview wiki loop state without writing files.');
+  console.log('  --json       Print the loop report as JSON.');
+  console.log('  --limit=N    Limit suggested source count.');
+  console.log('  --help, -h   Show this help.');
+  console.log('');
+}
+
+function showCleanHelp() {
+  console.log('');
+  console.log('Usage: atris clean [--dry-run]');
+  console.log('');
+  console.log('Description:');
+  console.log('  Check workspace housekeeping: stale tasks, MAP.md refs, old journals,');
+  console.log('  empty TODO sections, and stale wiki pages.');
+  console.log('');
+  console.log('Options:');
+  console.log('  --dry-run, -n   Preview cleanup without changing files.');
+  console.log('  --help, -h      Show this help.');
+  console.log('');
+}
+
 function showAutopilotHelp() {
   console.log('');
   console.log('Usage: atris autopilot [description] [options]');
@@ -457,11 +752,22 @@ const { planAtris: planCmd, doAtris: doCmd, reviewAtris: reviewCmd } = require('
 
 // All other commands are lazy-loaded inline (require() only when invoked)
 
+if (command === '2' && ['fast', 'pro'].includes(String(firstCommandArg || '').toLowerCase())) {
+  const userInput = process.argv.slice(2).join(' ');
+  planCmd(userInput)
+    .then(() => process.exit(0))
+    .catch((error) => {
+      console.error(`✗ Atris 2 failed: ${error.message || error}`);
+      process.exit(1);
+    });
+  return;
+}
+
 // Check if this is a known command or natural language input
 const knownCommands = ['init', 'log', 'now', 'status', 'analytics', 'visualize', 'brain', 'brainstorm', 'autopilot', 'run', 'plan', 'do', 'review', 'release',
-                       'activate', '_activate', 'agent', 'chat', 'console', 'login', 'logout', 'whoami', 'switch', 'use', 'accounts', '_resolve', '_profile-email', '_switch-session', 'shell-init', 'update', 'upgrade', 'version', 'help', 'next', 'atris',
-                       'clean', 'verify', 'search', 'skill', 'member', 'app', 'learn', 'plugin', 'experiments', 'receipt', 'proof', 'openclaw', 'pull', 'push', 'live', 'align', 'terminal', 'computer', 'diff', 'business', 'sync',
-                       'ingest', 'query', 'lint', 'loop', 'task', 'aeo',
+                       'activate', '_activate', 'agent', 'chat', 'console', 'serve', 'login', 'logout', 'whoami', 'switch', 'use', 'accounts', '_resolve', '_profile-email', '_switch-session', 'shell-init', 'update', 'upgrade', 'version', 'help', 'next', 'atris',
+                       'clean', 'verify', 'search', 'skill', 'member', 'codex-goal', 'app', 'apps', 'learn', 'lesson', 'plugin', 'experiments', 'receipt', 'proof', 'openclaw', 'pull', 'push', 'live', 'align', 'terminal', 'computer', 'diff', 'business', 'sync',
+                       'ingest', 'query', 'lint', 'loop', 'task', 'mission', 'worktree', 'aeo', 'xp', 'play', 'gm', 'x',
                        'gmail', 'calendar', 'twitter', 'slack', 'imessage', 'integrations', 'setup', 'clean-workspace', 'cw',
                        'fork', 'browse', 'publish', 'sleep', 'wake', 'feedback', 'errors', 'wiki', 'code-review', 'cr', 'soul', 'fleet'];
 
@@ -524,6 +830,17 @@ if (!command || !knownCommands.includes(command)) {
 if (!command || !knownCommands.includes(command)) {
   const userInput = process.argv.slice(2).join(' ');
 
+  if (process.argv.includes('--json')) {
+    console.log(JSON.stringify({
+      ok: false,
+      error: command ? `unknown command: ${command}` : 'unknown command',
+      command: command || null,
+      input: userInput,
+      usage: 'atris help',
+    }, null, 2));
+    process.exit(2);
+  }
+
   // Warn if this looks like a mistyped single-word command (no spaces)
   if (command && !userInput.includes(' ')) {
     console.log(`⚠ Unknown command: "${command}". Run "atris help" for available commands.`);
@@ -570,12 +887,27 @@ async function interactiveEntry(userInput) {
     ? context.inProgressFeaturesCount
     : (context.inProgressFeatures || []).length;
 
+  // Pull active missions (durable goals) — these outrank dev-pipeline state
+  // because a mission with an unverified verifier is a Keshav-attributable
+  // commitment that hasn't been closed yet.
+  const activeMissions = loadActiveMissions(workspaceDir);
+  const liveMissionsCount = activeMissions.length;
+  // Mission needs a tick when: it has a verifier configured AND that verifier
+  // hasn't passed yet. Planning-state missions count too — first tick is what
+  // moves them to running.
+  const needsTickMission = activeMissions.find(
+    (m) => m.verifier && !m.verifier_passed
+  );
+
   // Build status line
   const parts = [];
   const wipCount = inProgressTasksCount + inProgressFeaturesCount;
   if (wipCount > 0) {
     parts.push(`WIP: ${wipCount}`);
   }
+  if (liveMissionsCount > 0) {
+    parts.push(`Missions: ${liveMissionsCount}`);
+  }
   if (inboxCount > 0) {
     parts.push(`Inbox: ${inboxCount}`);
   }
@@ -627,16 +959,32 @@ async function interactiveEntry(userInput) {
     return;
   }
 
-  // Cold start - auto-advance based on current workspace state
+  // Surface live missions so the operator sees durable goals alongside dev WIP.
+  if (liveMissionsCount > 0) {
+    console.log('\nLive missions:');
+    for (const m of activeMissions.slice(0, 5)) {
+      const tickGate = m.verifier && !m.verifier_passed ? ' [needs tick]' : '';
+      const obj = m.objective.length > 70 ? `${m.objective.slice(0, 67)}...` : m.objective;
+      console.log(`- [${m.owner}] ${obj} (${m.status})${tickGate}`);
+    }
+  }
+
+  // Cold start auto-advance.
+  // ORDER MATTERS: missions outrank pipeline state because a mission's verifier
+  // is the contract that gates the Stop hook. Closing it unblocks everything else.
+  if (needsTickMission) {
+    console.log(`\nNext: atris mission tick (${needsTickMission.owner} mission has unverified verifier)`);
+    console.log(`Run: atris mission tick ${needsTickMission.id} --verify --complete-on-pass`);
+    return;
+  }
+
   if (completedTasksCount > 0) {
     const preview = context.completedTasks.slice(0, 3).map((t) => (t.length > 70 ? `${t.slice(0, 67)}...` : t));
     if (preview.length > 0) {
-      console.log('\nCompleted (preview):');
+      console.log('\nCompleted (history):');
       preview.forEach((t) => console.log(`- ${t}`));
+      console.log('Completed tasks are history, not pending review.');
     }
-    console.log('\nNext: atris review (pending validation)');
-    await reviewCmd();
-    return;
   }
 
   if (wipCount > 0 || backlogCount > 0) {
@@ -670,6 +1018,11 @@ async function interactiveEntry(userInput) {
     return;
   }
 
+  if (completedTasksCount > 0) {
+    console.log('Next: atris plan (new work)');
+    return;
+  }
+
   // No obvious next step - prompt for input
   const rl = readline.createInterface({
     input: process.stdin,
@@ -799,6 +1152,13 @@ function showWelcomeVisualization() {
 }
 
 if (command === 'init') {
+  // Help flag must short-circuit before initCmd() (which scaffolds files)
+  // and before interactiveEntry (which loads workspace context).
+  const initArg = process.argv[3];
+  if (initArg === '-h' || initArg === '--help' || initArg === 'help') {
+    initCmd();
+    process.exit(0);
+  }
   initCmd();
   // Flow directly into interactive prompt
   interactiveEntry()
@@ -812,15 +1172,36 @@ if (command === 'init') {
   Promise.resolve(require('../commands/task').run(process.argv.slice(3)))
     .then(() => process.exit(0))
     .catch((err) => { console.error(`\n✗ Error: ${err.message || err}`); process.exit(1); });
+} else if (command === 'mission') {
+  Promise.resolve(require('../commands/mission').missionCommand(process.argv.slice(3)))
+    .then(() => process.exit(0))
+    .catch((err) => { console.error(`\n✗ Error: ${err.message || err}`); process.exit(1); });
+} else if (command === 'worktree') {
+  Promise.resolve(require('../commands/worktree').worktreeCommand(process.argv.slice(3)))
+    .then((code) => process.exit(code || 0))
+    .catch((err) => { console.error(`\n✗ Error: ${err.message || err}`); process.exit(1); });
+} else if (command === 'codex-goal') {
+  Promise.resolve(require('../commands/codex-goal').codexGoalCommand(process.argv.slice(3)))
+    .then(() => process.exit(process.exitCode || 0))
+    .catch((err) => { console.error(`\n✗ Error: ${err.message || err}`); process.exit(1); });
 } else if (command === 'aeo') {
   // AEO: AI Engine Optimization — credit-metered citation drafting against the customer workspace.
   Promise.resolve(require('../commands/aeo').run(process.argv.slice(3)))
     .then(() => process.exit(0))
     .catch((err) => { console.error(`\n✗ Error: ${err.message || err}`); process.exit(1); });
 } else if (command === 'brain') {
-  Promise.resolve(require('../commands/brain').brainCommand(process.argv.slice(3)))
+  Promise.resolve()
+    .then(() => require('../commands/brain').brainCommand(process.argv.slice(3)))
     .then(() => process.exit(0))
-    .catch((err) => { console.error(`\n✗ Error: ${err.message || err}`); process.exit(1); });
+    .catch((err) => {
+      const message = err.message || String(err);
+      if (process.argv.slice(3).includes('--json')) {
+        console.log(JSON.stringify({ ok: false, error: message }, null, 2));
+      } else {
+        console.error(`\n✗ Error: ${message}`);
+      }
+      process.exit(1);
+    });
 } else if (command === 'agent') {
   agentAtris().then(() => process.exit(0)).catch((err) => { console.error(`\n✗ Error: ${err.message || err}`); process.exit(1); });
 } else if (command === 'log') {
@@ -832,7 +1213,14 @@ if (command === 'init') {
         console.error(`✗ Log sync failed: ${error.message || error}`);
         process.exit(1);
       });
-  } else if (subcommand && subcommand !== '--help' && !subcommand.startsWith('-')) {
+  } else if (subcommand === '--help' || subcommand === '-h' || subcommand === 'help') {
+    console.log('Usage: atris log [business-slug | sync | help]');
+    console.log('');
+    console.log('  atris log                Open today\'s journal REPL (write to ## Inbox)');
+    console.log('  atris log <slug>         Show business log history');
+    console.log('  atris log sync           Sync the local journal to cloud');
+    process.exit(0);
+  } else if (subcommand && !subcommand.startsWith('-')) {
     // Business log: atris log <business-slug>
     require('../commands/context-sync').businessLog(subcommand)
       .then(() => process.exit(0))
@@ -841,10 +1229,21 @@ if (command === 'init') {
     logCmd();
   }
 } else if (command === 'now') {
-  require('../commands/now').nowAtris(process.argv.slice(3));
+  const args = process.argv.slice(3);
+  if (args.includes('--help') || args.includes('-h') || args[0] === 'help') {
+    require('../commands/now').nowAtris(args);
+    process.exit(0);
+  }
+  require('../commands/now').nowAtris(args);
 } else if (command === 'activate') {
+  const args = process.argv.slice(3);
+  if (args.includes('--help') || args.includes('-h') || args[0] === 'help') {
+    showActivateHelp();
+    process.exit(0);
+  }
   activateCmd();
 } else if (command === 'update' || command === 'sync') {
+  const args = process.argv.slice(3);
   const firstSyncArg = process.argv[3];
   const isBusinessSync = command === 'sync'
     && (
@@ -853,6 +1252,10 @@ if (command === 'init') {
       || (firstSyncArg && !firstSyncArg.startsWith('-'))
     )
     && firstSyncArg !== 'all';
+  if ((args.includes('--help') || args.includes('-h') || args[0] === 'help') && !isBusinessSync) {
+    showUpdateHelp(command);
+    process.exit(0);
+  }
   if (isBusinessSync) {
     Promise.resolve(require('../commands/business-sync').businessSync(process.argv.slice(3)))
       .then(() => process.exit(0))
@@ -867,6 +1270,11 @@ if (command === 'init') {
     syncCmd();
   }
 } else if (command === 'upgrade') {
+  const args = process.argv.slice(3);
+  if (args.includes('--help') || args.includes('-h') || args[0] === 'help') {
+    showUpgradeHelp();
+    process.exit(0);
+  }
   upgradeAtris().then(() => process.exit(0)).catch((err) => { console.error(`\n✗ Error: ${err.message || err}`); process.exit(1); });
 } else if (command === 'chat') {
   chatAtris()
@@ -881,6 +1289,10 @@ if (command === 'init') {
   // Start the local AI Computer bridge — make this directory addressable
   // by cloud agents via the Atris API
   const serveArgs = process.argv.slice(3);
+  if (serveArgs.includes('--help') || serveArgs.includes('-h') || serveArgs[0] === 'help') {
+    showServeHelp();
+    process.exit(0);
+  }
   const serveOptions = {};
   for (let i = 0; i < serveArgs.length; i++) {
     if (serveArgs[i] === '--agent' && serveArgs[i + 1]) {
@@ -898,16 +1310,46 @@ if (command === 'init') {
 } else if (command === 'version') {
   require('../commands/version').showVersion();
 } else if (command === 'login') {
+  const args = process.argv.slice(3);
+  if (args.includes('--help') || args.includes('-h') || args[0] === 'help') {
+    showAuthHelp('login');
+    process.exit(0);
+  }
   require('../commands/auth').loginAtris();
 } else if (command === 'logout') {
+  const args = process.argv.slice(3);
+  if (args.includes('--help') || args.includes('-h') || args[0] === 'help') {
+    showAuthHelp('logout');
+    process.exit(0);
+  }
   require('../commands/auth').logoutAtris();
 } else if (command === 'whoami') {
+  const args = process.argv.slice(3);
+  if (args.includes('--help') || args.includes('-h') || args[0] === 'help') {
+    showAuthHelp('whoami');
+    process.exit(0);
+  }
   require('../commands/auth').whoamiAtris();
 } else if (command === 'switch') {
+  const args = process.argv.slice(3);
+  if (args.includes('--help') || args.includes('-h') || args[0] === 'help') {
+    showAuthHelp('switch');
+    process.exit(0);
+  }
   require('../commands/auth').switchAccount();
 } else if (command === 'use') {
+  const args = process.argv.slice(3);
+  if (args.includes('--help') || args.includes('-h') || args[0] === 'help') {
+    showAuthHelp('use');
+    process.exit(0);
+  }
   require('../commands/auth').useAccount();
 } else if (command === 'accounts') {
+  const args = process.argv.slice(3);
+  if (args.includes('--help') || args.includes('-h') || args[0] === 'help') {
+    showAuthHelp('accounts');
+    process.exit(0);
+  }
   require('../commands/auth').accountsCmd();
 } else if (command === '_resolve') {
   // Hidden: resolve a profile name query → print exact profile name
@@ -929,7 +1371,7 @@ if (command === 'init') {
     .catch((err) => { console.error(`\n✗ Error: ${err.message || err}`); process.exit(1); });
 } else if (command === 'run') {
   const args = process.argv.slice(3);
-  if (args.includes('--help') || args.includes('-h')) {
+  if (args.includes('--help') || args.includes('-h') || args[0] === 'help') {
     console.log('');
     console.log('Usage: atris run [options]');
     console.log('');
@@ -965,7 +1407,7 @@ if (command === 'init') {
     });
 } else if (command === 'autopilot') {
   const args = process.argv.slice(3);
-  if (args.includes('--help') || args.includes('-h')) {
+  if (args.includes('--help') || args.includes('-h') || args[0] === 'help') {
     showAutopilotHelp();
     process.exit(0);
   }
@@ -1008,6 +1450,10 @@ if (command === 'init') {
     });
 } else if (command === 'next' || command === 'atris') {
   const rawArgs = process.argv.slice(3);
+  if (rawArgs.includes('--help') || rawArgs.includes('-h') || rawArgs[0] === 'help') {
+    showNextHelp(command);
+    process.exit(0);
+  }
   const userInput = rawArgs.filter((arg) => !arg.startsWith('-')).join(' ').trim();
   interactiveEntry(userInput || null)
     .then(() => process.exit(0))
@@ -1052,6 +1498,11 @@ if (command === 'init') {
       process.exit(1);
     });
 } else if (command === 'status') {
+  const args = process.argv.slice(3);
+  if (args.includes('--help') || args.includes('-h') || args[0] === 'help') {
+    showStatusHelp();
+    process.exit(0);
+  }
   let subcommand = process.argv[3];
   if (subcommand && !subcommand.startsWith('-')) {
     require('../commands/context-sync').businessStatus(subcommand)
@@ -1064,11 +1515,26 @@ if (command === 'init') {
     statusCmd(isQuick, isJson, verbose);
   }
 } else if (command === 'analytics') {
+  const args = process.argv.slice(3);
+  if (args.includes('--help') || args.includes('-h') || args[0] === 'help') {
+    showAnalyticsHelp();
+    process.exit(0);
+  }
   require('../commands/analytics').analyticsAtris();
 } else if (command === 'clean') {
+  const args = process.argv.slice(3);
+  if (args.includes('--help') || args.includes('-h')) {
+    showCleanHelp();
+    process.exit(0);
+  }
   const dryRun = process.argv.includes('--dry-run') || process.argv.includes('-n');
   require('../commands/clean').cleanAtris({ dryRun });
 } else if (command === 'verify') {
+  const args = process.argv.slice(3);
+  if (args.includes('--help') || args.includes('-h') || args[0] === 'help') {
+    showVerifyHelp();
+    process.exit(0);
+  }
   const sectionIdx = process.argv.indexOf('--section');
   if (sectionIdx > 0 && process.argv[sectionIdx + 1]) {
     const slug = process.argv[3] && !process.argv[3].startsWith('--') ? process.argv[3] : null;
@@ -1079,6 +1545,11 @@ if (command === 'init') {
   const taskId = process.argv[3] || null;
   require('../commands/verify').verifyAtris(taskId);
 } else if (command === 'release') {
+  const args = process.argv.slice(3);
+  if (args.includes('--help') || args.includes('-h') || args[0] === 'help') {
+    showReleaseHelp();
+    process.exit(0);
+  }
   const dryRun = process.argv.includes('--dry-run');
   require('../commands/release').releaseAtris({ dryRun })
     .then(() => process.exit(0))
@@ -1086,6 +1557,18 @@ if (command === 'init') {
 } else if (command === 'search') {
   const keyword = process.argv.slice(3).join(' ');
   searchJournal(keyword);
+} else if (command === 'xp') {
+  require('../commands/xp').xpCommand(...process.argv.slice(3))
+    .then(() => process.exit(0))
+    .catch((err) => { console.error(`✗ Error: ${err.message || err}`); process.exit(1); });
+} else if (command === 'play') {
+  require('../commands/play').playCommand(...process.argv.slice(3))
+    .then(() => process.exit(0))
+    .catch((err) => { console.error(`✗ Error: ${err.message || err}`); process.exit(1); });
+} else if (command === 'gm') {
+  require('../commands/gm').gmCommand(...process.argv.slice(3))
+    .then(() => process.exit(0))
+    .catch((err) => { console.error(`✗ Error: ${err.message || err}`); process.exit(1); });
 } else if (command === 'gmail') {
   const { gmailCommand } = require('../commands/integrations');
   const subcommand = process.argv[3];
@@ -1122,6 +1605,11 @@ if (command === 'init') {
     .then(() => process.exit(0))
     .catch((err) => { console.error(`✗ Error: ${err.message || err}`); process.exit(1); });
 } else if (command === 'integrations') {
+  const args = process.argv.slice(3);
+  if (args.includes('--help') || args.includes('-h') || args[0] === 'help') {
+    showIntegrationsHelp();
+    process.exit(0);
+  }
   const { integrationsStatus } = require('../commands/integrations');
   integrationsStatus()
     .then(() => process.exit(0))
@@ -1130,6 +1618,10 @@ if (command === 'init') {
   const subcommand = process.argv[3];
   const args = process.argv.slice(4);
   require('../commands/learn')(subcommand, ...args);
+} else if (command === 'lesson') {
+  const subcommand = process.argv[3];
+  const args = process.argv.slice(4);
+  require('../commands/lesson')(subcommand, ...args);
 } else if (command === 'skill') {
   const subcommand = process.argv[3];
   const args = process.argv.slice(4);
@@ -1162,13 +1654,28 @@ if (command === 'init') {
   require('../commands/terminal').terminalAtris()
     .then(() => process.exit(0))
     .catch((err) => { console.error(`\n✗ Error: ${err.message || err}`); process.exit(1); });
+} else if (command === 'x') {
+  // Fast Agent SDK execution - like "atris x echo hello" or "atris x ls -la"
+  const userInput = process.argv.slice(3).join(' ').trim();
+  if (!userInput) {
+    console.log('Usage: atris x <command>');
+    console.log('Example: atris x echo "hello world"');
+    console.log('Example: atris x ls -la');
+    process.exit(1);
+  }
+  require('../commands/workflow').executeAgentSDKFast(userInput);
 } else if (command === 'computer') {
   require('../commands/computer').runComputer()
     .then(() => process.exit(0))
     .catch((err) => { console.error(`\n✗ Error: ${err.message || err}`); process.exit(1); });
 } else if (command === 'diff') {
   let diffSlug = process.argv[3];
+  if (diffSlug === '-h' || diffSlug === '--help') {
+    console.log('Usage: atris diff [business] [path]');
+    process.exit(0);
+  }
   if (!diffSlug || diffSlug.startsWith('-')) {
+    diffSlug = undefined;
     const bizFile = require('path').join(process.cwd(), '.atris', 'business.json');
     if (require('fs').existsSync(bizFile)) {
       try { diffSlug = JSON.parse(require('fs').readFileSync(bizFile, 'utf8')).slug; } catch {}
@@ -1210,6 +1717,10 @@ if (command === 'init') {
     .catch((err) => { console.error(`\n✗ Error: ${err.message || err}`); process.exit(1); });
 } else if (command === 'loop') {
   const args = process.argv.slice(3);
+  if (args.includes('--help') || args.includes('-h') || args[0] === 'help') {
+    showLoopHelp();
+    process.exit(0);
+  }
   require('../commands/loop').loopAtris(args)
     .then(() => process.exit(0))
     .catch((err) => { console.error(`\n✗ Error: ${err.message || err}`); process.exit(1); });
@@ -1231,6 +1742,11 @@ if (command === 'init') {
   const args = process.argv.slice(4);
   require('../commands/proof').proofCommand(subcommand, ...args);
 } else if (command === 'setup') {
+  const args = process.argv.slice(3);
+  if (args.includes('--help') || args.includes('-h') || args[0] === 'help') {
+    showSetupHelp();
+    process.exit(0);
+  }
   require('../commands/setup').setupAtris()
     .then(() => process.exit(0))
     .catch((err) => { console.error(`\n✗ Error: ${err.message || err}`); process.exit(1); });
@@ -1276,6 +1792,11 @@ async function upgradeAtris() {
   console.log('');
   console.log(`Current version: ${CLI_VERSION}`);
   console.log('');
+  const installWarning = formatInstallGitWarning(inspectInstallGitState(path.join(__dirname, '..')));
+  if (installWarning) {
+    console.log(installWarning);
+    console.log('');
+  }
   console.log('Checking for updates...');
 
   // Force check npm for latest version
@@ -1331,7 +1852,112 @@ function showVersion() {
 // Agent Selection
 // ============================================
 
+function fileContains(relPath, pattern) {
+  try {
+    const fullPath = path.join(process.cwd(), relPath);
+    if (!fs.existsSync(fullPath)) return false;
+    const text = fs.readFileSync(fullPath, 'utf8');
+    return pattern instanceof RegExp ? pattern.test(text) : text.includes(pattern);
+  } catch {
+    return false;
+  }
+}
+
+function commandOnPath(name) {
+  const result = spawnSync('which', [name], { encoding: 'utf8', timeout: 1000 });
+  return result.status === 0 ? result.stdout.trim() : null;
+}
+
+function inspectAgentCliWiring() {
+  const checks = [
+    {
+      id: 'atris-core',
+      label: 'Atris core',
+      ok: fs.existsSync(path.join(process.cwd(), 'atris', 'MAP.md'))
+        && fs.existsSync(path.join(process.cwd(), 'atris', 'TODO.md')),
+      fix: 'Run `atris init` from the workspace root.',
+    },
+    {
+      id: 'codex',
+      label: 'Codex / OpenAI agents',
+      ok: fileContains('AGENTS.md', /atris\/MAP\.md|atris atris\.md|atris task/),
+      fix: 'Add AGENTS.md with Atris boot, MAP, and task instructions.',
+    },
+    {
+      id: 'claude',
+      label: 'Claude Code',
+      ok: fileContains('.claude/commands/atris.md', /atris|AGENTS\.md/)
+        || fileContains('.claude/settings.json', /atris atris\.md|atris\/skills/)
+        || fileContains('CLAUDE.md', /Atris|atris/),
+      fix: 'Run `atris init` to create .claude commands/settings.',
+    },
+    {
+      id: 'cursor',
+      label: 'Cursor',
+      ok: fileContains('.cursor/rules/atris.mdc', /atris\/MAP\.md|AGENTS\.md|atris task/)
+        || fileContains('.cursorrules', /atris\/MAP\.md|AGENTS\.md|atris task/)
+        || fileContains('.cursor/commands/atris.md', /atris\/MAP\.md|atris\.md/),
+      fix: 'Run `atris init` to create Cursor rules, or add .cursor/commands/atris.md.',
+    },
+    {
+      id: 'devin',
+      label: 'Devin',
+      ok: fileContains('.devin/config.local.json', /Exec\(atris\)/),
+      fix: 'Run `atris init` or add .devin/config.local.json allowing Exec(atris).',
+    },
+  ];
+
+  const binaries = ['atris', 'claude', 'codex', 'cursor-agent', 'devin'].map((name) => ({
+    name,
+    path: commandOnPath(name),
+  }));
+  return { checks, binaries };
+}
+
+function agentDoctor() {
+  const args = process.argv.slice(4);
+  const json = args.includes('--json');
+  const { checks, binaries } = inspectAgentCliWiring();
+  const ok = checks.every((check) => check.ok);
+  const payload = { ok, action: 'agent_doctor', checks, binaries };
+
+  if (json) {
+    console.log(JSON.stringify(payload, null, 2));
+    process.exit(ok ? 0 : 1);
+  }
+
+  console.log('Atris agent CLI doctor');
+  console.log('');
+  for (const check of checks) {
+    console.log(`${check.ok ? '✓' : '✗'} ${check.label}`);
+    if (!check.ok) console.log(`  fix: ${check.fix}`);
+  }
+  console.log('');
+  console.log('Local binaries');
+  for (const binary of binaries) {
+    console.log(`${binary.path ? '✓' : '·'} ${binary.name}${binary.path ? ` -> ${binary.path}` : ' not on PATH'}`);
+  }
+  process.exit(ok ? 0 : 1);
+}
+
 async function agentAtris() {
+  // Respect -h / --help / help before any auth/state work
+  const firstArg = process.argv[3];
+  if (firstArg === '-h' || firstArg === '--help' || firstArg === 'help') {
+    console.log('Usage: atris agent [doctor]');
+    console.log('');
+    console.log('  Pick which cloud agent to chat with from this workspace.');
+    console.log('  Run `atris agent doctor` to verify local AI CLIs can see Atris context.');
+    console.log('  Requires `atris login` first.');
+    console.log('');
+    console.log('  After selecting, use: atris chat ["message"]');
+    process.exit(0);
+  }
+
+  if (firstArg === 'doctor') {
+    agentDoctor();
+  }
+
   const targetDir = path.join(process.cwd(), 'atris');
 
   // Check if atris/ folder exists
@@ -1423,6 +2049,18 @@ async function chatAtris() {
   // Get message from command line args
   const message = process.argv.slice(3).join(' ').trim();
 
+  // Respect -h / --help before any auth/state checks
+  if (message === '-h' || message === '--help' || message === 'help') {
+    console.log('Usage: atris chat ["message"]');
+    console.log('');
+    console.log('  Open an interactive session with the selected agent, or send a one-shot message.');
+    console.log('  Requires `atris login` and `atris agent` to be run first.');
+    console.log('');
+    console.log('  atris chat                  Interactive REPL with selected agent');
+    console.log('  atris chat "what now?"      One-shot message');
+    process.exit(0);
+  }
+
   // Check atris/ exists
   const targetDir = path.join(process.cwd(), 'atris');
   if (!fs.existsSync(targetDir)) {