clawkit-doctor 2.0.1 → 2.2.0

package/README.md

@@ -1,28 +1,88 @@
 # ClawKit Doctor
 
-> Instant environment diagnostic tool for OpenClaw.
+Fast diagnostics and safe auto-repair for OpenClaw environments.
+
+Maintainer: **@branzoom**
 
 ## Usage
 
-Simply run:
+```bash
+npx clawkit-doctor@latest
+```
+
+### Common modes
 
 ```bash
+# Diagnose only
 npx clawkit-doctor@latest
+
+# Diagnose + safe auto-repair
+npx clawkit-doctor@latest --fix
+
+# Paste an error for instant recognition + fix steps
+npx clawkit-doctor@latest --paste "Telegram getUpdates conflict 409"
+
+# Continue to full environment checks after paste diagnosis
+npx clawkit-doctor@latest --paste "token mismatch" --full
+
+# Language selection
+npx clawkit-doctor@latest --lang zh
+
+# Skip 0/1 follow-up prompts
+npx clawkit-doctor@latest --no-interactive
+
+# Machine-readable output
+npx clawkit-doctor@latest --json
 ```
 
-No installation required.
+## Flags
+
+- `--fix`: auto-repair supported issues (missing config dir, stale locks, token alignment, permissions)
+- `--paste "<error text>"`: detect known issues from pasted logs/errors and show steps
+- `--full`: with `--paste`, continue into full environment checks
+- `--lang en|zh|ja`: switch UI language
+- `--no-interactive`: disable the y/n resolution follow-up
+- `--json`: print full report JSON for CI/automation
+- `--quiet`: reduce console output
+- `--no-report`: skip shareable report URL
+- `--help`, `--version`
 
 ## What it checks
 
-1.  **Node.js Version**: Ensures you are running Node.js v18+.
-2.  **Config Directory**: Checks if `~/.openclaw` exists.
-3.  **Config File**: Checks if `clawhub.json` is present.
-4.  **Permissions**: Verifies write access to the config directory.
-5.  **Connectivity**: Checks if the local agent is running on port 3000.
+1. Node.js version (`v22+` required)
+2. Git availability
+3. Docker availability
+4. OpenClaw config directory (`~/.openclaw`)
+5. Config file syntax (`openclaw.json`)
+6. Directory write permissions
+7. Gateway token alignment (`auth`, `remote`, env override)
+8. Stale lock files under `~/.openclaw/sessions`
+9. Port `18789` (gateway)
+10. Port `3000` (agent)
+11. Port `18800` (browser CDP)
+
+## Resolution loop (best-practice UX)
+
+When `--paste` is used in an interactive terminal, Doctor asks:
+
+1. `y/n` whether the issue is solved (also accepts `1/0` for compatibility)
+2. If not solved, reason selection (`command`, `permission`, `timeout/network`, `not sure`)
+3. Provides fallback steps and asks `y/n` again
+4. Only after repeated failure, shows escalation links (issue details, troubleshooting index, contact)
 
-## Publishing (For Maintainers)
+This avoids hard-sell behavior and keeps flow focused on incident recovery.
 
-To publish a new version:
+## Built-in links (contextual)
 
-1.  Update the version in `package.json`.
-2.  Run `npm publish --access public`.
+Doctor links users naturally based on state:
+
+- Matched issue details page (`/docs/troubleshooting/...`)
+- Troubleshooting index: `https://getclawkit.com/docs/troubleshooting`
+- Prevention guide (post-resolution): `https://getclawkit.com/docs/guides/stable-ops`
+
+## Maintainer publish
+
+```bash
+cd packages/clawkit-doctor
+npm publish --access public
+```

package/bin/index.js

@@ -5,431 +5,741 @@ const path = require('path');
 const os = require('os');
 const chalk = require('chalk');
 const ora = require('ora');
-const http = require('http');
 const net = require('net');
+const readline = require('readline');
 const { execSync } = require('child_process');
 
-// --- Help & Version ---
-if (process.argv.includes('--help') || process.argv.includes('-h')) {
-    console.log(`
-${chalk.cyan.bold('🦞 ClawKit Doctor v2.0')} — Diagnose & fix your OpenClaw environment
+const pkg = require('../package.json');
 
-${chalk.bold('Usage:')}
-  npx clawkit-doctor@latest           Run all diagnostics (read-only)
-  npx clawkit-doctor@latest --fix     Run diagnostics + auto-repair issues
-  npx clawkit-doctor@latest --help    Show this help message
-  npx clawkit-doctor@latest --version Show version
-
-${chalk.bold('What it checks (11 items):')}
-  ${chalk.green('✓')} Node.js version (v18+ required)
-  ${chalk.green('✓')} Git installed and in PATH
-  ${chalk.green('✓')} Docker installed and in PATH
-  ${chalk.green('✓')} Config directory (~/.openclaw)
-  ${chalk.green('✓')} Config file validity (clawhub.json JSON syntax)
-  ${chalk.green('✓')} Directory write permissions
-  ${chalk.green('✓')} Gateway token alignment (auth vs remote vs env)
-  ${chalk.green('✓')} Stale lock files
-  ${chalk.green('✓')} Gateway port 18789
-  ${chalk.green('✓')} Agent port 3000
-  ${chalk.green('✓')} Browser CDP port 18800
-
-${chalk.bold('What --fix auto-repairs:')}
-  ${chalk.yellow('⚡')} Creates missing config directory
-  ${chalk.yellow('⚡')} Removes stale session lock files
-  ${chalk.yellow('⚡')} Aligns mismatched gateway tokens
-  ${chalk.yellow('⚡')} Fixes directory ownership (macOS/Linux)
-
-${chalk.bold('Report:')}
-  After running, a shareable report URL is generated.
-  Paste it in GitHub issues or Discord for quick support.
-
-${chalk.gray('More info: https://getclawkit.com/tools/doctor')}
-`);
-    process.exit(0);
-}
-
-if (process.argv.includes('--version') || process.argv.includes('-v')) {
-    console.log('clawkit-doctor v2.0.0');
-    process.exit(0);
-}
-
-// --- Configuration ---
 const SITE_URL = 'https://getclawkit.com';
 const CONFIG_DIR = path.join(os.homedir(), '.openclaw');
-const CONFIG_FILE = path.join(CONFIG_DIR, 'clawhub.json');
+const CONFIG_FILE = path.join(CONFIG_DIR, 'openclaw.json');
 const SESSIONS_DIR = path.join(CONFIG_DIR, 'sessions');
-const FIX_MODE = process.argv.includes('--fix');
 
