atris 3.53.0 → 3.55.0

package/bin/atris.js

@@ -41,7 +41,13 @@ const {
   autoUpdate,
   inspectInstallGitState,
   formatInstallGitWarning,
+  formatCliVersionLine,
 } = require('../utils/update-check');
+const {
+  requireAccountBound,
+  refuseAccountGlobal,
+} = require('../lib/account-bound');
+const { isHelpToken, argsWantHelp } = require('../lib/noninteractive');
 
 // State detection for smart default
 const { detectWorkspaceState, loadContext } = require('../lib/state-detection');
@@ -52,6 +58,12 @@ const {
   isAtrisMetaQuestion,
   renderPrompt: renderContextGathererPrompt,
 } = require('../lib/context-gatherer');
+const {
+  buildFirstMinute,
+  freshMinuteJson,
+  isBareAtrisFlag,
+  shouldAutoInitFresh,
+} = require('../lib/first-minute');
 
 // Journal & config utilities (canonical modules)
 const { getLogPath, ensureLogDirectory, createLogFile } = require('../lib/file-ops');
@@ -75,7 +87,7 @@ const {
   DEFAULT_CLIENT_ID, DEFAULT_USER_AGENT,
 } = require('../utils/api');
 const missionRuntime = require('../lib/mission-runtime-loop');
-const { knownCommands, suggestCommand } = require('../lib/known-commands');
+const { knownCommands, suggestCommand, suggestCommands } = require('../lib/known-commands');
 const { recordUsage } = require('../lib/usage');
 
 // Bind DI wrappers (utils/auth uses dependency injection for apiRequestJson)
@@ -153,6 +165,12 @@ function parseNaturalEntryArgs(args = []) {
       asJson = true;
       continue;
     }
