atris 3.25.2 → 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', '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'];
 
@@ -2059,6 +2056,52 @@ if (command === 'init') {
   Promise.resolve(require('../commands/compile').compileCommand(subcommand, ...args))
     .then(() => process.exit(process.exitCode || 0))
     .catch((err) => { console.error(`\n✗ Error: ${err.message || err}`); process.exit(1); });
+} else if (command === 'slop') {
+  // Slop: deterministic frontend-slop detector (no LLM). Exit 1 = slop found, for CI + the autopilot gate.
+  Promise.resolve(require('../commands/slop').slopCommand(process.argv.slice(3)))
+    .then((code) => process.exit(typeof code === 'number' ? code : 0))
+    .catch((err) => { console.error(`\n✗ Error: ${err.message || err}`); process.exit(1); });
+} else if (command === 'deck') {
+  // Deck: premium Google Slides from a plain content spec, via the Atris deck engine (anti-slop design system).
+  Promise.resolve(require('../commands/deck').run(process.argv.slice(3)))
+    .then((code) => process.exit(typeof code === 'number' ? code : 0))
+    .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); });
+} 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)))
+    .then((code) => process.exit(typeof code === 'number' ? code : 0))
+    .catch((err) => { console.error(`\n✗ Error: ${err.message || err}`); process.exit(1); });
+} else if (command === 'card') {
+  // Card: one line of text into an on-brand image (uses your theme + the design system).
+  Promise.resolve(require('../commands/card').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 === 'reel') {
+  // Reel: one line of text into a short on-brand video (an animated card; frames via Chrome + ffmpeg).
+  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);
@@ -2137,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
   });
@@ -2152,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/brain.js

@@ -32,13 +32,15 @@ const CORE_STATE_FILES = [
   'agents.jsonl',
   'approvals.jsonl',
 ];
+// Loop health measures loops that actually emit receipts. Channels with no writer
+// anywhere in the codebase were dropped so the dashboard reports real failures, not
+// never-built aspirations: "Overnight RL" duplicated the active Pulse AGI loop, and
+// "Company YC" had no data source. "Master loop" is now emitted by `atris run`.
 const LOOP_HEALTH_CHANNELS = [
   { label: 'Task plane', files: ['task_events.jsonl', 'tasks.projection.json'] },
-  { label: 'Overnight RL', files: ['overnight_rl_self_heal.jsonl'] },
   { label: 'Career XP', files: ['career_xp_receipts.jsonl', 'career_xp.projection.json', 'gm_xp.projection.json'] },
   { label: 'Master loop', files: ['master_loop_events.jsonl'] },
   { label: 'Missions', files: ['mission_events.jsonl', 'missions.jsonl'] },
-  { label: 'Company YC', files: ['company_yc_wow_events.jsonl', 'company_yc_wow_latest.json'] },
   { label: 'Codex goal', files: ['codex_goal.json'] },
   { label: 'Pulse AGI', files: ['pulse_agi_loop_receipts.jsonl'] },
 ];

package/commands/card.js

