atris 3.13.0 → 3.14.0

package/README.md

@@ -4,6 +4,16 @@
 
 It turns any repo into an AI workspace with shared context, a `plan -> do -> review` loop, daily logs, feature packs, and reusable skills.
 
+Atris gives every owner persistent AI computers.
+
+```text
+Owner = User | Business
+Owner has many Computers
+Computer = workspace + files + tools + secrets + memory + agents + validation loop
+```
+
+A computer can be personal or shared by a business. It can run a job like code, research, CRM, reporting, recruiting, event ops, support, or business ops.
+
 ## For Coding Agents
 
 If you're an agent, run:
@@ -19,6 +29,8 @@ Then read the workspace's `atris/atris.md` and follow it exactly. `atris.md` is
 ## What Atris Gives You
 
 - An AI workspace on top of any repo
+- Persistent AI computers for scoped jobs
+- A local computer card that makes each workspace inspectable
 - A strict `plan -> do -> review` loop
 - Daily logs, task tracking, feature packs, and project memory
 - Skills, team members, integrations, and cloud sync when you need them
@@ -54,6 +66,7 @@ atris --version
 ```
 
 Requires Node.js 18+.
+`atris task` uses built-in SQLite and requires Node.js 22+.
 
 If you want Atris cloud workspaces, businesses, or integrations, run `atris setup` after install.
 
@@ -73,9 +86,9 @@ Core loop: `plan` -> `do` -> `review`
 
 Integrates with any agent.
 
-## Business Workspaces
+## Business Owners
 
-If you want a real business workspace, use the business command instead of raw `atris init`.
+If you want a shared owner for a company, lab, collective, community, artist, team, or project, use the business command instead of raw `atris init`.
 
 ```bash
 atris business init "BLOND:ISH" --owner-email joel@blondish.world
@@ -84,10 +97,18 @@ atris business onboard --website https://blondish.world --contact "Joel Zimmerma
 atris align --fix
 ```
 
-That creates the cloud business, writes `.atris/business.json`, initializes `.atris/state/` for events and run history, and scaffolds the local `atris/` workspace under `~/arena/atris-business/<slug>/` with starter roles, a default recap template, and an initial task queue in `atris/TODO.md`.
+That creates the shared owner, creates its first/default computer, writes `.atris/business.json`, initializes `.atris/state/` for events and run history, and scaffolds the local `atris/` workspace under `~/arena/atris-business/<slug>/` with starter roles, a default recap template, and an initial task queue in `atris/TODO.md`.
 
 If you do not have a neat source pack yet, `atris business onboard` is the easiest intake step: give it a website, a named human, a few notes, or run it in a folder with loose files. Atris turns that into raw intake, a starter brief, a first workflow, a safe next action, and a short operator brief.
 
+Use the owner's language when you talk about it:
+
+```text
+Your business runs on Atris.
+Your lab runs on Atris.
+Your collective runs on Atris.
+```
+
 You can also use bare input:
 
 ```bash
@@ -116,12 +137,14 @@ atris business record atris/reports/2026-04-12-operator-recap.md --outcome mixed
 | `atris autopilot` | Guided loop with approvals |
 | `atris log` | Add inbox items to today's journal |
 | `atris status` | Show active work and completions |
+| `atris task` | Local agent task plane with atomic claims and TODO import |
 | `atris learn` | Manage structured learnings |
 | `atris ingest` | Stage raw evidence into `atris/context/` and compile into `atris/wiki/` |
 | `atris loop` | Refresh wiki health, stale/orphan signals, and next ingest candidates |
 | `atris wiki` | Full wiki namespace: ingest, query, lint, search, log, and loop |
 | `atris receipt` | Save evidence from an agent run |
 | `atris experiments` | Run small experiments and compare results |
+| `atris computer card` | Show or write the local owner/computer card |
 
 ## Built-In Systems
 
@@ -131,6 +154,7 @@ atris business record atris/reports/2026-04-12-operator-recap.md --outcome mixed
 - `atris wiki --private` stores local-only sensitive notes under `.atris/presidio/`
 - `atris loop` refreshes `atris/wiki/STATUS.md` and `atris/wiki/log.md`, flags stale/orphan pages, and suggests the next ingest
 - `atris activate` loads the current wiki status so the next session starts with project memory, not just tasks
