atris 3.58.5 → 3.58.7

package/bin/atris.js

@@ -120,7 +120,7 @@ const helpRequested = updateCommand === 'help'
 const jsonRequested = process.argv.slice(2).includes('--json');
 const dryRunRequested = updateArgs.includes('--dry-run');
 const skipUpdateCheck = Boolean(process.env.ATRIS_SKIP_UPDATE_CHECK || process.env.NO_UPDATE_NOTIFIER || helpRequested || jsonRequested);
-if (!skipUpdateCheck && (!updateCommand || (updateCommand && !['version', 'update'].includes(updateCommand)))) {
+if (!skipUpdateCheck && (!updateCommand || (updateCommand && !['version', 'update', 'mcp'].includes(updateCommand)))) {
   updateCheckPromise = checkForUpdates()
     .then((updateInfo) => {
       if (updateInfo) {
@@ -577,6 +577,7 @@ function showHelpAll() {
   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('  doc-health - workspace document size, navigation, and freshness (--json)');
   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)');
@@ -627,6 +628,7 @@ function showHelpAll() {
   console.log('  land       - The landing: what is actually done vs still in the air; --reap backs up + clears overdue');
   console.log('  caretaker  - Classify open pull requests on origin (scan only; no fix, comment, or merge)');
   console.log('  drive      - One self-driving tick: mission doctor -> auto-fix -> count disengagements');
+  console.log('  rsi        - Read the Dream-RSI attempt ledger (trees, attempts, policy, dreams)');
   console.log(`  autoland   - Approve the policy once; ${require('../lib/autoland').certifiedWorkLandsPhrase(process.cwd())}, you keep irreversible calls`);
   console.log('  engine     - engine registry, answer validation, dispatch flights, and live progress');
   console.log('  ci         - run github actions jobs locally with runs-on: atris');
@@ -714,6 +716,8 @@ function showHelpAll() {
   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('  design     - Extract a site design system, check brand adherence, search brands');
+  console.log('  mcp        - Run the atris MCP server (stdio) for Claude Desktop and Cursor');
   console.log('');
   console.log('Integrations:');
   console.log('  github    - github cli wrapper (doctor, auth, pr list/create/checks/view)');
@@ -1633,7 +1637,15 @@ function showWelcomeVisualization() {
   const isInitialized = fs.existsSync(atrisDir);
   let endgameState = { slug: 'unset', horizon: '' };
 
+  let keptCount = 0;
   if (isInitialized) {
+    try {
+      const kept = require('../lib/task-list-keeper').keepWorkspaceTaskList(cwd);
+      keptCount = (kept.put_away || []).length + (kept.reaped || []).length;
+      if (keptCount > 0) require('../commands/task').refreshKeptTaskList(cwd);
+    } catch {
+      keptCount = 0;
+    }
     try {
       glance = getTaskGlance(atrisDir);
     } catch {
@@ -1716,6 +1728,10 @@ function showWelcomeVisualization() {
   // Show the work itself, not counts. A newcomer in any domain (code, docs,
   // a travel plan) should read actual task names and know what's happening.
   // Waiting-on-you comes first: the one thing only a human can do.
+  if (keptCount > 0) {
+    const noun = keptCount === 1 ? 'item' : 'items';
+    console.log(row('kept', `put away ${keptCount} ${noun} that were finished or sitting still`));
+  }
   if (glance.reviewCertified > 0) {
     console.log(row('you', `${glance.reviewCertified} done, waiting for your ok:`));
     glance.certifiedTitles.forEach((t) => console.log(sub(trimTitle(t))));
@@ -1739,6 +1755,18 @@ function showWelcomeVisualization() {
     console.log(row('now', 'nothing on the list yet'));
   }
 
+  try {
+    const health = require('../commands/doc-health').computeDocHealth(cwd);
+    if (health.ok) {
+      const detail = health.lookup_hops.missing
+        ? 'add atris/doc-health/questions.jsonl'
+        : `${Math.round((health.lookup_hops.score || 0) * 100)}% one hop · boot ${(health.boot_load.approximate_tokens / 1000).toFixed(1)}k tokens`;
+      console.log(row('docs', `${health.overall.total}/100 · ${detail}`));
+    }
+  } catch {
+    // Document health is advisory and must never prevent startup.
+  }
+
   // landSummary is expensive (git board classification) - compute once per boot.
   let landInfo = null;
   try { landInfo = require('../commands/land').landSummary(cwd); } catch (err) { landInfo = null; }
@@ -1999,6 +2027,11 @@ if (command === 'guide') {
   Promise.resolve(require('../commands/drive').driveCommand(process.argv.slice(3)))
     .then((code) => process.exit(code || 0))
     .catch((err) => { console.error(`\n✗ Error: ${err.message || err}`); process.exit(1); });
+} else if (command === 'rsi') {
+  // RSI: read the Dream-RSI attempt ledger (trees, attempts, policy, dreams).
+  Promise.resolve(require('../commands/rsi').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 === 'orb') {
   Promise.resolve(orbCmd(process.argv.slice(3)))
     .then((code) => process.exit(typeof code === 'number' ? code : 0))
@@ -2026,6 +2059,22 @@ if (command === 'guide') {
   Promise.resolve(require('../commands/aeo').run(process.argv.slice(3)))
     .then(() => process.exit(0))
     .catch((err) => { console.error(`\n✗ Error: ${err.message || err}`); process.exit(1); });
+} else if (command === 'design') {
+  // Design: extract a site's design system, check brand adherence, search brands.
+  Promise.resolve(require('../commands/design').run(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 === 'mcp') {
+  // MCP: stdio Model Context Protocol server exposing the design tools.
+  {
+    const serverPath = require('path').join(__dirname, '..', 'mcp', 'atris-mcp', 'index.mjs');
+    const child = require('child_process').spawn(process.execPath, [serverPath, ...process.argv.slice(3)], { stdio: 'inherit' });
+    for (const signal of ['SIGTERM', 'SIGINT']) {
+      process.on(signal, () => { try { child.kill(signal); } catch { /* child already gone */ } });
+    }
+    child.on('error', (err) => { console.error(`\n✗ Error: ${err.message || err}`); process.exit(1); });
+    child.on('exit', (code) => process.exit(code == null ? 1 : code));
+  }
 } else if (command === 'improve') {
   // Improve: one paid RL tick via POST /api/improve (deducts credits), local autopilot fallback.
   Promise.resolve(require('../commands/improve').run(process.argv.slice(3)))
@@ -2696,8 +2745,12 @@ if (command === 'guide') {
     });
 } 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); });
+    .then((code) => { process.exitCode = typeof code === 'number' ? code : 0; })
+    .catch((err) => { console.error(`\n✗ Error: ${err.message || err}`); process.exitCode = 1; });
+} else if (command === 'doc-health') {
+  Promise.resolve(require('../commands/doc-health').docHealthCommand(process.argv.slice(3)))
+    .then((code) => { process.exitCode = typeof code === 'number' ? code : 0; })
+    .catch((err) => { console.error(err.message || err); process.exitCode = 1; });
 } else if (command === 'verify') {
   const args = process.argv.slice(3);
   if (args.includes('--help') || args.includes('-h') || args[0] === 'help') {

package/commands/auth.js

@@ -1,4 +1,4 @@
-const { AGENT_TOKEN_EXPIRED_DETAIL, loadCredentials, saveCredentials, deleteCredentials, getCredentialsPath, openBrowser, promptUser, displayAccountSummary, ensureValidCredentials, loadProfile, listProfiles, profileNameFromEmail, deleteProfile, saveProfile, getTokenExpiryEpochSeconds, getTerminalSessionId, setSessionProfile, getSessionProfile, clearSessionProfile, cleanStaleSessions, getSessionsDir } = require('../utils/auth');
+const { AGENT_TOKEN_EXPIRED_DETAIL, decodeJwtClaims, loadCredentials, saveCredentials, deleteCredentials, getCredentialsPath, openBrowser, promptUser, displayAccountSummary, ensureValidCredentials, loadProfile, listProfiles, profileNameFromEmail, deleteProfile, saveProfile, getTokenExpiryEpochSeconds, getTerminalSessionId, setSessionProfile, getSessionProfile, clearSessionProfile, cleanStaleSessions, getSessionsDir } = require('../utils/auth');
 const { getAppBaseUrl, apiRequestJson } = require('../utils/api');
 const { isNonInteractive, wantsJson } = require('../lib/noninteractive');
 const { hasFlag, readFlag } = require('../lib/arg-parser');
@@ -85,20 +85,49 @@ function extractAgentTokenMeta(data, requested, token) {
   return { scopes, dailyCreditCap, expiresAt };
 }
 
+function isAgentAccessToken(token) {
+  return decodeJwtClaims(token)?.type === 'agent_access';
+}
+
+function scopedTokenCandidate(credentials = {}) {
+  if (credentials.agent_token) return credentials.agent_token;
+  if (
+    credentials.source === 'env'
+    || credentials.source === 'agent_token_file'
+    || isAgentAccessToken(credentials.token)
+  ) {
+    return firstNonEmptyString(credentials.token);
+  }
+  return null;
+}
+
+function canMintFromLogin(credentials = {}) {
+  if (credentials.source === 'agent_token_file') return false;
+  if (credentials.source === 'env' && Array.isArray(credentials.scopes) && credentials.scopes.length) {
+    return false;
+  }
+  const login = firstNonEmptyString(credentials.token);
+  const refresh = firstNonEmptyString(credentials.refresh_token);
+  if (isAgentAccessToken(login) && !refresh) return false;
+  return Boolean(login || refresh);
+}
+
 function persistMintedAgentToken(credentials, token, extras = {}) {
+  if (isAgentAccessToken(credentials.token)) {
+    throw new Error('Refusing to save a scoped agent token as the login token; keep it under agent_token');
+  }
   const next = {
-    token,
+    ...credentials,
     refresh_token: extras.refresh_token || credentials.refresh_token || null,
-    email: credentials.email || null,
-    user_id: credentials.user_id || null,
-    provider: credentials.provider || null,
-    saved_at: extras.saved_at || new Date().toISOString(),
+    agent_token: token,
+    agent_token_scopes: extras.scopes || [],
+    agent_token_expires_at: extras.expiresAt || null,
   };
   if (credentials.source_profile) {
     saveProfile(credentials.source_profile, next);
     return next;
   }
-  saveCredentials(next.token, next.refresh_token, next.email, next.user_id, next.provider);
+  saveCredentials(next.token, next.refresh_token, next.email, next.user_id, next.provider, next);
   return next;
 }
 
@@ -139,10 +168,10 @@ async function mintScopedAgentToken(requested = {}, deps = {}) {
     ? requested.dailyCreditCap
     : DEFAULT_DAILY_CREDIT_CAP;
 
-  const credentials = load() || {};
+  const credentials = await load(api) || {};
   const accessToken = firstNonEmptyString(credentials.token);
   const refreshToken = firstNonEmptyString(credentials.refresh_token);
-  if (!accessToken && !refreshToken) {
+  if (!canMintFromLogin(credentials)) {
     return { ok: false, code: 'not_logged_in', error: NO_STORED_JWT_MESSAGE };
   }
 
@@ -150,7 +179,7 @@ async function mintScopedAgentToken(requested = {}, deps = {}) {
     scopes,
     daily_credit_cap: dailyCreditCap,
   };
-  let authToken = accessToken || refreshToken;
+  let authToken = isAgentAccessToken(accessToken) ? refreshToken : (accessToken || refreshToken);
   let result = await postAgentToken(api, authToken, body);
   if (!result.ok && result.status === 401 && refreshToken && authToken !== refreshToken) {
     authToken = refreshToken;
@@ -172,7 +201,9 @@ async function mintScopedAgentToken(requested = {}, deps = {}) {
     return { ok: false, code: 'missing_token', error: 'backend did not return an agent token' };
   }
 
+  const meta = extractAgentTokenMeta(result.data, { scopes, dailyCreditCap }, minted);
   persist(credentials, minted, {
+    ...meta,
     refresh_token: firstNonEmptyString(result.data && result.data.refresh_token) || refreshToken,
     saved_at: now(),
   });
@@ -180,7 +211,8 @@ async function mintScopedAgentToken(requested = {}, deps = {}) {
   return {
     ok: true,
     token: minted,
-    meta: extractAgentTokenMeta(result.data, { scopes, dailyCreditCap }, minted),
+    meta,
+    storedIn: credentials.source_profile ? `profile ${credentials.source_profile}, agent_token` : '~/.atris/credentials.json, agent_token',
   };
 }
 
@@ -191,24 +223,23 @@ async function ensureBilledCommandAuth(scope, deps = {}) {
   }
 
   const api = deps.apiRequestJson || apiRequestJson;
-  const ensureFn = deps.ensureValidCredentials || ensureValidCredentials;
   const load = deps.loadCredentials || loadCredentials;
   const mint = deps.mintScopedAgentToken || mintScopedAgentToken;
 
-  if (!deps.forceMint) {
-    const ensured = await ensureFn(api);
-    if (ensured && ensured.credentials && ensured.credentials.token) {
-      return {
-        ok: true,
-        token: ensured.credentials.token,
-        minted: false,
-        credentials: ensured.credentials,
-      };
-    }
+  const ensured = !deps.forceMint && deps.ensureValidCredentials
+    ? await deps.ensureValidCredentials(api) : null;
+  const credentials = ensured?.credentials || await load(api) || {};
+  const candidate = scopedTokenCandidate(credentials);
+  const claims = decodeJwtClaims(candidate);
+  const scopes = claims?.scopes || credentials.agent_token_scopes || credentials.scopes || [];
+  const expiry = claims?.exp
+    ? claims.exp * 1000
+    : Date.parse(credentials.agent_token_expires_at || credentials.expires_at);
+  if (!deps.forceMint && candidate && Array.isArray(scopes) && scopes.includes(wanted) && Number.isFinite(expiry) && expiry > Date.now()) {
+    return { ok: true, token: candidate, minted: false, credentials };
   }
 
-  const credentials = load() || {};
-  if (!firstNonEmptyString(credentials.token, credentials.refresh_token)) {
+  if (!canMintFromLogin(credentials)) {
     return { ok: false, error: NO_STORED_JWT_MESSAGE };
   }
 
@@ -267,6 +298,7 @@ async function mintAgentToken(args = [], deps = {}) {
     output(JSON.stringify({
       ok: true,
       minted: true,
+      stored_in: minted.storedIn,
       scopes: minted.meta.scopes,
       daily_credit_cap: minted.meta.dailyCreditCap,
       expires_at: minted.meta.expiresAt,
@@ -275,6 +307,7 @@ async function mintAgentToken(args = [], deps = {}) {
   }
 
   printAgentTokenMint(minted.meta, output);
+  output(`stored in ${minted.storedIn}`);
   return 0;
 }
 
@@ -982,6 +1015,7 @@ module.exports = {
   shellInit,
   parseAgentTokenArgs,
   mintAgentToken,
+  persistMintedAgentToken,
   ensureBilledCommandAuth,
   wantsAgentToken,
 };

package/commands/brain.js

@@ -1774,6 +1774,7 @@ function brainCommand(args = process.argv.slice(3)) {
 }
 
 module.exports = {
+  readText,
   brainCommand,
   collectState,
   renderStatus,

package/commands/design.js

@@ -0,0 +1,362 @@
+'use strict';
+
+/**
+ * atris design, brand design-system commands against api.atris.ai.
+ *
+ *   atris design extract <url> [--json] [--sections colors,typography]
+ *   atris design check <url> --against <brand-url> [--json]
+ *   atris design search "<words>" [--limit n] [--json]
+ *
+ * Auth: developer key as `Authorization: Bearer atris_...`, resolved by
+ * lib/design-api.js (ATRIS_API_KEY, then the atris login token, then
+ * ~/.atris/design-api-key).
+ */
+
+const {
+  resolveDesignKey,
+  designRequest,
+  pollDesignJob,
+  billingOf,
+  creditLine,
+} = require('../lib/design-api');
+
+const NO_KEY = 'no api key found. set ATRIS_API_KEY or run: atris login (or save a key in ~/.atris/design-api-key)';
+
+function showDesignHelp() {
+  console.log('usage: atris design extract <url> [--json] [--sections colors,typography]');
+  console.log('       atris design check <url> --against <brand-url> [--json]');
+  console.log('       atris design search "<words>" [--limit n] [--json]');
+  console.log('pull a site\'s design system, score a page against a brand, or search extracted brands.');
+}
+
+function wantsHelp(args) {
+  return args.includes('--help') || args.includes('-h') || args[0] === 'help';
+}
+
+function readFlag(args, name) {
+  for (let i = 0; i < args.length; i += 1) {
+    const a = String(args[i]);
+    if (a === name) {
+      const v = args[i + 1];
+      if (v === undefined || String(v).startsWith('--')) return { error: `${name} needs a value` };
+      args.splice(i, 2);
+      return { value: String(v) };
+    }
+    if (a.startsWith(`${name}=`)) {
+      args.splice(i, 1);
+      return { value: a.slice(name.length + 1) };
+    }
+  }
+  return {};
+}
+
+function positionals(args) {
+  return args.filter((a) => !String(a).startsWith('--'));
+}
+
+function unknownFlags(args, allowed) {
+  return args.filter((a) => String(a).startsWith('--') && !allowed.includes(a));
+}
+
+function normalizeUrl(url) {
+  return /^https?:\/\//i.test(url) ? url : `https://${url}`;
+}
+
+function isTerminal(job) {
+  const s = String(job && job.status || '').toLowerCase();
+  return s === 'completed' || s === 'failed' || s === 'error' || s === 'succeeded';
+}
+
+// One-line spinner on TTY only; off TTY stays silent so --json and pipes stay clean.
+function makeSpinner(label, io) {
+  const write = io.write;
+  if (!io.tty || typeof write !== 'function') return { stop() {} };
+  const start = Date.now();
+  const frames = ['-', '\\', '|', '/'];
+  let n = 0;
+  const timer = setInterval(() => {
+    const secs = Math.floor((Date.now() - start) / 1000);
+    write(`\r  ${frames[n++ % frames.length]} ${label} ${secs}s`);
+  }, 250);
+  if (timer.unref) timer.unref();
+  return {
+    stop() {
+      clearInterval(timer);
+      write('\r\x1b[2K');
+    },
+  };
+}
+
+function uniqueHexes(colors = {}, palette = []) {
+  const out = [];
+  for (const key of ['primary', 'secondary', 'accent']) {
+    const hex = colors[key];
+    if (hex && !out.includes(hex)) out.push(hex);
+  }
+  for (const p of Array.isArray(palette) ? palette : []) {
+    const hex = p && typeof p === 'object' ? p.hex : p;
+    if (hex && !out.includes(hex)) out.push(hex);
+    if (out.length >= 6) break;
+  }
+  return out.slice(0, 6);
+}
+
+function fontFamily(value) {
+  if (!value) return null;
+  if (typeof value === 'string') return value;
+  if (typeof value === 'object') return value.family || null;
+  return null;
+}
+
+// Short readable card for an extraction job.
+function extractionCard(job = {}) {
+  const ds = job.result && job.result.design_system ? job.result.design_system : {};
+  const profile = ds.profile || {};
+  const colors = ds.colors || {};
+  const typo = ds.typography || {};
+  const lines = [];
+  lines.push('');
+  lines.push(`  ${profile.brand_name || job.source_url || 'unknown brand'}`);
+  if (job.source_url) lines.push(`  ${job.source_url}`);
+  lines.push('');
+  const hexes = uniqueHexes(colors, colors.palette);
+  if (hexes.length) lines.push(`  colors    ${hexes.join(' ')}`);
+  const heading = fontFamily(typo.heading);
+  const body = fontFamily(typo.body);
+  if (heading) lines.push(`  heading   ${heading}`);
+  if (body) lines.push(`  body      ${body}`);
+  if (profile.one_line_positioning) lines.push(`  line      ${profile.one_line_positioning}`);
+  lines.push('');
+  lines.push(`  ${creditLine(job)}`);
+  lines.push('');
+  return lines.join('\n');
+}
+
+// Short readable card for an adherence job.
+function adherenceCard(job = {}) {
+  const result = job.result && typeof job.result === 'object' ? job.result : {};
+  const lines = [];
+  lines.push('');
+  const score = Number(result.score);
+  lines.push(`  score     ${Number.isFinite(score) ? score.toFixed(2) : '?'}`);
+  if (job.source_url) lines.push(`  source    ${job.source_url}`);
+  if (job.reference_url) lines.push(`  against   ${job.reference_url}`);
+  lines.push('');
+  for (const key of ['fixes', 'recommendations']) {
+    const items = Array.isArray(result[key]) ? result[key] : [];
+    if (!items.length) continue;
+    lines.push(`  ${key}:`);
+    for (const item of items.slice(0, 5)) {
+      const text = typeof item === 'string' ? item : (item && (item.title || item.detail || item.message)) || JSON.stringify(item);
+      lines.push(`   - ${String(text).replace(/\s+/g, ' ').trim()}`);
+    }
+    lines.push('');
+  }
+  lines.push(`  ${creditLine(job)}`);
+  lines.push('');
+  return lines.join('\n');
+}
+
+// Short readable card for a search response.
+function searchCard(data = {}, query = '') {
+  const results = Array.isArray(data.results) ? data.results : [];
+  const lines = [];
+  lines.push('');
+  lines.push(`  ${results.length} result${results.length === 1 ? '' : 's'} for "${query}"`);
+  lines.push('');
+  for (const r of results) {
+    const name = r.brand_name || r.source_url || 'unknown';
+    lines.push(`  ${name}${r.source_url ? `  ${r.source_url}` : ''}`);
+    const palette = Array.isArray(r.palette) ? r.palette.slice(0, 6).join(' ') : '';
+    if (palette) lines.push(`    ${palette}`);
+  }
+  lines.push('');
+  lines.push(`  ${creditLine(data)}`);
+  lines.push('');
+  return lines.join('\n');
+}
+
+async function designExtract(args, ctx) {
+  const json = args.includes('--json');
+  const sections = readFlag(args, '--sections');
+  if (sections.error) { ctx.err(sections.error); return 1; }
+  const bad = unknownFlags(args, ['--json']);
+  if (bad.length) { ctx.err(`unknown flag for design extract: ${bad.join(' ')}`); return 1; }
+  const url = positionals(args)[0];
+  if (!url) { ctx.err('usage: atris design extract <url> [--json] [--sections colors,typography]'); return 1; }
+  const target = normalizeUrl(url);
+
+  const body = { url: target };
+  if (sections.value) body.sections = sections.value;
+  const first = await ctx.request('/design/extractions', { method: 'POST', body, key: ctx.key });
+  if (!first.ok) {
+    ctx.err(`design extract failed (${first.status}): ${first.error}`);
+    return 1;
+  }
+  let job = first.data || {};
+  const pollMs = ctx.pollMs;
+  if (!isTerminal(job) && job.id) {
+    const qs = sections.value ? `?sections=${encodeURIComponent(sections.value)}` : '';
+    const spinner = makeSpinner(`extracting ${target}`, ctx.io);
+    let failures = 0;
+    const polled = await pollDesignJob(async () => {
+      const res = await ctx.request(`/design/extractions/${job.id}${qs}`, { key: ctx.key });
+      if (!res.ok) {
+        failures += 1;
+        if (failures >= 3) return { status: 'failed', error: res.error };
+        return { status: 'polling' };
+      }
+      failures = 0;
+      return res.data;
+    }, { intervalMs: pollMs, timeoutMs: ctx.maxWaitMs, sleep: ctx.sleep });
+    spinner.stop();
+    if (polled.timedOut) {
+      ctx.err(`still running after ${Math.round(ctx.maxWaitMs / 1000)}s. job id: ${job.id}`);
+      return 1;
+    }
+    job = polled.job || job;
+  }
+  if (json) { ctx.out(JSON.stringify(job, null, 2)); return job.status === 'completed' ? 0 : 1; }
+  if (!isTerminal(job) || job.status !== 'completed') {
+    ctx.err(`extraction did not finish: ${job.error || job.status || 'unknown'}`);
+    return 1;
+  }
+  ctx.out(extractionCard(job));
+  return 0;
+}
+
+async function designCheck(args, ctx) {
+  const json = args.includes('--json');
+  const against = readFlag(args, '--against');
+  if (against.error) { ctx.err(against.error); return 1; }
+  const bad = unknownFlags(args, ['--json']);
+  if (bad.length) { ctx.err(`unknown flag for design check: ${bad.join(' ')}`); return 1; }
+  const url = positionals(args)[0];
+  if (!url || !against.value) {
+    ctx.err('usage: atris design check <url> --against <brand-url> [--json]');
+    return 1;
+  }
+  const source = normalizeUrl(url);
+  const reference = normalizeUrl(against.value);
+
+  const first = await ctx.request('/design/adherence', {
+    method: 'POST',
+    body: { source_url: source, reference_url: reference },
+    key: ctx.key,
+  });
+  if (!first.ok) {
+    ctx.err(`design check failed (${first.status}): ${first.error}`);
+    return 1;
+  }
+  let job = first.data || {};
+  if (!isTerminal(job) && job.id) {
+    const spinner = makeSpinner(`checking ${source}`, ctx.io);
+    let failures = 0;
+    const polled = await pollDesignJob(async () => {
+      const res = await ctx.request(`/design/adherence/${job.id}`, { key: ctx.key });
+      if (!res.ok) {
+        failures += 1;
+        if (failures >= 3) return { status: 'failed', error: res.error };
+        return { status: 'polling' };
+      }
+      failures = 0;
+      return res.data;
+    }, { intervalMs: ctx.pollMs, timeoutMs: ctx.maxWaitMs, sleep: ctx.sleep });
+    spinner.stop();
+    if (polled.timedOut) {
+      ctx.err(`still running after ${Math.round(ctx.maxWaitMs / 1000)}s. job id: ${job.id}`);
+      return 1;
+    }
+    job = polled.job || job;
+  }
+  if (json) { ctx.out(JSON.stringify(job, null, 2)); return job.status === 'completed' ? 0 : 1; }
+  if (job.status !== 'completed') {
+    ctx.err(`check did not finish: ${job.error || job.status || 'unknown'}`);
+    return 1;
+  }
+  ctx.out(adherenceCard(job));
+  return 0;
+}
+
+async function designSearch(args, ctx) {
+  const json = args.includes('--json');
+  const limitFlag = readFlag(args, '--limit');
+  if (limitFlag.error) { ctx.err(limitFlag.error); return 1; }
+  const bad = unknownFlags(args, ['--json']);
+  if (bad.length) { ctx.err(`unknown flag for design search: ${bad.join(' ')}`); return 1; }
+  const query = positionals(args).join(' ').trim();
+  if (!query) { ctx.err('usage: atris design search "<words>" [--limit n] [--json]'); return 1; }
+  let limit;
+  if (limitFlag.value != null) {
+    limit = parseInt(limitFlag.value, 10);
+    if (!Number.isInteger(limit) || limit < 1) {
+      ctx.err(`invalid --limit value: "${limitFlag.value}". expected a positive integer.`);
+      return 1;
+    }
+  }
+
+  const body = { query };
+  if (limit != null) body.limit = limit;
+  const res = await ctx.request('/design/search', { method: 'POST', body, key: ctx.key });
+  if (!res.ok) {
+    ctx.err(`design search failed (${res.status}): ${res.error}`);
+    return 1;
+  }
+  const data = res.data || {};
+  if (json) { ctx.out(JSON.stringify(data, null, 2)); return 0; }
+  ctx.out(searchCard(data, query));
+  return 0;
+}
+
+async function run(args = [], deps = {}) {
+  const rest = args.slice();
+  if (rest.length === 0 || wantsHelp(rest)) {
+    showDesignHelp();
+    return rest.length === 0 ? 1 : 0;
+  }
+  const sub = rest.shift();
+
+  const io = deps.io || {
+    out: (s) => process.stdout.write(`${s}\n`),
+    err: (s) => process.stderr.write(`${s}\n`),
+    write: (s) => process.stdout.write(s),
+    tty: Boolean(process.stdout.isTTY),
+  };
+  const ctx = {
+    out: deps.out || io.out,
+    err: deps.err || io.err,
+    io,
+    key: deps.key !== undefined ? deps.key : resolveDesignKey(process.env, deps),
+    request: deps.request || designRequest,
+    sleep: deps.sleep,
+    pollMs: deps.pollMs != null
+      ? deps.pollMs
+      : Number(process.env.ATRIS_DESIGN_POLL_MS) || undefined,
+    maxWaitMs: deps.maxWaitMs != null
+      ? deps.maxWaitMs
+      : Number(process.env.ATRIS_DESIGN_TIMEOUT_MS) || 3 * 60 * 1000,
+  };
+
+  if (!['extract', 'check', 'search'].includes(sub)) {
+    ctx.err(`unknown design subcommand: ${sub}`);
+    showDesignHelp();
+    return 1;
+  }
+  if (!ctx.key) {
+    ctx.err(NO_KEY);
+    return 1;
+  }
+
+  try {
+    if (sub === 'extract') return await designExtract(rest, ctx);
+    if (sub === 'check') return await designCheck(rest, ctx);
+    return await designSearch(rest, ctx);
+  } catch (error) {
+    ctx.err(`design ${sub} failed: ${(error && error.message) || error}`);
+    return 1;
+  }
+}
+
+module.exports = {
+  run,
+};