-// --- Report collector ---
+const argv = process.argv.slice(2);
+const args = new Set(argv);
+function getArgValue(flag) {
+  for (let i = 0; i < argv.length; i += 1) {
+    const token = argv[i];
+    if (token === flag && i + 1 < argv.length) return argv[i + 1];
+    if (token.startsWith(`${flag}=`)) return token.slice(flag.length + 1);
+  }
+  return '';
+}
+
+const requestedLang = (getArgValue('--lang') || process.env.LANG || 'en').toLowerCase();
+const LANG = requestedLang.startsWith('zh') ? 'zh' : requestedLang.startsWith('ja') ? 'ja' : 'en';
+const PASTE_TEXT = (getArgValue('--paste') || '').trim();
+const FULL_MODE = args.has('--full');
+const FIX_MODE = args.has('--fix');
+const JSON_MODE = args.has('--json');
+const QUIET_MODE = args.has('--quiet') || JSON_MODE;
+const INTERACTIVE_MODE = !args.has('--no-interactive') && !!process.stdin.isTTY && !JSON_MODE;
+const NO_REPORT = args.has('--no-report');
+
 const report = {
-    ts: new Date().toISOString(),
-    os: `${os.platform()} ${os.arch()} ${os.release()}`,
-    node: process.version,
-    fix: FIX_MODE,
-    checks: [],
+  ts: new Date().toISOString(),
+  version: pkg.version,
+  os: `${os.platform()} ${os.arch()} ${os.release()}`,
+  node: process.version,
+  fix: FIX_MODE,
+  checks: [],
+  totals: {},
+  resolution: null,
+};
+
+const i18n = {
+  en: {
+    subtitle: 'Reliable OpenClaw diagnostics and repair',
+    docs: 'Troubleshooting index',
+    prevent: 'Prevention guide',
+    explore: 'Explore more skills & workflows',
+    support: 'Support channel',
+    summary: 'Summary',
+    tipFix: 'Tip: run with --fix for safe auto-repairs where supported.',
+    blocking: 'Blocking issues',
+    share: 'Shareable report',
+    pasteTitle: 'Pasted error diagnosis',
+    pasteMatched: 'Matched issue',
+    pasteNoMatch: 'No direct match found',
+    pasteNext: 'Next step',
+    pasteDetails: 'See detailed fix',
+    resolvedAsk: 'Did this fix restore your setup? (y=yes, n=no)',
+    resolvedAskAgain: 'After the fallback steps, is it solved now? (y=yes, n=no)',
+    resolvedDone: 'Nice. Incident closed.',
+    resolvedDoneDetail: 'System is back online.',
+    unresolvedReason: 'Why not solved? 1=command error 2=permission issue 3=timeout/network 4=not sure',
+    retrySteps: 'Recommended fallback steps',
+    escalate: 'Escalation',
+    askFull: 'Run full environment diagnostics now? (y=yes, n=no)',
+    nonInteractive: 'Interactive follow-up skipped (non-TTY).',
+  },
+  zh: {
+    subtitle: 'OpenClaw 环境诊断与安全修复',
+    docs: '故障排查总览',
+    prevent: '预防建议',
+    explore: '继续探索 skills 与 workflows',
+    support: '支持渠道',
+    summary: '诊断总结',
+    tipFix: '提示：可用 --fix 自动修复可安全处理的问题。',
+    blocking: '阻塞问题',
+    share: '可分享报告',
+    pasteTitle: '粘贴错误诊断',
+    pasteMatched: '匹配到问题',
+    pasteNoMatch: '未直接匹配到已知问题',
+    pasteNext: '下一步',
+    pasteDetails: '查看该问题的详细修复',
+    resolvedAsk: '执行后是否恢复正常？(y=是, n=否)',
+    resolvedAskAgain: '执行补救步骤后，现在是否已解决？(y=是, n=否)',
+    resolvedDone: '搞定，故障已关闭。',
+    resolvedDoneDetail: '系统已恢复可用。',
+    unresolvedReason: '未解决的主要原因？1=命令报错 2=权限问题 3=超时/网络 4=不确定',
+    retrySteps: '建议的补救步骤',
+    escalate: '升级处理',
+    askFull: '是否继续执行完整环境诊断？(y=是, n=否)',
+    nonInteractive: '当前不是交互终端，已跳过 0/1 追问。',
+  },
+  ja: {
+    subtitle: 'OpenClaw 環境の診断と安全な修復',
+    docs: 'トラブルシューティング一覧',
+    prevent: '再発防止ガイド',
+    explore: 'skills と workflows を探す',
+    support: 'サポート窓口',
+    summary: '診断サマリー',
+    tipFix: '--fix で安全に自動修復できます。',
+    blocking: 'ブロッキング問題',
+    share: '共有レポート',
+    pasteTitle: '貼り付けエラー診断',
+    pasteMatched: '一致した問題',
+    pasteNoMatch: '既知パターンに一致しませんでした',
+    pasteNext: '次のステップ',
+    pasteDetails: 'この問題の詳細な修正手順',
+    resolvedAsk: 'この修正で復旧しましたか？ (y=はい, n=いいえ)',
+    resolvedAskAgain: '追加手順の後、解決しましたか？ (y=はい, n=いいえ)',
+    resolvedDone: '解決完了。インシデントをクローズしました。',
+    resolvedDoneDetail: 'システムは正常に戻りました。',
+    unresolvedReason: '未解決の理由は？ 1=コマンド失敗 2=権限問題 3=タイムアウト/ネットワーク 4=不明',
+    retrySteps: '推奨フォールバック手順',
+    escalate: 'エスカレーション',
+    askFull: 'フル環境診断を続行しますか？ (y=はい, n=いいえ)',
+    nonInteractive: '対話端末ではないため追跡質問をスキップしました。',
+  },
 };
+const t = i18n[LANG];
 