@@ -0,0 +1,121 @@
+// atris card — one line of text -> a beautiful, on-brand image (your theme).
+//
+//   atris card "Ship faster" --kind statement --theme brand --size og
+//   atris card "It just works" --kind quote --by "a happy user"
+//   atris card --kind stat --number "10x" --label "faster reviews"
+//
+// Writes an .html (always) and a .png (when headless Chrome is available).
+
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+const { execFileSync, spawnSync } = require('child_process');
+const { buildCard, SIZES, KINDS } = require('../lib/card');
+
+function parseFlags(argv) {
+  const flags = {}; const pos = [];
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === '--html-only') { flags.htmlOnly = true; continue; }
+    if (a.startsWith('--')) {
+      const key = a.slice(2);
+      const next = argv[i + 1];
+      if (next != null && !next.startsWith('--')) { flags[key] = next; i++; } else flags[key] = true;
+      continue;
+    }
+    pos.push(a);
+  }
+  return { flags, pos };
+}
+
+// find an installed Chrome/Chromium without adding a dependency
+function findChrome() {
+  if (process.env.CHROME_PATH && fs.existsSync(process.env.CHROME_PATH)) return process.env.CHROME_PATH;
+  const macApps = [
+    '/Applications/Google Chrome.app/Contents/MacOS/Google Chrome',
+    '/Applications/Chromium.app/Contents/MacOS/Chromium',
+    '/Applications/Microsoft Edge.app/Contents/MacOS/Microsoft Edge',
+  ];
+  for (const p of macApps) if (fs.existsSync(p)) return p;
+  for (const name of ['google-chrome', 'google-chrome-stable', 'chromium', 'chromium-browser', 'chrome']) {
+    const r = spawnSync('command', ['-v', name], { shell: true, encoding: 'utf8' });
+    if (r.status === 0 && r.stdout.trim()) return r.stdout.trim();
+  }
+  return null;
+}
+
+function renderPng(chrome, html, width, height, outPng) {
+  const tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'atris-card-'));
+  const htmlFile = path.join(tmp, 'card.html');
+  fs.writeFileSync(htmlFile, html);
+  const args = [
+    '--headless=new', '--disable-gpu', '--hide-scrollbars',
+    '--force-device-scale-factor=2',
+    `--window-size=${width},${height}`,
+    '--virtual-time-budget=4000',
+    `--screenshot=${outPng}`,
+    `file://${htmlFile}`,
+  ];
+  execFileSync(chrome, args, { stdio: 'ignore', timeout: 60000 });
+  return fs.existsSync(outPng);
+}
+
+function run(argv) {
+  const { flags, pos } = parseFlags(argv);
+
+  if (pos[0] === 'help' || flags.help) {
+    console.log(`\n  atris card — one line of text into an on-brand image\n
+  atris card "Your headline" [--kind statement|quote|stat] [--theme <name>] [--size og|wide|square|story]
+  flags: --sub --kicker --by --number --label --brand --version --out <file.png> --html-only\n
+  examples:
+    atris card "Design that builds itself" --kicker "Atris v3.23.0" --theme brand
+    atris card "It just works." --kind quote --by "a founder" --size square
+    atris card --kind stat --number "1260" --label "tests, all green"\n`);
+    return 0;
+  }
+
+  const text = pos.join(' ').trim();
+  const kind = flags.kind || 'statement';
+  if (!KINDS.includes(kind)) { console.error(`  unknown kind "${kind}". try: ${KINDS.join(', ')}`); return 2; }
+  if (flags.size && !SIZES[flags.size]) { console.error(`  unknown size "${flags.size}". try: ${Object.keys(SIZES).join(', ')}`); return 2; }
+  if (kind === 'stat' && !flags.number && !text) { console.error('  stat cards need --number (e.g. --number "10x")'); return 2; }
+  if (kind !== 'stat' && !text) { console.error('  give the card some text: atris card "Your headline"'); return 2; }
+
+  const spec = {
+    kind, text, headline: text,
+    theme: flags.theme, size: flags.size,
+    sub: flags.sub, kicker: flags.kicker, by: flags.by,
+    number: flags.number, label: flags.label,
+    brand: flags.brand, version: flags.version,
+  };
+
+  let card;
+  try { card = buildCard(spec); }
+  catch (e) { console.error(`  could not build card: ${e.message}`); return 1; }
+
+  const base = (flags.out ? String(flags.out).replace(/\.png$/i, '') : `card-${kind}-${card.theme}-${card.size}`);
+  const outPng = path.resolve(`${base}.png`);
+  const outHtml = path.resolve(`${base}.html`);
+  fs.writeFileSync(outHtml, card.html);
+
+  if (flags.htmlOnly) {
+    console.log(`\n  ✓ ${card.kind} card (${card.width}x${card.height}, theme ${card.theme})\n    html: ${outHtml}\n    open it, or render a png with Chrome installed.\n`);
+    return 0;
+  }
+
+  const chrome = findChrome();
+  if (!chrome) {
+    console.log(`\n  ✓ wrote html: ${outHtml}\n    no Chrome found for png. open the html, or set CHROME_PATH and re-run.\n`);
+    return 0;
+  }
+  try {
+    renderPng(chrome, card.html, card.width, card.height, outPng);
+    console.log(`\n  ✓ ${card.kind} card, ${card.width}x${card.height}, theme ${card.theme}\n    ${outPng}\n`);
+    return 0;
+  } catch (e) {
+    console.log(`\n  ! png render failed (${e.message.split('\n')[0]})\n    html is ready: ${outHtml}\n`);
+    return 0;
+  }
+}
+
+module.exports = { run };

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/deck.js

