atris 3.26.0 → 3.27.0

package/README.md

@@ -319,6 +319,8 @@ atris upgrade     # Install latest from npm
 atris update      # Sync local workspace files to new version
 ```
 
+Packaged npm installs check for new versions during normal commands and start a background update automatically. Git checkout installs stay manual so linked development copies are not overwritten unexpectedly.
+
 ---
 
 **License:** MIT | **Repo:** [github.com/atrislabs/atris](https://github.com/atrislabs/atris.git)

package/bin/atris.js

@@ -92,14 +92,10 @@ if (!skipUpdateCheck && (!updateCommand || (updateCommand && !['version', 'updat
     .then((updateInfo) => {
       // Show notification if update available (after command completes)
       if (updateInfo) {
-        // Notify only — never auto-update mid-session (opt-in via ATRIS_AUTO_UPDATE=1)
-        if (process.env.ATRIS_AUTO_UPDATE === '1') {
-          setTimeout(() => {
-            if (!autoUpdate(updateInfo)) {
-              showUpdateNotification(updateInfo);
-            }
-          }, 100);
-        } else {
+        const autoUpdateStarted = autoUpdate(updateInfo, {
+          packageRoot: path.join(__dirname, '..'),
+        });
+        if (!autoUpdateStarted) {
           showUpdateNotification(updateInfo);
         }
       }
@@ -644,6 +640,7 @@ function showUpgradeHelp() {
   console.log('');
   console.log('Description:');
   console.log('  Check npm for the latest Atris CLI and install it globally if newer.');
+  console.log('  Normal packaged installs also auto-update in the background.');
   console.log('');
   console.log('Options:');
   console.log('  --help, -h       Show this help.');
@@ -826,7 +823,7 @@ if (command === '2' && ['fast', 'pro'].includes(String(firstCommandArg || '').to
 const knownCommands = ['init', 'log', 'now', 'radar', 'ctop', 'status', 'analytics', 'visualize', 'brain', 'brainstorm', 'autopilot', 'run', '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', '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', 'aeo', 'slop', 'deck', 'site', 'theme', 'card', 'reel', 'improve', 'xp', 'play', 'gm', 'x', 'recap',
+                       'ingest', 'query', 'lint', 'loop', 'pulse', 'task', 'mission', 'probe', 'worktree', 'aeo', 'slop', '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', 'compile', 'spaceship'];
 
@@ -2089,6 +2086,22 @@ if (command === 'init') {
   Promise.resolve(require('../commands/reel').run(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 === 'signup') {
+  // Signup: one-call seedless agent signup (POST /auth/agent/signup) → writes the
+  // active profile so `atris play` works next. The install→signup→play seam.
+  Promise.resolve(require('../commands/signup').signupCommand(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 === 'moves') {
+  // Moves: your 3 next moves — approve one into the loop, kill, or skip.
+  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 === '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 === 'receipt' || command === 'proof' || command === 'openclaw') {
   const subcommand = process.argv[3];
   const args = process.argv.slice(4);
@@ -2167,8 +2180,8 @@ async function upgradeAtris() {
   console.log('Installing update...');
   console.log('');
 
-  // Run npm update -g atris
-  const result = spawnSync('npm', ['update', '-g', 'atris'], {
+  // Run npm install -g atris@latest
+  const result = spawnSync('npm', ['install', '-g', 'atris@latest'], {
     stdio: 'inherit',
     shell: true
   });
@@ -2182,10 +2195,10 @@ async function upgradeAtris() {
   } else {
     console.log('');
     console.log('✗ Upgrade failed. Try running manually:');
-    console.log('  npm update -g atris');
+    console.log('  npm install -g atris@latest');
     console.log('');
     console.log('If you see permission errors, try:');
-    console.log('  sudo npm update -g atris');
+    console.log('  sudo npm install -g atris@latest');
     console.log('');
   }
 }

package/commands/activate.js

@@ -158,6 +158,30 @@ function activateAtris() {
     wikiStatus.bullets.forEach((line) => console.log(`- ${line.replace(/^- /, '')}`));
   }
   console.log('');
+  try {
+    const { nextMoves } = require('../lib/next-moves');
+    const { readProfile, isEmptyProfile } = require('../lib/clarity');
+    const root = process.cwd();
+    const moves = nextMoves(root, 3);
+    console.log('Your next moves:');
+    if (moves.length) {
+      moves.forEach((m, i) => console.log(`  ${i + 1}. ${m.title}`));
+      console.log('  steer them: atris moves');
+    } else {
+      console.log('  none queued. add to ROADMAP.md under "## Open loop items", or jot one with atris log');
+    }
+    const profile = readProfile(root);
+    console.log('');
+    if (isEmptyProfile(profile)) {
+      console.log('Tip: run atris clarity once so agents learn how you work.');
+    } else {
+      console.log('How you work (atris clarity):');
+      ['focus', 'voice', 'cadence', 'done', 'leash']
+        .filter((k) => profile[k])
+        .forEach((k) => console.log(`  ${k}: ${profile[k]}`));
+    }
+    console.log('');
+  } catch { /* alive onboarding is best-effort; never block activate */ }
   console.log('Next: atris plan → do → review (or atris log)');
   console.log('');
 }

package/commands/clarity.js

@@ -0,0 +1,125 @@
+'use strict';
+
+// `atris clarity`: interview the operator for how they work, write it down once.
+// The interview moves one question at a time so you stay in flow. The result is
+// a durable profile (.atris/clarity.json + atris/CLARITY.md) that agents read.
+
+const readline = require('readline');
+const {
+  QUESTIONS,
+  KEYS,
+  mergeProfile,
+  isEmptyProfile,
+  renderClarityMd,
+  readProfile,
+  writeProfile,
+  profilePaths,
+} = require('../lib/clarity');
+
+function parseSets(args) {
+  const answers = {};
+  for (let i = 0; i < args.length; i++) {
+    if (args[i] === '--set' && args[i + 1]) {
+      const eq = args[i + 1].indexOf('=');
+      if (eq > 0) {
+        const key = args[i + 1].slice(0, eq).trim();
+        const val = args[i + 1].slice(eq + 1).trim();
+        if (KEYS.includes(key)) answers[key] = val;
+      }
+      i++;
+    }
+  }
+  return answers;
+}
+
+function ask(rl, question) {
+  return new Promise((resolve) => rl.question(question, (a) => resolve(a)));
+}
+
+async function clarityCommand(args = [], root = process.cwd()) {
+  const sub = args[0];
+  const stamp = new Date().toISOString();
+
+  if (args.includes('--help') || args.includes('-h') || sub === 'help') {
+    console.log('');
+    console.log('Usage: atris clarity [show|--json|--set key=value|--reset]');
+    console.log('');
+    console.log('Interview the operator for how they work, once. Agents read the result.');
+    console.log('');
+    console.log('  atris clarity                 Run the interview (one question at a time)');
+    console.log('  atris clarity show            Show the current profile');
+    console.log('  atris clarity --json          Print the profile as JSON');
+    console.log('  atris clarity --set voice=plain   Set one field without prompting');
+    console.log('  atris clarity --reset         Clear the profile');
+    console.log('');
+    console.log(`Fields: ${KEYS.join(', ')}`);
+    console.log('');
+    return 0;
+  }
+
+  if (args.includes('--reset')) {
+    writeProfile(root, { updated_at: stamp });
+    console.log('clarity profile reset.');
+    return 0;
+  }
+
+  const existing = readProfile(root);
+
+  if (args.includes('--json')) {
+    console.log(JSON.stringify(existing, null, 2));
+    return 0;
+  }
+
+  if (sub === 'show') {
+    console.log(renderClarityMd(existing));
+    return 0;
+  }
+
+  // Non-interactive set: write fields and exit.
+  const sets = parseSets(args);
+  if (Object.keys(sets).length) {
+    const merged = mergeProfile(existing, sets, stamp);
+    // Only the keys whose values actually landed (mergeProfile drops empties).
+    const changed = Object.keys(sets).filter((k) => sets[k].trim() && merged[k] === sets[k].trim());
+    if (!changed.length) {
+      console.log('nothing to set (empty value ignored). use --reset to clear all.');
+      return 0;
+    }
+    const { md } = writeProfile(root, merged);
+    console.log(`saved ${changed.join(', ')} to ${md.replace(`${root}/`, '')}`);
+    return 0;
+  }
+
+  // Interactive interview. Only on a terminal, so spawns never hang.
+  if (!process.stdin.isTTY) {
+    console.log(renderClarityMd(existing));
+    if (isEmptyProfile(existing)) {
+      console.log('Run `atris clarity` in a terminal to fill this in, or use --set key=value.');
+    }
+    return 0;
+  }
+
+  console.log('');
+  console.log('clarity interview. plain answers, one at a time. enter to keep the current value.');
+  console.log('');
+  const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+  const answers = {};
+  for (const { key, q } of QUESTIONS) {
+    const current = existing[key] ? ` [${existing[key]}]` : '';
+    // eslint-disable-next-line no-await-in-loop
+    const a = (await ask(rl, `${q}${current}\n> `)).trim();
+    if (a) answers[key] = a;
+    console.log('');
+  }
+  rl.close();
+
+  const merged = mergeProfile(existing, answers, stamp);
+  const { md } = writeProfile(root, merged);
+  console.log('clarity saved. agents will read it from:');
+  console.log(`  ${md.replace(`${root}/`, '')}`);
+  console.log('');
+  console.log(renderClarityMd(merged));
+  return 0;
+}
+
+module.exports = { clarityCommand, parseSets };

package/commands/moves.js

@@ -0,0 +1,156 @@
+'use strict';
+
+// `atris moves`: alive onboarding. Shows the 3 highest-leverage next moves and
+// lets you approve (seed it into the loop), kill (stop suggesting it), or skip.
+// This is the seed of proactiveness: the workspace proposes, you steer.
+
+const readline = require('readline');
+const {
+  nextMoves,
+  recordDecision,
+  seedInboxFromMove,
+} = require('../lib/next-moves');
+
+function currentMoves(root, limit) {
+  return nextMoves(root, limit);
+}
+
+function renderMoves(moves) {
+  if (!moves.length) {
+    return [
+      '',
+      'your next moves',
+      '',
+      '  nothing queued. add an item to ROADMAP.md under "## Open loop items",',
+      '  or jot an idea with `atris log`.',
+      '',
+    ].join('\n');
+  }
+  const lines = ['', 'your next moves', ''];
+  moves.forEach((m, i) => {
+    lines.push(`  ${i + 1}. ${m.title}`);
+    lines.push(`     why: ${m.why}   id: ${m.id}`);
+    lines.push('');
+  });
+  lines.push('  approve:  atris moves --approve <id|N>   seed it into the loop');
+  lines.push('  kill:     atris moves --kill <id|N>      stop suggesting it');
+  lines.push('  (use the id when you act later; the numbered order can shift)');
+  lines.push('');
+  return lines.join('\n');
+}
+
+function parseIndexes(value) {
+  return String(value || '')
+    .split(/[\s,]+/)
+    .map((s) => parseInt(s, 10))
+    .filter((n) => Number.isInteger(n) && n >= 1);
+}
+
+// Resolve --approve/--kill tokens to move objects. A token is either a stable
+// move id (m_...) or a 1-based position. The id is preferred because the list
+// can re-rank between viewing and acting, so a bare index can hit a different
+// move than the one you saw.
+function resolveSelection(moves, value) {
+  const tokens = String(value || '').split(/[\s,]+/).filter(Boolean);
+  const byId = new Map(moves.map((m) => [m.id, m]));
+  const seen = new Set();
+  const out = [];
+  for (const tok of tokens) {
+    let move = null;
+    if (byId.has(tok)) move = byId.get(tok);
+    else if (/^\d+$/.test(tok)) move = moves[parseInt(tok, 10) - 1];
+    if (move && !seen.has(move.id)) { seen.add(move.id); out.push(move); }
+  }
+  return out;
+}
+
+function applyDecision(root, selectedMoves, decision, stamp) {
+  const { claimRoadmapItem } = require('../lib/next-moves');
+  const acted = [];
+  for (const move of selectedMoves) {
+    recordDecision(root, move, decision, stamp);
+    if (decision === 'approve') {
+      // Seed then claim, mirroring the loop. For a roadmap-sourced move, mark it
+      // claimed in ROADMAP so the loop and the moves list agree it is handled.
+      const seeded = seedInboxFromMove(root, move);
+      if (move.source === 'roadmap') claimRoadmapItem(root, move.title);
+      acted.push({ move, seeded });
+    } else {
+      acted.push({ move });
+    }
+  }
+  return acted;
+}
+
+function readArgValue(args, name) {
+  const i = args.indexOf(name);
+  if (i === -1) return null;
+  return args[i + 1] || '';
+}
+
+async function movesCommand(args = [], root = process.cwd()) {
+  if (args.includes('--help') || args.includes('-h') || args[0] === 'help') {
+    console.log('');
+    console.log('Usage: atris moves [--approve <id|N>] [--kill <id|N>] [--json] [--limit N]');
+    console.log('');
+    console.log('Show the next moves and steer them. Each move has a stable id; prefer it');
+    console.log('over the position number, which can shift between viewing and acting.');
+    console.log('');
+    console.log('  atris moves                  Show the 3 next moves (prompts on a terminal)');
+    console.log('  atris moves --approve <id|N> Seed that move into the loop (writes the inbox)');
+    console.log('  atris moves --kill <id|N>    Stop suggesting that move');
+    console.log('  atris moves --json           Print the moves (with ids) as JSON, no prompt');
+    console.log('  atris moves --limit N        Show N moves (default 3)');
+    console.log('');
+    return 0;
+  }
+
+  const limitArg = readArgValue(args, '--limit');
+  const limit = limitArg && !Number.isNaN(parseInt(limitArg, 10)) ? Math.max(1, parseInt(limitArg, 10)) : 3;
+  const stamp = new Date().toISOString();
+
+  const approveVal = readArgValue(args, '--approve');
+  const killVal = readArgValue(args, '--kill');
+
+  if (approveVal !== null || killVal !== null) {
+    const moves = currentMoves(root, limit);
+    const killed = applyDecision(root, resolveSelection(moves, killVal), 'kill', stamp);
+    const approved = applyDecision(root, resolveSelection(moves, approveVal), 'approve', stamp);
+    for (const a of approved) {
+      const note = a.seeded && a.seeded.alreadyPresent ? 'already in the inbox' : 'seeded into the loop';
+      console.log(`approved: ${a.move.title}  ->  ${note}`);
+    }
+    for (const k of killed) console.log(`killed: ${k.move.title}  ->  will not suggest again`);
+    if (!approved.length && !killed.length) console.log('no matching move for that id or number.');
+    return 0;
+  }
+
+  const moves = currentMoves(root, limit);
+
+  if (args.includes('--json')) {
+    console.log(JSON.stringify({ moves }, null, 2));
+    return 0;
+  }
+
+  console.log(renderMoves(moves));
+
+  // Only prompt on a real terminal, so spawned/non-interactive runs never hang.
+  if (!process.stdin.isTTY || !moves.length) return 0;
+
+  const answer = await new Promise((resolve) => {
+    const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+    rl.question('approve N, kill kN, or enter to skip: ', (a) => { rl.close(); resolve(a.trim()); });
+  });
+  if (!answer) return 0;
+
+  const killTokens = (answer.match(/k\s*\d+/gi) || []).map((t) => t.replace(/k/i, '').trim());
+  const approveTokens = answer.replace(/k\s*\d+/gi, '').trim();
+
+  const killed = applyDecision(root, resolveSelection(moves, killTokens.join(' ')), 'kill', stamp);
+  const approved = applyDecision(root, resolveSelection(moves, approveTokens), 'approve', stamp);
+  for (const a of approved) console.log(`approved: ${a.move.title}  ->  seeded into the loop`);
+  for (const k of killed) console.log(`killed: ${k.move.title}`);
+  return 0;
+}
+
+module.exports = { movesCommand, renderMoves, currentMoves, parseIndexes, resolveSelection };

package/commands/signup.js

@@ -0,0 +1,101 @@
+// atris signup <handle>
+//
+// One-call seedless agent signup. A brand-new agent with no account hits
+// POST /api/auth/agent/signup (unauthenticated) and gets back a real, INERT
+// Atris identity + token, then we write the active profile so `atris play`
+// works on the very next command. This closes the install -> signup -> play
+// seam: `npm i -g atris && atris signup x && atris play`.
+//
+// The account is born inert by design (0 credits, no executing agent, external
+// mail paid-gated) — identity is free, capability is earned via AgentXP.
+// Backend: backend/routers/agent_auth_router.py (POST /auth/agent/signup).
+
+const crypto = require('crypto');
+const { apiRequestJson, getApiBaseUrl } = require('../utils/api');
+const { saveCredentials } = require('../utils/auth');
+
+// Mirror the server rule exactly (^[a-z0-9]{3,30}$) so we fail fast and friendly
+// before spending a network round trip / a rate-limit slot.
+const HANDLE_RE = /^[a-z0-9]{3,30}$/;
+
+// Proof-of-work — mirror the server (agent_auth_router.py). The signup endpoint
+// requires a nonce whose sha256(prefix:handle:bucket:nonce) has DIFFICULTY_BITS
+// leading zero bits. Bucket = current 5-min window. Solved locally (~1s) so
+// signup stays a single call; this is the cost that makes mass-minting expensive.
+const POW_PREFIX = 'atris-signup-v1';
+const POW_WINDOW_S = 300;
+const POW_DIFFICULTY_BITS = 20;
+
+function solvePow(handle) {
+  const bucket = Math.floor(Date.now() / 1000 / POW_WINDOW_S);
+  const fullBytes = Math.floor(POW_DIFFICULTY_BITS / 8);
+  const remBits = POW_DIFFICULTY_BITS % 8;
+  for (let n = 0; ; n++) {
+    const d = crypto.createHash('sha256').update(`${POW_PREFIX}:${handle}:${bucket}:${n}`).digest();
+    let ok = true;
+    for (let i = 0; i < fullBytes; i++) { if (d[i] !== 0) { ok = false; break; } }
+    if (ok && remBits && (d[fullBytes] >> (8 - remBits)) !== 0) ok = false;
+    if (ok) return String(n);
+  }
+}
+
+function parseHandle(args = []) {
+  const positional = args.find((a) => a && !a.startsWith('-'));
+  return (positional || '').trim().toLowerCase();
+}
+
+async function signupCommand(args = []) {
+  const handle = parseHandle(args);
+
+  if (!handle) {
+    console.error('Usage: atris signup <handle>');
+    console.error('  handle: 3–30 characters, lowercase letters and digits only.');
+    return 1;
+  }
+  if (!HANDLE_RE.test(handle)) {
+    console.error(`✗ Invalid handle "${handle}".`);
+    console.error('  Must be 3–30 characters, lowercase letters and digits (a–z, 0–9). No spaces or symbols.');
+    return 1;
+  }
+
+  console.log(`Claiming @${handle} … (solving proof-of-work)`);
+  const pow = solvePow(handle);
+
+  const res = await apiRequestJson('/auth/agent/signup', {
+    method: 'POST',
+    body: { handle, pow },
+  });
+
+  if (res.ok && res.data && res.data.token) {
+    const { token, email, user_id: userId } = res.data;
+    const identity = email || `${handle}@atrismail.com`;
+    saveCredentials(token, null, identity, userId || null, 'atrisos');
+    console.log(`\n✓ You're in — ${identity}`);
+    console.log('  Inert starter account (0 credits): identity is free, capability is earned.');
+    console.log('  Saved to your active profile.');
+    console.log('\nNext:');
+    console.log('  atris play     # claim a starter mission and earn your first proof-backed rep');
+    console.log('  atris xp       # see where you stand on the board');
+    return 0;
+  }
+
+  // Friendly, actionable errors — no stack traces for expected cases.
+  if (res.status === 409) {
+    console.error(`✗ "${handle}" is already taken or reserved. Try a different handle.`);
+    return 1;
+  }
+  if (res.status === 429) {
+    console.error('✗ Too many signups right now. Wait a minute and try again.');
+    return 1;
+  }
+  if (res.status === 404) {
+    console.error('✗ Seedless signup isn’t available on this backend yet.');
+    console.error('  Use `atris login` for now, or try again after the next deploy.');
+    return 1;
+  }
+  console.error(`✗ Signup failed: ${res.error || 'unknown error'} (status ${res.status}).`);
+  console.error(`  API: ${getApiBaseUrl()}`);
+  return 1;
+}
+
+module.exports = { signupCommand, parseHandle, HANDLE_RE };