+    if (value === '--yes' || value === '-y' || value === '--verbose') {
+      continue;
+    }
+    if (isHelpToken(value)) {
+      continue;
+    }
     const inlineFlag = NATURAL_VALUE_FLAGS.find((name) => value.startsWith(`${name}=`));
     if (inlineFlag) {
       const optionValue = value.slice(inlineFlag.length + 1);
@@ -262,7 +280,13 @@ const isBusinessSyncSafetyCommand = command === 'sync'
 
 // Auto-sync skills only for commands that modify workspace state. Help must
 // stay read-only, including global ~/.claude and ~/.codex skill directories.
-if (!helpRequested && !dryRunRequested && (['init', 'update', 'upgrade'].includes(command) || (command === 'sync' && !isBusinessSyncSafetyCommand))) {
+// update/sync stay plan-only until --yes, so do not write skills on a bare update.
+const updateWriteYes = updateArgs.includes('--yes') || updateArgs.includes('-y');
+if (!helpRequested && !dryRunRequested && (
+  ['init', 'upgrade'].includes(command)
+  || (command === 'update' && updateWriteYes)
+  || (command === 'sync' && !isBusinessSyncSafetyCommand && updateWriteYes)
+)) {
   try {
     const { syncSkills } = require('../commands/sync');
     const skillsUpdated = syncSkills({ silent: true });
@@ -446,40 +470,83 @@ function consoleCmd() {
   process.exit(result.status ?? 0);
 }
 
-function showHelp() {
+function showStartHelp() {
+  console.log('');
+  console.log('Usage: atris start [options]');
+  console.log('');
+  console.log('Starts the durable mission loop for one useful self-improvement mission.');
+  console.log('');
+  console.log('Options:');
+  console.log('  --json       Print the mission route without starting it.');
+  console.log('  --owner X    Override mission owner.');
+  console.log('  --cadence X  Override mission cadence.');
+  console.log('');
+}
+
+function showHelpShort() {
+  console.log('atris: you say what you want; atris builds it, checks it, and shows proof.');
+  console.log('');
+  console.log('Golden path:');
+  console.log('  atris init [--yes] [--minimal]   scaffold this project');
+  console.log('  atris                           load context (MAP, tasks, journal)');
+  console.log('  atris task new "..."            file work');
+  console.log('  atris task claim <id> --as <m>  take ownership');
+  console.log('  atris task ready <id> --proof "..."');
+  console.log('  atris review                    validate');
+  console.log('  atris recap                     spoken recap of what landed');
+  console.log('  atris mission status            active goals + next move');
+  console.log('');
+  console.log('More: atris help --all   ·   machine list: atris help --json');
+}
+
+function helpCatalog() {
+  return [
+    { name: 'init', summary: 'scaffold atris/ in this project', json: false, interactive_risk: 'medium' },
+    { name: 'task', summary: 'local task plane: new, claim, ready, accept', json: true, interactive_risk: 'low' },
+    { name: 'review', summary: 'validate work and capture learnings', json: false, interactive_risk: 'low' },
+    { name: 'recap', summary: 'spoken recap of what your team did', json: true, interactive_risk: 'low' },
+    { name: 'mission', summary: 'durable goal + owner + verifier + tick', json: true, interactive_risk: 'medium' },
+    { name: 'log', summary: 'append an idea to today inbox (or --repl)', json: false, interactive_risk: 'medium' },
+    { name: 'wish', summary: 'headless inbox / mission intake', json: true, interactive_risk: 'low' },
+    { name: 'learn', summary: 'structured project learnings', json: false, interactive_risk: 'low' },
+    { name: 'activate', summary: 'load atris context for this session', json: false, interactive_risk: 'low' },
+    { name: 'status', summary: 'local work and completions', json: true, interactive_risk: 'low' },
+    { name: 'engine', summary: 'engine roster, ask, validate, dispatch', json: true, interactive_risk: 'low' },
+    { name: 'help', summary: 'this help (default short; --all full)', json: true, interactive_risk: 'none' },
+  ];
+}
+
+function showHelpAll() {
   console.log('');
   console.log('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━');
   console.log('atris');
   console.log('you say what you want in plain words. atris builds it, checks it, and shows you proof.');
   console.log('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━');
   console.log('');
-  console.log('Quick Start:');
+  console.log('Quick start:');
   console.log('');
-  console.log('  1. atris                  Open a persistent AI computer for this workspace');
-  console.log('     npx atris              Same command after a local project install');
-  console.log('  2. Describe what you want run, built, researched, or validated');
-  console.log('  3. Atris acts with context, memory, tools, and a review loop');
+  console.log('  1. atris                  load context (MAP, tasks, journal)');
+  console.log('     npx atris              same after a local install');
+  console.log('  2. say what you want built, checked, or researched');
+  console.log('  3. atris files the work, then you review');
   console.log('');
   console.log('Common invocations:');
-  console.log('  atris "<request>"         Build one isolated change, verify it, and stop in Review');
+  console.log('  atris "<request>"         one isolated change, then Review');
   console.log('  atris "<request>" --verify "<cmd>" --json');
-  console.log('                            Supply proof explicitly and return one JSON result');
-  console.log('  atris init [--yes]        Global install: initialize this project');
-  console.log('  npx atris init [--yes]    Local install: initialize this project');
+  console.log('  atris init [--yes]        scaffold this project');
+  console.log('  npx atris init [--yes]    same after a local install');
+  console.log('  atris mission status      current mission + next move');
+  console.log('  atris task ready <id> --proof "..."');
   console.log('  atris computer');
-  console.log('  atris ask "what you want" [--budget <usd>]');
-  console.log('  atris mission              Show the current mission');
-  console.log('  atris approve              Approve the step waiting for you');
-  console.log('  atris stop                 Stop the current mission');
-  console.log('  atris check <run-id>       Show the checks for a mission');
-  console.log('  atris ready --json         Show which mission features are ready');
-  console.log('  atris engine validate latest  check the newest ask receipt with a cheap referee');
+  console.log('  atris engine validate latest');
+  console.log('  atris playbook                 workspace style rules and paired trials');
   console.log('  atris business init "My Company"');
   console.log('  atris run');
   console.log('  atris drill');
   console.log('  atris status');
   console.log('  atris soul');
   console.log('  atris fleet status');
+  console.log('  ask/stop/ready            see atris mission and atris task ready');
   console.log('');
   console.log('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━');
   console.log('');
@@ -490,7 +557,8 @@ 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 (--yes skips prompts)');
+  console.log('  init       - Initialize Atris in current project (--yes skips prompts; --minimal for lean scaffold)');
+  console.log('  install    - Install the atris/ brain if missing (alias: workspace install)');
   console.log('  update     - Update local files to latest version');
   console.log('  upgrade    - Install latest Atris from npm');
   console.log('');
@@ -505,7 +573,7 @@ function showHelp() {
   console.log('  spaceship  - Bounded overnight runner that survives bad ticks and emails updates');
   console.log('');
   console.log('Context & tracking:');
-  console.log('  log        - Add ideas to inbox');
+  console.log('  log        - Add ideas to inbox (`atris log "note"`; `log --repl` for the editor; see also `wish`)');
   console.log('  wish       - Say one plain sentence, then Atris asks only for gaps or delegates it');
   console.log('  now        - Show atris/now.md, the current operating truth');
   console.log('  goal       - goal, distance, and what moved today (alias: wtf)');
@@ -518,13 +586,15 @@ function showHelp() {
   console.log('  team       - One team view: members, roles, engine assignments (presence for live)');
   console.log('  watch      - Turn one sentence into an always-on background watcher');
   console.log('  ctop       - Show a process-first live agent CPU/memory view');
+  console.log('  doctor     - Node/task/auth/workspace readiness (--json for agents)');
   console.log('  launchpad  - Show the next action from local brain, task, mission, and proof state');
   console.log('  brief      - Show the one-glance operator brief');
   console.log('  status     - See local work and completions (`atris status <business>` for remote)');
-  console.log('  recap      - What your AI team did, in plain English (--share for paste-ready)');
+  console.log('  recap      - What your AI team did, in spoken lines (--verbose for the old report)');
   console.log('  report     - Weekly block: landings, journal completions, and Career XP');
   console.log('  xp         - Show Career XP and contribution graph');
   console.log('  analytics  - Show recent productivity from journals');
+  console.log('  revisions  - show possible human revisions after atris-assisted landings');
   console.log('  search     - Search workspace memory (atris search <keyword>)');
   console.log('  clean      - Housekeeping (stale tasks, archive journals, broken refs)');
   console.log('  close      - track open loops with deadlines and daily escalation');
@@ -542,14 +612,14 @@ function showHelp() {
   console.log('    atris autoland tick   # second check runs, task lands');
   console.log('  mission    - Goal + loop + member owner + verifier + receipt; --budget quick|long|deep sets bounded tiers');
   console.log('  decide     - Answer open mission asks and send the decision to the next tick');
-  console.log('  release    - Tag release, bump version, create GitHub release, draft /launch');
+  console.log('  release    - Tag release, bump version, create GitHub release, draft /launch; atris release preflight before a v* tag');
   console.log('  learn      - Project learnings (patterns, pitfalls, preferences)');
   console.log('  study      - On-demand learning feed: ingest topic, start server, open browser');
   console.log('  rainmaker  - Relationship manager dashboard (atrisos-backend/scripts/rainmaker.py)');
   console.log('  meet       - onboard a stranger in one sitting and print their /book link');
   console.log('  avail      - Booking availability (/book/{username} weekly windows)');
   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 (add --detector validates the falsifier at write time; ledger/revert audit every mutation; mine: distill receipts/episodes/scorecards into policy lessons)');
+  console.log('  lesson     - atris lesson add <slug> <pass|fail> "<text>" (mine/sweep/resolve/revert/ledger; --detector validates the falsifier at write time)');
   console.log('  taste      - Record the operator\'s keep, kill, and more creative verdicts');
   console.log('  teach      - Turn a bad turn into a failing benchmark, then a permanent guard (red gate: no promotion without a proven failure)');
   console.log('  ingest     - Local-first wiki ingest into atris/wiki/');
@@ -572,7 +642,8 @@ function showHelp() {
   console.log('  router     - inspect ax lane outcomes and promote gated reflex overrides');
   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    - Free local notes, weekly digest, or 5-credit cloud process for YouTube videos');
+  console.log('  youtube    - Free search + notes, weekly digest, 5-credit paid search, or 5-credit cloud process for YouTube videos');
+  console.log('  x-search   - 5-credit X/Twitter search (tweet text + x.com links)');
   console.log('');
   console.log('Experiments:');
   console.log('  experiments init [slug]     - Prepare atris/experiments/ or scaffold a pack');
@@ -640,12 +711,16 @@ function showHelp() {
   console.log('  agent      - Select cloud agent, spawn worker requests, or run `agent doctor`');
   console.log('  chat       - Chat with Atris 2 Fast in this workspace (--agent for cloud agent; or: atris chat scan)');
   console.log('  fast       - Chat with Atris2 Fast');
-  console.log('  login      - Sign in or add another account');
+  console.log('  login      - Sign in, add an account, or mint a scoped agent token (--agent)');
   console.log('  logout     - Sign out of current account');
   console.log('  whoami     - Show active account');
   console.log('  switch     - Switch account globally (atris switch <name>)');
   console.log('  use        - Set account for this terminal only (atris use <name>)');
   console.log('  accounts   - Manage accounts (list, add, remove)');
+  console.log('  balance    - Show credit balance in dollars');
+  console.log('  usage      - Show developer API usage');
+  console.log('  api-key    - Create, list, rotate, or revoke a developer API key');
+  console.log('  topup      - Buy credits and print a Stripe checkout URL');
   console.log('');
   console.log('Integrations:');
   console.log('  github    - github cli wrapper (doctor, auth, pr list/create/checks/view)');
@@ -653,7 +728,7 @@ function showHelp() {
   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('  gmail      - email commands (connect, inbox, read, archive, accounts, use)');
   console.log('  calendar   - Calendar commands (today, week)');
   console.log('  twitter    - Twitter commands (post)');
   console.log('  slack      - Slack commands (channels)');
@@ -666,6 +741,7 @@ function showHelp() {
   console.log('  skill list          - Show all skills with compliance status');
   console.log('  skill audit [name]  - Validate skill against Anthropic guide');
   console.log('  skill fix [name]    - Auto-fix common compliance issues');
+  console.log('  skill eval <path>   - Run an independent rubric review and write its receipt');
   console.log('  skill delete <name> - Delete a skill and its symlinks');
   console.log('');
   console.log('Team:');
@@ -682,47 +758,64 @@ function showHelp() {
   console.log('Feedback:');
   console.log('  feedback "msg"             - Submit feedback');
   console.log('  feedback                   - List feedback queue');
+  console.log('  feedback triage <id>       - Print a reproduction brief (--dispatch to run)');
   console.log('  feedback resolve <id> "<note>" - Mark resolved (admin)');
   console.log('  feedback close <id>        - Close as wontfix (admin)');
   console.log('  feedback delete <id>       - Delete feedback (admin)');
   console.log('');
   console.log('Other:');
   console.log('  version    - Show Atris version');
-  console.log('  help       - Show this help');
+  console.log('  help       - Short golden path (help --all for every command)');
   console.log('');
-  console.log('💡 Tip: Just run "atris" to get started');
+  console.log('Tip: Just run "atris" to get started');
   console.log('');
 }
 
+function showHelp(options = {}) {
+  const args = options.args || process.argv.slice(3);
+  const asJson = options.json === true || args.includes('--json');
+  const all = options.all === true || args.includes('--all');
+  if (asJson) {
+    console.log(JSON.stringify({ ok: true, commands: helpCatalog() }, null, 2));
+    return;
+  }
+  if (all) {
+    showHelpAll();
+    return;
+  }
+  showHelpShort();
+}
+
 function showPlanHelp() {
   console.log('');
-  console.log('Usage: atris plan [--execute] [--full]');
+  console.log('Usage: atris plan [--execute] [--prompt|--verbose|--full]');
   console.log('');
   console.log('Description:');
-  console.log('  Activate the Navigator agent to plan work.');
-  console.log('  Reads your journal Inbox, TODO.md, MAP.md, and features/, then prints a');
-  console.log('  short, copy/pasteable prompt for your coding agent.');
+  console.log('  Same two spoken lines as bare atris.');
+  console.log('  --prompt prints the navigator copy/paste prompt.');
+  console.log('  Leftover words stay a request.');
   console.log('');
   console.log('Options:');
-  console.log('  --execute   Run in agent mode via Atris cloud (requires login + agent).');
-  console.log('  --full      Print full spec/context dumps (verbose copy/paste).');
-  console.log('  --verbose   Alias for --full.');
+  console.log('  --execute   ACTION TAKEN: run in agent mode via Atris cloud (requires login + agent).');
+  console.log('  --prompt    Print the navigator copy/paste prompt.');
+  console.log('  --verbose   Alias for --prompt, plus full spec dumps.');
+  console.log('  --full      Alias for --verbose.');
   console.log('');
 }
 
 function showDoHelp() {
   console.log('');
-  console.log('Usage: atris do [--execute] [--full]');
+  console.log('Usage: atris do [--execute] [--prompt|--verbose|--full]');
   console.log('');
   console.log('Description:');
-  console.log('  Activate the Executor agent to build tasks.');
-  console.log('  Reads TODO.md and features/*/build.md, then prints step-by-step');
-  console.log('  execution instructions (and, in agent mode, edits code + runs commands).');
+  console.log('  Same two spoken lines as bare atris.');
+  console.log('  --prompt prints the executor copy/paste prompt.');
   console.log('');
   console.log('Options:');
-  console.log('  --execute   Run in agent mode via Atris cloud (requires login + agent).');
-  console.log('  --full      Print full spec/context dumps (verbose copy/paste).');
-  console.log('  --verbose   Alias for --full.');
+  console.log('  --execute   ACTION TAKEN: edit code + run commands via Atris cloud.');
+  console.log('  --prompt    Print the executor copy/paste prompt.');
+  console.log('  --verbose   Alias for --prompt, plus full spec dumps.');
+  console.log('  --full      Alias for --verbose.');
   console.log('');
 }
 
@@ -731,8 +824,9 @@ function showReviewHelp() {
   console.log('Usage: atris review [--limit N|--all|--json] [--full|--execute]');
   console.log('');
   console.log('Description:');
-  console.log('  Show the certified Review queue: proof-ready work waiting for');
-  console.log('  human accept or revise. Human accept is the AgentXP gate.');
+  console.log('  Show the one finished thing waiting for your ok.');
+  console.log('  Certified work leads with atris task accept. Uncertified stays');
+  console.log('  still being checked. Use --json/--all for the full queue.');
   console.log('  Use --full/--verbose for the legacy Validator prompt.');
   console.log('');
   console.log('Options:');
@@ -773,6 +867,21 @@ function showAnalyticsHelp() {
   console.log('');
 }
 
+function showRevisionsHelp() {
+  console.log('');
+  console.log('usage: atris revisions [--json]');
+  console.log('');
+  console.log('description:');
+  console.log('  count possible human revisions after atris-assisted landings.');
+  console.log('  uses same-file git follow-ups as a signal, not proof of intent.');
+  console.log('  saves one rolling seven-day summary row per utc day.');
+  console.log('');
+  console.log('options:');
+  console.log('  --json       print the measured landings and revision signals as json.');
+  console.log('  --help, -h   show this help.');
+  console.log('');
+}
+
 function showActivateHelp() {
   console.log('');
   console.log('Usage: atris activate');
@@ -820,15 +929,18 @@ function showVerifyHelp() {
 function showUpdateHelp(commandName = 'update') {
   console.log('');
   const selfFlag = commandName === 'update' ? ' [--self]' : '';
-  console.log(`Usage: atris ${commandName} [--all] [--dry-run] [--force]${selfFlag}`);
+  console.log(`Usage: atris ${commandName} [--all] [--dry-run] [--yes] [--force]${selfFlag}`);
   console.log('');
   console.log('Description:');
   console.log('  Sync Atris workspace files from the installed CLI templates.');
+  console.log('  Default is plan-only: print the file list and exit without writing.');
+  console.log('  Pass --yes to apply writes. Non-TTY sessions without --yes exit 2.');
   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('  --yes, -y    Apply the planned writes.');
+  console.log('  --force      Overwrite existing template files where supported (with --yes).');
   if (commandName === 'update') {
     console.log('  --self       Update the installed atris cli from npm (packaged installs only).');
   }
@@ -852,9 +964,11 @@ function showUpgradeHelp() {
 function showReleaseHelp() {
   console.log('');
   console.log('Usage: atris release [--dry-run]');
+  console.log('       atris release preflight');
   console.log('');
   console.log('Description:');
   console.log('  Draft or publish a release from local git history.');
+  console.log('  preflight checks master, a clean tree, origin/master, the version tag, and the full test suite with CI=true.');
   console.log('');
   console.log('Options:');
   console.log('  --dry-run    Print the planned release without committing, tagging, or pushing.');
@@ -864,9 +978,9 @@ function showReleaseHelp() {
 
 function showAuthHelp(commandName) {
   const usage = {
-    login: 'Usage: atris login [--token <token>] [--force]',
+    login: 'Usage: atris login [--token <token>] [--force] [--agent]',
     logout: 'Usage: atris logout',
-    whoami: 'Usage: atris whoami',
+    whoami: 'Usage: atris whoami [--json]',
     switch: 'Usage: atris switch [account] [--global]',
     use: 'Usage: atris use [account]',
     accounts: 'Usage: atris accounts [add|remove <account>|remove --all]',
@@ -877,6 +991,7 @@ function showAuthHelp(commandName) {
   console.log('Description:');
   if (commandName === 'login') {
     console.log('  Sign in with browser OAuth or a pasted API token.');
+    console.log('  --agent mints a scoped agent token from stored credentials. No browser.');
   } else if (commandName === 'logout') {
     console.log('  Sign out of the current Atris account.');
   } else if (commandName === 'whoami') {
@@ -891,8 +1006,11 @@ function showAuthHelp(commandName) {
   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.');
+    console.log('  --token <token>           Save an API token without prompting.');
+    console.log('  --force, -f               Re-run login even if credentials already exist.');
+    console.log('  --agent                   Mint a scoped agent token from the stored login.');
+    console.log('  --scopes <list>           Comma-separated scopes (default: x-search,youtube).');
+    console.log('  --daily-credit-cap <n>    Daily credit cap (default: 50).');
   } else if (commandName === 'switch') {
     console.log('  --global, -g     Switch the account for all terminals.');
   }
@@ -1002,7 +1120,7 @@ function showAutopilotHelp() {
 }
 
 if (command === 'help' || command === '--help' || command === '-h') {
-  showHelp();
+  showHelp({ args: process.argv.slice(3) });
   process.exit(0);
 }
 
@@ -1043,26 +1161,20 @@ if (isSpecFile(command)) {
 
 // --version flag (works anywhere: atris --version, atris -v)
 if (command === '--version' || command === '-v' || process.argv.includes('--version')) {
-  console.log(`atris v${CLI_VERSION}`);
+  console.log(formatCliVersionLine(CLI_VERSION, path.join(__dirname, '..')));
   process.exit(0);
 }
 
 // If no command OR command is not recognized, treat as natural language
 // Voice-friendly aliases — natural language → command mapping
 // Solves speech-to-text issues (inspired by gstack v0.14.6 voice-triggers)
-const START_MISSION_OBJECTIVE = 'self improve goal after goal: pick one useful bounded mission from current Atris state, run proof, and continue only with real next work';
-
+// One-word voice aliases like start/go/audit/deploy must not spawn runners.
+// Unmatched single verbs exit 2 with did-you-mean (see below). Keep phrases
+// that name a real command without overnight side effects.
 const voiceTriggers = {
-  'start': '_start',
-  'start now': '_start',
-  'go': '_start',
-  'keep going': '_start',
-  'keepgoing': '_start',
-  'keep-going': '_start',
   'review my code': 'code-review',
   'check my code': 'code-review',
   'run a review': 'code-review',
-  'audit': 'code-review',
   'create a business': 'business',
   'start a business': 'business',
   'new business': 'business',
@@ -1072,7 +1184,6 @@ const voiceTriggers = {
   'what is going on': 'radar',
   'run tests': 'verify',
   'check health': 'status',
-  'deploy': 'business',
   'show my businesses': 'business',
   'pull latest': 'pull',
   'push changes': 'push',
@@ -1080,6 +1191,17 @@ const voiceTriggers = {
   'what did i learn': 'learn',
 };
 
+// -h/--help/help on argv[1] (including voice words like start) is usage
+// + exit 2 before NL and before _start. Never file a task titled a flag.
+if (command && !knownCommands.includes(command) && argsWantHelp(process.argv.slice(2))) {
+  if (String(command).toLowerCase() === 'start') showStartHelp();
+  else {
+    showHelpShort();
+    console.log('Usage: atris help');
+  }
+  process.exit(2);
+}
+
 if (!command || !knownCommands.includes(command)) {
   // Check voice triggers before falling through to natural language
   const fullInput = process.argv.slice(2).join(' ').toLowerCase().trim();
@@ -1099,11 +1221,31 @@ if (!command || !knownCommands.includes(command)) {
 if (!command || !knownCommands.includes(command)) {
   const rawNaturalArgs = process.argv.slice(2);
   const natural = parseNaturalEntryArgs(rawNaturalArgs);
+  if (command && isBareAtrisFlag(command)) {
+    command = '';
+  }
   const userInput = natural.input;
-  const directSingleWordNatural = !natural.multiword
-    && SINGLE_WORD_NATURAL_INTENTS.has(userInput.toLowerCase());
 
-  if (natural.asJson && !natural.multiword && !directSingleWordNatural) {
+  // An unmatched first token that looks like a command (or a typo of one)
+  // is not a request to create work, even when extra args follow
+  // (`atris taks list`). A lone verb (`atris build`) is also unknown:
+  // never mint a task from argv[1]. Quoted sentences (`atris "build
+  // the site"`), multiword phrases (`atris build a thing`), task new,
+  // and wish still create work.
+  const firstToken = String((natural.positionals && natural.positionals[0]) || command || '').trim();
+  const firstLooksLikeCommand = Boolean(firstToken) && !/\s/.test(firstToken);
+  const firstIsWorkVerb = SINGLE_WORD_NATURAL_INTENTS.has(firstToken.toLowerCase());
+  // `atris test` is the documented first-minute alias, not an unknown command
+  // and not a new first task. Extra words (`atris test the login`) still
+  // create work once MAP is real.
+  const firstMinuteAlias = firstToken.toLowerCase() === 'test' && !natural.multiword;
+  const unknownCommandToken = Boolean(command)
+    && firstLooksLikeCommand
+    && !knownCommands.includes(firstToken)
+    && !firstMinuteAlias
+    && (!natural.multiword || !firstIsWorkVerb);
+
+  if (unknownCommandToken && natural.asJson) {
     console.log(JSON.stringify({
       ok: false,
       error: command ? `unknown command: ${command}` : 'unknown command',
@@ -1114,18 +1256,26 @@ if (!command || !knownCommands.includes(command)) {
     process.exit(2);
   }
 
-  // Warn if this looks like a mistyped single-word command (no spaces)
-  if (command && !natural.multiword && !directSingleWordNatural) {
-    console.log(`⚠ Unknown command: "${command}". Run "atris help" for available commands.`);
-    const suggestion = suggestCommand(command);
-    if (suggestion) {
-      console.log(`  Did you mean "atris ${suggestion}"?`);
+  if (unknownCommandToken) {
+    const suggestions = suggestCommands(command);
+    console.error(`Unknown command: "${command}". Run "atris help" for available commands.`);
+    if (suggestions.length) {
+      console.error(`Did you mean ${suggestions.map((name) => `"atris ${name}"`).join(' or ')}?`);
+    } else {
+      console.error('To create work from a sentence, run: atris "<request>" (quoted), or atris task new / atris wish.');
     }
-    console.log('  Treating as natural language input...\n');
+    process.exit(2);
   }
 
   // Launch interactive entry (the "Performance")
-  interactiveEntry(userInput, { oneLap: true, asJson: natural.asJson, engine: natural.engine, verifier: natural.verifier, optionError: natural.error })
+  interactiveEntry(firstMinuteAlias ? '' : userInput, {
+    oneLap: true,
+    asJson: natural.asJson,
+    engine: natural.engine,
+    verifier: natural.verifier,
+    optionError: natural.error,
+    firstMinuteAlias,
+  })
     .then((code) => process.exit(Number.isInteger(code) ? code : 0))
     .catch((error) => {
       console.error(`✗ Error: ${error.message || error}`);
@@ -1149,7 +1299,12 @@ function printAtrisOverview() {
 }
 
 function useInteractiveAtrisUi() {
-  return Boolean(process.stdin.isTTY && process.stdout.isTTY && !process.env.ATRIS_NO_INTERACTIVE);
+  return Boolean(
+    process.stdin.isTTY
+    && process.stdout.isTTY
+    && !process.env.ATRIS_NO_INTERACTIVE
+    && process.env.ATRIS_NONINTERACTIVE !== '1'
+  );
 }
 
 function initNonInteractiveFlag() {
@@ -1189,21 +1344,44 @@ function printFirstUseNext() {
   console.log(`Then: ${firstUseCommand()}`);
 }
 
-function printStarterTaskNext(starter) {
-  console.log('next setup: open atris/MAP.md, then claim the starter task.');
-  if (starter && starter.display_id) {
-    console.log(`Next: atris task claim ${starter.display_id} --as ${localOwnerName()}`);
-    return;
-  }
-  console.log('Next: atris task next --as ' + localOwnerName());
+function runMinimalInit() {
+  const script = process.argv[1] || path.join(__dirname, 'atris.js');
+  const result = spawnSync(process.execPath, [script, 'init', '--minimal', '--yes'], {
+    cwd: process.cwd(),
+    env: process.env,
+    encoding: 'utf8',
+    stdio: 'inherit',
+  });
+  return Number.isInteger(result.status) ? result.status : 1;
+}
+
+function printFirstMinuteScreen(options) {
+  const screen = buildFirstMinute(options);
+  console.log('');
+  console.log(screen.text);
+  return screen;
 }
 
 async function interactiveEntry(userInput, options = {}) {
   const workspaceDir = process.cwd();
   const state = detectWorkspaceState(workspaceDir);
+
+  // Fresh folder is the first-minute product: one next command, no menu.
+  if (state.state === 'fresh') {
+    if (options.asJson) {
+      console.log(JSON.stringify(freshMinuteJson(), null, 2));
+      return 2;
+    }
+    if (shouldAutoInitFresh(process.argv.slice(2))) {
+      return runMinimalInit();
+    }
+    printFirstMinuteScreen({ root: workspaceDir, fresh: true });
+    return 0;
+  }
+
   const context = loadContext(workspaceDir);
 
-  if (options.asJson && !String(userInput || '').trim()) {
+  if (options.asJson && !String(userInput || '').trim() && !options.firstMinuteAlias) {
     console.log(JSON.stringify({
       schema: 'atris.one_lap.v1',
       ok: false,
@@ -1229,25 +1407,6 @@ async function interactiveEntry(userInput, options = {}) {
     return;
   }
 
-  // Fresh install - offer init
-  if (state.state === 'fresh') {
-    if (options.asJson) {
-      console.log(JSON.stringify({
-        schema: 'atris.one_lap.v1',
-        ok: false,
-        status: 'stuck',
-        reason: 'this workspace is not initialized',
-        next_action: 'atris init --yes',
-      }, null, 2));
-      return 2;
-    }
-    console.log('\nNo atris/ folder found.');
-    console.log('');
-    console.log('Next: atris init');
-    console.log('Local project install instead? Run: npx atris init');
-    return;
-  }
-
   // Ensure today's journal exists (so "atris" always has somewhere to write/read)
   try {
     ensureLogDirectory();
@@ -1302,6 +1461,29 @@ async function interactiveEntry(userInput, options = {}) {
     return 2;
   }
 
+  // Placeholder or missing MAP is already a first-minute job. Do not send the
+  // operator to a rewrite lobby, and do not treat `test` as a new first task.
+  if (mapStatus !== 'ready') {
+    const screenOptions = {
+      root: workspaceDir,
+      context,
+      missions: activeMissions,
+    };
+    if (options.asJson) {
+      const screen = buildFirstMinute(screenOptions);
+      console.log(JSON.stringify({
+        schema: 'atris.one_lap.v1',
+        ok: false,
+        status: 'stuck',
+        reason: 'the generate-map task is already waiting',
+        next_action: screen.nextCommand,
+      }, null, 2));
+      return 2;
+    }
+    printFirstMinuteScreen(screenOptions);
+    return 0;
+  }
+
   if (userInput && mapStatus === 'ready' && !gatherContext && options.oneLap !== false) {
     return require('../commands/one-lap').runOneLap(userInput, {
       root: workspaceDir,
@@ -1316,75 +1498,17 @@ async function interactiveEntry(userInput, options = {}) {
       schema: 'atris.one_lap.v1',
       ok: false,
       status: 'stuck',
-      reason: mapStatus !== 'ready' ? 'the workspace map is not ready' : 'first-contact context is required',
-      next_action: mapStatus !== 'ready' ? 'atris init --yes' : 'atris "<first direction>"',
+      reason: 'first-contact context is required',
+      next_action: 'atris "<first direction>"',
     }, null, 2));
     return 2;
   }
-  // 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 = [];
-  if (wipCount > 0) {
-    parts.push(`work in progress: ${wipCount}`);
-  }
-  if (liveMissionsCount > 0) {
-    parts.push(`missions: ${liveMissionsCount}`);
-  }
-  if (inboxCount > 0) {
-    parts.push(`inbox: ${inboxCount}`);
-  }
-  if (backlogCount > 0) {
-    parts.push(`backlog: ${backlogCount}`);
-  }
-  if (completedTasksCount > 0) {
-    parts.push(`done: ${completedTasksCount}`);
-  }
-  const statusLine = parts.length > 0 ? parts.join('  |  ') : 'clean slate';
+  const hasRequest = Boolean(String(userInput || '').trim());
 
-  console.log('');
-  const contextRow = (label, value) => `  ${label.padEnd(9)}${value}`;
-  console.log(contextRow('context', 'loaded'));
-  console.log(contextRow('status', statusLine));
-
-  if (gatherContext) {
-    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('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') {
-        printStarterTaskNext(starter);
-        return;
-      }
-      await planCmd(answer);
-      return;
-    }
-    if (shouldSkipContextGatherer()) {
-      console.log('');
-      if (process.argv.includes('--verbose')) {
-        console.log('context gatherer skipped (non-interactive).');
-      }
-      printFirstUseNext();
-      return;
-    } else {
+  // Bare `atris` is the first-minute screen: one win, one next command.
+  // Interactive first-contact still asks once when the folder has no work yet.
+  if (!hasRequest) {
+    if (gatherContext && !shouldSkipContextGatherer()) {
       const answer = await askContextGatherer(workspaceDir);
       if (isAtrisMetaQuestion(answer)) {
         printAtrisOverview();
@@ -1406,105 +1530,39 @@ async function interactiveEntry(userInput, options = {}) {
       } else if (starter && starter.title) {
         console.log(`First task: ${starter.title}`);
       }
-      if (mapStatus !== 'ready') {
-        printStarterTaskNext(starter);
-        return;
-      }
       await planCmd(answer);
       return;
     }
+    printFirstMinuteScreen({
+      root: workspaceDir,
+      context,
+      missions: activeMissions,
+    });
+    return 0;
   }
 
-  if (mapStatus !== 'ready') {
-    printMapBootstrap({ userInput });
-    return;
-  }
-
-  // Hot start - user provided input directly
-  if (userInput) {
-    console.log(`\n> ${userInput}`);
-    await planCmd(userInput);
-    return;
-  }
-
-  // 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 (history):');
-      preview.forEach((t) => console.log(`- ${t}`));
-      console.log('Completed tasks are history, not pending review.');
-    }
-  }
-
-  if (wipCount > 0 || backlogCount > 0) {
-    const featurePreview = Array.isArray(context.inProgressFeatures) ? context.inProgressFeatures : [];
-    const inProgressPreview = context.inProgressTasks.slice(0, 2).map((t) => (t.length > 70 ? `${t.slice(0, 67)}...` : t));
-    const backlogPreview = context.backlogTasks.slice(0, 2).map((t) => (t.length > 70 ? `${t.slice(0, 67)}...` : t));
-    if (featurePreview.length > 0) {
-      console.log(`\nIn-progress features: ${featurePreview.join(', ')}`);
-    }
-    if (inProgressPreview.length > 0) {
-      console.log('\nIn Progress (preview):');
-      inProgressPreview.forEach((t) => console.log(`- ${t}`));
-    }
-    if (backlogPreview.length > 0) {
-      console.log('\nBacklog (preview):');
-      backlogPreview.forEach((t) => console.log(`- ${t}`));
+  if (gatherContext) {
+    const answer = String(userInput || '').trim();
+    if (isAtrisMetaQuestion(answer)) {
+      printAtrisOverview();
+      return;
     }
-    console.log('\nNext: atris do (work ready to execute)');
-    await doCmd();
-    return;
-  }
-
-  if (inboxCount > 0) {
-    const preview = context.inboxItems.slice(0, 3).map((t) => (t.length > 70 ? `${t.slice(0, 67)}...` : t));
-    if (preview.length > 0) {
-      console.log('\nInbox (preview):');
-      preview.forEach((t) => console.log(`- ${t}`));
+    const profile = saveContextProfile(workspaceDir, answer, { source: 'hot_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}`);
     }
-    console.log('\nNext: atris plan (Inbox has ideas)');
-    await planCmd();
-    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,
-    output: process.stdout
-  });
-
-  const request = await new Promise(r => rl.question('\nWhat do you want to build?\n> ', r));
-  rl.close();
-
-  if (!request.trim()) {
+    await planCmd(answer);
     return;
   }
 
-  await planCmd(request);
+  console.log(`\n> ${userInput}`);
+  await planCmd(userInput);
 }
 
 async function askContextGatherer(workspaceDir) {
@@ -1518,30 +1576,6 @@ async function askContextGatherer(workspaceDir) {
   return answer;
 }
 
-function printMapBootstrap({ userInput, prefix = 'Bootstrap required' } = {}) {
-  console.log('');
-  console.log('┌─────────────────────────────────────────────────────────────┐');
-  console.log(`│ ${String(prefix).toUpperCase().padEnd(60)}│`);
-  console.log('└─────────────────────────────────────────────────────────────┘');
-  console.log('');
-  console.log('Atris needs a real `atris/MAP.md` so future steps are grounded in the workspace.');
-  console.log('');
-  console.log('For an agent:');
-  console.log('─────────────────────────────────────────────────────────────');
-  console.log('Read `atris/atris.md`, then generate a complete `atris/MAP.md` for this repo.');
-  console.log('Rules: include file:line refs, keep it grep-friendly, do NOT change code.');
-  if (userInput) {
-    console.log('');
-    console.log('After MAP is generated, continue with:');
-    console.log(`- ${userInput}`);
-  } else {
-    console.log('');
-    console.log('Then rerun: atris');
-  }
-  console.log('─────────────────────────────────────────────────────────────');
-  console.log('');
-}
-
 // Boot status: plain rows, honest numbers, one next action.
 // The banner only renders in a real terminal; when a hook or agent captures
 // this output it stays compact so it costs almost nothing in context.
@@ -1787,40 +1821,10 @@ if (command === 'init') {
       console.error(`✗ Error: ${error.message || error}`);
       process.exit(1);
     });
-} else if (command === '_start') {
-  const args = process.argv.slice(3);
-  if (args.includes('--help') || args.includes('-h') || args[0] === 'help') {
-    console.log('');
-    console.log('Usage: atris start [options]');
-    console.log('');
-    console.log('Starts the durable mission loop for one useful self-improvement mission.');
-    console.log('');
-    console.log('Options:');
-    console.log('  --json       Print the mission route without starting it.');
-    console.log('  --owner X    Override mission owner.');
-    console.log('  --cadence X  Override mission cadence.');
-    console.log('');
-    process.exit(0);
-  }
-
-  if (args.includes('--json')) {
-    console.log(JSON.stringify({
-      ok: true,
-      action: 'start_mission_run',
-      route: `atris mission run "${START_MISSION_OBJECTIVE}"`,
-      reason: 'casual_launch',
-      objective: START_MISSION_OBJECTIVE,
-      expected_loop: 'mission_run',
-    }, null, 2));
-    process.exit(0);
-  }
-
-  Promise.resolve(require('../commands/mission').missionCommand(['run', START_MISSION_OBJECTIVE, ...args]))
-    .then(() => process.exit(process.exitCode || 0))
-    .catch((error) => {
-      console.error(`✗ Start failed: ${error.message || error}`);
-      process.exit(1);
-    });
+} else if (command === 'install' || command === 'workspace') {
+  const { installCommand } = require('../commands/install');
+  const code = installCommand(process.argv.slice(3), { verb: command });
+  process.exit(typeof code === 'number' ? code : 0);
 } else if (command === 'task') {
   // SQLite-backed task plane. ~/.atris/tasks.db, gitignored, per-workspace.
   Promise.resolve(require('../commands/task').run(process.argv.slice(3)))
@@ -1916,9 +1920,20 @@ if (command === 'init') {
     .then((code) => process.exit(code || 0))
     .catch((err) => { console.error(`\n✗ Error: ${err.message || err}`); process.exit(1); });
 } else if (command === 'land') {
-  Promise.resolve(require('../commands/land').landCommand(process.argv.slice(3)))
+  // landCommand can throw synchronously on empty repos; wrap so callers get a
+  // one-line error instead of an uncaught stack from Promise.resolve(fn()).
+  Promise.resolve()
+    .then(() => 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); });
+    .catch((err) => {
+      const msg = String(err && err.message || err || '');
+      if (/no master\/main|no commits|not a git/i.test(msg)) {
+        console.error(msg);
+      } else {
+        console.error(`land: ${msg}`);
+      }
+      process.exit(1);
+    });
 } else if (command === 'caretaker') {
   Promise.resolve(require('../commands/caretaker').caretakerCommand(process.argv.slice(3)))
     .then((code) => process.exit(typeof code === 'number' ? code : 0))
@@ -1956,7 +1971,7 @@ if (command === 'init') {
 } else if (command === 'truth') {
   // Truth: one table rolling up mission state, tasks, feature proof receipts, and loop heartbeats.
   Promise.resolve(require('../commands/truth').truthCommand(process.argv.slice(3)))
-    .then((code) => process.exit(code || 0))
+    .then((code) => process.exit(typeof code === 'number' ? 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)))
@@ -1978,12 +1993,20 @@ if (command === 'init') {
     .then((code) => process.exit(typeof code === 'number' ? code : 0))
     .catch((err) => { console.error(`\n✗ Error: ${err.message || err}`); process.exit(1); });
 } else if (command === 'rainmaker') {
-  const code = require('../commands/rainmaker').rainmakerCommand(process.argv.slice(3));
-  process.exit(typeof code === 'number' ? code : 0);
+  {
+    const gate = requireAccountBound(process.argv.slice(3));
+    if (!gate.ok) process.exit(refuseAccountGlobal());
+    const code = require('../commands/rainmaker').rainmakerCommand(gate.args);
+    process.exit(typeof code === 'number' ? code : 0);
+  }
 } else if (command === 'avail') {
-  Promise.resolve(require('../commands/avail').availCommand(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); });
+  {
+    const gate = requireAccountBound(process.argv.slice(3));
+    if (!gate.ok) process.exit(refuseAccountGlobal());
+    Promise.resolve(require('../commands/avail').availCommand(gate.args))
+      .then((code) => process.exit(typeof code === 'number' ? code : 0))
+      .catch((err) => { console.error(`\n✗ Error: ${err.message || err}`); process.exit(1); });
+  }
 } else if (command === 'meet') {
   Promise.resolve(require('../commands/meet').meetCommand(process.argv.slice(3)))
     .then((code) => process.exit(typeof code === 'number' ? code : 0))
@@ -1991,7 +2014,7 @@ if (command === 'init') {
 } else if (command === 'brain') {
   Promise.resolve()
     .then(() => require('../commands/brain').brainCommand(process.argv.slice(3)))
-    .then(() => process.exit(0))
+    .then((code) => process.exit(typeof code === 'number' ? code : 0))
     .catch((err) => {
       const message = err.message || String(err);
       if (process.argv.slice(3).includes('--json')) {
@@ -2002,9 +2025,17 @@ if (command === 'init') {
       process.exit(1);
     });
 } else if (command === 'agent') {
-  agentAtris().then(() => process.exit(0)).catch((err) => { console.error(`\n✗ Error: ${err.message || err}`); process.exit(1); });
+  {
+    const gate = requireAccountBound(process.argv.slice(3));
+    if (!gate.ok) process.exit(refuseAccountGlobal());
+    // Re-slice argv so agentAtris sees args without --account.
+    process.argv = [process.argv[0], process.argv[1], 'agent', ...gate.args];
+    agentAtris().then(() => process.exit(0)).catch((err) => { console.error(`\n✗ Error: ${err.message || err}`); process.exit(1); });
+  }
 } else if (command === 'log') {
-  const subcommand = process.argv[3];
+  const logArgs = process.argv.slice(3);
+  const subcommand = logArgs[0];
+  const positional = logArgs.filter((arg) => !String(arg).startsWith('-'));
   if (subcommand === 'sync') {
     require('../commands/log-sync').logSyncAtris()
       .then(() => process.exit(0))
@@ -2013,15 +2044,22 @@ if (command === 'init') {
         process.exit(1);
       });
   } else if (subcommand === '--help' || subcommand === '-h' || subcommand === 'help') {
-    console.log('Usage: atris log [business-slug | sync | help]');
+    console.log('Usage: atris log ["note"] | --repl | sync | <business-slug> | 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 "an idea"      Append a note to today\'s ## Inbox');
+    console.log('  atris log --repl         Open today\'s journal REPL');
+    console.log('  atris log                Open the REPL (needs a terminal)');
     console.log('  atris log sync           Sync the local journal to cloud');
+    console.log('  atris log <slug>         Show business log history (single slug token)');
+    console.log('  atris wish "..."         Headless inbox write; add --json --no-mission for agents');
     process.exit(0);
-  } else if (subcommand && !subcommand.startsWith('-')) {
-    // Business log: atris log <business-slug>
-    require('../commands/context-sync').businessLog(subcommand)
+  } else if (
+    positional.length === 1
+    && !logArgs.includes('--repl')
+    && /^[a-z0-9][a-z0-9_-]{0,63}$/i.test(positional[0])
+  ) {
+    // Business log: atris log <business-slug> (single slug token only)
+    require('../commands/context-sync').businessLog(positional[0])
       .then(() => process.exit(0))
       .catch((err) => { console.error(`\n✗ Error: ${err.message || err}`); process.exit(1); });
   } else {
@@ -2090,13 +2128,15 @@ if (command === 'init') {
       .catch((err) => { console.error(`\n✗ Error: ${err.message || err}`); process.exit(1); });
   } else if (process.argv.includes('--all')) {
     const dryRun = process.argv.includes('--dry-run');
-    const force = process.argv.includes('--force') || process.argv.includes('--yes') || process.argv.includes('-y');
-    Promise.resolve(syncAllCmd({ dryRun, force }))
+    const yes = process.argv.includes('--yes') || process.argv.includes('-y');
+    const force = process.argv.includes('--force') || yes;
+    Promise.resolve(syncAllCmd({ dryRun, force, yes }))
       .then(() => process.exit(0))
       .catch((err) => { console.error(`\n✗ Error: ${err.message || err}`); process.exit(1); });
   } else {
     syncCmd({
       dryRun: args.includes('--dry-run'),
+      yes: args.includes('--yes') || args.includes('-y'),
       force: args.includes('--force') || args.includes('--yes') || args.includes('-y'),
     });
   }
@@ -2140,6 +2180,14 @@ if (command === 'init') {
     showServeHelp();
     process.exit(0);
   }
+  const { refuseHeadlessUnless } = require('../lib/noninteractive');
+  if (refuseHeadlessUnless(serveArgs, {
+    allowYes: false,
+    allowOnce: true,
+    usage: 'Usage: atris serve [--agent <id>] [--allow-bash] [--once <op_id>]\nHeadless serve needs --once <op_id>.',
+  })) {
+    process.exit(2);
+  }
   const serveOptions = {};
   for (let i = 0; i < serveArgs.length; i++) {
     if (serveArgs[i] === '--agent' && serveArgs[i + 1]) {
@@ -2147,6 +2195,9 @@ if (command === 'init') {
       i++;
     } else if (serveArgs[i] === '--allow-bash') {
       serveOptions.allowBash = true;
+    } else if (serveArgs[i] === '--once' && serveArgs[i + 1]) {
+      serveOptions.once = serveArgs[i + 1];
+      i++;
     }
   }
   require('../commands/serve').serveAtris(serveOptions)
@@ -2155,7 +2206,7 @@ if (command === 'init') {
       process.exit(1);
     });
 } else if (command === 'version') {
-  require('../commands/version').showVersion();
+  require('../commands/version').showVersion(process.argv.slice(3));
 } else if (command === 'login') {
   const args = process.argv.slice(3);
   if (args.includes('--help') || args.includes('-h') || args[0] === 'help') {
@@ -2197,7 +2248,23 @@ if (command === 'init') {
     showAuthHelp('accounts');
     process.exit(0);
   }
-  require('../commands/auth').accountsCmd();
+  require('../commands/auth').accountsCmd(args);
+} else if (command === 'balance') {
+  Promise.resolve(require('../commands/balance').balanceCommand(process.argv.slice(3)))
+    .then((code) => process.exit(typeof code === 'number' ? code : 0))
+    .catch((err) => { console.error(String(err.message || err).replace(/\s+/g, ' ')); process.exit(1); });
+} else if (command === 'usage') {
+  Promise.resolve(require('../commands/usage').usageCommand(process.argv.slice(3)))
+    .then((code) => process.exit(typeof code === 'number' ? code : 0))
+    .catch((err) => { console.error(String(err.message || err).replace(/\s+/g, ' ')); process.exit(1); });
+} else if (command === 'api-key') {
+  Promise.resolve(require('../commands/api-key').apiKeyCommand(process.argv.slice(3)))
+    .then((code) => process.exit(typeof code === 'number' ? code : 0))
+    .catch((err) => { console.error(String(err.message || err).replace(/\s+/g, ' ')); process.exit(1); });
+} else if (command === 'topup') {
+  Promise.resolve(require('../commands/topup').topupCommand(process.argv.slice(3)))
+    .then((code) => process.exit(typeof code === 'number' ? code : 0))
+    .catch((err) => { console.error(String(err.message || err).replace(/\s+/g, ' ')); process.exit(1); });
 } else if (command === '_resolve') {
   // Hidden: resolve a profile name query → print exact profile name
   require('../commands/auth').resolveProfile();
@@ -2220,6 +2287,10 @@ if (command === 'init') {
   require('../commands/youtube').youtubeCommand(process.argv.slice(3))
     .then(() => exitWhenFlushed(0))
     .catch((err) => { console.error(`\n✗ Error: ${err.message || err}`); exitWhenFlushed(1); });
+} else if (command === 'x-search') {
+  require('../commands/x-search').xSearchCommand(process.argv.slice(3))
+    .then((code) => exitWhenFlushed(Number.isInteger(code) ? code : 0))
+    .catch((err) => { console.error(`\n✗ Error: ${err.message || err}`); exitWhenFlushed(1); });
 } else if (command === 'run') {
   const args = process.argv.slice(3);
   if (args[0] === 'logs') {
@@ -2536,6 +2607,14 @@ if (command === 'init') {
     process.exit(0);
   }
   require('../commands/analytics').analyticsAtris();
+} else if (command === 'revisions') {
+  const args = process.argv.slice(3);
+  if (args.includes('--help') || args.includes('-h') || args[0] === 'help') {
+    showRevisionsHelp();
+    process.exit(0);
+  }
+  const code = require('../commands/revisions').revisionsCommand(args);
+  process.exit(code);
 } else if (command === 'clean') {
   const args = process.argv.slice(3);
   if (args.includes('--help') || args.includes('-h')) {
@@ -2551,6 +2630,10 @@ if (command === 'init') {
       console.error(err.message || err);
       process.exit(1);
     });
+} else if (command === 'doctor') {
+  Promise.resolve(require('../commands/doctor').doctorCommand(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 === 'verify') {
   const args = process.argv.slice(3);
   if (args.includes('--help') || args.includes('-h') || args[0] === 'help') {
@@ -2584,14 +2667,19 @@ if (command === 'init') {
     const code = require('../commands/verify').verifyRubric(slug, section);
     process.exit(code);
   }
-  const taskId = process.argv[3] || null;
-  require('../commands/verify').verifyAtris(taskId);
+  const taskId = process.argv[3] && !String(process.argv[3]).startsWith('--') ? process.argv[3] : null;
+  const code = require('../commands/verify').verifyAtris(taskId);
+  process.exit(typeof code === 'number' ? code : 0);
 } else if (command === 'release') {
   const args = process.argv.slice(3);
   if (args.includes('--help') || args.includes('-h') || args[0] === 'help') {
     showReleaseHelp();
     process.exit(0);
   }
+  if (args[0] === 'preflight') {
+    const code = require('../commands/release').releasePreflight();
+    process.exit(typeof code === 'number' ? code : 1);
+  }
   const dryRun = process.argv.includes('--dry-run');
   require('../commands/release').releaseAtris({ dryRun })
     .then(() => process.exit(0))
@@ -2647,12 +2735,23 @@ if (command === 'init') {
   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];
-  const args = process.argv.slice(4);
-  gmailCommand(subcommand, ...args)
-    .then(() => process.exit(0))
-    .catch((err) => { console.error(`✗ Error: ${err.message || err}`); process.exit(1); });
+  {
+    const raw = process.argv.slice(3);
+    const { gmailCommand, extractGmailMailboxAccount } = require('../commands/integrations');
+    const mailbox = extractGmailMailboxAccount(raw);
+    const gateInput = mailbox.mailboxAccountId ? ['--account', ...mailbox.args] : mailbox.args;
+    const gate = requireAccountBound(gateInput);
+    if (!gate.ok) {
+      process.exit(refuseAccountGlobal());
+      return;
+    }
+    const subcommand = gate.args[0];
+    const args = gate.args.slice(1);
+    if (mailbox.mailboxAccountId) args.push('--account', mailbox.mailboxAccountId);
+    gmailCommand(subcommand, ...args)
+      .then(() => process.exit(process.exitCode || 0))
+      .catch((err) => { console.error(`✗ Error: ${err.message || err}`); process.exit(1); });
+  }
 } else if (command === 'calendar') {
   const { calendarCommand } = require('../commands/integrations');
   const subcommand = process.argv[3];
@@ -2661,19 +2760,30 @@ if (command === 'init') {
     .then(() => process.exit(0))
     .catch((err) => { console.error(`✗ Error: ${err.message || err}`); process.exit(1); });
 } else if (command === 'twitter') {
-  const { twitterCommand } = require('../commands/integrations');
-  const subcommand = process.argv[3];
-  const args = process.argv.slice(4);
-  twitterCommand(subcommand, ...args)
-    .then(() => process.exit(0))
-    .catch((err) => { console.error(`✗ Error: ${err.message || err}`); process.exit(1); });
+  {
+    const raw = process.argv.slice(3);
+    const helpOnly = raw.length === 0 || raw.includes('--help') || raw.includes('-h') || raw[0] === 'help';
+    const gate = helpOnly ? { ok: true, args: raw } : requireAccountBound(raw);
+    if (!gate.ok) process.exit(refuseAccountGlobal());
+    const { twitterCommand } = require('../commands/integrations');
+    const subcommand = gate.args[0];
+    const args = gate.args.slice(1);
+    twitterCommand(subcommand, ...args)
+      .then(() => process.exit(0))
+      .catch((err) => { console.error(`✗ Error: ${err.message || err}`); process.exit(1); });
+  }
 } else if (command === 'slack') {
-  const { slackCommand } = require('../commands/integrations');
-  const subcommand = process.argv[3];
-  const args = process.argv.slice(4);
-  slackCommand(subcommand, ...args)
-    .then(() => process.exit(0))
-    .catch((err) => { console.error(`✗ Error: ${err.message || err}`); process.exit(1); });
+  {
+    const raw = process.argv.slice(3);
+    const gate = requireAccountBound(raw);
+    if (!gate.ok) process.exit(refuseAccountGlobal());
+    const { slackCommand } = require('../commands/integrations');
+    const subcommand = gate.args[0];
+    const args = gate.args.slice(1);
+    slackCommand(subcommand, ...args)
+      .then(() => process.exit(0))
+      .catch((err) => { console.error(`✗ Error: ${err.message || err}`); process.exit(1); });
+  }
 } else if (command === 'imessage') {
   const { imessageCommand } = require('../commands/integrations');
   const subcommand = process.argv[3];
@@ -2688,8 +2798,8 @@ if (command === 'init') {
     process.exit(0);
   }
   const { integrationsStatus } = require('../commands/integrations');
-  integrationsStatus()
-    .then(() => process.exit(0))
+  integrationsStatus(args)
+    .then((code) => process.exit(typeof code === 'number' ? code : 0))
     .catch((err) => { console.error(`✗ Error: ${err.message || err}`); process.exit(1); });
 } else if (command === 'apps') {
   // Keep APP.md app-pack operations independent from the heavier workspace boot
@@ -2714,11 +2824,13 @@ if (command === 'init') {
 } else if (command === 'teach') {
   const subcommand = process.argv[3];
   const args = process.argv.slice(4);
-  require('../commands/teach')(subcommand, ...args);
+  const teachCode = require('../commands/teach')(subcommand, ...args);
+  process.exit(typeof teachCode === 'number' ? teachCode : 0);
 } else if (command === 'skill') {
   const subcommand = process.argv[3];
   const args = process.argv.slice(4);
-  require('../commands/skill').skillCommand(subcommand, ...args);
+  const code = require('../commands/skill').skillCommand(subcommand, ...args);
+  if (Number.isInteger(code) && code !== 0) process.exitCode = code;
 } else if (command === 'member') {
   const subcommand = process.argv[3];
   const args = process.argv.slice(4);
@@ -2756,12 +2868,14 @@ if (command === 'init') {
     .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) {
+  const xArgs = process.argv.slice(3);
+  const userInput = xArgs.join(' ').trim();
+  const helpOnly = xArgs.length === 1 && (xArgs[0] === '--help' || xArgs[0] === '-h' || xArgs[0] === 'help' || xArgs[0] === '-?');
+  if (!userInput || helpOnly) {
     console.log('Usage: atris x <command>');
     console.log('Example: atris x echo "hello world"');
     console.log('Example: atris x ls -la');
-    process.exit(1);
+    process.exit(helpOnly ? 2 : 1);
   }
   require('../commands/workflow').executeAgentSDKFast(userInput);
 } else if (command === 'computer') {
@@ -2786,11 +2900,21 @@ if (command === 'init') {
     .then(() => process.exit(0))
     .catch((err) => { console.error(`\n✗ Error: ${err.message || err}`); process.exit(1); });
 } else if (command === 'business') {
-  const subcommand = process.argv[3];
-  const args = process.argv.slice(4);
-  require('../commands/business').businessCommand(subcommand, ...args)
-    .then(() => process.exit(process.exitCode || 0))
-    .catch((err) => { console.error(`\n✗ Error: ${err.message || err}`); process.exit(1); });
+  {
+    const raw = process.argv.slice(3);
+    const helpOnly = raw.length === 0
+      || raw.includes('--help')
+      || raw.includes('-h')
+      || raw[0] === 'help'
+      || raw[0] === 'quickstart';
+    const gate = helpOnly ? { ok: true, args: raw } : requireAccountBound(raw);
+    if (!gate.ok) process.exit(refuseAccountGlobal());
+    const subcommand = gate.args[0];
+    const args = gate.args.slice(1);
+    require('../commands/business').businessCommand(subcommand, ...args)
+      .then(() => process.exit(process.exitCode || 0))
+      .catch((err) => { console.error(`\n✗ Error: ${err.message || err}`); process.exit(1); });
+  }
 } else if (command === 'soul') {
   const args = process.argv.slice(3);
   require('../commands/soul').soul(args)
@@ -2875,6 +2999,11 @@ if (command === 'init') {
   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 === 'playbook') {
+  Promise.resolve()
+    .then(() => require('../commands/playbook').playbookCommand(process.argv.slice(3)))
+    .then((code) => process.exit(typeof code === 'number' ? code : 0))
+    .catch((err) => { console.error(`playbook could not continue: ${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); }
@@ -2943,9 +3072,17 @@ if (command === 'init') {
     .catch((err) => { console.error(`\n✗ Error: ${err.message || err}`); process.exit(1); });
 } else if (command === 'site') {
   // Site: beautiful static site from a folder of markdown, in the anti-slop design system.
-  Promise.resolve(require('../commands/site').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); });
+  {
+    const raw = process.argv.slice(3);
+    const deployWrite = raw[0] === 'deploy'
+      && !argsWantHelp(raw)
+      && !raw.includes('--dry-run');
+    const gate = deployWrite ? requireAccountBound(raw) : { ok: true, args: raw };
+    if (!gate.ok) process.exit(refuseAccountGlobal());
+    Promise.resolve(require('../commands/site').run(gate.args))
+      .then((code) => process.exit(typeof code === 'number' ? code : 0))
+      .catch((err) => { console.error(`\n✗ Error: ${err.message || err}`); process.exit(1); });
+  }
 } else if (command === 'theme') {
   // Theme: brand themes (.atris/theme.json) for the whole design system (deck/html/site).
   Promise.resolve(require('../commands/theme').run(process.argv.slice(3)))
@@ -3004,11 +3141,64 @@ if (command === 'init') {
     .then(() => process.exit(0))
     .catch((err) => { console.error(`\n✗ Error: ${err.message || err}`); process.exit(1); });
 } else if (command === 'feedback') {
-  require('../commands/feedback').feedbackCommand()
+  {
+    const gate = requireAccountBound(process.argv.slice(3));
+    if (!gate.ok) process.exit(refuseAccountGlobal());
+    process.argv = [process.argv[0], process.argv[1], 'feedback', ...gate.args];
+    require('../commands/feedback').feedbackCommand()
+      .then(() => process.exit(0))
+      .catch((err) => { console.error(`\n✗ Error: ${err.message || err}`); process.exit(1); });
+  }
+} else if (command === 'errors') {
+  {
+    const gate = requireAccountBound(process.argv.slice(3));
+    if (!gate.ok) process.exit(refuseAccountGlobal());
+    // Keep --account so errors can default to --local inside bound workspaces.
+    const errorArgs = gate.account ? ['--account', ...gate.args] : gate.args;
+    process.argv = [process.argv[0], process.argv[1], 'errors', ...errorArgs];
+    require('../commands/errors').errorsCommand()
+      .then(() => process.exit(0))
+      .catch((err) => { console.error(`✗ Error: ${err.message || err}`); process.exit(1); });
+  }
+} else if (command === 'social') {
+  require('../commands/social').socialCommand()
     .then(() => process.exit(0))
     .catch((err) => { console.error(`\n✗ Error: ${err.message || err}`); process.exit(1); });
-} else if (command === 'errors') {
-  require('../commands/errors').errorsCommand()
+} else if (command === 'people') {
+  require('../commands/social').peopleCommand()
+    .then(() => process.exit(0))
+    .catch((err) => { console.error(`\n✗ Error: ${err.message || err}`); process.exit(1); });
+} else if (command === 'follow') {
+  require('../commands/social').followCommand()
+    .then(() => process.exit(0))
+    .catch((err) => { console.error(`\n✗ Error: ${err.message || err}`); process.exit(1); });
+} else if (command === 'unfollow') {
+  require('../commands/social').unfollowCommand()
+    .then(() => process.exit(0))
+    .catch((err) => { console.error(`\n✗ Error: ${err.message || err}`); process.exit(1); });
+} else if (command === 'friends') {
+  require('../commands/social').friendsCommand()
+    .then(() => process.exit(0))
+    .catch((err) => { console.error(`\n✗ Error: ${err.message || err}`); process.exit(1); });
+} else if (command === 'msg') {
+  require('../commands/social').msgCommand()
+    .then(() => process.exit(0))
+    .catch((err) => { console.error(`\n✗ Error: ${err.message || err}`); process.exit(1); });
+} else if (command === 'inbox') {
+  {
+    const gate = requireAccountBound(process.argv.slice(3));
+    if (!gate.ok) process.exit(refuseAccountGlobal());
+    process.argv = [process.argv[0], process.argv[1], 'inbox', ...gate.args];
+    require('../commands/social').inboxCommand()
+      .then(() => process.exit(0))
+      .catch((err) => { console.error(`✗ Error: ${err.message || err}`); process.exit(1); });
+  }
+} else if (command === 'join') {
+  require('../commands/social').joinCommand()
+    .then(() => process.exit(0))
+    .catch((err) => { console.error(`\n✗ Error: ${err.message || err}`); process.exit(1); });
+} else if (command === 'invite') {
+  require('../commands/social').inviteCommand()
     .then(() => process.exit(0))
     .catch((err) => { console.error(`\n✗ Error: ${err.message || err}`); process.exit(1); });
 } else {