-function record(id, status, message, helpUrl) {
-    report.checks.push({ id, status, message });
-    return { id, status, message, helpUrl };
+if (args.has('--help') || args.has('-h')) {
+  console.log(`
+${chalk.cyan.bold('ClawKit Doctor')} ${chalk.gray(`v${pkg.version}`)}
+${chalk.gray('by @branzoom (GitHub)')}
+
+${chalk.bold('Usage:')}
+  npx clawkit-doctor@latest
+  npx clawkit-doctor@latest --fix
+  npx clawkit-doctor@latest --paste "your error text"
+  npx clawkit-doctor@latest --json
+
+${chalk.bold('Flags:')}
+  --fix        Auto-repair supported issues
+  --paste      Diagnose a pasted error and print fix steps
+  --full       Run full environment checks after --paste
+  --lang       Language: en | zh | ja
+  --no-interactive  Skip 0/1 resolution follow-up prompts
+  --json       Output machine-readable JSON report
+  --quiet      Suppress banners and non-essential logs
+  --no-report  Do not print shareable report URL
+  --version    Print version
+  --help       Show this help
+
+${chalk.bold('Checks:')}
+  Node.js (v22+), Git, Docker, OpenClaw config, permissions,
+  gateway token alignment, stale lock files, and key local ports.
+
+${chalk.gray(`Docs: ${SITE_URL}/docs/troubleshooting`)}`);
+  process.exit(0);
+}
+
+if (args.has('--version') || args.has('-v')) {
+  console.log(`clawkit-doctor v${pkg.version}`);
+  process.exit(0);
+}
+
+function createSpinner(text) {
+  if (QUIET_MODE) {
+    return {
+      text,
+      start() { return this; },
+      succeed() {},
+      fail() {},
+      warn() {},
+      info() {},
+    };
+  }
+  return ora(text).start();
+}
+
+function logLine(message) {
+  if (!QUIET_MODE) console.log(message);
 }
 
-// --- Helpers ---
 function commandExists(cmd) {
-    try {
-        const where = os.platform() === 'win32' ? 'where' : 'which';
-        execSync(`${where} ${cmd}`, { stdio: 'ignore' });
-        return true;
-    } catch {
-        return false;
-    }
+  try {
+    const where = os.platform() === 'win32' ? 'where' : 'which';
+    execSync(`${where} ${cmd}`, { stdio: 'ignore' });
+    return true;
+  } catch {
+    return false;
+  }
 }
 
 function getCommandVersion(cmd) {
-    try {
-        return execSync(`${cmd} --version`, { encoding: 'utf8', timeout: 5000 }).trim().split('\n')[0];
-    } catch {
-        return null;
-    }
+  try {
+    return execSync(`${cmd} --version`, { encoding: 'utf8', timeout: 5000 }).trim().split('\n')[0];
+  } catch {
+    return null;
+  }
 }
 
 function checkPort(port) {
-    return new Promise((resolve) => {
-        const server = net.createServer();
-        server.listen(port, '127.0.0.1', () => {
-            server.close(() => resolve(false)); // port is free
-        });
-        server.on('error', () => resolve(true)); // port is in use
+  return new Promise((resolve) => {
+    const server = net.createServer();
+    server.listen(port, '127.0.0.1', () => {
+      server.close(() => resolve(false));
     });
+    server.on('error', () => resolve(true));
+  });
 }
 
 function readConfig() {
-    try {
-        const raw = fs.readFileSync(CONFIG_FILE, 'utf8');
-        return JSON.parse(raw);
-    } catch {
-        return null;
-    }
+  try {
+    return JSON.parse(fs.readFileSync(CONFIG_FILE, 'utf8'));
+  } catch {
+    return null;
+  }
 }
 
 function getNestedValue(obj, keyPath) {
-    return keyPath.split('.').reduce((o, k) => (o && o[k] !== undefined ? o[k] : undefined), obj);
+  return keyPath.split('.').reduce((acc, segment) => (acc && acc[segment] !== undefined ? acc[segment] : undefined), obj);
 }
 
-// ============================================================
-// Checks
-// ============================================================
-
-async function checkNodeVersion() {
-    const spinner = ora('Checking Node.js version...').start();
-    const major = parseInt(process.version.substring(1).split('.')[0], 10);
+function setNestedValue(obj, keyPath, value) {
+  const keys = keyPath.split('.');
+  let current = obj;
+  for (let i = 0; i < keys.length - 1; i += 1) {
+    const key = keys[i];
+    if (!current[key] || typeof current[key] !== 'object') current[key] = {};
+    current = current[key];
+  }
+  current[keys[keys.length - 1]] = value;
+}
 
-    if (major >= 18) {
-        spinner.succeed(chalk.green(`Node.js ${process.version}`));
-        return record('node', 'pass', `Node.js ${process.version}`);
-    } else {
-        spinner.fail(chalk.red(`Node.js ${process.version} is too old. Install Node.js v18+.`));
-        return record('node', 'fail', `Node.js ${process.version} — requires v18+`);
-    }
+function recordResult(id, status, message, detail, helpUrl, elapsedMs) {
+  const item = {
+    id,
+    status,
+    message,
+    detail: detail || null,
+    helpUrl: helpUrl || null,
+    elapsedMs,
+  };
+  report.checks.push(item);
+  return item;
 }
 
-async function checkGit() {
-    const spinner = ora('Checking Git...').start();
-    if (commandExists('git')) {
-        const ver = getCommandVersion('git') || 'found';
-        spinner.succeed(chalk.green(`Git: ${ver}`));
-        return record('git', 'pass', ver);
-    } else {
-        const helpUrl = `${SITE_URL}/docs/troubleshooting/spawn-git-enoent`;
-        spinner.fail(chalk.red(`Git not found. npm packages that use Git will fail.`));
-        console.log(chalk.gray(`  Fix: ${helpUrl}`));
-        if (FIX_MODE && os.platform() === 'win32') {
-            console.log(chalk.yellow('  Auto-fix: running winget install Git.Git ...'));
-            try { execSync('winget install Git.Git', { stdio: 'inherit' }); } catch { /* ignore */ }
-        }
-        return record('git', 'fail', 'Git not installed or not in PATH', helpUrl);
-    }
+async function runCheck(id, title, fn) {
+  const start = Date.now();
+  const spinner = createSpinner(title);
+  try {
+    const result = await fn(spinner);
+    return recordResult(id, result.status, result.message, result.detail, result.helpUrl, Date.now() - start);
+  } catch (error) {
+    spinner.fail('Unexpected check error');
+    return recordResult(id, 'fail', 'Unexpected check error', String(error.message || error), null, Date.now() - start);
+  }
 }
 
-async function checkDocker() {
-    const spinner = ora('Checking Docker...').start();
-    if (commandExists('docker')) {
-        const ver = getCommandVersion('docker') || 'found';
-        spinner.succeed(chalk.green(`Docker: ${ver}`));
-        return record('docker', 'pass', ver);
-    } else {
-        const helpUrl = `${SITE_URL}/docs/troubleshooting/spawn-docker-enoent`;
-        spinner.warn(chalk.yellow('Docker not found. Agent sandbox mode will fail.'));
-        console.log(chalk.gray(`  Fix: Install Docker or disable sandbox: openclaw config set agents.defaults.sandbox.mode off`));
-        console.log(chalk.gray(`  Guide: ${helpUrl}`));
-        return record('docker', 'warn', 'Docker not installed (sandbox mode will fail)', helpUrl);
-    }
+async function checkNodeVersion(spinner) {
+  const major = Number.parseInt(process.version.slice(1).split('.')[0], 10);
+  if (major >= 22) {
+    spinner.succeed(chalk.green(`Node.js ${process.version}`));
+    return { status: 'pass', message: `Node.js ${process.version}` };
+  }
+  spinner.fail(chalk.red(`Node.js ${process.version} is too old. Install Node.js v22+.`));
+  return {
+    status: 'fail',
+    message: `Node.js ${process.version} (requires v22+)`,
+    helpUrl: `${SITE_URL}/docs/troubleshooting/windows-npm-install-errors`,
+  };
 }
 
-async function checkConfigDir() {
-    const spinner = ora('Checking config directory...').start();
-    try {
-        await fs.promises.access(CONFIG_DIR);
-        spinner.succeed(chalk.green(`Config directory: ${CONFIG_DIR}`));
-        return record('config_dir', 'pass', CONFIG_DIR);
-    } catch {
-        spinner.fail(chalk.red(`Config directory missing: ${CONFIG_DIR}`));
-        console.log(chalk.gray(`  Fix: Run 'openclaw init' or use ${SITE_URL}/tools/config`));
-        if (FIX_MODE) {
-            console.log(chalk.yellow('  Auto-fix: creating directory...'));
-            fs.mkdirSync(CONFIG_DIR, { recursive: true });
-            console.log(chalk.green('  Created.'));
-        }
-        return record('config_dir', 'fail', `Missing: ${CONFIG_DIR}`);
-    }
+async function checkGit(spinner) {
+  if (!commandExists('git')) {
+    const helpUrl = `${SITE_URL}/docs/troubleshooting/spawn-git-enoent`;
+    spinner.fail(chalk.red('Git not found in PATH.'));
+    logLine(chalk.gray(`  Fix: ${helpUrl}`));
+    return { status: 'fail', message: 'Git missing', helpUrl };
+  }
+  const version = getCommandVersion('git') || 'git found';
+  spinner.succeed(chalk.green(`Git: ${version}`));
+  return { status: 'pass', message: version };
 }
 
-async function checkConfigFile() {
-    const spinner = ora('Checking config file (clawhub.json)...').start();
-    try {
-        await fs.promises.access(CONFIG_FILE);
-    } catch {
-        const helpUrl = `${SITE_URL}/tools/config`;
-        spinner.fail(chalk.yellow('Config file missing (clawhub.json).'));
-        console.log(chalk.gray(`  Generate one: ${helpUrl}`));
-        return record('config_file', 'fail', 'clawhub.json not found', helpUrl);
-    }
+async function checkDocker(spinner) {
+  if (!commandExists('docker')) {
+    const helpUrl = `${SITE_URL}/docs/troubleshooting/spawn-docker-enoent`;
+    spinner.warn(chalk.yellow('Docker not found. Sandbox mode may fail.'));
+    logLine(chalk.gray(`  Guide: ${helpUrl}`));
+    return { status: 'warn', message: 'Docker missing (sandbox mode risk)', helpUrl };
+  }
+  const version = getCommandVersion('docker') || 'docker found';
+  spinner.succeed(chalk.green(`Docker: ${version}`));
+  return { status: 'pass', message: version };
+}
 
-    // Validate JSON syntax
-    try {
-        const raw = fs.readFileSync(CONFIG_FILE, 'utf8');
-        JSON.parse(raw);
-        spinner.succeed(chalk.green('Config file found and valid JSON.'));
-        return record('config_file', 'pass', 'clawhub.json valid');
-    } catch (e) {
-        const helpUrl = `${SITE_URL}/docs/troubleshooting/json-parse-errors`;
-        spinner.fail(chalk.red(`Config file has invalid JSON: ${e.message}`));
-        console.log(chalk.gray(`  Fix: ${helpUrl}`));
-        return record('config_file', 'fail', `Invalid JSON: ${e.message}`, helpUrl);
-    }
+async function checkConfigDir(spinner) {
+  if (fs.existsSync(CONFIG_DIR)) {
+    spinner.succeed(chalk.green(`Config directory: ${CONFIG_DIR}`));
+    return { status: 'pass', message: CONFIG_DIR };
+  }
+
+  if (FIX_MODE) {
+    fs.mkdirSync(CONFIG_DIR, { recursive: true });
+    spinner.warn(chalk.yellow(`Config directory created: ${CONFIG_DIR}`));
+    return { status: 'warn', message: `Created missing directory: ${CONFIG_DIR}` };
+  }
+
+  spinner.fail(chalk.red(`Missing config directory: ${CONFIG_DIR}`));
+  return {
+    status: 'fail',
+    message: `Missing directory: ${CONFIG_DIR}`,
+    helpUrl: `${SITE_URL}/tools/config`,
+  };
 }
 
-async function checkPermissions() {
-    const spinner = ora('Checking directory permissions...').start();
-    try {
-        if (!fs.existsSync(CONFIG_DIR)) {
-            spinner.info(chalk.gray('Skipped (directory missing).'));
-            return record('permissions', 'skip', 'Directory missing');
-        }
-        await fs.promises.access(CONFIG_DIR, fs.constants.W_OK);
-        spinner.succeed(chalk.green('Write permission OK for ~/.openclaw'));
-        return record('permissions', 'pass', 'Write permission OK');
-    } catch {
-        spinner.fail(chalk.red('No write permission for ~/.openclaw'));
-        console.log(chalk.gray('  Fix: sudo chown -R $(whoami) ~/.openclaw'));
-        if (FIX_MODE && os.platform() !== 'win32') {
-            console.log(chalk.yellow('  Auto-fix: fixing ownership...'));
-            try { execSync(`chown -R $(whoami) "${CONFIG_DIR}"`, { stdio: 'inherit' }); } catch { /* ignore */ }
-        }
-        return record('permissions', 'fail', 'No write permission');
-    }
+async function checkConfigFile(spinner) {
+  if (!fs.existsSync(CONFIG_FILE)) {
+    spinner.fail(chalk.red('openclaw.json not found.'));
+    return {
+      status: 'fail',
+      message: 'Missing openclaw.json',
+      helpUrl: `${SITE_URL}/tools/config`,
+    };
+  }
+
+  try {
+    JSON.parse(fs.readFileSync(CONFIG_FILE, 'utf8'));
+    spinner.succeed(chalk.green('openclaw.json syntax valid.'));
+    return { status: 'pass', message: 'openclaw.json valid' };
+  } catch (error) {
+    const helpUrl = `${SITE_URL}/docs/troubleshooting/json-parse-errors`;
+    spinner.fail(chalk.red('openclaw.json has invalid JSON syntax.'));
+    logLine(chalk.gray(`  Fix: ${helpUrl}`));
+    return {
+      status: 'fail',
+      message: 'Invalid JSON in openclaw.json',
+      detail: String(error.message || error),
+      helpUrl,
+    };
+  }
 }
 
-async function checkGatewayTokens() {
-    const spinner = ora('Checking gateway token alignment...').start();
-    const config = readConfig();
-    if (!config) {
-        spinner.info(chalk.gray('Skipped (no valid config).'));
-        return record('tokens', 'skip', 'No config to check');
+async function checkPermissions(spinner) {
+  if (!fs.existsSync(CONFIG_DIR)) {
+    spinner.info(chalk.gray('Skipped: config directory missing.'));
+    return { status: 'skip', message: 'Config directory missing' };
+  }
+
+  try {
+    await fs.promises.access(CONFIG_DIR, fs.constants.W_OK);
+    spinner.succeed(chalk.green('Write permission OK for ~/.openclaw')); 
+    return { status: 'pass', message: 'Write permission OK' };
+  } catch {
+    const fixCmd = `chown -R $(whoami) "${CONFIG_DIR}"`;
+    if (FIX_MODE && os.platform() !== 'win32') {
+      try {
+        execSync(fixCmd, { stdio: 'ignore' });
+        spinner.warn(chalk.yellow('Permission repaired with chown.'));
+        return { status: 'warn', message: 'Permission repaired by --fix', detail: fixCmd };
+      } catch {
+        spinner.fail(chalk.red('No write permission for ~/.openclaw')); 
+      }
+    } else {
+      spinner.fail(chalk.red('No write permission for ~/.openclaw')); 
     }
 
-    const authToken = getNestedValue(config, 'gateway.auth.token');
-    const remoteToken = getNestedValue(config, 'gateway.remote.token');
-    const envToken = process.env.OPENCLAW_GATEWAY_TOKEN;
-
-    if (!authToken && !remoteToken) {
-        spinner.info(chalk.gray('No gateway tokens configured (will auto-generate).'));
-        return record('tokens', 'info', 'No tokens configured');
-    }
+    return {
+      status: 'fail',
+      message: 'No write permission for ~/.openclaw',
+      detail: `Run: sudo ${fixCmd}`,
+    };
+  }
+}
 
-    // Check env override
-    if (envToken && authToken && envToken !== authToken) {
-        const helpUrl = `${SITE_URL}/docs/troubleshooting/gateway-token-mismatch`;
-        spinner.fail(chalk.red('OPENCLAW_GATEWAY_TOKEN env var overrides config! Tokens will mismatch.'));
-        console.log(chalk.gray(`  Env: ${envToken.substring(0, 8)}...  Config: ${authToken.substring(0, 8)}...`));
-        console.log(chalk.gray(`  Fix: ${helpUrl}`));
-        return record('tokens', 'fail', 'Env var overrides gateway.auth.token', helpUrl);
+async function checkGatewayTokens(spinner) {
+  const config = readConfig();
+  if (!config) {
+    spinner.info(chalk.gray('Skipped: no readable openclaw.json'));
+    return { status: 'skip', message: 'No valid config' };
+  }
+
+  const authToken = getNestedValue(config, 'gateway.auth.token');
+  const remoteToken = getNestedValue(config, 'gateway.remote.token');
+  const envToken = process.env.OPENCLAW_GATEWAY_TOKEN;
+
+  if (!authToken && !remoteToken && !envToken) {
+    spinner.info(chalk.gray('No gateway tokens configured.'));
+    return { status: 'info', message: 'No tokens configured' };
+  }
+
+  if (envToken && authToken && envToken !== authToken) {
+    const helpUrl = `${SITE_URL}/docs/troubleshooting/gateway-token-mismatch`;
+    spinner.fail(chalk.red('OPENCLAW_GATEWAY_TOKEN conflicts with config token.'));
+    return {
+      status: 'fail',
+      message: 'Env token overrides gateway.auth.token',
+      detail: `env=${envToken.slice(0, 8)}... config=${authToken.slice(0, 8)}...`,
+      helpUrl,
+    };
+  }
+
+  if (authToken && remoteToken && authToken !== remoteToken) {
+    const helpUrl = `${SITE_URL}/docs/troubleshooting/gateway-token-mismatch`;
+    if (FIX_MODE) {
+      setNestedValue(config, 'gateway.remote.token', authToken);
+      fs.writeFileSync(CONFIG_FILE, JSON.stringify(config, null, 2), 'utf8');
+      spinner.warn(chalk.yellow('Token mismatch fixed (remote token aligned).'));
+      return { status: 'warn', message: 'Aligned gateway.remote.token with gateway.auth.token', helpUrl };
     }
 
-    if (authToken && remoteToken && authToken !== remoteToken) {
-        const helpUrl = `${SITE_URL}/docs/troubleshooting/gateway-token-mismatch`;
-        spinner.fail(chalk.red('gateway.auth.token ≠ gateway.remote.token — clients cannot connect.'));
-        console.log(chalk.gray(`  Auth:   ${authToken.substring(0, 8)}...`));
-        console.log(chalk.gray(`  Remote: ${remoteToken.substring(0, 8)}...`));
-        console.log(chalk.gray(`  Fix: ${helpUrl}`));
-        if (FIX_MODE) {
-            console.log(chalk.yellow('  Auto-fix: aligning remote token to match auth token...'));
-            config.gateway.remote.token = authToken;
-            fs.writeFileSync(CONFIG_FILE, JSON.stringify(config, null, 2), 'utf8');
-            console.log(chalk.green('  Fixed. Restart gateway: openclaw gateway restart'));
-        }
-        return record('tokens', 'fail', 'auth.token ≠ remote.token', helpUrl);
-    }
+    spinner.fail(chalk.red('gateway.auth.token and gateway.remote.token mismatch.'));
+    return {
+      status: 'fail',
+      message: 'auth.token != remote.token',
+      detail: `auth=${authToken.slice(0, 8)}... remote=${remoteToken.slice(0, 8)}...`,
+      helpUrl,
+    };
+  }
+
+  spinner.succeed(chalk.green('Gateway tokens aligned.'));
+  return { status: 'pass', message: 'Tokens aligned' };
+}
 
-    spinner.succeed(chalk.green('Gateway tokens aligned.'));
-    return record('tokens', 'pass', 'Tokens aligned');
+async function checkStaleLocks(spinner) {
+  if (!fs.existsSync(SESSIONS_DIR)) {
+    spinner.info(chalk.gray('No sessions directory.'));
+    return { status: 'skip', message: 'No sessions directory' };
+  }
+
+  const lockFiles = fs.readdirSync(SESSIONS_DIR).filter((name) => name.endsWith('.lock'));
+  if (!lockFiles.length) {
+    spinner.succeed(chalk.green('No stale lock files.'));
+    return { status: 'pass', message: 'No lock files' };
+  }
+
+  if (FIX_MODE) {
+    lockFiles.forEach((file) => fs.unlinkSync(path.join(SESSIONS_DIR, file)));
+    spinner.warn(chalk.yellow(`Removed ${lockFiles.length} lock file(s).`));
+    return { status: 'warn', message: `Removed ${lockFiles.length} stale lock(s)` };
+  }
+
+  const helpUrl = `${SITE_URL}/docs/troubleshooting/gateway-lock-timeout`;
+  spinner.warn(chalk.yellow(`Found ${lockFiles.length} stale lock(s).`));
+  return {
+    status: 'warn',
+    message: `${lockFiles.length} stale lock file(s) found`,
+    detail: lockFiles.join(', '),
+    helpUrl,
+  };
 }
 
-async function checkStaleLocks() {
-    const spinner = ora('Checking for stale lock files...').start();
-    if (!fs.existsSync(SESSIONS_DIR)) {
-        spinner.info(chalk.gray('No sessions directory.'));
-        return record('locks', 'skip', 'No sessions directory');
+async function checkPortUsage(id, title, port, expectedInUse) {
+  return runCheck(id, title, async (spinner) => {
+    const inUse = await checkPort(port);
+    if (expectedInUse && inUse) {
+      spinner.succeed(chalk.green(`Port ${port} is in use.`));
+      return { status: 'pass', message: `Port ${port} in use` };
     }
-
-    try {
-        const files = fs.readdirSync(SESSIONS_DIR).filter(f => f.endsWith('.lock'));
-        if (files.length === 0) {
-            spinner.succeed(chalk.green('No stale lock files.'));
-            return record('locks', 'pass', 'No lock files');
-        }
-
-        const helpUrl = `${SITE_URL}/docs/troubleshooting/gateway-lock-timeout`;
-        spinner.warn(chalk.yellow(`Found ${files.length} lock file(s): ${files.join(', ')}`));
-        console.log(chalk.gray(`  This may cause "gateway already running" errors.`));
-        console.log(chalk.gray(`  Fix: ${helpUrl}`));
-
-        if (FIX_MODE) {
-            console.log(chalk.yellow('  Auto-fix: removing stale locks...'));
-            for (const f of files) {
-                fs.unlinkSync(path.join(SESSIONS_DIR, f));
-            }
-            console.log(chalk.green(`  Removed ${files.length} lock file(s).`));
-        }
-        return record('locks', 'warn', `${files.length} lock file(s) found`, helpUrl);
-    } catch (e) {
-        spinner.info(chalk.gray(`Could not check locks: ${e.message}`));
-        return record('locks', 'skip', e.message);
+    if (expectedInUse && !inUse) {
+      spinner.info(chalk.gray(`Port ${port} is free.`));
+      return { status: 'info', message: `Port ${port} free` };
     }
-}
-
-async function checkGatewayPort() {
-    const spinner = ora('Checking Gateway port (18789)...').start();
-    const inUse = await checkPort(18789);
-    if (inUse) {
-        spinner.succeed(chalk.green('Gateway port 18789 is in use (gateway likely running).'));
-        return record('gateway_port', 'pass', 'Port 18789 in use (gateway running)');
-    } else {
-        spinner.info(chalk.gray('Gateway port 18789 is free (gateway not running).'));
-        return record('gateway_port', 'info', 'Port 18789 free (gateway not running)');
+    if (!expectedInUse && inUse) {
+      spinner.info(chalk.gray(`Port ${port} is in use.`));
+      return { status: 'info', message: `Port ${port} in use` };
     }
+    spinner.succeed(chalk.green(`Port ${port} is free.`));
+    return { status: 'pass', message: `Port ${port} free` };
+  });
 }
 
-async function checkAgentPort() {
-    const spinner = ora('Checking Agent port (3000)...').start();
-    const inUse = await checkPort(3000);
-    if (inUse) {
-        spinner.succeed(chalk.green('Agent port 3000 is in use (agent likely running).'));
-        return record('agent_port', 'pass', 'Port 3000 in use');
-    } else {
-        spinner.info(chalk.gray('Agent port 3000 is free (agent not running).'));
-        return record('agent_port', 'info', 'Port 3000 free');
-    }
+function generateReportUrl() {
+  const payload = {
+    t: report.ts,
+    v: report.version,
+    o: report.os,
+    n: report.node,
+    f: report.fix,
+    c: report.checks.map((c) => [c.id, c.status[0], c.message.slice(0, 100)]),
+  };
+  return `${SITE_URL}/tools/doctor?r=${Buffer.from(JSON.stringify(payload)).toString('base64url')}`;
 }
 
-async function checkCDPPort() {
-    const spinner = ora('Checking Browser CDP port (18800)...').start();
-    const inUse = await checkPort(18800);
-    if (inUse) {
-        spinner.info(chalk.gray('CDP port 18800 in use (browser control active or stray process).'));
-        return record('cdp_port', 'info', 'Port 18800 in use');
-    } else {
-        spinner.succeed(chalk.green('CDP port 18800 is free.'));
-        return record('cdp_port', 'pass', 'Port 18800 free');
-    }
+function diagnosePastedError(text) {
+  const normalized = text.toLowerCase();
+  const rules = [
+    {
+      id: 'gateway-args',
+      pattern: /too many arguments.*gateway/,
+      title: "Too many arguments for 'gateway'",
+      docUrl: `${SITE_URL}/docs/troubleshooting/gateway-lock-timeout`,
+      steps: ['Run: openclaw gateway --help', 'Update command flags to current syntax', 'Retry after removing deprecated args'],
+    },
+    {
+      id: 'allowed-origins',
+      pattern: /non-loopback.*allowedorigins|allowedorigins/i,
+      title: 'Control UI requires allowedOrigins',
+      docUrl: `${SITE_URL}/docs/troubleshooting/device-token-mismatch`,
+      steps: ['Set explicit allowedOrigins in openclaw.json', 'Restart gateway service', 'Validate via localhost first'],
+    },
+    {
+      id: 'docker-access',
+      pattern: /docker pull access denied.*openclaw\/openclaw|pull access denied/i,
+      title: 'Docker image pull access denied',
+      docUrl: `${SITE_URL}/docs/troubleshooting/docker-macos-errors`,
+      steps: ['Check image name/tag', 'Run: docker login', 'Use mirrored/public image per docs'],
+    },
+    {
+      id: 'err-empty-response',
+      pattern: /err_empty_response/i,
+      title: 'ERR_EMPTY_RESPONSE',
+      docUrl: `${SITE_URL}/docs/troubleshooting/connection-errors`,
+      steps: ['Check gateway/agent process status', 'Verify port 18789/3000 are reachable', 'Rotate token if mismatch suspected'],
+    },
+    {
+      id: 'systemctl-user',
+      pattern: /systemctl\s+--user.*unavailable|eacces/i,
+      title: 'systemctl --user unavailable',
+      docUrl: `${SITE_URL}/docs/troubleshooting/windows-gateway-errors`,
+      steps: ['Use foreground run mode or service manager for your OS', 'Avoid systemctl --user on unsupported environments', 'Apply OS-specific startup instructions'],
+    },
+    {
+      id: 'provider-400',
+      pattern: /400 provider returned error|provider returned error/i,
+      title: 'Provider returned 400',
+      docUrl: `${SITE_URL}/docs/troubleshooting/api-key-problems`,
+      steps: ['Verify API key and model name', 'Check provider request payload schema', 'Reduce unsupported params and retry'],
+    },
+    {
+      id: 'telegram-409',
+      pattern: /telegram.*409|getupdates conflict/i,
+      title: 'Telegram getUpdates conflict 409',
+      docUrl: `${SITE_URL}/docs/troubleshooting/message-ordering-conflict`,
+      steps: ['Keep only one active polling consumer', 'Stop duplicate bot sessions', 'Restart bot once with a single token'],
+    },
+    {
+      id: 'run-timeout',
+      pattern: /embedded run timeout|run timeout/i,
+      title: 'Embedded run timeout',
+      docUrl: `${SITE_URL}/docs/troubleshooting/ollama-timeout-errors`,
+      steps: ['Increase timeout in config', 'Reduce tool chain depth', 'Validate provider latency and retry'],
+    },
+    {
+      id: 'token-mismatch',
+      pattern: /token mismatch|unauthorized.*device|pairing required/i,
+      title: 'Gateway token mismatch',
+      docUrl: `${SITE_URL}/docs/troubleshooting/gateway-token-mismatch`,
+      steps: ['Align gateway.auth.token and gateway.remote.token', 'Unset conflicting OPENCLAW_GATEWAY_TOKEN', 'Restart gateway and agent'],
+    },
+  ];
+
+  const matched = rules.find((rule) => rule.pattern.test(normalized));
+  if (!matched) return null;
+  return matched;
 }
 
-// ============================================================
-// Report Generator
-// ============================================================
-
-function generateReportUrl() {
-    const compressed = JSON.stringify({
-        t: report.ts,
-        o: report.os,
-        n: report.node,
-        f: report.fix,
-        c: report.checks.map(c => [c.id, c.status[0], c.message.substring(0, 80)]),
+function ask(question) {
+  const rl = readline.createInterface({
+    input: process.stdin,
+    output: process.stdout,
+  });
+  return new Promise((resolve) => {
+    rl.question(`${question}\n> `, (answer) => {
+      rl.close();
+      resolve((answer || '').trim());
     });
-    const encoded = Buffer.from(compressed).toString('base64url');
-    return `${SITE_URL}/tools/doctor?r=${encoded}`;
+  });
 }
 
-// ============================================================
-// Main
-// ============================================================
-
-const steps = [
-    checkNodeVersion,
-    checkGit,
-    checkDocker,
-    checkConfigDir,
-    checkConfigFile,
-    checkPermissions,
-    checkGatewayTokens,
-    checkStaleLocks,
-    checkGatewayPort,
-    checkAgentPort,
-    checkCDPPort,
-];
-
-async function run() {
-    console.clear();
-    console.log(chalk.cyan.bold('\n🦞 ClawKit Doctor v2.0\n'));
-
-    if (FIX_MODE) {
-        console.log(chalk.yellow.bold('⚡ Fix mode enabled — will auto-repair issues where possible.\n'));
-    }
-
-    for (const step of steps) {
-        await step();
-    }
-
-    // Summary
-    const fails = report.checks.filter(c => c.status === 'fail');
-    const warns = report.checks.filter(c => c.status === 'warn');
-    const passes = report.checks.filter(c => c.status === 'pass');
+async function askBinary(question, fallback = 'n') {
+  if (!INTERACTIVE_MODE) return fallback;
+  const answer = (await ask(question)).toLowerCase();
+  if (answer === 'y' || answer === 'yes' || answer === '1') return 'y';
+  if (answer === 'n' || answer === 'no' || answer === '0') return 'n';
+  return fallback;
+}
 
-    console.log('');
-    console.log(chalk.bold('─'.repeat(50)));
+function getFallbackSteps(reason, match) {
+  if (reason === '1') {
+    return [
+      'Re-run the command with verbose output and copy the first 20 error lines.',
+      'Verify CLI syntax with: openclaw gateway --help',
+      `Open issue-specific details: ${match.docUrl}`,
+    ];
+  }
+  if (reason === '2') {
+    return [
+      `Fix ownership: sudo chown -R $(whoami) "${CONFIG_DIR}"`,
+      'Retry with: npx clawkit-doctor@latest --fix',
+      `If still blocked, open: ${SITE_URL}/docs/troubleshooting/windows-gateway-errors`,
+    ];
+  }
+  if (reason === '3') {
+    return [
+      'Check service status and ports: 18789 / 3000',
+      'Retry with stable network or increased timeout settings',
+      `Timeout-focused guide: ${SITE_URL}/docs/troubleshooting/ollama-timeout-errors`,
+    ];
+  }
+  return [
+    'Run full diagnostics: npx clawkit-doctor@latest --full',
+    `Open troubleshooting index: ${SITE_URL}/docs/troubleshooting`,
+    `Then open matched details: ${match.docUrl}`,
+  ];
+}
 
-    if (fails.length === 0 && warns.length === 0) {
-        console.log(chalk.green.bold('\n✅ All checks passed! Your environment looks healthy.\n'));
+async function run() {
+  if (!QUIET_MODE) {
+    console.log(chalk.cyan.bold('\nClawKit Doctor'));
+    console.log(chalk.gray(`v${pkg.version}  •  @branzoom (GitHub)`));
+    console.log(chalk.gray(`${t.subtitle}\n`));
+  }
+
+  let shouldContinueToFull = FULL_MODE;
+  if (PASTE_TEXT) {
+    const match = diagnosePastedError(PASTE_TEXT);
+    report.pastedError = { input: PASTE_TEXT.slice(0, 600), matchId: match?.id || null };
+
+    if (JSON_MODE) {
+      report.pasteDiagnosis = match
+        ? { issueId: match.id, title: match.title, steps: match.steps, docUrl: match.docUrl }
+        : { issueId: null, title: null, steps: [], docUrl: `${SITE_URL}/tools/doctor` };
+      if (!FULL_MODE) {
+        process.stdout.write(`${JSON.stringify(report, null, 2)}\n`);
+        return;
+      }
     } else {
-        console.log(chalk.yellow.bold(`\n📋 Summary: ${passes.length} passed, ${warns.length} warnings, ${fails.length} failed\n`));
-
-        if (fails.length > 0) {
-            console.log(chalk.red.bold('  Issues to fix:'));
-            for (const f of fails) {
-                console.log(chalk.red(`    ✗ ${f.message}`));
+      console.log(chalk.bold(`\n${t.pasteTitle}`));
+      if (match) {
+        console.log(chalk.green(`  ${t.pasteMatched}: ${match.title}`));
+        match.steps.forEach((step, index) => {
+          console.log(chalk.gray(`  ${index + 1}. ${step}`));
+        });
+        console.log(chalk.gray(`  ${t.pasteDetails}: ${match.docUrl}`));
+
+        if (INTERACTIVE_MODE) {
+          const firstResolved = await askBinary(t.resolvedAsk, 'n');
+          if (firstResolved === 'y') {
+            report.resolution = { solved: 1, round: 1, reason: null };
+            console.log(chalk.green(`  ${t.resolvedDone}`));
+            console.log(chalk.gray(`  ${t.resolvedDoneDetail}`));
+            console.log(chalk.gray(`  ${t.prevent}: ${SITE_URL}/docs/guides/stable-ops`));
+            console.log(chalk.cyan(`  ${t.explore}: ${SITE_URL}/skills`));
+          } else {
+            const reason = await ask(t.unresolvedReason);
+            const normalizedReason = ['1', '2', '3', '4'].includes(reason) ? reason : '4';
+            const fallbackSteps = getFallbackSteps(normalizedReason, match);
+            console.log(chalk.yellow(`  ${t.retrySteps}:`));
+            fallbackSteps.forEach((step, index) => {
+              console.log(chalk.gray(`  ${index + 1}. ${step}`));
+            });
+
+            const secondResolved = await askBinary(t.resolvedAskAgain, 'n');
+            if (secondResolved === 'y') {
+              report.resolution = { solved: 1, round: 2, reason: normalizedReason };
+              console.log(chalk.green(`  ${t.resolvedDone}`));
+              console.log(chalk.gray(`  ${t.resolvedDoneDetail}`));
+              console.log(chalk.gray(`  ${t.prevent}: ${SITE_URL}/docs/guides/stable-ops`));
+              console.log(chalk.cyan(`  ${t.explore}: ${SITE_URL}/skills`));
+            } else {
+              report.resolution = { solved: 0, round: 2, reason: normalizedReason };
+              console.log(chalk.red(`  ${t.escalate}:`));
+              console.log(chalk.gray(`  ${t.pasteDetails}: ${match.docUrl}`));
+              console.log(chalk.gray(`  ${t.docs}: ${SITE_URL}/docs/troubleshooting`));
+              console.log(chalk.gray(`  ${t.support}: ${SITE_URL}/contact`));
+              shouldContinueToFull = shouldContinueToFull || (await askBinary(t.askFull, 'n')) === 'y';
             }
+          }
+        } else {
+          console.log(chalk.gray(`  ${t.nonInteractive}`));
         }
-        if (warns.length > 0) {
-            console.log(chalk.yellow.bold('  Warnings:'));
-            for (const w of warns) {
-                console.log(chalk.yellow(`    ⚠ ${w.message}`));
-            }
+      } else {
+        console.log(chalk.yellow(`  ${t.pasteNoMatch}`));
+        console.log(chalk.gray(`  ${t.pasteNext}: ${SITE_URL}/tools/doctor`));
+        console.log(chalk.gray(`  ${t.docs}: ${SITE_URL}/docs/troubleshooting`));
+        if (INTERACTIVE_MODE) {
+          shouldContinueToFull = shouldContinueToFull || (await askBinary(t.askFull, 'y')) === 'y';
         }
+      }
 
-        if (!FIX_MODE && fails.length > 0) {
-            console.log(chalk.cyan(`\n  💡 Run with --fix to auto-repair: npx clawkit-doctor@latest --fix\n`));
-        }
+      if (!shouldContinueToFull) return;
+      console.log('');
     }
+  }
+
+  await runCheck('node', 'Checking Node.js version...', checkNodeVersion);
+  await runCheck('git', 'Checking Git...', checkGit);
+  await runCheck('docker', 'Checking Docker...', checkDocker);
+  await runCheck('config_dir', 'Checking OpenClaw config directory...', checkConfigDir);
+  await runCheck('config_file', 'Checking openclaw.json...', checkConfigFile);
+  await runCheck('permissions', 'Checking directory permissions...', checkPermissions);
+  await runCheck('tokens', 'Checking gateway token alignment...', checkGatewayTokens);
+  await runCheck('locks', 'Checking stale lock files...', checkStaleLocks);
+  await checkPortUsage('gateway_port', 'Checking gateway port (18789)...', 18789, true);
+  await checkPortUsage('agent_port', 'Checking agent port (3000)...', 3000, true);
+  await checkPortUsage('cdp_port', 'Checking browser CDP port (18800)...', 18800, false);
+
+  const totals = {
+    pass: report.checks.filter((x) => x.status === 'pass').length,
+    warn: report.checks.filter((x) => x.status === 'warn').length,
+    fail: report.checks.filter((x) => x.status === 'fail').length,
+    info: report.checks.filter((x) => x.status === 'info').length,
+    skip: report.checks.filter((x) => x.status === 'skip').length,
+  };
+  report.totals = totals;
+
+  if (JSON_MODE) {
+    if (!NO_REPORT) report.reportUrl = generateReportUrl();
+    process.stdout.write(`${JSON.stringify(report, null, 2)}\n`);
+    return;
+  }
+
+  console.log(chalk.bold('\n' + '-'.repeat(56)));
+  console.log(chalk.bold(t.summary));
+  console.log(`  Passed: ${chalk.green(totals.pass)}  Warnings: ${chalk.yellow(totals.warn)}  Failed: ${chalk.red(totals.fail)}  Info/Skip: ${totals.info + totals.skip}`);
+
+  if (totals.fail > 0 && !FIX_MODE) {
+    console.log(chalk.cyan(`\n${t.tipFix}`));
+    console.log(chalk.gray('  npx clawkit-doctor@latest --fix'));
+  }
+
+  const blocking = report.checks.filter((c) => c.status === 'fail');
+  if (blocking.length) {
+    console.log(chalk.red.bold(`\n${t.blocking}`));
+    blocking.forEach((item) => {
+      console.log(chalk.red(`  - [${item.id}] ${item.message}`));
+      if (item.helpUrl) console.log(chalk.gray(`    ${item.helpUrl}`));
+    });
+  }
+
+  if (!NO_REPORT) {
+    console.log(chalk.bold(`\n${t.share}`));
+    console.log(`  ${generateReportUrl()}`);
+  }
 
-    // Report URL
-    const reportUrl = generateReportUrl();
-    console.log(chalk.gray('─'.repeat(50)));
-    console.log(chalk.cyan.bold('\n📋 Share this report:'));
-    console.log(chalk.white(`   ${reportUrl}\n`));
-    console.log(chalk.gray(`For full troubleshooting guides: ${SITE_URL}/docs/troubleshooting\n`));
+  console.log(chalk.gray(`\n${t.docs}: ${SITE_URL}/docs/troubleshooting`));
+  console.log(chalk.gray(`${t.prevent}: ${SITE_URL}/docs/guides/stable-ops\n`));
 }
 
-run().catch(err => {
-    console.error(chalk.red('\n❌ Unexpected Error:'), err.message);
-    process.exit(1);
+run().catch((error) => {
+  console.error(chalk.red('\nUnexpected Error:'), error.message || error);
+  process.exit(1);
 });

package/package.json

@@ -1,24 +1,37 @@
 {
-    "name": "clawkit-doctor",
-    "version": "2.0.1",
-    "description": "Diagnostic and auto-fix tool for OpenClaw environment",
-    "main": "bin/index.js",
-    "bin": {
-        "clawkit-doctor": "bin/index.js"
-    },
-    "scripts": {
-        "test": "echo \"Error: no test specified\" && exit 1"
-    },
-    "keywords": [
-        "openclaw",
-        "diagnostic",
-        "doctor",
-        "cli"
-    ],
-    "author": "OpenClaw Team",
-    "license": "MIT",
-    "dependencies": {
-        "chalk": "^4.1.2",
-        "ora": "^5.4.1"
-    }
-}
+  "name": "clawkit-doctor",
+  "version": "2.2.0",
+  "description": "Guided OpenClaw diagnostic CLI with issue-first recovery flow",
+  "main": "bin/index.js",
+  "bin": {
+    "clawkit-doctor": "bin/index.js"
+  },
+  "scripts": {
+    "test": "node bin/index.js --json --no-report"
+  },
+  "keywords": [
+    "openclaw",
+    "diagnostic",
+    "doctor",
+    "cli",
+    "troubleshooting"
+  ],
+  "author": "branzoom",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/branzoom/getclawkit-web.git",
+    "directory": "packages/clawkit-doctor"
+  },
+  "homepage": "https://getclawkit.com/tools/doctor",
+  "bugs": {
+    "url": "https://github.com/branzoom/getclawkit-web/issues"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "dependencies": {
+    "chalk": "^4.1.2",
+    "ora": "^5.4.1"
+  }
+}