atris 3.34.0 → 3.35.0

package/bin/atris.js

@@ -29,7 +29,6 @@ try {
 const {
   checkForUpdates,
   showUpdateNotification,
-  autoUpdate,
   inspectInstallGitState,
   formatInstallGitWarning,
 } = require('../utils/update-check');
@@ -91,14 +90,10 @@ const skipUpdateCheck = Boolean(process.env.ATRIS_SKIP_UPDATE_CHECK || process.e
 if (!skipUpdateCheck && (!updateCommand || (updateCommand && !['version', 'update'].includes(updateCommand)))) {
   updateCheckPromise = checkForUpdates()
     .then((updateInfo) => {
-      // Show notification if update available (after command completes)
       if (updateInfo) {
-        const autoUpdateStarted = autoUpdate(updateInfo, {
+        showUpdateNotification(updateInfo, {
           packageRoot: path.join(__dirname, '..'),
         });
-        if (!autoUpdateStarted) {
-          showUpdateNotification(updateInfo);
-        }
       }
       return updateInfo;
     })
@@ -469,8 +464,8 @@ function showHelp() {
   console.log('  3. Atris acts with context, memory, tools, and a review loop');
   console.log('');
   console.log('Common invocations:');
-  console.log('  atris init                Global install: initialize this project');
-  console.log('  npx atris init            Local install: initialize this project');
+  console.log('  atris init [--yes]        Global install: initialize this project');
+  console.log('  npx atris init [--yes]    Local install: initialize this project');
   console.log('  atris computer');
   console.log('  atris business init "My Company"');
   console.log('  atris run');
@@ -487,7 +482,7 @@ function showHelp() {
   console.log('');
   console.log('Setup:');
   console.log('  setup      - Guided first-time setup (login, pick business, pull)');
-  console.log('  init       - Initialize Atris in current project');
+  console.log('  init       - Initialize Atris in current project (--yes skips prompts)');
   console.log('  update     - Update local files to latest version');
   console.log('  upgrade    - Install latest Atris from npm');
   console.log('');
@@ -517,6 +512,12 @@ function showHelp() {
   console.log('  harvest    - Find bugs and next actions from receipts, run logs, and thinking');
   console.log('  verify     - Validate work is done (tests, MAP.md, changes)');
   console.log('  task       - Local agent task plane (atomic claims, TODO import)');
+  console.log('  golden path (zero human turns):');
+  console.log('    atris task delegate "fix the login bug" --to <member>');
+  console.log('    atris task claim <id> --as <member>');
+  console.log('    ... build ...');
+  console.log('    atris task ready <id> --verify');
+  console.log('    atris autoland tick   # second check runs, task lands');
   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)');
@@ -526,6 +527,7 @@ function showHelp() {
   console.log('  query      - Local-first wiki query against atris/wiki/');
   console.log('  lint       - Local-first wiki lint for atris/wiki/');
   console.log('  loop       - Local wiki upkeep loop (stale pages, orphans, next ingest)');
+  console.log('  write      - Guided writing sessions: you write every word, atris structures + reviews');
   console.log('');
   console.log('Optional helpers:');
   console.log('  brainstorm - Explore ideas conversationally before planning');
@@ -533,8 +535,9 @@ function showHelp() {
   console.log('  improve    - Run one paid RL tick (POST /api/improve, deducts credits)');
   console.log('  worktree   - Isolated Git worktrees plus guarded ship/merge for parallel agents');
   console.log('  land       - The landing: what is actually done vs still in the air; --reap backs up + clears overdue');
+  console.log('  drive      - One self-driving tick: mission doctor -> auto-fix -> count disengagements');
   console.log('  autoland   - Approve the policy once; certified work lands itself, you keep irreversible calls');
-  console.log('  engine     - Bring any intelligence: roster of installed coding CLIs, default engine, --engine per run, `engine test` preflight');
+  console.log('  engine     - Bring any intelligence: roster of installed coding CLIs, default engine, --engine per run, `engine test` preflight, `engine dispatch <task-id> --engine <name>` one-command claim/build/verify/ship');
   console.log('  sign       - Co-author trailer on every commit in an atris workspace (on/off/status)');
   console.log('  visualize  - Generate a Slack/deck-ready visual from a prompt');
   console.log('  youtube    - Process YouTube videos with timestamped transcript-first analysis');
@@ -606,6 +609,11 @@ function showHelp() {
   console.log('  accounts   - Manage accounts (list, add, remove)');
   console.log('');
   console.log('Integrations:');
+  console.log('  github    - github cli wrapper (doctor, auth, pr list/create/checks/view)');
+  console.log('  vercel    - vercel cli wrapper (doctor, auth, deploy/ls/logs/inspect)');
+  console.log('  supabase  - supabase cli wrapper (doctor, auth, status/db/functions)');
+  console.log('  linear    - linear cli wrapper (doctor, auth, issue list/create/view/update)');
+  console.log('  stripe    - stripe cli wrapper (doctor, auth, listen/trigger/products)');
   console.log('  gmail      - Email commands (inbox, read, archive)');
   console.log('  calendar   - Calendar commands (today, week)');
   console.log('  twitter    - Twitter commands (post)');
@@ -766,7 +774,8 @@ function showVerifyHelp() {
 
 function showUpdateHelp(commandName = 'update') {
   console.log('');
-  console.log(`Usage: atris ${commandName} [--all] [--dry-run] [--force]`);
+  const selfFlag = commandName === 'update' ? ' [--self]' : '';
+  console.log(`Usage: atris ${commandName} [--all] [--dry-run] [--force]${selfFlag}`);
   console.log('');
   console.log('Description:');
   console.log('  Sync Atris workspace files from the installed CLI templates.');
@@ -775,6 +784,9 @@ function showUpdateHelp(commandName = 'update') {
   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.');
+  if (commandName === 'update') {
+    console.log('  --self       Update the installed atris cli from npm (packaged installs only).');
+  }
   console.log('  --help, -h       Show this help.');
   console.log('');
 }
@@ -974,9 +986,9 @@ if (command === '2' && ['fast', 'pro'].includes(String(firstCommandArg || '').to
 const knownCommands = ['init', 'log', 'now', 'radar', 'ctop', 'launchpad', 'status', 'analytics', 'visualize', 'brain', 'brainstorm', 'autopilot', 'run', '_start', 'plan', 'do', 'review', 'release',
                        'activate', '_activate', 'agent', 'chat', 'fast', 'ax', 'console', 'serve', 'login', 'logout', 'whoami', 'switch', 'use', 'accounts', '_resolve', '_profile-email', '_switch-session', 'shell-init', 'update', 'upgrade', 'version', 'help', 'next', 'atris',
                        'clean', 'harvest', 'verify', 'search', 'skill', 'member', 'codex-goal', 'app', 'apps', 'learn', 'lesson', 'plugin', 'experiments', 'receipt', 'proof', 'openclaw', 'pull', 'push', 'live', 'align', 'terminal', 'computer', 'diff', 'business', 'sync', 'youtube',
-                       'ingest', 'query', 'lint', 'loop', 'pulse', 'task', 'mission', 'probe', 'worktree', 'land', 'autoland', 'aeo', 'slop', 'strings', 'security-review', 'secure', 'deck', 'site', 'theme', 'card', 'reel', 'improve', 'xp', 'play', 'gm', 'x', 'recap', 'signup', 'clarity', 'moves',
-                       'gmail', 'calendar', 'twitter', 'slack', 'imessage', 'integrations', 'setup', 'clean-workspace', 'cw',
-                       'fork', 'browse', 'publish', 'sleep', 'wake', 'feedback', 'errors', 'wiki', 'code-review', 'cr', 'soul', 'fleet', 'loops', 'compile', 'spaceship', 'truth', 'sign', 'engine', 'engines'];
+                       'ingest', 'query', 'lint', 'loop', 'pulse', 'task', 'mission', 'probe', 'worktree', 'land', 'autoland', 'drive', 'aeo', 'slop', 'strings', 'write', 'security-review', 'secure', 'deck', 'site', 'theme', 'card', 'reel', 'improve', 'xp', 'play', 'gm', 'x', 'recap', 'signup', 'clarity', 'interview', 'moves', 'unknowns',
+                       'github', 'vercel', 'supabase', 'linear', 'stripe', 'gmail', 'calendar', 'twitter', 'slack', 'imessage', 'integrations', 'setup', 'clean-workspace', 'cw',
+                       'fork', 'browse', 'publish', 'sleep', 'wake', 'feedback', 'errors', 'wiki', 'code-review', 'cr', 'soul', 'fleet', 'loops', 'compile', 'spaceship', 'truth', 'sign', 'engine', 'engines', 'feed'];
 
 // Check if command is an atris.md spec file - triggers welcome visualization
 function isSpecFile(cmd) {
@@ -1086,6 +1098,19 @@ function printAtrisOverview() {
   console.log('');
 }
 
+function useInteractiveAtrisUi() {
+  return Boolean(process.stdin.isTTY && process.stdout.isTTY && !process.env.ATRIS_NO_INTERACTIVE);
+}
+
+function initNonInteractiveFlag() {
+  const args = process.argv.slice(2);
+  return args.includes('--yes') || args.includes('-y');
+}
+
+function shouldSkipContextGatherer() {
+  return !useInteractiveAtrisUi() || initNonInteractiveFlag();
+}
+
 async function interactiveEntry(userInput) {
   const workspaceDir = process.cwd();
   const state = detectWorkspaceState(workspaceDir);
@@ -1174,33 +1199,62 @@ async function interactiveEntry(userInput) {
     backlogCount,
     inboxCount,
   })) {
-    const answer = String(userInput || '').trim() || await askContextGatherer(workspaceDir);
-    if (isAtrisMetaQuestion(answer)) {
-      printAtrisOverview();
-      return;
-    }
-    if (!answer.trim()) {
+    const hotAnswer = String(userInput || '').trim();
+    if (hotAnswer) {
+      const answer = hotAnswer;
+      if (isAtrisMetaQuestion(answer)) {
+        printAtrisOverview();
+        return;
+      }
+      const profile = saveContextProfile(workspaceDir, answer, { source: 'hot_start' });
+      const starter = createStarterTask(workspaceDir, answer);
       console.log('');
-      console.log('No problem. When you are ready, answer in normal words.');
-      console.log('Example: "help me organize college applications" or "help me build a small website".');
+      console.log('Got it. I saved your first direction.');
+      console.log(`Focus: ${profile.first_answer}`);
+      if (starter && starter.display_id) {
+        console.log(`First task: ${starter.display_id} — ${starter.title}`);
+      } else if (starter && starter.title) {
+        console.log(`First task: ${starter.title}`);
+      }
+      if (mapStatus !== 'ready') {
+        printMapBootstrap({ userInput: answer, prefix: 'Next setup step' });
+        return;
+      }
+      await planCmd(answer);
       return;
     }
-    const profile = saveContextProfile(workspaceDir, answer, { source: userInput ? 'hot_start' : 'cold_start' });
-    const starter = createStarterTask(workspaceDir, answer);
-    console.log('');
-    console.log('Got it. I saved your first direction.');
-    console.log(`Focus: ${profile.first_answer}`);
-    if (starter && starter.display_id) {
-      console.log(`First task: ${starter.display_id} — ${starter.title}`);
-    } else if (starter && starter.title) {
-      console.log(`First task: ${starter.title}`);
-    }
-    if (mapStatus !== 'ready') {
-      printMapBootstrap({ userInput: answer, prefix: 'Next setup step' });
+    if (shouldSkipContextGatherer()) {
+      console.log('');
+      console.log("context gatherer skipped (non-interactive). run 'atris plan' when you're ready.");
+    } else {
+      const answer = await askContextGatherer(workspaceDir);
+      if (isAtrisMetaQuestion(answer)) {
+        printAtrisOverview();
+        return;
+      }
+      if (!answer.trim()) {
+        console.log('');
+        console.log('No problem. When you are ready, answer in normal words.');
+        console.log('Example: "help me organize college applications" or "help me build a small website".');
+        return;
+      }
+      const profile = saveContextProfile(workspaceDir, answer, { source: 'cold_start' });
+      const starter = createStarterTask(workspaceDir, answer);
+      console.log('');
+      console.log('Got it. I saved your first direction.');
+      console.log(`Focus: ${profile.first_answer}`);
+      if (starter && starter.display_id) {
+        console.log(`First task: ${starter.display_id} — ${starter.title}`);
+      } else if (starter && starter.title) {
+        console.log(`First task: ${starter.title}`);
+      }
+      if (mapStatus !== 'ready') {
+        printMapBootstrap({ userInput: answer, prefix: 'Next setup step' });
+        return;
+      }
+      await planCmd(answer);
       return;
     }
-    await planCmd(answer);
-    return;
   }
 
   if (mapStatus !== 'ready') {
@@ -1436,6 +1490,44 @@ function showWelcomeVisualization() {
       const landText = `${landInfo.branches} in the air, ${landInfo.due} overdue`;
       console.log(`    │   🛬 Land:    ${landText.padEnd(26)}│`);
     }
+    let rotInfo = null;
+    try {
+      const { parseLessons } = require('../lib/memory-view');
+      const resolved = path.resolve(cwd);
+      const parent = path.dirname(resolved);
+      const grandparent = path.dirname(parent);
+      let worktreeDir;
+      if (path.basename(grandparent) === '.agent-worktrees') {
+        worktreeDir = parent;
+      } else {
+        worktreeDir = path.join(path.dirname(resolved), '.agent-worktrees', path.basename(resolved));
+      }
+      let worktrees = 0;
+      if (fs.existsSync(worktreeDir)) {
+        worktrees = fs.readdirSync(worktreeDir, { withFileTypes: true })
+          .filter((entry) => entry.isDirectory()).length;
+      }
+      let lessonsText = '';
+      try {
+        lessonsText = fs.readFileSync(path.join(atrisDir, 'lessons.md'), 'utf8');
+      } catch (err) {
+        lessonsText = '';
+      }
+      // rot = fail lessons nobody has resolved. A `pass` lesson is knowledge
+      // that worked — it has nothing to resolve and counting it guilt-trips
+      // the operator with a number (600+) no one can ever drive to zero.
+      const unresolvedLessons = parseLessons(lessonsText)
+        .filter((lesson) => lesson.status === 'fail' && !lesson.resolved && !/\[resolved\]/i.test(lesson.text)).length;
+      if (worktrees > 0 || unresolvedLessons > 0) {
+        rotInfo = { worktrees, lessons: unresolvedLessons };
+      }
+    } catch (err) {
+      rotInfo = null;
+    }
+    if (rotInfo) {
+      const rotText = `${rotInfo.worktrees} stale worktree${rotInfo.worktrees === 1 ? '' : 's'}, ${rotInfo.lessons} unresolved lesson${rotInfo.lessons === 1 ? '' : 's'}`;
+      console.log(`    │   🧹 rot:      ${rotText.padEnd(26)}│`);
+    }
     console.log(`    │   📝 Journal: ${(journalEntries + ' entries today').padEnd(26)}│`);
     if (endgameState.slug !== 'unset' && endgameState.horizon) {
       const endgameLine = endgameState.slug + ' — ' + endgameState.horizon;
@@ -1550,6 +1642,11 @@ if (command === 'init') {
   Promise.resolve(require('../commands/land').landCommand(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 === 'drive') {
+  // Drive: one self-driving tick — mission doctor -> auto-fix safe findings -> count disengagements.
+  Promise.resolve(require('../commands/drive').driveCommand(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 === 'radar' || command === 'ctop') {
   const radarArgs = command === 'ctop' ? ['--agents', ...process.argv.slice(3)] : process.argv.slice(3);
   Promise.resolve(require('../commands/radar').radarCommand(radarArgs))
@@ -1643,6 +1740,11 @@ if (command === 'init') {
     showUpdateHelp(command);
     process.exit(0);
   }
+  if (command === 'update' && args.includes('--self')) {
+    const { updateSelf } = require('../commands/update');
+    const result = updateSelf({ packageRoot: path.join(__dirname, '..') });
+    process.exit(result.ok ? 0 : 1);
+  }
   if (isBusinessSync) {
     Promise.resolve(require('../commands/business-sync').businessSync(process.argv.slice(3)))
       .then(() => process.exit(0))
@@ -2126,6 +2228,21 @@ if (command === 'init') {
   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 === 'github') {
+  const status = require('../commands/github').githubCommand(process.argv.slice(3));
+  process.exit(status);
+} else if (command === 'vercel') {
+  const status = require('../commands/vercel').vercelCommand(process.argv.slice(3));
+  process.exit(status);
+} else if (command === 'supabase') {
+  const status = require('../commands/supabase').supabaseCommand(process.argv.slice(3));
+  process.exit(status);
+} else if (command === 'linear') {
+  const status = require('../commands/linear').linearCommand(process.argv.slice(3));
+  process.exit(status);
+} else if (command === 'stripe') {
+  const status = require('../commands/stripe').stripeCommand(process.argv.slice(3));
+  process.exit(status);
 } else if (command === 'gmail') {
   const { gmailCommand } = require('../commands/integrations');
   const subcommand = process.argv[3];
@@ -2326,10 +2443,13 @@ if (command === 'init') {
 } else if (command === 'engine' || command === 'engines') {
   // Engine: bring any intelligence — roster of installed coding CLIs, default
   // engine per workspace, --engine <name> rides any loop for one run.
-  try {
-    const engineArgs = command === 'engines' && process.argv.length <= 3 ? [] : process.argv.slice(3);
-    process.exit(require('../commands/engine').engineCommand(engineArgs) || 0);
-  } catch (err) { console.error(`\n✗ Error: ${err.message || err}`); process.exit(1); }
+  // `engine dispatch` runs an async claim -> build -> ship flight, so the
+  // return value may be a promise or a plain number; Promise.resolve handles
+  // both (mirrors the `compile` command dispatch just above).
+  const engineArgs = command === 'engines' && process.argv.length <= 3 ? [] : process.argv.slice(3);
+  Promise.resolve(require('../commands/engine').engineCommand(engineArgs))
+    .then((code) => process.exit(typeof code === 'number' ? code : 0))
+    .catch((err) => { console.error(`\n✗ Error: ${err.message || err}`); process.exit(1); });
 } else if (command === 'sign') {
   // Sign: prepare-commit-msg hook that credits Atris as co-author on commits in atris workspaces.
   try { process.exit(require('../commands/sign').signCommand(process.argv[3]) || 0); }
@@ -2339,6 +2459,11 @@ if (command === 'init') {
   Promise.resolve(require('../commands/slop').slopCommand(process.argv.slice(3)))
     .then((code) => process.exit(typeof code === 'number' ? code : 0))
     .catch((err) => { console.error(`\n✗ Error: ${err.message || err}`); process.exit(1); });
+} else if (command === 'write') {
+  // Write: guided writing sessions — human types every word, atris structures + reviews (plan-do-review for prose).
+  Promise.resolve(require('../commands/write').writeCommand(process.argv.slice(3)))
+    .then((code) => process.exit(typeof code === 'number' ? code : 0))
+    .catch((err) => { console.error(`\n✗ Error: ${err.message || err}`); process.exit(1); });
 } else if (command === 'strings') {
   // Strings: content design system from live code (no LLM). Extracts UI strings, flags variants,
   // enforces preferred terms at the gate. Exit 1 = variants/banned terms found, for CI + the gate.
@@ -2361,11 +2486,27 @@ if (command === 'init') {
   Promise.resolve(require('../commands/moves').movesCommand(process.argv.slice(3)))
     .then((code) => process.exit(typeof code === 'number' ? code : 0))
     .catch((err) => { console.error(`\n✗ Error: ${err.message || err}`); process.exit(1); });
+} else if (command === 'unknowns') {
+  // Unknowns: blindspot pass from local territory context into the SQLite ledger.
+  Promise.resolve(require('../commands/unknowns').unknownsCommand(process.argv.slice(3)))
+    .then((code) => process.exit(typeof code === 'number' ? code : 0))
+    .catch((err) => { console.error(`\n✗ Error: ${err.message || err}`); process.exit(1); });
+} else if (command === 'feed') {
+  // Feed: read and post the business group feed — receipts and state changes only.
+  // Sets exitCode instead of process.exit() so large --json output flushes fully.
+  Promise.resolve(require('../commands/feed').feedCommand(process.argv.slice(3)))
+    .then((code) => { process.exitCode = typeof code === 'number' ? code : 0; })
+    .catch((err) => { console.error(`\n✗ Error: ${err.message || err}`); process.exitCode = 1; });
 } else if (command === 'clarity') {
   // Clarity: interview yourself once; agents read how you work so you stop repeating it.
   Promise.resolve(require('../commands/clarity').clarityCommand(process.argv.slice(3)))
     .then((code) => process.exit(typeof code === 'number' ? code : 0))
     .catch((err) => { console.error(`\n✗ Error: ${err.message || err}`); process.exit(1); });
+} else if (command === 'interview') {
+  // Interview: the interlinked 1-on-1 — live interview that extracts judgment into a member file.
+  Promise.resolve(require('../commands/interview').interviewCommand(process.argv.slice(3)))
+    .then((code) => process.exit(typeof code === 'number' ? code : 0))
+    .catch((err) => { console.error(`\n✗ Error: ${err.message || err}`); process.exit(1); });
 } else if (command === 'deck') {
   // Deck: premium Google Slides from a plain content spec, via the Atris deck engine (anti-slop design system).
   Promise.resolve(require('../commands/deck').run(process.argv.slice(3)))
@@ -2734,8 +2875,19 @@ async function agentAtris() {
 async function chatAtris() {
   // Get message from command line args; --agent forces the legacy cloud-agent lane
   const rawArgs = process.argv.slice(3);
-  const agentLane = rawArgs.includes('--agent');
-  const message = rawArgs.filter(arg => arg !== '--agent').join(' ').trim();
+  const fastLaneFlags = [];
+  const messageArgs = [];
+  let agentLane = false;
+  for (const arg of rawArgs) {
+    if (arg === '--agent') {
+      agentLane = true;
+    } else if (arg === '--print' || arg === '--headless') {
+      fastLaneFlags.push(arg);
+    } else {
+      messageArgs.push(arg);
+    }
+  }
+  const message = messageArgs.join(' ').trim();
 
   // Respect -h / --help before any auth/state checks
   if (message === '-h' || message === '--help' || message === 'help') {
@@ -2746,6 +2898,7 @@ async function chatAtris() {
     console.log('');
     console.log('  atris chat                  Interactive chat (ax --fast --chat)');
     console.log('  atris chat "what now?"      One-shot message (ax --fast)');
+    console.log('  atris chat --print "..."    Headless JSON result (ax --fast --print)');
     console.log('  atris chat --agent [...]    Legacy cloud-agent lane (needs `atris agent`)');
     process.exit(0);
   }
@@ -2757,7 +2910,7 @@ async function chatAtris() {
     process.exit(1);
   }
 
-  const missionIntent = missionRunIntentFromFastMessage(message);
+  const missionIntent = fastLaneFlags.length ? null : missionRunIntentFromFastMessage(message);
   if (missionIntent) {
     process.exit(await runLocalFastMission(missionIntent));
   }
@@ -2770,7 +2923,7 @@ async function chatAtris() {
   if (!agentLane) {
     try {
       const axPath = path.join(__dirname, '..', 'ax');
-      const axArgs = message ? ['--fast', message] : ['--fast', '--chat'];
+      const axArgs = message || fastLaneFlags.length ? ['--fast', ...fastLaneFlags, message].filter(Boolean) : ['--fast', '--chat'];
       const run = spawnSync(process.execPath, [axPath, ...axArgs], { stdio: 'inherit' });
       process.exit(run.status || 0);
     } catch {

package/commands/aeo.js

@@ -157,6 +157,9 @@ function pickSlug(args) {
 
 function printHelp() {
   console.log('Usage:');
+  console.log('  Live scan (no login needed):');
+  console.log('    atris aeo scan <url> [--vs <competitor-url>] [--json]');
+  console.log('');
   console.log('  Backend / EC2:');
   console.log('    atris aeo init   [--workspace <slug>]');
   console.log('    atris aeo draft  "<topic>" [--workspace <slug>] [--queries q1,q2] [--slug X] [--url URL]');
@@ -178,6 +181,54 @@ function printHelp() {
   console.log('  atris aeo discover https://atris.ai/aeo --canonical-url https://atris.ai/aeo');
 }
 
+const FREE_SCAN_BASE = process.env.ATRIS_API_BASE || 'https://api.atris.ai';
+
+async function aeoScan(args) {
+  const asJson = args.includes('--json');
+  const vs = readArg(args, '--vs');
+  const url = args.filter((a) => !a.startsWith('--') && a !== vs)[0];
+  if (!url) {
+    console.error('Usage: atris aeo scan <url> [--vs <competitor-url>] [--json]');
+    process.exit(1);
+  }
+  const target = /^https?:\/\//i.test(url) ? url : `https://${url}`;
+  const qs = new URLSearchParams({ url: target });
+  if (vs) qs.set('vs', /^https?:\/\//i.test(vs) ? vs : `https://${vs}`);
+  const endpoint = `${FREE_SCAN_BASE}/api/business/aeo/free-scan?${qs}`;
+  let data;
+  try {
+    const res = await fetch(endpoint, { signal: AbortSignal.timeout(60000) });
+    if (!res.ok) {
+      const body = await res.text().catch(() => '');
+      console.error(`Scan failed (${res.status}): ${body.slice(0, 200)}`);
+      process.exit(1);
+    }
+    data = await res.json();
+  } catch (e) {
+    console.error(`Scan failed: ${e.message}`);
+    process.exit(1);
+  }
+  if (asJson) { console.log(JSON.stringify(data, null, 2)); return; }
+  console.log(`\n  ${data.name || target}`);
+  console.log(`  Score: ${data.score}/100 (${data.grade}) — ${data.status}`);
+  if (data.gap_statement) console.log(`\n  ${data.gap_statement}`);
+  const gaps = data.gaps || [];
+  if (gaps.length) {
+    console.log('\n  Gaps:');
+    for (const g of gaps) console.log(`   ✗ ${g.title || g.key}: ${g.fix || ''}`);
+  }
+  const comp = data.competitors || [];
+  if (comp.length) {
+    console.log('\n  Head-to-head:');
+    for (const c of comp) console.log(`   ${pad(String(c.score ?? '?'), 4)} ${c.url || c.name}`);
+  }
+  if (data.draft_llms_txt) {
+    console.log('\n  Draft llms.txt included — save it with:');
+    console.log(`   atris aeo scan ${url} --json | jq -r .draft_llms_txt > llms.txt`);
+  }
+  console.log('');
+}
+
 async function aeoInit(args) {
   const slug = pickSlug(args);
   if (!slug) {
@@ -545,6 +596,7 @@ async function run(args = []) {
   const sub = args[0];
   if (!sub || sub === 'help' || sub === '--help' || sub === '-h') return printHelp();
   const rest = args.slice(1);
+  if (sub === 'scan') return aeoScan(rest);
   if (sub === 'init') return aeoInit(rest);
   if (sub === 'draft') return aeoDraft(rest);
   if (sub === 'log') return aeoLog(rest);