feat(doctor): add --help flag with comprehensive command documentation

- Add showHelp() with usage, options, checks, examples, exit codes
- Update handleDoctorCommand to accept args array instead of boolean
- Update ccs.ts to pass restArgs to doctor command
- Add doctor to CLAUDE.md Help Location Reference table

CLAUDE.md

@@ -109,10 +109,14 @@ bun run validate            # Step 3: Final check (must pass)
 | Command | Help Handler Location |
 |---------|----------------------|
 | `ccs --help` | `src/commands/help-command.ts` |
+| `ccs api --help` | `src/commands/api-command.ts` → `showHelp()` |
+| `ccs cleanup --help` | `src/commands/cleanup-command.ts` → `printHelp()` |
 | `ccs cliproxy --help` | `src/commands/cliproxy-command.ts` → `showHelp()` |
-| `ccs auth --help` | `src/commands/auth-command.ts` |
-| `ccs api --help` | `src/commands/api-command.ts` |
-| `ccs copilot --help` | `src/commands/copilot-command.ts` |
+| `ccs config --help` | `src/commands/config-command.ts` → `showHelp()` |
+| `ccs copilot --help` | `src/commands/copilot-command.ts` → `handleHelp()` |
+| `ccs doctor --help` | `src/commands/doctor-command.ts` → `showHelp()` |
+| `ccs migrate --help` | `src/commands/migrate-command.ts` → `printMigrateHelp()` |
+| `ccs setup --help` | `src/commands/setup-command.ts` → `showHelp()` |
 
 **Note:** `lib/ccs` and `lib/ccs.ps1` are bootstrap wrappers only—they delegate to Node.js and contain no help text.
 

src/ccs.ts

@@ -340,8 +340,8 @@ async function main(): Promise<void> {
 
   // Special case: doctor command
   if (firstArg === 'doctor' || firstArg === '--doctor') {
-    const shouldFix = args.includes('--fix') || args.includes('-f');
-    await handleDoctorCommand(shouldFix);
+    const restArgs = args.slice(args.indexOf(firstArg) + 1);
+    await handleDoctorCommand(restArgs);
     return;
   }
 

src/commands/doctor-command.ts

@@ -4,22 +4,80 @@
  * Handle doctor command for CCS.
  */
 
+import { initUI, header, dim, color, subheader } from '../utils/ui';
+
+/**
+ * Show help for doctor command
+ */
+function showHelp(): void {
+  console.log('');
+  console.log(header('ccs doctor'));
+  console.log('');
+  console.log('  Run health diagnostics on CCS installation.');
+  console.log('');
+
+  console.log(subheader('Usage:'));
+  console.log(`  ${color('ccs doctor', 'command')} [options]`);
+  console.log('');
+
+  console.log(subheader('Options:'));
+  console.log(`  ${color('--fix, -f', 'command')}     Attempt to auto-fix detected issues`);
+  console.log(`  ${color('--help, -h', 'command')}    Show this help message`);
+  console.log('');
+
+  console.log(subheader('Checks performed:'));
+  console.log(`  ${dim('-')} Config files (config.yaml, config.json)`);
+  console.log(`  ${dim('-')} CLIProxy installation and process status`);
+  console.log(`  ${dim('-')} OAuth port availability (8085, 1455, 51121)`);
+  console.log(`  ${dim('-')} Symlink integrity (shared settings)`);
+  console.log(`  ${dim('-')} Profile configuration validity`);
+  console.log('');
+
+  console.log(subheader('Auto-fix capabilities:'));
+  console.log(`  ${dim('-')} Kill zombie CLIProxy processes`);
+  console.log(`  ${dim('-')} Free blocked OAuth callback ports`);
+  console.log(`  ${dim('-')} Regenerate outdated CLIProxy config`);
+  console.log(`  ${dim('-')} Restore broken shared settings symlinks`);
+  console.log('');
+
+  console.log(subheader('Examples:'));
+  console.log(
+    `  $ ${color('ccs doctor', 'command')}          ${dim('# Run diagnostics (read-only)')}`
+  );
+  console.log(
+    `  $ ${color('ccs doctor --fix', 'command')}    ${dim('# Run diagnostics and fix issues')}`
+  );
+  console.log('');
+
+  console.log(subheader('Exit codes:'));
+  console.log(`  ${color('0', 'command')}  All checks passed`);
+  console.log(`  ${color('1', 'command')}  One or more checks failed`);
+  console.log('');
+}
+
 /**
  * Handle doctor command
- * @param shouldFix - If true, attempt to fix detected issues
+ * @param args - Command line arguments
  */
-export async function handleDoctorCommand(shouldFix = false): Promise<void> {
+export async function handleDoctorCommand(args: string[]): Promise<void> {
+  await initUI();
+
+  if (args.includes('--help') || args.includes('-h')) {
+    showHelp();
+    return;
+  }
+
+  const shouldFix = args.includes('--fix') || args.includes('-f');
+
   const DoctorModule = await import('../management/doctor');
   const Doctor = DoctorModule.default;
   const doctor = new Doctor();
 
   await doctor.runAllChecks();
 
-  // Attempt to fix issues if --fix flag provided
   if (shouldFix) {
     await doctor.fixIssues();
   }
 
-  // Exit with error code if unhealthy
   process.exit(doctor.isHealthy() ? 0 : 1);
 }