package/lib/clarity.js

@@ -0,0 +1,97 @@
+'use strict';
+
+// The clarity interview. The front door of the product: draw out how the human
+// works, write it down once, and let every agent read it so they prompt
+// themselves well. A small, high-signal profile, not a survey.
+
+const fs = require('fs');
+const path = require('path');
+
+// One or two ideas at a time, plain English. Each answer is free text; the
+// parenthetical is a nudge, not a fixed menu.
+const QUESTIONS = [
+  { key: 'focus', q: 'what are you building, and who is it for?' },
+  { key: 'voice', q: 'how should output sound? (plain, terse, warm, formal)' },
+  { key: 'cadence', q: 'how do you like to work? (one idea at a time, batch, overnight autonomous)' },
+  { key: 'done', q: 'what does "done" mean to you? (tests green, shipped, you reviewed it)' },
+  { key: 'leash', q: 'how much should agents do without asking? (ask first, proceed and report, full auto)' },
+];
+
+const KEYS = QUESTIONS.map((x) => x.key);
+
+function isEmptyProfile(profile) {
+  return !profile || !KEYS.some((k) => profile[k]);
+}
+
+function renderClarityMd(profile = {}) {
+  const labels = {
+    focus: 'Focus',
+    voice: 'Voice',
+    cadence: 'Cadence',
+    done: 'Done means',
+    leash: 'Leash',
+  };
+  const lines = [
+    '# Clarity profile',
+    '',
+    'How the operator works. Agents read this to prompt themselves well,',
+    'so the human does not have to repeat themselves.',
+    '',
+  ];
+  for (const key of KEYS) {
+    if (profile[key]) lines.push(`- ${labels[key]}: ${profile[key]}`);
+  }
+  if (isEmptyProfile(profile)) {
+    lines.push('- (not set yet, run `atris clarity` to fill this in)');
+  }
+  lines.push('');
+  if (profile.updated_at) lines.push(`Updated: ${profile.updated_at}`);
+  lines.push('');
+  return lines.join('\n');
+}
+
+function profilePaths(root = process.cwd()) {
+  return {
+    json: path.join(root, '.atris', 'clarity.json'),
+    md: path.join(root, 'atris', 'CLARITY.md'),
+  };
+}
+
+function readProfile(root = process.cwd()) {
+  const { json } = profilePaths(root);
+  try {
+    return JSON.parse(fs.readFileSync(json, 'utf8'));
+  } catch {
+    return {};
+  }
+}
+
+function writeProfile(root, profile) {
+  const { json, md } = profilePaths(root);
+  fs.mkdirSync(path.dirname(json), { recursive: true });
+  fs.mkdirSync(path.dirname(md), { recursive: true });
+  fs.writeFileSync(json, `${JSON.stringify(profile, null, 2)}\n`, 'utf8');
+  fs.writeFileSync(md, renderClarityMd(profile), 'utf8');
+  return { json, md };
+}
+
+// Merge new answers over an existing profile (so --set is incremental).
+function mergeProfile(existing, answers, stamp) {
+  const merged = { ...existing };
+  for (const key of KEYS) {
+    if (typeof answers[key] === 'string' && answers[key].trim()) merged[key] = answers[key].trim();
+  }
+  merged.updated_at = stamp || merged.updated_at || null;
+  return merged;
+}
+
+module.exports = {
+  QUESTIONS,
+  KEYS,
+  mergeProfile,
+  isEmptyProfile,
+  renderClarityMd,
+  profilePaths,
+  readProfile,
+  writeProfile,
+};