@@ -0,0 +1,184 @@
+// atris deck — generate a premium, on-brand Google Slides deck from a plain
+// content spec, using the Atris deck engine (lib/slides-deck.js). The pitch:
+// describe the deck, get the design system for free. No Arial-on-white slop.
+//
+// Usage:
+//   atris deck themes                         list design themes
+//   atris deck build <spec.json> [--title T] [--theme terminal|paper] [--update ID]
+//   atris deck sample [--theme paper]         print a starter spec to stdout
+//
+// A spec is JSON: { theme, brand:{name,accent}, slides:[ {type,...} ] }.
+// Slide types: title, statement, columns, panel, chips, bignumber, close.
+
+const fs = require('fs');
+const https = require('https');
+const os = require('os');
+const { buildDeck, THEMES } = require('../lib/slides-deck');
+const { parseMarkdownToSpec } = require('../lib/deck-from-md');
+const { mergedThemes } = require('../lib/theme');
+
+const BASE = 'api.atris.ai';
+const PFX = '/api/integrations/google-slides';
+
+function token() {
+  try { return require(os.homedir() + '/.atris/credentials.json').token; }
+  catch { return null; }
+}
+function api(method, path, body, tok) {
+  return new Promise((resolve, reject) => {
+    const data = body ? JSON.stringify(body) : null;
+    const req = https.request({ host: BASE, path: PFX + path, method,
+      headers: { Authorization: 'Bearer ' + tok, 'Content-Type': 'application/json',
+        ...(data ? { 'Content-Length': Buffer.byteLength(data) } : {}) } },
+      (res) => { let b = ''; res.on('data', (c) => (b += c)); res.on('end', () => {
+        let j; try { j = JSON.parse(b); } catch { j = b; }
+        if (res.statusCode >= 300) reject(new Error('HTTP ' + res.statusCode + ': ' + (typeof j === 'string' ? j : JSON.stringify(j)).slice(0, 600)));
+        else resolve(j); }); });
+    req.on('error', reject); if (data) req.write(data); req.end();
+  });
+}
+
+const SAMPLE = {
+  theme: 'terminal',
+  brand: { name: 'Sentinel', accent: '.' },
+  slides: [
+    { type: 'title', headline: 'Read your incidents in the **dark.**',
+      sub: "On-call shouldn't mean panic. Every alert ranked by blast radius, in one calm view.",
+      panel: { header: { title: 'Active incidents', meta: 'updated 12s ago' },
+        rows: [
+          { title: 'Checkout latency spike', sub: 'api-gateway · us-east-1', value: '42%', valueSub: 'of traffic', sev: 0, active: true },
+          { title: 'Stale read replica', sub: 'orders-db · eu-west-2', value: '8%', valueSub: 'of traffic', sev: 1 },
+          { title: 'Elevated 4xx on search', sub: 'search-svc · global', value: '1.2%', valueSub: 'of traffic', sev: 2 },
+        ], footer: { left: '3 active, 1 worth a page', right: 'View all' } } },
+    { type: 'statement', text: "On-call shouldn't mean **panic.**",
+      sub: 'So the console is calm by default. One screen, ranked by real impact.' },
+    { type: 'columns', heading: 'What makes it calm', columns: [
+      { h: 'Ranked by impact', b: 'Severity comes from real blast radius, so the top of the list is the thing to fix.' },
+      { h: 'Quiet by default', b: 'One page-worthy signal per incident. The rest stays in the log until you ask.' },
+      { h: 'Built for 3am', b: 'High contrast, keyboard-first, and readable before you are fully awake.' } ] },
+    { type: 'bignumber', number: '11 min', label: 'median time to first action', sub: 'down from 47 minutes before Sentinel.' },
+    { type: 'close', tagline: 'Read your incidents in the dark.',
+      buttons: [{ label: 'Open the console', primary: true }, { label: 'Read the docs' }], footer: 'sentinel.sh · 2026' },
+  ],
+};
+
+// shared: spec -> live deck. Returns the URL.
+async function publishDeck(spec, { title, updateId, tok }) {
+  const { requests } = buildDeck(spec, { themes: mergedThemes(THEMES) });
+  let id, firstSlide;
+  if (updateId) {
+    id = updateId;
+    const got = await api('GET', `/presentations/${id}`, null, tok);
+    const slides = got.slides || (got.presentation && got.presentation.slides) || [];
+    firstSlide = slides[0] && slides[0].objectId;
+  } else {
+    const pres = await api('POST', '/presentations', { title }, tok);
+    id = pres.presentationId || pres.id || (pres.presentation && pres.presentation.presentationId);
+    const slides = pres.slides || (pres.presentation && pres.presentation.slides) || [];
+    firstSlide = slides[0] && slides[0].objectId;
+  }
+  const reqs = firstSlide ? [...requests, { deleteObject: { objectId: firstSlide } }] : requests;
+  console.log(`  building ${spec.slides.length} slides (${spec.theme}) · ${reqs.length} ops...`);
+  await api('POST', `/presentations/${id}/batch-update`, { requests: reqs }, tok);
+  return `https://docs.google.com/presentation/d/${id}/edit`;
+}
+
+// beautiful HTML output (page or AppBlock JSON) from a content spec
+function outputHtml(spec, argv, srcLabel) {
+  const { renderHtml, renderBlock, THEMES: HTML_THEMES } = require('../lib/html-render');
+  const themes = mergedThemes(HTML_THEMES);
+  if (!themes[spec.theme]) spec.theme = 'atris';
+  const title = flag(argv, '--title');
+  if (hasFlag(argv, '--block')) {
+    console.log(JSON.stringify(renderBlock(spec, { title, themes }), null, 2));
+    return 0;
+  }
+  const html = renderHtml(spec, { title, themes });
+  const out = flag(argv, '--out');
+  if (out) { fs.writeFileSync(out, html); console.log(`\n  ✓ html written: ${out}${srcLabel ? ` (from ${srcLabel})` : ''}\n`); }
+  else process.stdout.write(html + '\n');
+  return 0;
+}
+
+async function run(argv) {
+  const sub = argv[0];
+
+  if (sub === 'from') {
+    const docPath = argv.slice(1).find((a) => !a.startsWith('-'));
+    if (!docPath) { console.error('  usage: atris deck from <doc.md> [--theme x] [--brand Name] [--build] [--title T]'); return 2; }
+    let md;
+    try { md = fs.readFileSync(docPath, 'utf8'); }
+    catch (e) { console.error(`  cannot read doc: ${e.message}`); return 2; }
+    const spec = parseMarkdownToSpec(md, { theme: flag(argv, '--theme'), brandName: flag(argv, '--brand') });
+    if (hasFlag(argv, '--html') || hasFlag(argv, '--block')) return outputHtml(spec, argv, docPath);
+    { const dt = mergedThemes(THEMES); if (!dt[spec.theme]) { console.error(`  unknown theme "${spec.theme}". try: ${Object.keys(dt).join(', ')}`); return 2; } }
+    if (!hasFlag(argv, '--build')) {
+      // default: print the spec so the PM can tweak before building
+      console.log(JSON.stringify(spec, null, 2));
+      return 0;
+    }
+    const tok = token();
+    if (!tok) { console.error('  no credentials at ~/.atris/credentials.json — run `atris login` and connect Google Drive.'); return 1; }
+    const title = flag(argv, '--title') || `${(spec.brand && spec.brand.name) || 'Atris'} deck`;
+    const url = await publishDeck(spec, { title, updateId: flag(argv, '--update'), tok });
+    console.log(`\n  ✓ deck from ${docPath} ready: ${url}\n`);
+    return 0;
+  }
+
+  if (sub === 'themes') {
+    console.log('\n  atris deck themes:\n');
+    for (const [name, t] of Object.entries(THEMES)) {
+      console.log(`  ${name.padEnd(10)} ${t.fonts.display} + ${t.fonts.body}  ·  accent ${t.color.accent}  bg ${t.color.bg}`);
+    }
+    console.log('\n  slide types: title, statement, columns, panel, chips, bignumber, close\n');
+    return 0;
+  }
+
+  if (sub === 'sample') {
+    const theme = flag(argv, '--theme') || 'terminal';
+    console.log(JSON.stringify({ ...SAMPLE, theme }, null, 2));
+    return 0;
+  }
+
+  if (sub === 'build') {
+    const specPath = argv.slice(1).find((a) => !a.startsWith('-'));
+    if (!specPath) { console.error('  usage: atris deck build <spec.json> [--title T] [--theme x] [--update ID]'); return 2; }
+    let spec;
+    try { spec = JSON.parse(fs.readFileSync(specPath, 'utf8')); }
+    catch (e) { console.error(`  cannot read spec: ${e.message}`); return 2; }
+    const themeOverride = flag(argv, '--theme'); if (themeOverride) spec.theme = themeOverride;
+    if (hasFlag(argv, '--html') || hasFlag(argv, '--block')) return outputHtml(spec, argv, specPath);
+    { const dt = mergedThemes(THEMES); if (!dt[spec.theme]) { console.error(`  unknown theme "${spec.theme}". try: ${Object.keys(dt).join(', ')}`); return 2; } }
+    const title = flag(argv, '--title') || `${(spec.brand && spec.brand.name) || 'Atris'} deck`;
+
+    const tok = token();
+    if (!tok) { console.error('  no credentials at ~/.atris/credentials.json — run `atris login` and connect Google Drive.'); return 1; }
+
+    const url = await publishDeck(spec, { title, updateId: flag(argv, '--update'), tok });
+    console.log(`\n  ✓ deck ready: ${url}\n`);
+    return 0;
+  }
+
+  console.log(`
+  atris deck — premium Google Slides from a plain content spec or a markdown doc
+
+    atris deck from doc.md [--build] [--title T]   turn a markdown doc into a deck
+    atris deck from doc.md --html --out page.html  beautiful HTML page (theme: atris|terminal|paper)
+    atris deck from doc.md --block                 emit the AppBlock JSON for a web app
+    atris deck sample [--theme paper] > my.json    start from a sample spec
+    atris deck build my.json [--title "Q3 review"] create the deck, print the URL
+    atris deck build my.json --html --out p.html   render the spec as HTML instead of slides
+    atris deck themes                              list design themes
+
+  'from' maps headings to slides (## with bullets -> columns, "**X** label" -> a
+  big number, Close -> a closing slide). Without --build it prints the spec to tweak.
+  Design system is baked in: distinctive fonts, one accent, real data panels, and
+  no AI tells (em dashes sanitized, sentence-case labels, no gradient text).
+`);
+  return 0;
+}
+
+function flag(argv, name) { const i = argv.indexOf(name); return i !== -1 ? argv[i + 1] : null; }
+function hasFlag(argv, name) { return argv.includes(name); }
+
+module.exports = { run, SAMPLE, publishDeck };