+- `atris task` keeps a local SQLite task plane for agents while `atris/TODO.md` remains the readable project board
 - `atris experiments` runs small test packs in `atris/experiments/`
 - `atris pull` and `atris push` sync cloud workspaces and journals
 

package/bin/atris.js

@@ -204,19 +204,26 @@ function showHelp() {
   console.log('');
   console.log('Quick Start:');
   console.log('');
-  console.log('  1. atris                  Load context, start building');
-  console.log('  2. Describe what you want (in your editor or terminal)');
-  console.log('  3. Agent shows visualization, you approve, it builds');
+  console.log('  1. atris                  Open a persistent AI computer for this workspace');
+  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('');
   console.log('Common invocations:');
   console.log('  atris init');
+  console.log('  atris computer');
+  console.log('  atris business init "My Company"');
   console.log('  atris run');
   console.log('  atris status');
   console.log('  atris soul');
-  console.log('  atris fleet');
+  console.log('  atris fleet status');
   console.log('');
   console.log('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━');
   console.log('');
+  console.log('Atris Computers:');
+  console.log('  Owner = User | Business');
+  console.log('  Owners have Computers: workspace + files + tools + secrets + memory + agents + validation');
+  console.log('  Types: code, research, CRM, reporting, recruiting, events, support, business ops');
+  console.log('');
   console.log('Setup:');
   console.log('  setup      - Guided first-time setup (login, pick business, pull)');
   console.log('  init       - Initialize Atris in current project');
@@ -237,6 +244,7 @@ function showHelp() {
   console.log('  search     - Search journal history (atris search <keyword>)');
   console.log('  clean      - Housekeeping (stale tasks, archive journals, broken refs)');
   console.log('  verify     - Validate work is done (tests, MAP.md, changes)');
+  console.log('  task       - Local agent task plane (atomic claims, TODO import)');
   console.log('  release    - Tag release, bump version, create GitHub release, draft /launch');
   console.log('  learn      - Project learnings (patterns, pitfalls, preferences)');
   console.log('  ingest     - Local-first wiki ingest into atris/wiki/');
@@ -272,7 +280,7 @@ function showHelp() {
   console.log('  wake [business]    - Resume workspace (agents restart)');
   console.log('');
   console.log('Business:');
-  console.log('  business init <name>   - RECOMMENDED: create business environment (cloud + local)');
+  console.log('  business init <name>   - Create shared owner + first/default computer');
   console.log('  business onboard       - Onboard from sparse input (--name, --website, --contact)');
   console.log('  business add <slug>    - Connect a business');
   console.log('  business list          - Show connected businesses');
@@ -280,6 +288,7 @@ function showHelp() {
   console.log('  business team [slug]   - Show members, roles, and admin access');
   console.log('  business health <slug> - Health report (members, workspace, issues)');
   console.log('  business audit         - One-line health summary of all businesses');
+  console.log('  business doctor        - Catch stale cache, alias, and folder bindings');
   console.log('  business create <name> - Cloud-only business record; add --workspace to also scaffold local');
   console.log('  business connect <svc> - Wire a skill/integration');
   console.log('  business notify <mode> - Set notification mode (digest/silent/push)');
@@ -290,9 +299,11 @@ function showHelp() {
   console.log('  cr --all               - Audit all backend services');
   console.log('');
   console.log('Cloud & agents:');
-  console.log('  computer   - Talk directly to the AI computer (bash or agent exec)');
+  console.log('  computer   - Open a scoped AI computer (cloud/local, personal/business)');
   console.log('  receipt    - Save evidence from an agent run');
   console.log('  console    - Start/attach always-on coding console (tmux daemon)');
+  console.log('  soul       - Show, snapshot, or fork workspace identity');
+  console.log('  fleet      - Inspect local fleet status');
   console.log('  agent      - Select which Atris agent to use');
   console.log('  chat       - Chat with the selected Atris agent');
   console.log('  login      - Sign in or add another account');
@@ -434,7 +445,7 @@ const { planAtris: planCmd, doAtris: doCmd, reviewAtris: reviewCmd } = require('
 const knownCommands = ['init', 'log', 'status', 'analytics', 'visualize', 'brainstorm', 'autopilot', 'run', 'plan', 'do', 'review', 'release',
                        'activate', '_activate', 'agent', 'chat', 'console', 'login', 'logout', 'whoami', 'switch', 'use', 'accounts', '_resolve', '_profile-email', '_switch-session', 'shell-init', 'update', 'upgrade', 'version', 'help', 'next', 'atris',
                        'clean', 'verify', 'search', 'skill', 'member', 'app', 'learn', 'plugin', 'experiments', 'receipt', 'proof', 'openclaw', 'pull', 'push', 'align', 'terminal', 'computer', 'diff', 'business', 'sync',
-                       'ingest', 'query', 'lint', 'loop',
+                       'ingest', 'query', 'lint', 'loop', 'task',
                        'gmail', 'calendar', 'twitter', 'slack', 'integrations', 'setup', 'clean-workspace', 'cw',
                        'fork', 'browse', 'publish', 'sleep', 'wake', 'feedback', 'errors', 'wiki', 'code-review', 'cr', 'soul', 'fleet'];
 
@@ -780,6 +791,11 @@ if (command === 'init') {
       console.error(`✗ Error: ${error.message || error}`);
       process.exit(1);
     });
+} else if (command === 'task') {
+  // SQLite-backed task plane. ~/.atris/tasks.db, gitignored, per-workspace.
+  Promise.resolve(require('../commands/task').run(process.argv.slice(3)))
+    .then(() => process.exit(0))
+    .catch((err) => { console.error(`\n✗ Error: ${err.message || err}`); process.exit(1); });
 } else if (command === 'agent') {
   agentAtris().then(() => process.exit(0)).catch((err) => { console.error(`\n✗ Error: ${err.message || err}`); process.exit(1); });
 } else if (command === 'log') {

package/commands/business.js

@@ -33,10 +33,292 @@ function loadBusinesses() {
   try { return JSON.parse(fs.readFileSync(p, 'utf8')); } catch { return {}; }
 }
 
+function businessAliases(business) {
+  const aliases = business?.aliases || business?.config?.aliases || [];
+  return Array.isArray(aliases) ? aliases : [];
+}
+
+function businessMatchesSlug(business, slug, { includeName = false } = {}) {
+  if (!business || !slug) return false;
+  const wanted = String(slug).toLowerCase();
+  const canonical = String(business.slug || '').toLowerCase();
+  const aliases = businessAliases(business).map((alias) => String(alias).toLowerCase());
+  if (canonical === wanted || aliases.includes(wanted)) return true;
+  return includeName && String(business.name || '').toLowerCase() === wanted;
+}
+
 function saveBusinesses(data) {
   fs.writeFileSync(getBusinessConfigPath(), JSON.stringify(data, null, 2));
 }
 
+function buildBusinessCacheEntry(business, localSlug, existing = {}) {
+  const aliases = businessAliases(business);
+  const entry = {
+    business_id: business.id || business.business_id,
+    workspace_id: business.workspace_id,
+    name: business.name || localSlug,
+    slug: localSlug || business.slug,
+    added_at: existing.added_at || new Date().toISOString(),
+  };
+  if (business.slug && business.slug !== entry.slug) entry.canonical_slug = business.slug;
+  else if (business.slug) entry.canonical_slug = business.slug;
+  if (aliases.length > 0) entry.aliases = aliases;
+  return entry;
+}
+
+function readBusinessFolderBindings(rootDir = path.join(os.homedir(), 'arena', 'atris-business')) {
+  const skip = new Set([
+    '.git', '.DS_Store', 'archive', 'archives', '_archive', 'bench', 'deals',
+    'node_modules', 'shelf', '_shelf', 'templates',
+  ]);
+  if (!fs.existsSync(rootDir)) return [];
+
+  return fs.readdirSync(rootDir, { withFileTypes: true })
+    .filter((entry) => !entry.name.startsWith('.') && !skip.has(entry.name))
+    .map((entry) => {
+      const fullPath = path.join(rootDir, entry.name);
+      let isDirectory = entry.isDirectory();
+      const isSymlink = entry.isSymbolicLink();
+      let symlinkTarget = null;
+      if (isSymlink) {
+        try {
+          symlinkTarget = fs.readlinkSync(fullPath);
+          isDirectory = fs.statSync(fullPath).isDirectory();
+        } catch {
+          isDirectory = false;
+        }
+      }
+      if (!isDirectory) return null;
+
+      const businessJsonPath = path.join(fullPath, '.atris', 'business.json');
+      const atrisDir = path.join(fullPath, 'atris');
+      const binding = {
+        name: entry.name,
+        path: fullPath,
+        isSymlink,
+        symlinkTarget,
+        hasAtris: fs.existsSync(atrisDir) && fs.statSync(atrisDir).isDirectory(),
+        hasBusinessJson: fs.existsSync(businessJsonPath),
+        businessJsonPath,
+        meta: null,
+        error: null,
+      };
+
+      if (binding.hasBusinessJson) {
+        try {
+          binding.meta = JSON.parse(fs.readFileSync(businessJsonPath, 'utf8'));
+        } catch (err) {
+          binding.error = err.message || 'invalid JSON';
+        }
+      }
+      return binding;
+    })
+    .filter(Boolean);
+}
+
+function analyzeBusinessDoctor({ cache = {}, cloudBusinesses = [], folderBindings = [] } = {}) {
+  const issues = [];
+  const cacheUpdates = {};
+  const activeById = new Map();
+  const activeBySlug = new Map();
+  const realFolderIds = new Map();
+
+  for (const business of cloudBusinesses || []) {
+    const id = business.id || business.business_id;
+    if (!id) continue;
+    activeById.set(id, business);
+    if (business.slug) {
+      const lower = String(business.slug).toLowerCase();
+      if (activeBySlug.has(lower)) {
+        issues.push({
+          level: 'fail',
+          code: 'duplicate-active-slug',
+          subject: business.slug,
+          message: `multiple active cloud businesses use slug ${business.slug}`,
+        });
+      }
+      activeBySlug.set(lower, business);
+    }
+  }
+
+  const findActiveMatch = (key, entry = {}) => {
+    if (entry.business_id && activeById.has(entry.business_id)) return activeById.get(entry.business_id);
+    const candidates = [key, entry.slug, entry.canonical_slug, entry.name].filter(Boolean);
+    return cloudBusinesses.find((business) =>
+      candidates.some((candidate) => businessMatchesSlug(business, candidate, { includeName: true }))
+    ) || null;
+  };
+
+  for (const [key, entry] of Object.entries(cache || {})) {
+    const active = findActiveMatch(key, entry);
+    if (!active) {
+      issues.push({
+        level: 'fail',
+        code: 'stale-cache',
+        subject: key,
+        message: `${key} points at a deleted/inaccessible business (${entry.business_id || 'missing id'})`,
+      });
+      continue;
+    }
+
+    if (entry.business_id && entry.business_id !== active.id) {
+      issues.push({
+        level: 'fail',
+        code: 'stale-cache-repoint',
+        subject: key,
+        message: `${key} points at ${entry.business_id}; active cloud row is ${active.id}`,
+        fixable: true,
+      });
+      cacheUpdates[key] = buildBusinessCacheEntry(active, key, entry);
+    }
+
+    if (!businessMatchesSlug({ ...active, aliases: businessAliases(active) }, key, { includeName: true }) && key !== active.slug) {
+      issues.push({
+        level: 'warn',
+        code: 'cache-key-not-alias',
+        subject: key,
+        message: `${key} is cached but is not the canonical slug, alias, or name for ${active.slug}`,
+      });
+    }
+  }
+
+  for (const business of cloudBusinesses || []) {
+    const canonicalKey = business.slug;
+    if (canonicalKey && (!cache[canonicalKey] || cache[canonicalKey].business_id !== business.id)) {
+      issues.push({
+        level: 'warn',
+        code: 'missing-canonical-cache',
+        subject: canonicalKey,
+        message: `${canonicalKey} is active in cloud but missing/stale in local cache`,
+        fixable: true,
+      });
+      cacheUpdates[canonicalKey] = buildBusinessCacheEntry(business, canonicalKey, cache[canonicalKey]);
+    }
+
+    for (const alias of businessAliases(business)) {
+      if (!cache[alias] || cache[alias].business_id !== business.id) {
+        issues.push({
+          level: 'warn',
+          code: 'missing-alias-cache',
+          subject: alias,
+          message: `${alias} is an active alias for ${business.slug} but missing/stale in local cache`,
+          fixable: true,
+        });
+        cacheUpdates[alias] = buildBusinessCacheEntry(business, alias, cache[alias]);
+      }
+    }
+  }
+
+  for (const binding of folderBindings || []) {
+    if (binding.error) {
+      issues.push({
+        level: 'fail',
+        code: 'invalid-business-json',
+        subject: binding.name,
+        message: `${binding.name}/.atris/business.json is invalid: ${binding.error}`,
+      });
+      continue;
+    }
+
+    if (!binding.hasBusinessJson) {
+      if (binding.hasAtris && !binding.isSymlink) {
+        issues.push({
+          level: 'warn',
+          code: 'folder-unbound',
+          subject: binding.name,
+          message: `${binding.name} has atris/ but no .atris/business.json`,
+        });
+      }
+      continue;
+    }
+
+    const meta = binding.meta || {};
+    const active = findActiveMatch(binding.name, {
+      business_id: meta.business_id,
+      slug: meta.slug,
+      canonical_slug: meta.canonical_slug,
+      name: meta.name,
+    });
+
+    if (!active) {
+      issues.push({
+        level: 'fail',
+        code: 'stale-folder-binding',
+        subject: binding.name,
+        message: `${binding.name} is bound to deleted/inaccessible business ${meta.business_id || meta.slug || 'unknown'}`,
+      });
+      continue;
+    }
+
+    if (meta.business_id && meta.business_id !== active.id) {
+      issues.push({
+        level: 'fail',
+        code: 'folder-id-mismatch',
+        subject: binding.name,
+        message: `${binding.name} points at ${meta.business_id}; active cloud row is ${active.id}`,
+      });
+    }
+
+    if (meta.slug && !businessMatchesSlug(active, meta.slug, { includeName: true })) {
+      issues.push({
+        level: 'fail',
+        code: 'folder-slug-mismatch',
+        subject: binding.name,
+        message: `${binding.name} uses slug ${meta.slug}, which is not ${active.slug} or an alias`,
+      });
+    }
+
+    if (!businessMatchesSlug(active, binding.name, { includeName: false }) && !binding.isSymlink) {
+      issues.push({
+        level: 'warn',
+        code: 'folder-name-not-slug-or-alias',
+        subject: binding.name,
+        message: `${binding.name} is not a canonical slug or alias for ${active.slug}`,
+      });
+    }
+
+    if (!binding.isSymlink) {
+      const existing = realFolderIds.get(active.id) || [];
+      existing.push(binding.name);
+      realFolderIds.set(active.id, existing);
+    }
+
+    const cacheKey = meta.slug || binding.name;
+    if (!cache[cacheKey] || cache[cacheKey].business_id !== active.id) {
+      issues.push({
+        level: 'warn',
+        code: 'folder-cache-missing',
+        subject: cacheKey,
+        message: `${binding.name} is bound locally but ${cacheKey} is missing/stale in local cache`,
+        fixable: true,
+      });
+      cacheUpdates[cacheKey] = buildBusinessCacheEntry(active, cacheKey, cache[cacheKey]);
+    }
+  }
+
+  for (const [businessId, names] of realFolderIds.entries()) {
+    if (names.length > 1) {
+      issues.push({
+        level: 'fail',
+        code: 'duplicate-real-folders',
+        subject: businessId,
+        message: `business ${businessId} has multiple real folders: ${names.join(', ')}`,
+      });
+    }
+  }
+
+  return {
+    issues,
+    cacheUpdates,
+    stats: {
+      cache_entries: Object.keys(cache || {}).length,
+      cloud_active: cloudBusinesses.length,
+      folders: folderBindings.length,
+      fixable_cache_entries: Object.keys(cacheUpdates).length,
+    },
+  };
+}
+
 function parseCreateBusinessFlags(flags, cwd = process.cwd()) {
   const options = {
     description: '',
@@ -797,7 +1079,7 @@ async function findExistingBusinessBySlug(slug, token) {
     return { id: local[slug].business_id, name: local[slug].name, slug, source: 'local' };
   }
   for (const v of Object.values(local)) {
-    if (v && v.slug === slug) {
+    if (businessMatchesSlug(v, slug)) {
       return { id: v.business_id, name: v.name, slug, source: 'local' };
     }
   }
@@ -815,7 +1097,7 @@ async function findExistingBusinessBySlug(slug, token) {
 
   const list = await apiRequestJson('/business/', { method: 'GET', token });
   if (list.ok && Array.isArray(list.data)) {
-    const match = list.data.find(b => b && b.slug === slug);
+    const match = list.data.find(b => businessMatchesSlug(b, slug));
     if (match) return { id: match.id, name: match.name, slug: match.slug, source: 'cloud' };
   }
 
@@ -848,7 +1130,7 @@ async function addBusiness(slug) {
     // Try listing all and matching
     const listResult = await apiRequestJson('/business/', { method: 'GET', token: creds.token });
     if (listResult.ok && Array.isArray(listResult.data)) {
-      const match = listResult.data.find(b => b.slug === slug || b.name.toLowerCase() === slug.toLowerCase());
+      const match = listResult.data.find(b => businessMatchesSlug(b, slug, { includeName: true }));
       if (match) {
         const businesses = loadBusinesses();
         businesses[slug] = {
@@ -1099,7 +1381,7 @@ async function resolveSlug(slug, creds) {
   // Fallback: list all and match
   const listResult = await apiRequestJson('/business/', { method: 'GET', token: creds.token });
   if (listResult.ok && Array.isArray(listResult.data)) {
-    const match = listResult.data.find(b => b.slug === slug || b.name.toLowerCase() === slug.toLowerCase());
+    const match = listResult.data.find(b => businessMatchesSlug(b, slug, { includeName: true }));
     if (match) {
       return { business_id: match.id, workspace_id: match.workspace_id, name: match.name, slug: match.slug };
     }
@@ -1313,6 +1595,103 @@ async function businessAudit() {
   console.log('');
 }
 
+function parseBusinessDoctorOptions(args = []) {
+  const options = {
+    fix: args.includes('--fix'),
+    json: args.includes('--json'),
+    root: path.join(os.homedir(), 'arena', 'atris-business'),
+  };
+  const rootIdx = args.indexOf('--root');
+  if (rootIdx !== -1 && args[rootIdx + 1]) {
+    options.root = path.resolve(args[rootIdx + 1]);
+  }
+  return options;
+}
+
+function printBusinessDoctorHelp() {
+  console.log('Usage: atris business doctor [--fix] [--root <dir>] [--json]');
+  console.log('');
+  console.log('Checks cloud-active businesses against:');
+  console.log('  - ~/.atris/businesses.json');
+  console.log('  - ~/arena/atris-business/*/.atris/business.json');
+  console.log('  - canonical slug + alias bindings');
+  console.log('');
+  console.log('--fix rewrites only safe local cache entries. It does not rename folders or touch cloud data.');
+}
+
+async function businessDoctor(...args) {
+  if (args.some(isHelpToken)) {
+    printBusinessDoctorHelp();
+    return;
+  }
+
+  const options = parseBusinessDoctorOptions(args);
+  const creds = loadCredentials();
+  if (!creds || !creds.token) {
+    console.error('Not logged in. Run: atris login');
+    process.exit(1);
+  }
+
+  const listResult = await apiRequestJson('/business/', { method: 'GET', token: creds.token });
+  if (!listResult.ok || !Array.isArray(listResult.data)) {
+    console.error(`Failed to fetch businesses: ${listResult.errorMessage || listResult.error || listResult.status || 'unknown error'}`);
+    process.exit(1);
+  }
+
+  let cache = loadBusinesses();
+  const folderBindings = readBusinessFolderBindings(options.root);
+  let analysis = analyzeBusinessDoctor({
+    cache,
+    cloudBusinesses: listResult.data,
+    folderBindings,
+  });
+
+  const cacheUpdateKeys = Object.keys(analysis.cacheUpdates);
+  let fixed = [];
+  if (options.fix && cacheUpdateKeys.length > 0) {
+    cache = { ...cache, ...analysis.cacheUpdates };
+    saveBusinesses(cache);
+    fixed = cacheUpdateKeys;
+    analysis = analyzeBusinessDoctor({
+      cache,
+      cloudBusinesses: listResult.data,
+      folderBindings,
+    });
+  }
+
+  if (options.json) {
+    console.log(JSON.stringify({
+      root: options.root,
+      stats: analysis.stats,
+      fixed,
+      issues: analysis.issues,
+    }, null, 2));
+  } else {
+    console.log('');
+    console.log('Business Doctor');
+    console.log('---------------');
+    console.log(`cloud active: ${analysis.stats.cloud_active}`);
+    console.log(`cache entries: ${analysis.stats.cache_entries}`);
+    console.log(`folders scanned: ${analysis.stats.folders}`);
+    if (fixed.length > 0) console.log(`fixed cache entries: ${fixed.join(', ')}`);
+    console.log('');
+
+    if (analysis.issues.length === 0) {
+      console.log('OK no business binding drift found.');
+    } else {
+      for (const issue of analysis.issues) {
+        const label = issue.level === 'fail' ? 'FAIL' : 'WARN';
+        const fixHint = issue.fixable ? ' (run with --fix)' : '';
+        console.log(`${label} ${issue.code}: ${issue.message}${fixHint}`);
+      }
+    }
+    console.log('');
+  }
+
+  const failures = analysis.issues.filter((issue) => issue.level === 'fail');
+  if (failures.length > 0) process.exitCode = 1;
+}
+
 async function createBusinessInternal(name, flags = [], mode = 'auto') {
   if (!name || isHelpToken(name) || String(name).startsWith('-')) {
     console.error('Usage: atris business create <name> [--description "..."] [--workspace] [--here|--root <dir>]');
@@ -1778,7 +2157,7 @@ async function deployBusiness(slug) {
     // Try to find by slug in cloud
     const listResult = await apiRequestJson('/business/', { method: 'GET', token: creds.token });
     if (listResult.ok && Array.isArray(listResult.data)) {
-      const match = listResult.data.find(b => b.slug === slug);
+      const match = listResult.data.find(b => businessMatchesSlug(b, slug));
       if (match) {
         bizConfig = { business_id: match.id, workspace_id: match.workspace_id, name: match.name, slug: match.slug };
         businesses[slug] = { ...bizConfig, added_at: new Date().toISOString() };
@@ -1933,6 +2312,7 @@ function printBusinessHelp() {
   console.log('  status <slug>        Quick status check');
   console.log('  health [slug]        Full health dashboard');
   console.log('  audit                Audit all businesses');
+  console.log('  doctor [--fix]       Find stale business cache, alias, and folder bindings');
   console.log('  connect <service>    Connect a skill/integration');
   console.log('  notify <mode>        Set notification mode (digest/silent/push)');
   console.log('  deploy <slug>        Push local business to cloud');
@@ -1951,7 +2331,7 @@ async function businessCommand(subcommand, ...args) {
     printBusinessHelp();
     return;
   }
-  if (args.length > 0 && isHelpToken(args[0])) {
+  if (args.length > 0 && isHelpToken(args[0]) && subcommand !== 'doctor') {
     printBusinessHelp();
     return;
   }
@@ -2001,6 +2381,9 @@ async function businessCommand(subcommand, ...args) {
     case 'audit':
       await businessAudit();
       break;
+    case 'doctor':
+      await businessDoctor(...args);
+      break;
     case 'connect':
       await connectService(args[0], ...args.slice(1));
       break;
@@ -2036,10 +2419,14 @@ module.exports = {
   businessCommand,
   businessHealth,
   businessAudit,
+  businessDoctor,
   businessTeam,
   loadBusinesses,
   saveBusinesses,
   getBusinessConfigPath,
+  businessMatchesSlug,
+  analyzeBusinessDoctor,
+  readBusinessFolderBindings,
   createCanonicalBusinessWorkspace,
   initBusinessWorkspace,
   onboardBusiness,