atris 3.25.1 → 3.26.0

package/commands/skill.js

@@ -622,15 +622,19 @@ curl -s "https://api.atris.ai/api/integrations/YOUR_INTEGRATION/items" \\
 // --- CREATE subcommand ---
 
 function skillCreate(nameArg, ...flags) {
-  if (!nameArg) {
-    console.error('Usage: atris skill create <name> [--integration] [--description="..."] [--local]');
-    console.error('');
-    console.error('Examples:');
-    console.error('  atris skill create daily-standup');
-    console.error('  atris skill create email-outreach --integration');
-    console.error('  atris skill create example-co/bol-processor --integration');
-    console.error('  atris skill create my-skill --local     # project only, skip system dirs');
-    process.exit(1);
+  // A flag-shaped first arg is not a skill name (e.g. `skill create --help`);
+  // show usage instead of creating a junk folder named "--help".
+  const wantsHelp = nameArg === '--help' || nameArg === '-h' || nameArg === 'help';
+  if (!nameArg || nameArg.startsWith('-')) {
+    const out = wantsHelp ? console.log : console.error;
+    out('Usage: atris skill create <name> [--integration] [--description="..."] [--local]');
+    out('');
+    out('Examples:');
+    out('  atris skill create daily-standup');
+    out('  atris skill create email-outreach --integration');
+    out('  atris skill create example-co/bol-processor --integration');
+    out('  atris skill create my-skill --local     # project only, skip system dirs');
+    process.exit(wantsHelp ? 0 : 1);
   }
 
   const isIntegration = flags.includes('--integration');

package/commands/slop.js

@@ -0,0 +1,307 @@
+// atris slop — deterministic frontend-slop detector (no LLM).
+//
+// Steal-from-Impeccable, the Atris way: makes "looks AI-generated" concrete and
+// CHECKABLE. A failure is a fact (file:line + rule), not a taste opinion — so it
+// drops straight into the autopilot/review verification gate and CI. Each finding
+// is the seed of a typed lesson; the ruleset is meant to GROW from lessons.md
+// rather than be hand-curated forever.
+//
+// Zero external deps (Node built-ins only) — repo contract.
+//
+// Usage:
+//   atris slop detect [path]        # scan a file or dir (default: .)
+//   atris slop detect src/ --json   # machine output for CI / the loop
+//   atris slop detect src/ --quiet  # only print the summary line
+//
+// Exit code: 0 = clean, 1 = slop found, 2 = bad usage. CI/PR gates read this.
+
+const fs = require('fs');
+const path = require('path');
+const { execFileSync } = require('child_process');
+
+const SCAN_EXTS = new Set(['.css', '.scss', '.sass', '.less', '.tsx', '.jsx', '.ts', '.js', '.mjs', '.html', '.vue', '.svelte', '.astro',
+  '.md', '.mdx', '.txt']); // prose too: the voice doctrine (em-dash, hype-copy) is enforceable, not just advice
+const SKIP_DIRS = new Set(['node_modules', '.git', 'dist', 'build', '.next', '.astro', 'coverage', '.cache', 'out', 'vendor']);
+
+// Each rule is deterministic: a regex + a one-line why. severity drives the icon.
+// Kept high-precision on purpose — a noisy gate gets muted, and a muted gate is dead.
+const RULES = [
+  { id: 'ai-gradient-text', sev: 'error',
+    re: /(text-transparent[^"'`]{0,40}bg-clip-text|bg-clip-text[^"'`]{0,40}text-transparent|-webkit-text-fill-color:\s*transparent|background-clip:\s*text)/i,
+    why: 'gradient-filled text headline: the #1 generated-look tell' },
+  { id: 'ai-purple-gradient', sev: 'error',
+    re: /((from|via|to)-(purple|violet|indigo|fuchsia)-\d{2,3}\b|linear-gradient\([^)]*(#6366f1|#8b5cf6|#a855f7|#7c3aed|#4f46e5|\bpurple\b|\bviolet\b|\bindigo\b))/i,
+    why: 'purple/indigo gradient: default "AI startup" palette' },
+  { id: 'ai-indigo-brand', sev: 'warn',
+    re: /(#6366f1|#4f46e5|#4338ca|(?:bg|text|border|from|to|ring)-indigo-(?:500|600|700)\b)/i,
+    why: 'canonical AI indigo used as brand color' },
+  { id: 'glassmorphism', sev: 'warn',
+    re: /(backdrop-blur(?:-\w+)?\b|backdrop-filter:\s*blur)/i,
+    why: 'glassmorphism (frosted blur): overused default' },
+  { id: 'over-rounding', sev: 'warn',
+    re: /(rounded-(?:3xl|\[(?:[2-9]\d?|1\d\d)(?:px|rem)\])|border-radius:\s*(?:2[4-9]|[3-9]\d|\d{3})px|border-radius:\s*(?:[2-9](?:\.\d+)?)rem)/i,
+    why: 'over-rounded corners (>=24px / rounded-3xl)' },
+  { id: 'mega-shadow', sev: 'warn',
+    re: /(shadow-2xl\b|box-shadow:\s*0\s+\d{2,}px)/i,
+    why: 'oversized generic drop shadow (depth-by-blur)' },
+  { id: 'side-stripe-card', sev: 'warn',
+    re: /border-(?:left|l)-(?:4|8|\[\d+px\])\b|border-left:\s*[3-9]px\s+solid/i,
+    why: 'accent side-stripe on a card: generated layout reflex' },
+  { id: 'transition-all', sev: 'warn',
+    re: /\btransition-all\b|transition:\s*all\b/i,
+    why: 'transition-all: animate-everything laziness, not intent' },
+  { id: 'pulse-animation', sev: 'warn',
+    re: /animation:[^;]*\binfinite\b|@keyframes\s+(pulse|ping|blink|glow|throb)\b|\banimate-(pulse|ping|bounce)\b/i,
+    why: 'looping pulse/ping/glow animation: distracting live-status reflex' },
+  { id: 'eyebrow-caps', sev: 'warn',
+    re: /text-transform:\s*uppercase\b|\buppercase\b[^"'`]{0,30}tracking-|tracking-[^"'`]{0,30}\buppercase\b/i,
+    why: 'tracked all-caps eyebrow/label: dated reflex; use sentence case' },
+  { id: 'decorative-emoji', sev: 'warn',
+    re: /[✨\u{1F680}\u{1F4A1}\u{1F525}\u{1F389}⚡\u{1F31F}\u{1FA84}\u{1F4AB}\u{1F44B}]/u,
+    why: 'decorative emoji in UI copy' },
+  { id: 'em-dash', sev: 'warn',
+    re: /—/,
+    fix: (s) => s.replace(/\s*—\s*/g, ', '), // safe deterministic repair (prose)
+    why: 'em dash: a top AI-writing tell; use a comma, colon, or period' },
+  { id: 'hype-copy', sev: 'error',
+    re: /\b(boost your productivity|supercharge|unleash|game[- ]?chang(?:er|ing)|seamlessly|effortlessly|revolutioniz(?:e|ing)|take your .{1,30} to the next level|elevate your|cutting[- ]edge|powered by ai|next[- ]generation)\b/i,
+    why: 'hype/marketing slop phrase: say the specific thing instead' },
+];
+
+const ICON = { error: '✗', warn: '⚠' }; // ✗  ⚠
+
+const PROJECT_RULES_FILE = path.join('.atris', 'slop.rules.json');
+
+// Compounding: projects grow their own anti-slop ruleset in .atris/slop.rules.json.
+// Each entry: { id, pattern, flags?, why?, sev? }. Loaded on top of the built-ins.
+function loadProjectRules(root = process.cwd()) {
+  try {
+    const raw = JSON.parse(fs.readFileSync(path.join(root, PROJECT_RULES_FILE), 'utf8'));
+    const arr = Array.isArray(raw) ? raw : (raw.rules || []);
+    return arr.map((r) => {
+      if (!r || !r.id || !r.pattern) return null;
+      let re; try { re = new RegExp(r.pattern, r.flags || 'i'); } catch { return null; }
+      return { id: r.id, sev: r.sev === 'error' ? 'error' : 'warn', re, why: r.why || r.id, project: true };
+    }).filter(Boolean);
+  } catch { return []; }
+}
+
+function addProjectRule(rule, root = process.cwd()) {
+  const file = path.join(root, PROJECT_RULES_FILE);
+  let arr = [];
+  try { const raw = JSON.parse(fs.readFileSync(file, 'utf8')); arr = Array.isArray(raw) ? raw : (raw.rules || []); } catch {}
+  arr = arr.filter((r) => r.id !== rule.id);
+  arr.push(rule);
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  fs.writeFileSync(file, JSON.stringify(arr, null, 2) + '\n');
+  return file;
+}
+
+// Map<absFile, Set<changedLineNumber>> from the working-tree (or --cached) git diff.
+function gitChangedLines(staged, cwd = process.cwd()) {
+  const map = new Map();
+  let out;
+  try { out = execFileSync('git', ['diff', '--unified=0', ...(staged ? ['--cached'] : [])], { encoding: 'utf8', cwd }); }
+  catch { return map; }
+  let cur = null;
+  for (const line of out.split('\n')) {
+    const f = line.match(/^\+\+\+ b\/(.+)$/);
+    if (f) { cur = path.resolve(cwd, f[1]); map.set(cur, map.get(cur) || new Set()); continue; }
+    const h = line.match(/^@@ -\d+(?:,\d+)? \+(\d+)(?:,(\d+))? @@/);
+    if (h && cur) { const start = +h[1], count = h[2] != null ? +h[2] : 1; for (let i = 0; i < count; i++) map.get(cur).add(start + i); }
+  }
+  return map;
+}
+
+// Install a pre-commit hook that gates staged changes through `atris slop detect --staged`.
+// Idempotent and non-destructive: appends a marked block, skips gracefully if atris is absent.
+function installHook(root = process.cwd()) {
+  if (!fs.existsSync(path.join(root, '.git'))) throw new Error('not a git repo (no .git here)');
+  const hookDir = path.join(root, '.git', 'hooks');
+  fs.mkdirSync(hookDir, { recursive: true });
+  const hookPath = path.join(hookDir, 'pre-commit');
+  const marker = '# atris slop gate';
+  let content = '';
+  try { content = fs.readFileSync(hookPath, 'utf8'); } catch {}
+  if (content.includes(marker)) return { hookPath, already: true };
+  if (!content) content = '#!/bin/sh\n';
+  if (!content.endsWith('\n')) content += '\n';
+  content += `\n${marker}\nif command -v atris >/dev/null 2>&1; then atris slop detect --staged --quiet || exit 1; fi\n`;
+  fs.writeFileSync(hookPath, content);
+  fs.chmodSync(hookPath, 0o755);
+  return { hookPath, already: false };
+}
+
+// Apply every fixable rule's safe transform in place. Returns { fixedCount, fixedFiles }.
+function applyFixes(files, rules) {
+  const fixable = rules.filter((r) => typeof r.fix === 'function');
+  let fixedCount = 0; const fixedFiles = [];
+  for (const file of files) {
+    let text; try { text = fs.readFileSync(file, 'utf8'); } catch { continue; }
+    const lines = text.split('\n');
+    let touched = false;
+    for (let i = 0; i < lines.length; i++) {
+      let line = lines[i];
+      for (const r of fixable) { if (r.re.test(line)) { const nl = r.fix(line); if (nl !== line) { line = nl; fixedCount++; } } }
+      if (line !== lines[i]) { lines[i] = line; touched = true; }
+    }
+    if (touched) { fs.writeFileSync(file, lines.join('\n')); fixedFiles.push(file); }
+  }
+  return { fixedCount, fixedFiles };
+}
+
+function walk(target, out) {
+  let stat;
+  try { stat = fs.statSync(target); } catch { return out; }
+  if (stat.isFile()) {
+    if (SCAN_EXTS.has(path.extname(target))) out.push(target);
+    return out;
+  }
+  if (stat.isDirectory()) {
+    if (SKIP_DIRS.has(path.basename(target))) return out;
+    for (const name of fs.readdirSync(target)) {
+      if (name.startsWith('.') && name !== '.') continue;
+      walk(path.join(target, name), out);
+    }
+  }
+  return out;
+}
+
+function scanFile(file, rules = RULES) {
+  const findings = [];
+  let text;
+  try { text = fs.readFileSync(file, 'utf8'); } catch { return findings; }
+  const lines = text.split('\n');
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+    for (const rule of rules) {
+      const m = rule.re.exec(line);
+      if (m) {
+        findings.push({
+          file, line: i + 1, rule: rule.id, sev: rule.sev, why: rule.why,
+          snippet: m[0].trim().slice(0, 48),
+        });
+      }
+    }
+  }
+  return findings;
+}
+
+function detect(argv) {
+  const json = argv.includes('--json');
+  const quiet = argv.includes('--quiet');
+  const doFix = argv.includes('--fix');
+  const staged = argv.includes('--staged');
+  const diffMode = staged || argv.includes('--diff');
+  const rules = RULES.concat(loadProjectRules());
+
+  // pick the file set: a git diff (changed files) or a path walk
+  let files, changed = null;
+  if (diffMode) {
+    changed = gitChangedLines(staged);
+    files = [...changed.keys()].filter((f) => SCAN_EXTS.has(path.extname(f)) && fs.existsSync(f));
+  } else {
+    const target = argv.find((a) => !a.startsWith('-')) || '.';
+    files = walk(path.resolve(target), []);
+  }
+
+  let fixed = null;
+  if (doFix) {
+    fixed = applyFixes(files, rules);
+    if (!json && fixed.fixedCount) {
+      console.log(`\n  ✎ fixed ${fixed.fixedCount} tell${fixed.fixedCount === 1 ? '' : 's'} in ${fixed.fixedFiles.length} file${fixed.fixedFiles.length === 1 ? '' : 's'}`);
+    }
+  }
+
+  let findings = files.flatMap((f) => scanFile(f, rules));
+  if (diffMode && changed) findings = findings.filter((f) => changed.get(f.file) && changed.get(f.file).has(f.line));
+  const errors = findings.filter((f) => f.sev === 'error').length;
+
+  if (json) {
+    console.log(JSON.stringify({
+      ok: findings.length === 0, scanned: files.length,
+      mode: diffMode ? (staged ? 'staged' : 'diff') : 'path',
+      fixed: fixed ? fixed.fixedCount : 0,
+      slop: findings.length, errors,
+      findings: findings.map((f) => ({ ...f, file: path.relative(process.cwd(), f.file) })),
+    }, null, 2));
+    return findings.length ? 1 : 0;
+  }
+
+  const rel = (f) => path.relative(process.cwd(), f);
+  if (!quiet) {
+    if (!findings.length) {
+      console.log(`\n  ✓ clean — no slop tells in ${files.length} file${files.length === 1 ? '' : 's'}`);
+    } else {
+      console.log('');
+      const w = Math.max(...findings.map((f) => `${rel(f.file)}:${f.line}`.length));
+      for (const f of findings) {
+        const loc = `${rel(f.file)}:${f.line}`.padEnd(w);
+        console.log(`  ${ICON[f.sev]} ${loc}  ${f.rule.padEnd(20)} ${f.why}`);
+      }
+    }
+  }
+  if (findings.length) {
+    console.log(`\n  ${findings.length} slop tell${findings.length === 1 ? '' : 's'} (${errors} error) · exit 1\n`);
+  } else if (quiet) {
+    console.log(`  ✓ clean · exit 0`);
+  }
+  return findings.length ? 1 : 0;
+}
+
+function slopCommand(argv) {
+  const sub = argv[0];
+  if (!sub || sub === 'detect' || sub.startsWith('-') || !['detect', 'rules', 'help', 'hook', 'install-hook'].includes(sub)) {
+    // default + `detect`: scan. Bare `atris slop` scans cwd too.
+    const rest = sub === 'detect' ? argv.slice(1) : argv;
+    return detect(rest);
+  }
+  if (sub === 'hook' || sub === 'install-hook') {
+    try {
+      const { hookPath, already } = installHook();
+      console.log(already
+        ? `\n  already installed: ${path.relative(process.cwd(), hookPath)}\n`
+        : `\n  ✓ slop pre-commit gate installed: ${path.relative(process.cwd(), hookPath)}\n    every commit now runs: atris slop detect --staged\n`);
+      return 0;
+    } catch (e) { console.error(`  ${e.message}`); return 2; }
+  }
+
+  if (sub === 'rules') {
+    if (argv.includes('--add')) {
+      const rest = argv.slice(argv.indexOf('--add') + 1).filter((a) => !a.startsWith('-'));
+      const [id, pattern, ...whyParts] = rest;
+      if (!id || !pattern) { console.error('  usage: atris slop rules --add <id> <regex-pattern> <why...> [--sev error|warn]'); return 2; }
+      let valid = true; try { new RegExp(pattern, 'i'); } catch { valid = false; }
+      if (!valid) { console.error(`  invalid regex: ${pattern}`); return 2; }
+      const sev = (argv[argv.indexOf('--sev') + 1] === 'error') ? 'error' : 'warn';
+      const file = addProjectRule({ id, pattern, why: whyParts.join(' ') || id, sev });
+      console.log(`  ✓ added project rule "${id}" to ${path.relative(process.cwd(), file)}`);
+      return 0;
+    }
+    const project = loadProjectRules();
+    console.log('\n  atris slop — deterministic rules:\n');
+    for (const r of RULES) console.log(`  ${ICON[r.sev]} ${r.id.padEnd(20)} ${r.why}`);
+    for (const r of project) console.log(`  ${ICON[r.sev]} ${r.id.padEnd(20)} ${r.why}  (project)`);
+    console.log(`\n  ${RULES.length} built-in${project.length ? ` + ${project.length} project` : ''} rule${RULES.length + project.length === 1 ? '' : 's'}\n`);
+    return 0;
+  }
+  // help
+  console.log(`
+  atris slop — deterministic slop detector + repairer (no LLM)
+
+    atris slop detect [path]      scan a file or dir (default: .)
+    atris slop detect --diff      scan only changed lines (commit/PR gate)
+    atris slop detect --staged    scan only staged changes (pre-commit hook)
+    atris slop detect --fix       auto-repair the safe tells (em dashes), report the rest
+    atris slop detect [path] --json   machine output for CI / the loop
+    atris slop rules              list active rules (built-in + project)
+    atris slop rules --add <id> <pattern> <why>   grow the project ruleset
+    atris slop hook               install a pre-commit gate (runs --staged)
+
+  Project rules live in .atris/slop.rules.json and compound over time.
+  exit 0 = clean, 1 = slop found. Wire into PR checks and the autopilot gate.
+`);
+  return 0;
+}
+
+module.exports = { slopCommand, detect, scanFile, RULES, loadProjectRules, addProjectRule, gitChangedLines, applyFixes, installHook };

package/commands/task.js

@@ -7,7 +7,7 @@ const fs = require('fs');
 const http = require('http');
 const path = require('path');
 const os = require('os');
-const { taskProofState } = require('../lib/task-proof');
+const { taskProofState, buildVerifiedProof } = require('../lib/task-proof');
 const { evaluateAutoAccept, parseVerifyCommand } = require('../lib/auto-accept-certified');
 const { extractReceiptEvidence } = require('../lib/receipt-evidence');
 const escapeRegExp = require('../lib/escape-regexp');
@@ -96,6 +96,7 @@ atris task - durable local task state (SQLite, gitignored)
   atris task say <id> "<message>"         Add context to a task
   atris task chat <id> "<message>" [--goal "..."]  Refine a task chat + working goal
   atris task ready <id> --proof "..."      Agent proof ready; native goal can complete
+  atris task ready <id> --verify "<cmd>"   Run <cmd>; only ready if it exits 0 (executed proof)
   atris task review-chat <id> [--as <owner>]  Start a task-owned /codex verification chat
   atris task accept <id> [--proof "..."]   Human accepts proof, marks done
   atris task auto-accept-certified --dry-run [--strict-verify] [--limit <n>]
@@ -6317,12 +6318,29 @@ function cmdReady(args) {
     console.error('atris task ready: id required');
     process.exit(2);
   }
-  const proof = flag(args, '--proof');
-  if (!proof || proof === true) {
-    console.error('atris task ready: --proof required');
+  // Two ways to prove: --proof "<note>" (claimed, pattern-checked, unchanged) or
+  // --verify "<command>" which actually RUNS the command and gates ready on exit 0,
+  // turning a claim into executed evidence. --verify can carry an optional --proof note.
+  const proofFlag = flag(args, '--proof');
+  const verifyFlag = flag(args, '--verify');
+  let proof = typeof proofFlag === 'string' ? proofFlag : '';
+  if (typeof verifyFlag === 'string' && verifyFlag.trim()) {
+    const verified = buildVerifiedProof(verifyFlag, proof, undefined, { cwd: process.cwd() });
+    if (!verified.ok) {
+      const detail = verified.exit != null ? ` (exit ${verified.exit})` : (verified.signal ? ` (signal ${verified.signal})` : '');
+      console.error(`atris task ready: verifier failed${detail}: ${verifyFlag}`);
+      if (verified.output) console.error(verified.output);
+      else if (verified.error) console.error(verified.error);
+      process.exit(1);
+    }
+    proof = verified.proof;
+    if (!wantsJson(args)) console.log(`✓ verified: \`${verifyFlag}\` exited 0`);
+  }
+  if (!proof) {
+    console.error('atris task ready: --proof or --verify required');
     process.exit(2);
   }
-  requireMeaningfulTaskProof('atris task ready', String(proof));
+  requireMeaningfulTaskProof('atris task ready', proof);
   const lesson = flag(args, '--lesson') || '';
   const nextTaskInput = normalizeReviewNextTaskInput(typeof flag(args, '--next') === 'string' ? flag(args, '--next') : '');
   const actor = String(flag(args, '--as') || DEFAULT_OWNER);

package/commands/theme.js

@@ -0,0 +1,217 @@
+// atris theme — brand themes for the whole design system. Define your colors and
+// fonts once in .atris/theme.json; every deck, HTML page, and site uses them.
+//
+//   atris theme create        guided interview -> your own theme (alias: new)
+//   atris theme edit <name>   re-run the interview to tweak an existing theme
+//   atris theme init          scaffold a starter .atris/theme.json
+//   atris theme list          list built-in + project themes
+//   atris theme show <name>   print a resolved theme
+
+const readline = require('readline');
+const {
+  mergedThemes, writeStarterTheme, loadProjectThemes, loadThemeRecipe, PROJECT_THEME_FILE,
+  MOODS, MOOD_NAMES, FONT_PERSONALITIES, buildTheme, themeWarnings, upsertProjectTheme,
+  resolveMode, isHex, normHex, hexToRgb,
+} = require('../lib/theme');
+const { THEMES: HTML_THEMES } = require('../lib/html-render');
+
+// ---------- small terminal helpers ----------
+function parseFlags(argv) {
+  const flags = {}; const pos = [];
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === '-y' || a === '--yes') { flags.yes = 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 };
+}
+
+// a colored block when we're on a real terminal, two blank cells otherwise (clean pipes)
+function sw(hex) {
+  const c = hexToRgb(hex);
+  if (!c || !process.stdout.isTTY) return '  ';
+  return `\x1b[48;2;${c.r};${c.g};${c.b}m  \x1b[0m`;
+}
+
+function printPreview(name, answers, theme) {
+  const c = theme.color;
+  const mode = resolveMode(answers.mood || 'editorial', answers.mode);
+  console.log(`\n  ${name}  ·  ${answers.mood || 'editorial'} ${mode}`);
+  const row = (label, hex) => console.log(`   ${sw(hex)} ${label.padEnd(8)} ${hex}`);
+  row('bg', c.bg);
+  row('ink', c.ink);
+  row('accent', c.accent);
+  row('accent2', c.accent2);
+  console.log(`      ${theme.fonts.display} display, ${theme.fonts.body} body`);
+}
+
+// ---------- the guided interview (tasteful vocabulary) ----------
+async function interview(defaults = {}) {
+  const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+  const ask = (q) => new Promise((res) => rl.question(q, res));
+  const ans = {};
+  try {
+    console.log('\n  let\'s make your theme. five quick choices, all changeable later.\n');
+
+    const dn = defaults.name || 'brand';
+    ans.name = (await ask(`  1/5  name it [${dn}]: `)).trim() || dn;
+
+    console.log('\n  2/5  what should it feel like?');
+    MOOD_NAMES.forEach((m, i) => console.log(`     ${i + 1}. ${m.padEnd(10)} ${MOODS[m].blurb}`));
+    const dmIdx = Math.max(0, MOOD_NAMES.indexOf(defaults.mood || 'editorial'));
+    const moodPick = (await ask(`     pick 1-${MOOD_NAMES.length} [${dmIdx + 1}]: `)).trim();
+    ans.mood = MOOD_NAMES[(parseInt(moodPick, 10) - 1)] || MOOD_NAMES[dmIdx];
+    const mood = MOODS[ans.mood];
+
+    if (mood.forceMode) {
+      ans.mode = mood.forceMode;
+      console.log(`     (${ans.mood} is ${mood.forceMode}-only)`);
+    } else {
+      const dmode = defaults.mode || mood.defaultMode;
+      const mp = (await ask(`\n  3/5  light or dark? [${dmode[0]}]: `)).trim().toLowerCase();
+      ans.mode = mp.startsWith('l') ? 'light' : mp.startsWith('d') ? 'dark' : dmode;
+    }
+
+    console.log('\n  4/5  your accent — the one color that is unmistakably yours:');
+    mood.swatches.forEach((s, i) => console.log(`     ${i + 1}. ${sw(s)} ${s}`));
+    const dac = normHex(defaults.accent) || mood.swatches[0];
+    const ap = (await ask(`     pick 1-${mood.swatches.length}, or paste a hex [${dac}]: `)).trim();
+    if (!ap) ans.accent = dac;
+    else if (/^[1-9]$/.test(ap) && mood.swatches[parseInt(ap, 10) - 1]) ans.accent = mood.swatches[parseInt(ap, 10) - 1];
+    else if (isHex(ap)) ans.accent = normHex(ap);
+    else { console.log(`     '${ap}' is not 1-${mood.swatches.length} or a hex, keeping ${dac}`); ans.accent = dac; }
+
+    console.log('\n  5/5  type personality:');
+    const fontKeys = Object.keys(FONT_PERSONALITIES);
+    fontKeys.forEach((k, i) => console.log(`     ${i + 1}. ${k.padEnd(15)} ${FONT_PERSONALITIES[k].display} / ${FONT_PERSONALITIES[k].body}`));
+    const dfIdx = fontKeys.indexOf(typeof defaults.fonts === 'string' ? defaults.fonts : mood.fonts);
+    const fp = (await ask(`     pick 1-${fontKeys.length} [${(dfIdx < 0 ? 0 : dfIdx) + 1}]: `)).trim();
+    ans.fonts = fontKeys[(parseInt(fp, 10) - 1)] || fontKeys[dfIdx < 0 ? 0 : dfIdx];
+  } finally {
+    rl.close();
+  }
+  return ans;
+}
+
+function confirmSync(q) {
+  const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+  return new Promise((res) => rl.question(q, (a) => { rl.close(); res(!String(a).trim().toLowerCase().startsWith('n')); }));
+}
+
+// shared create/edit flow. defaults seed an edit; flags override anything; interactive
+// only when there's a TTY and no defining flags.
+async function createFlow({ name, defaults = {}, flags }) {
+  const answers = { ...defaults };
+  if (flags.mood) answers.mood = flags.mood;
+  if (flags.mode) answers.mode = flags.mode;
+  if (flags.accent) answers.accent = flags.accent;
+  if (flags.accent2) answers.accent2 = flags.accent2;
+  if (flags.fonts) answers.fonts = flags.fonts;
+  let themeName = name || flags.name || defaults.name || 'brand';
+
+  const hasDefiningFlag = Boolean(flags.mood || flags.mode || flags.accent || flags.accent2 || flags.fonts || flags.name);
+  const interactive = Boolean(process.stdin.isTTY) && !flags.yes && !hasDefiningFlag;
+
+  if (interactive) {
+    const r = await interview({ name: themeName, ...answers });
+    Object.assign(answers, r);
+    themeName = r.name || themeName;
+  }
+  themeName = String(themeName).trim() || 'brand';
+
+  if (answers.mood && !MOODS[answers.mood]) { console.error(`  unknown mood "${answers.mood}". try: ${MOOD_NAMES.join(', ')}`); return 2; }
+  if (answers.accent && !isHex(answers.accent)) { console.error(`  not a hex color: ${answers.accent}`); return 2; }
+  if (answers.accent2 && !isHex(answers.accent2)) { console.error(`  not a hex color: ${answers.accent2}`); return 2; }
+  if (answers.fonts && typeof answers.fonts === 'string' && !FONT_PERSONALITIES[answers.fonts]) {
+    console.error(`  unknown font personality "${answers.fonts}". try: ${Object.keys(FONT_PERSONALITIES).join(', ')}`); return 2;
+  }
+
+  const theme = buildTheme(answers);
+  printPreview(themeName, answers, theme);
+  const warns = themeWarnings(theme);
+  if (warns.length) { console.log('\n  heads up:'); warns.forEach((w) => console.log(`   ! ${w}`)); }
+
+  if (interactive) {
+    const ok = await confirmSync('\n  save this theme? [enter = yes, n = cancel] ');
+    if (!ok) { console.log('  cancelled, nothing written.\n'); return 0; }
+  }
+
+  const recipe = {
+    mood: answers.mood || 'editorial',
+    mode: resolveMode(answers.mood || 'editorial', answers.mode),
+    accent: theme.color.accent,
+    accent2: theme.color.accent2,
+    fonts: typeof answers.fonts === 'string' ? answers.fonts : (MOODS[answers.mood || 'editorial'].fonts),
+  };
+
+  let res;
+  try { res = upsertProjectTheme(themeName, theme, process.cwd(), recipe); }
+  catch (e) { console.error(`  ${e.message}`); return 1; }
+
+  console.log(`\n  ✓ ${res.action} theme "${res.name}" in ${PROJECT_THEME_FILE}  (${res.count} theme${res.count === 1 ? '' : 's'})`);
+  console.log('    use it anywhere:');
+  console.log(`      atris deck from doc.md --html --theme ${res.name}`);
+  console.log(`      atris site ./docs --theme ${res.name}`);
+  console.log(`    tweak it later:  atris theme edit ${res.name}\n`);
+  return 0;
+}
+
+async function run(argv) {
+  const sub = argv[0];
+  const rest = argv.slice(1);
+
+  if (sub === 'create' || sub === 'new') {
+    const { flags, pos } = parseFlags(rest);
+    return createFlow({ name: pos[0], flags });
+  }
+
+  if (sub === 'edit') {
+    const { flags, pos } = parseFlags(rest);
+    const name = pos[0] || flags.name;
+    if (!name) { console.error('  usage: atris theme edit <name>'); return 2; }
+    const existing = loadProjectThemes()[name];
+    if (!existing) { console.error(`  no project theme "${name}". make one with: atris theme create ${name}`); return 2; }
+    // prefer the saved recipe; otherwise seed from the resolved colors/fonts
+    const recipe = loadThemeRecipe(name);
+    const defaults = recipe || { accent: existing.color.accent, accent2: existing.color.accent2, fonts: existing.fonts };
+    defaults.name = name;
+    return createFlow({ name, defaults, flags });
+  }
+
+  if (sub === 'init') {
+    const { file, already } = writeStarterTheme();
+    console.log(already
+      ? `\n  already exists: ${file}\n  customize it with: atris theme edit brand\n`
+      : `\n  ✓ brand theme scaffolded: ${file}\n    or build one by feel:  atris theme create\n`);
+    return 0;
+  }
+
+  if (sub === 'show') {
+    const name = rest[0];
+    const t = mergedThemes(HTML_THEMES)[name];
+    if (!t) { console.error(`  unknown theme "${name}"`); return 2; }
+    console.log(JSON.stringify(t, null, 2));
+    return 0;
+  }
+
+  // list (default)
+  const project = loadProjectThemes();
+  const all = mergedThemes(HTML_THEMES);
+  console.log('\n  atris themes:\n');
+  for (const name of Object.keys(all)) {
+    const tag = project[name] ? 'project' : 'built-in';
+    console.log(`  ${sw(all[name].color.accent)} ${name.padEnd(12)} accent ${all[name].color.accent}  bg ${all[name].color.bg}  (${tag})`);
+  }
+  console.log(`\n  make your own by feel:  atris theme create`);
+  console.log(`  themes live in ${PROJECT_THEME_FILE}. Used by deck, html, and site.\n`);
+  return 0;
+}
+
+module.exports = { run };