package/lib/next-moves.js

@@ -0,0 +1,362 @@
+'use strict';
+
+// Alive onboarding: the engine behind `atris moves`.
+//
+// It reads the workspace for the highest-leverage next moves (the goal in
+// ROADMAP.md, work already in flight, fresh inbox ideas), ranks them, and lets
+// the human approve, kill, or skip. Approved moves are seeded into today's
+// inbox, which the loop's hasWork() already reads, so onboarding feeds the
+// loop without touching the autonomous core.
+
+const fs = require('fs');
+const path = require('path');
+
+function safeRead(p) {
+  try { return fs.readFileSync(p, 'utf8'); } catch { return ''; }
+}
+
+// Normalize a title for dedup and suppression, the same way moveId does, so a
+// move matches itself across case and whitespace.
+function norm(title) {
+  return String(title == null ? '' : title).trim().toLowerCase();
+}
+
+// Short, stable id so a kill on Tuesday still suppresses the same move on
+// Wednesday. Pure function of (source, title).
+function moveId(source, title) {
+  const s = `${source}:${String(title).trim().toLowerCase()}`;
+  let h = 2166136261;
+  for (let i = 0; i < s.length; i++) {
+    h ^= s.charCodeAt(i);
+    h = Math.imul(h, 16777619);
+  }
+  return `m_${(h >>> 0).toString(36)}`;
+}
+
+const WEIGHT = { roadmap: 100, task: 60, inbox: 40 };
+
+// One section-boundary shape for every reader and writer: tolerate a header
+// suffix (e.g. "(priority)"), stop at a sibling/parent heading (## or #) or a
+// malformed "##Next", but NOT at a child ### inside the section. Keeping a single
+// definition is the whole point: divergent boundaries are how the gate and the
+// picker drift apart.
+const SECTION_TAIL = '\\b[^\\n]*\\r?\\n([\\s\\S]*?)(?=\\r?\\n##[^#]|\\r?\\n# |$)';
+const OPEN_ITEMS_RE = new RegExp(`##\\s+Open loop items${SECTION_TAIL}`, 'i');
+const INBOX_RE = new RegExp(`##\\s+Inbox${SECTION_TAIL}`, 'i');
+
+// Locate a section's body and its character span, so a writer can splice an edit
+// back into exactly the region a reader parsed.
+function findSection(text, re) {
+  const m = text.match(re);
+  if (!m) return null;
+  const bodyStart = m.index + m[0].length - m[1].length;
+  return { body: m[1], start: bodyStart, end: bodyStart + m[1].length };
+}
+
+// Clean inbox titles out of a journal's ## Inbox section. The one inbox parser,
+// shared by latestInboxItems, todayInboxItems, and the run.js work gate.
+function parseInboxTitles(text) {
+  const m = (text || '').match(INBOX_RE);
+  if (!m) return [];
+  return m[1]
+    .split(/\r?\n/)
+    .map((l) => l.trim())
+    .filter((l) => l.startsWith('- ') && l.length > 2)
+    .map((l) => l.replace(/^-\s*\*\*[IC]?\d*:?\*\*\s*/, '').replace(/^-\s*\*\*/, '').replace(/\*\*$/, '').replace(/^-\s*/, '').trim())
+    .filter(Boolean);
+}
+
+function readRoadmapOpenItems(root) {
+  const text = safeRead(path.join(root, 'ROADMAP.md'));
+  if (!text) return [];
+  const section = findSection(text, OPEN_ITEMS_RE);
+  if (!section) return [];
+  return section.body
+    .split(/\r?\n/)
+    .map((l) => l.trim())
+    .filter((l) => /^- \[ \]/.test(l))
+    .map((l) => l.replace(/^- \[ \]\s*/, '').trim())
+    .filter(Boolean)
+    .map((title) => ({
+      title,
+      why: 'open item in ROADMAP.md, the goal the loop pursues',
+      source: 'roadmap',
+      weight: WEIGHT.roadmap,
+    }));
+}
+
+function readActiveTasks(root) {
+  const text = safeRead(path.join(root, '.atris', 'state', 'tasks.projection.json'));
+  if (!text) return [];
+  let proj;
+  try { proj = JSON.parse(text); } catch { return []; }
+  const tasks = Array.isArray(proj && proj.tasks) ? proj.tasks : [];
+  return tasks
+    .filter((t) => t && t.title && ['open', 'claimed'].includes(String(t.status || '').toLowerCase()))
+    .map((t) => ({
+      title: String(t.title).trim(),
+      why: `task in flight (${t.status}${t.claimed_by ? `, ${t.claimed_by}` : ''})`,
+      source: 'task',
+      ref: t.display_id || t.id || null,
+      weight: WEIGHT.task,
+    }));
+}
+
+function inboxItemsFrom(text) {
+  return parseInboxTitles(text).map((title) => ({ title, why: 'fresh idea in today\'s inbox', source: 'inbox', weight: WEIGHT.inbox }));
+}
+
+// Most recent journal under atris/logs/YYYY/, parsed for ## Inbox items. Used to
+// SURFACE ideas in `atris moves`.
+function latestInboxItems(root) {
+  const logsDir = path.join(root, 'atris', 'logs');
+  let years;
+  try { years = fs.readdirSync(logsDir).filter((d) => /^\d{4}$/.test(d)).sort(); } catch { return []; }
+  if (!years.length) return [];
+  const yearDir = path.join(logsDir, years[years.length - 1]);
+  let files;
+  try { files = fs.readdirSync(yearDir).filter((f) => /^\d{4}-\d{2}-\d{2}\.md$/.test(f)).sort(); } catch { return []; }
+  if (!files.length) return [];
+  return inboxItemsFrom(safeRead(path.join(yearDir, files[files.length - 1])));
+}
+
+// TODAY's journal inbox only. The loop's work gate and the seed-suppression must
+// read the SAME file the seeder writes (today's), or a prior-day duplicate makes
+// them disagree. Returns [] if today's file is absent.
+function todayInboxItems(root) {
+  const { file } = todayLogFile(root);
+  if (!fs.existsSync(file)) return [];
+  return inboxItemsFrom(safeRead(file));
+}
+
+function gatherCandidates(root = process.cwd()) {
+  return [
+    ...readRoadmapOpenItems(root),
+    ...readActiveTasks(root),
+    ...latestInboxItems(root),
+  ];
+}
+
+// Pure ranking: drop killed/approved, sort by weight, then dedupe by title
+// (keeping the highest-weight copy), take `limit`.
+//
+// Suppression: the exact move the operator acted on is dropped by id. Titles are
+// only suppressed for IDEAS (roadmap/inbox), never for a real `task`, so killing
+// or approving an idea can't hide a genuine in-flight task that happens to share
+// the title.
+function pickNextMoves(candidates, { limit = 3, killedIds = [], killedTitles = [], approvedIds = [], approvedTitles = [] } = {}) {
+  const blockedIds = new Set([...killedIds, ...approvedIds]);
+  const blockedTitles = new Set([...killedTitles, ...approvedTitles].map(norm));
+  const seen = new Set();
+  return candidates
+    .map((c) => ({ ...c, id: moveId(c.source, c.title), _key: norm(c.title) }))
+    .filter((c) => {
+      if (!c._key) return false;
+      if (blockedIds.has(c.id)) return false;
+      if (c.source !== 'task' && blockedTitles.has(c._key)) return false;
+      return true;
+    })
+    .sort((a, b) => (b.weight || 0) - (a.weight || 0))
+    .filter((c) => {
+      if (seen.has(c._key)) return false;
+      seen.add(c._key);
+      return true;
+    })
+    .map(({ _key, ...c }) => c)
+    .slice(0, limit);
+}
+
+const DECISIONS_FILE = ['.atris', 'state', 'moves.decisions.jsonl'];
+
+function decisionsPath(root) {
+  return path.join(root, ...DECISIONS_FILE);
+}
+
+function readDecisions(root = process.cwd()) {
+  const text = safeRead(decisionsPath(root));
+  const rows = text.split(/\r?\n/).map((l) => l.trim()).filter(Boolean)
+    .map((l) => { try { return JSON.parse(l); } catch { return null; } })
+    .filter(Boolean);
+  const idsFor = (decision) => rows.filter((r) => r.decision === decision).map((r) => r.id);
+  const titlesFor = (decision) => rows.filter((r) => r.decision === decision).map((r) => norm(r.title));
+  return {
+    killedIds: idsFor('kill'),
+    killedTitles: titlesFor('kill'),
+    approvedIds: idsFor('approve'),
+    approvedTitles: titlesFor('approve'),
+  };
+}
+
+function recordDecision(root, move, decision, stamp) {
+  const p = decisionsPath(root);
+  fs.mkdirSync(path.dirname(p), { recursive: true });
+  const row = { id: move.id, title: move.title, source: move.source, decision, at: stamp || null };
+  fs.appendFileSync(p, `${JSON.stringify(row)}\n`, 'utf8');
+  return row;
+}
+
+function todayLogFile(root, date = new Date()) {
+  const y = date.getFullYear();
+  const m = String(date.getMonth() + 1).padStart(2, '0');
+  const d = String(date.getDate()).padStart(2, '0');
+  const dateFormatted = `${y}-${m}-${d}`;
+  return { file: path.join(root, 'atris', 'logs', String(y), `${dateFormatted}.md`), dateFormatted };
+}
+
+// The canonical day-journal sections every reader expects (status, analytics,
+// section parsers). Mirrors lib/journal.js createLogFile, minus the em dash in
+// its title, so a journal first created by the idle-seed path is not malformed.
+function canonicalJournal(dateFormatted) {
+  return `# Log ${dateFormatted}\n\n## Handoff\n\n---\n\n## Completed ✅\n\n---\n\n## In Progress 🔄\n\n---\n\n## Backlog\n\n---\n\n## Notes\n\n---\n\n## Inbox\n\n`;
+}
+
+// Seed an approved move into today's inbox so the loop's hasWork() finds it.
+// Idempotent by title: if the same title is already in today's inbox, it is not
+// appended again (so a retry or a concurrent cycle cannot duplicate it).
+function seedInboxFromMove(root, move, date) {
+  const { file, dateFormatted } = todayLogFile(root, date);
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  let content = safeRead(file);
+  if (!content) {
+    content = canonicalJournal(dateFormatted);
+  }
+  if (!/##\s+Inbox/i.test(content)) {
+    content = content.replace(/^(#.*\n)/, `$1\n## Inbox\n`);
+    if (!/##\s+Inbox/i.test(content)) content += `\n## Inbox\n`;
+  }
+  const target = norm(move.title);
+  if (parseInboxTitles(content).some((t) => norm(t) === target)) {
+    return { file, line: null, nextId: null, alreadyPresent: true };
+  }
+  const existingIds = (content.match(/-\s*\*\*I(\d+):/g) || []).map((m2) => parseInt(m2.match(/I(\d+)/)[1], 10));
+  const nextId = existingIds.length ? Math.max(...existingIds) + 1 : 1;
+  const line = `- **I${nextId}:** ${move.title}`;
+  // Insert right after the Inbox header line only (do not consume blank lines or
+  // following sections). Use a function replacer so a title containing $ tokens
+  // ($1, $&, $$) is inserted literally, not interpreted as a replacement pattern.
+  content = content.replace(/(##\s+Inbox[^\n]*\r?\n)/i, (m) => `${m}${line}\n`);
+  fs.writeFileSync(file, content, 'utf8');
+  return { file, line, nextId };
+}
+
+// Claim an open ROADMAP item for the loop by flipping its `- [ ]` to `- [~]`
+// (claimed, in flight) WITHIN the "## Open loop items" section only. This is the
+// single source of truth for "the loop took this on": readRoadmapOpenItems only
+// returns `- [ ]`, so a claimed item is excluded, and the work gate and the seed
+// picker stay in agreement. Scoped to the section so a same-titled `- [ ]` in
+// another section (Big jobs, an example block) is never flipped by mistake.
+// `- [~]` is distinct from human `- [x]` (done) so a reader is not misled.
+function claimRoadmapItem(root, title) {
+  const p = path.join(root, 'ROADMAP.md');
+  const text = safeRead(p);
+  if (!text) return false;
+  const section = findSection(text, OPEN_ITEMS_RE);
+  if (!section) return false;
+  const target = norm(title);
+  let changed = false;
+  const newBody = section.body.split(/\r?\n/).map((line) => {
+    if (changed) return line;
+    const m = line.match(/^(\s*)- \[ \]\s*(.+?)\s*$/);
+    if (m && norm(m[2]) === target) {
+      changed = true;
+      return `${m[1]}- [~] ${m[2].trim()}`;
+    }
+    return line;
+  }).join('\n');
+  if (!changed) return false;
+  const out = text.slice(0, section.start) + newBody + text.slice(section.end);
+  fs.writeFileSync(p, out, 'utf8');
+  return true;
+}
+
+// Add one bounded item to the "## Open loop items" section so the loop (and
+// `atris moves`) will pursue it: messy input straight into the working queue,
+// no markdown editing. Creates ROADMAP.md and the section if missing. Dedups
+// against existing OPEN items only (a done/claimed one can be re-added).
+function addRoadmapItem(root, text) {
+  // Collapse any whitespace/newlines to single spaces (a multi-line title would
+  // break the markdown line) and strip a leading bullet/checkbox the user may
+  // have pasted, so the item is exactly one well-formed `- [ ]` line.
+  const title = String(text || '').replace(/\s+/g, ' ').trim().replace(/^- \[[ x~]\]\s*/, '').replace(/^- /, '').trim();
+  if (!title) return { added: false, reason: 'empty', title: null };
+  const p = path.join(root, 'ROADMAP.md');
+  let content = safeRead(p);
+  if (!content) content = '# Roadmap\n\n## Open loop items\n\n';
+  let section = findSection(content, OPEN_ITEMS_RE);
+  if (!section) {
+    if (!content.endsWith('\n')) content += '\n';
+    content += '\n## Open loop items\n\n';
+    section = findSection(content, OPEN_ITEMS_RE);
+  }
+  const openTitles = section.body.split(/\r?\n/)
+    .map((l) => l.trim())
+    .filter((l) => /^- \[ \]/.test(l))
+    .map((l) => norm(l.replace(/^- \[ \]\s*/, '')));
+  if (openTitles.includes(norm(title))) return { added: false, reason: 'already an open item', title };
+  // Insert at the top of the section body so the loop pulls it next.
+  const out = `${content.slice(0, section.start)}\n- [ ] ${title}\n${content.slice(section.start)}`;
+  fs.writeFileSync(p, out, 'utf8');
+  return { added: true, title };
+}
+
+// Group the Open loop items by state: queued `- [ ]`, in-flight `- [~]` (claimed
+// by the loop), done `- [x]`. The evidence for a loop report.
+function roadmapItemsByState(root) {
+  const out = { open: [], claimed: [], done: [] };
+  const text = safeRead(path.join(root, 'ROADMAP.md'));
+  if (!text) return out;
+  const section = findSection(text, OPEN_ITEMS_RE);
+  if (!section) return out;
+  for (const raw of section.body.split(/\r?\n/)) {
+    const l = raw.trim();
+    let m;
+    if ((m = l.match(/^- \[ \]\s*(.+)$/))) out.open.push(m[1].trim());
+    else if ((m = l.match(/^- \[~\]\s*(.+)$/))) out.claimed.push(m[1].trim());
+    else if ((m = l.match(/^- \[x\]\s*(.+)$/))) out.done.push(m[1].trim());
+  }
+  return out;
+}
+
+// The top open ROADMAP item the loop has not already handled. Claimed items are
+// marked `- [~]` (so readRoadmapOpenItems drops them); this also skips anything
+// already in TODAY's inbox or killed/approved, so an idle loop advances to the
+// next item each cycle. todayInboxItems (not latestInboxItems) so the picker, the
+// work gate, and the seeder all read the same file. Root-explicit and pure of
+// cwd, so it is testable without a live runner.
+function pickRoadmapSeed(root = process.cwd()) {
+  const items = readRoadmapOpenItems(root);
+  if (!items.length) return null;
+  const inbox = todayInboxItems(root).map((i) => norm(i.title));
+  const { killedTitles, approvedTitles } = readDecisions(root);
+  const blocked = new Set([...inbox, ...killedTitles, ...approvedTitles]);
+  return items.find((it) => !blocked.has(norm(it.title))) || null;
+}
+
+// Shared "3 next moves" recipe used by both `atris moves` and `atris activate`,
+// so the ranking inputs live in one place.
+function nextMoves(root = process.cwd(), limit = 3) {
+  const { killedIds, killedTitles, approvedIds, approvedTitles } = readDecisions(root);
+  return pickNextMoves(gatherCandidates(root), { limit, killedIds, killedTitles, approvedIds, approvedTitles });
+}
+
+module.exports = {
+  moveId,
+  norm,
+  WEIGHT,
+  parseInboxTitles,
+  readRoadmapOpenItems,
+  readActiveTasks,
+  latestInboxItems,
+  todayInboxItems,
+  gatherCandidates,
+  pickNextMoves,
+  nextMoves,
+  readDecisions,
+  recordDecision,
+  seedInboxFromMove,
+  pickRoadmapSeed,
+  claimRoadmapItem,
+  addRoadmapItem,
+  roadmapItemsByState,
+  todayLogFile,
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "atris",
-  "version": "3.26.0",
+  "version": "3.27.0",
   "main": "bin/atris.js",
   "bin": {
     "atris": "bin/atris.js",

package/utils/update-check.js

@@ -2,7 +2,7 @@ const https = require('https');
 const fs = require('fs');
 const path = require('path');
 const os = require('os');
-const { spawnSync } = require('child_process');
+const { spawn, spawnSync } = require('child_process');
 
 const PACKAGE_NAME = 'atris';
 const CHECK_INTERVAL_MS = 60 * 60 * 1000; // 1 hour
@@ -34,6 +34,8 @@ function getCacheData() {
       return {
         lastCheck: data.lastCheck ? new Date(data.lastCheck) : null,
         latestVersion: data.latestVersion || null,
+        lastAutoUpdate: data.lastAutoUpdate ? new Date(data.lastAutoUpdate) : null,
+        lastAutoUpdateVersion: data.lastAutoUpdateVersion || null,
       };
     }
   } catch (error) {
@@ -52,7 +54,11 @@ function saveCacheData(latestVersion) {
     if (!fs.existsSync(ATRIS_DIR)) {
       fs.mkdirSync(ATRIS_DIR, { recursive: true });
     }
+    const existing = fs.existsSync(CACHE_FILE)
+      ? JSON.parse(fs.readFileSync(CACHE_FILE, 'utf8'))
+      : {};
     const data = {
+      ...existing,
       lastCheck: new Date().toISOString(),
       latestVersion: latestVersion,
     };
@@ -62,6 +68,34 @@ function saveCacheData(latestVersion) {
   }
 }
 
+function markAutoUpdateStarted(latestVersion) {
+  try {
+    if (!fs.existsSync(ATRIS_DIR)) {
+      fs.mkdirSync(ATRIS_DIR, { recursive: true });
+    }
+    const existing = fs.existsSync(CACHE_FILE)
+      ? JSON.parse(fs.readFileSync(CACHE_FILE, 'utf8'))
+      : {};
+    fs.writeFileSync(CACHE_FILE, JSON.stringify({
+      ...existing,
+      lastAutoUpdate: new Date().toISOString(),
+      lastAutoUpdateVersion: latestVersion,
+    }, null, 2));
+  } catch (error) {
+    // Ignore cache write errors
+  }
+}
+
+function autoUpdateRecentlyStarted(latestVersion, now = new Date()) {
+  const cache = getCacheData();
+  return Boolean(
+    latestVersion &&
+    cache.lastAutoUpdate &&
+    cache.lastAutoUpdateVersion === latestVersion &&
+    now - cache.lastAutoUpdate < CHECK_INTERVAL_MS
+  );
+}
+
 /**
  * Fetch the latest version of atris from npm registry.
  * @returns {Promise<string>} Latest version string
@@ -189,7 +223,7 @@ function showUpdateNotification(updateInfo) {
   // Single yellow warning line — non-intrusive
   const yellow = '\x1b[33m';
   const reset = '\x1b[0m';
-  console.log(`${yellow}Update available: ${updateInfo.installed} → ${updateInfo.latest}. Run: npm install -g atris${reset}`);
+  console.log(`${yellow}Update available: ${updateInfo.installed} → ${updateInfo.latest}. Run: atris upgrade${reset}`);
 }
 
 function inspectInstallGitState(packageRoot = path.join(__dirname, '..')) {
@@ -237,37 +271,55 @@ function formatInstallGitWarning(state) {
   if (state.detached) flags.push(`detached HEAD${state.head ? ` ${state.head}` : ''}`);
   if (state.dirty) flags.push(`dirty worktree (${state.dirtyCount} file${state.dirtyCount === 1 ? '' : 's'})`);
   return `WARNING: Atris is running from a ${flags.join(' + ')} at ${state.root}.\n` +
-    'npm update may not change the code currently on PATH; resolve that checkout before trusting upgrade status.';
+    'npm install -g atris@latest may not change the code currently on PATH; resolve that checkout before trusting upgrade status.';
 }
 
-function autoUpdate(updateInfo) {
+function normalizeAutoUpdateMode(env = process.env) {
+  const raw = String(env.ATRIS_AUTO_UPDATE || '').trim().toLowerCase();
+  if (['0', 'false', 'no', 'off', 'notify'].includes(raw)) return 'off';
+  if (['1', 'true', 'yes', 'on', 'force'].includes(raw)) return 'force';
+  return 'auto';
+}
+
+function shouldAutoUpdate(updateInfo, state, env = process.env) {
   if (!updateInfo || !updateInfo.needsUpdate) return false;
 
-  const { execSync } = require('child_process');
+  const mode = normalizeAutoUpdateMode(env);
+  if (mode === 'off') return false;
+  if (mode === 'force') return true;
 
-  console.log('');
-  console.log(`⬆️  Updating atris ${updateInfo.installed} → ${updateInfo.latest}...`);
+  // Packaged npm installs are not git repositories. Git checkouts may be linked
+  // dev installs, where a global npm install would not update the code on PATH.
+  return !(state && state.isGitRepo);
+}
 
-  try {
-    execSync('npm update -g atris', { stdio: 'pipe', timeout: 30000 });
-    console.log(`✅ Updated to ${updateInfo.latest}`);
-
-    // Auto-sync skills into current project if atris/skills/ exists
-    try {
-      if (fs.existsSync(path.join(process.cwd(), 'atris', 'skills'))) {
-        execSync('atris sync', { stdio: 'pipe', timeout: 10000 });
-        console.log(`✅ Skills synced`);
-      }
-    } catch (e) {
-      // Sync failed — not critical
-    }
+function autoUpdate(updateInfo, options = {}) {
+  if (!updateInfo || !updateInfo.needsUpdate) return false;
+
+  const env = options.env || process.env;
+  const packageRoot = options.packageRoot || path.join(__dirname, '..');
+  const installState = options.installState || inspectInstallGitState(packageRoot);
+  if (!shouldAutoUpdate(updateInfo, installState, env)) return false;
+
+  const recentlyStarted = options.recentlyStarted || autoUpdateRecentlyStarted;
+  if (recentlyStarted(updateInfo.latest)) return false;
 
-    console.log('');
+  const spawnImpl = options.spawn || spawn;
+  const markStarted = options.markStarted || markAutoUpdateStarted;
+  const log = options.log || console.log;
+
+  try {
+    const child = spawnImpl('npm', ['install', '-g', `${PACKAGE_NAME}@latest`], {
+      detached: true,
+      stdio: 'ignore',
+      windowsHide: true,
+    });
+    if (child && typeof child.on === 'function') child.on('error', () => {});
+    if (child && typeof child.unref === 'function') child.unref();
+    markStarted(updateInfo.latest);
+    log(`Auto-update started: atris ${updateInfo.installed} -> ${updateInfo.latest} (background)`);
     return true;
   } catch (error) {
-    // npm update failed (permissions, network, etc) — fall back to notification
-    console.log(`⚠️  Auto-update failed. Run manually: npm update -g atris`);
-    console.log('');
     return false;
   }
 }
@@ -276,6 +328,7 @@ module.exports = {
   checkForUpdates,
   showUpdateNotification,
   autoUpdate,
+  shouldAutoUpdate,
   inspectInstallGitState,
   formatInstallGitWarning,
 };