docs(cli): Add status and doctor command documentation

Also improves dex doctor to:
- Use gh CLI auth check (not just GITHUB_TOKEN env var)
- Detect missing [sync.github.auto] config in both global and project configs
- Offer to add default auto-sync settings with --fix

Adds comprehensive test coverage for doctor command.

Co-Authored-By: Claude <noreply@anthropic.com>

Author: dcramer

docs/src/pages/cli.astro

@@ -9,6 +9,31 @@ import { Code } from 'astro:components';
 
   <h2>Core Commands</h2>
 
+  <div class="command-card">
+    <h3>dex status</h3>
+    <div class="synopsis">dex status [options]</div>
+    <p>Show a dashboard overview of your tasks. <strong>This is the default command</strong> — running <code>dex</code> with no arguments runs <code>dex status</code>.</p>
+    <ul>
+      <li><code>--json</code> — Output as JSON for scripting</li>
+    </ul>
+    <p>The dashboard shows:</p>
+    <ul>
+      <li><strong>Stats</strong> — Total, pending, completed, blocked, and ready counts</li>
+      <li><strong>Ready to Work</strong> — Pending tasks with no blockers (up to 5)</li>
+      <li><strong>Blocked</strong> — Tasks waiting on dependencies</li>
+      <li><strong>Recently Completed</strong> — Latest completed tasks (up to 5)</li>
+    </ul>
+    <Terminal title="Terminal">
+      <Code
+        code={`dex                    # Show dashboard (default)
+dex status             # Same as above
+dex status --json      # Output as JSON`}
+        lang="bash"
+        theme="vitesse-black"
+      />
+    </Terminal>
+  </div>
+
   <div class="command-card">
     <h3>dex create</h3>
     <div class="synopsis">dex create -d &lt;description&gt; --context &lt;context&gt; [options]</div>
@@ -156,6 +181,30 @@ dex plan feature.md --parent abc123`}
     </Terminal>
   </div>
 
+  <h2>Diagnostics</h2>
+
+  <div class="command-card">
+    <h3>dex doctor</h3>
+    <div class="synopsis">dex doctor [options]</div>
+    <p>Check dex configuration and storage for issues, with optional auto-repair.</p>
+    <ul>
+      <li><code>--fix</code> — Automatically fix detected issues</li>
+    </ul>
+    <p>Checks performed:</p>
+    <ul>
+      <li><strong>Config</strong> — Valid TOML syntax, deprecated settings, missing environment variables</li>
+      <li><strong>Storage</strong> — Task file validity, relationship consistency, orphaned references, depth limits</li>
+    </ul>
+    <Terminal title="Terminal">
+      <Code
+        code={`dex doctor             # Check for issues (read-only)
+dex doctor --fix       # Check and fix issues`}
+        lang="bash"
+        theme="vitesse-black"
+      />
+    </Terminal>
+  </div>
+
   <h2>Other</h2>
 
   <div class="command-card">

src/cli/doctor.test.ts

@@ -0,0 +1,134 @@
+import { describe, it, expect, beforeEach, afterEach, vi } from "vitest";
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { FileStorage } from "../core/storage.js";
+import { runCli } from "./index.js";
+import { captureOutput, createTempStorage, CapturedOutput } from "./test-helpers.js";
+
+describe("doctor command", () => {
+  let storage: FileStorage;
+  let cleanup: () => void;
+  let output: CapturedOutput;
+  let mockExit: ReturnType<typeof vi.spyOn>;
+
+  beforeEach(() => {
+    const temp = createTempStorage();
+    storage = temp.storage;
+    cleanup = temp.cleanup;
+    output = captureOutput();
+    mockExit = vi.spyOn(process, "exit").mockImplementation((() => {
+      throw new Error("process.exit called");
+    }) as () => never);
+  });
+
+  afterEach(() => {
+    output.restore();
+    cleanup();
+    mockExit.mockRestore();
+  });
+
+  it("shows help with --help flag", async () => {
+    await runCli(["doctor", "--help"], { storage });
+
+    const out = output.stdout.join("\n");
+    expect(out).toContain("dex doctor");
+    expect(out).toContain("Check and repair");
+    expect(out).toContain("--fix");
+  });
+
+  it("reports no issues when config and storage are valid", async () => {
+    await runCli(["doctor"], { storage });
+
+    const out = output.stdout.join("\n");
+    expect(out).toContain("Checking config");
+    expect(out).toContain("Config valid");
+    expect(out).toContain("Checking storage");
+    expect(out).toContain("No issues found");
+  });
+
+  it("detects orphaned parent references", async () => {
+    // Create a task and manually corrupt its parent_id
+    const storagePath = storage.getIdentifier();
+    const taskId = "test1234";
+    const taskPath = path.join(storagePath, "tasks", `${taskId}.json`);
+
+    fs.mkdirSync(path.dirname(taskPath), { recursive: true });
+    fs.writeFileSync(taskPath, JSON.stringify({
+      id: taskId,
+      parent_id: "nonexistent",
+      description: "Test task",
+      context: "ctx",
+      priority: 1,
+      completed: false,
+      result: null,
+      blockedBy: [],
+      blocks: [],
+      children: [],
+      created_at: new Date().toISOString(),
+      updated_at: new Date().toISOString(),
+      completed_at: null,
+    }));
+
+    await runCli(["doctor"], { storage });
+
+    const out = output.stdout.join("\n");
+    expect(out).toContain("parent_id 'nonexistent' does not exist");
+    expect(out).toContain("orphaned");
+  });
+
+  it("detects missing auto-sync config when github sync is enabled", async () => {
+    // Create a config file with github sync enabled but no auto section
+    const storagePath = storage.getIdentifier();
+    const configPath = path.join(storagePath, "config.toml");
+
+    fs.writeFileSync(configPath, `[sync.github]
+enabled = true
+`);
+
+    await runCli(["doctor"], { storage });
+
+    const out = output.stdout.join("\n");
+    expect(out).toContain("Missing [sync.github.auto]");
+    expect(out).toContain("project config");
+  });
+
+  it("fixes missing auto-sync config with --fix", async () => {
+    // Create a config file with github sync enabled but no auto section
+    const storagePath = storage.getIdentifier();
+    const configPath = path.join(storagePath, "config.toml");
+
+    fs.writeFileSync(configPath, `[sync.github]
+enabled = true
+`);
+
+    await runCli(["doctor", "--fix"], { storage });
+
+    const out = output.stdout.join("\n");
+    expect(out).toContain("Fixed:");
+    expect(out).toContain("[sync.github.auto]");
+
+    // Verify the config was updated
+    const updatedConfig = fs.readFileSync(configPath, "utf-8");
+    expect(updatedConfig).toContain("on_change");
+  });
+
+  it("does not warn about auto-sync when it's already present", async () => {
+    // Create a config file with github sync and auto section
+    const storagePath = storage.getIdentifier();
+    const configPath = path.join(storagePath, "config.toml");
+
+    fs.writeFileSync(configPath, `[sync.github]
+enabled = true
+
+[sync.github.auto]
+on_change = false
+`);
+
+    await runCli(["doctor"], { storage });
+
+    const out = output.stdout.join("\n");
+    // Should NOT warn about missing auto-sync since it's present
+    expect(out).not.toContain("Missing [sync.github.auto]");
+    // May still warn about GITHUB_TOKEN, which is a separate check
+  });
+});

src/cli/doctor.ts

@@ -1,5 +1,6 @@
 import * as fs from "node:fs";
-import { parse as parseToml } from "smol-toml";
+import * as path from "node:path";
+import { parse as parseToml, stringify as stringifyToml } from "smol-toml";
 import {
   CliOptions,
   colors,
@@ -12,6 +13,14 @@ import {
   getProjectConfigPath,
   loadConfig,
 } from "../core/config.js";
+import { getGitHubToken } from "../core/github-sync.js";
+
+/**
+ * Default auto-sync configuration to add when missing.
+ */
+const DEFAULT_AUTO_SYNC_CONFIG = {
+  on_change: true,
+};
 
 export interface DoctorIssue {
   type: "error" | "warning";
@@ -197,18 +206,90 @@ async function checkConfig(options: CliOptions): Promise<DoctorIssue[]> {
   // Check GitHub sync config if enabled
   if (config.sync?.github?.enabled) {
     const tokenEnv = config.sync.github.token_env || "GITHUB_TOKEN";
-    if (!process.env[tokenEnv]) {
+    const token = getGitHubToken(tokenEnv);
+    if (!token) {
+      issues.push({
+        type: "warning",
+        category: "config",
+        message: `GitHub sync enabled but no token found (checked ${tokenEnv} env var and gh CLI)`,
+      });
+    }
+
+    // Check for missing auto-sync configuration in both global and project configs
+    // We check each file that has sync.github.enabled and warn if it's missing the auto section
+    const configsToCheck: { path: string; label: string }[] = [];
+
+    // Check global config
+    if (fs.existsSync(globalConfigPath)) {
+      const globalParsed = parseConfigFileRaw(globalConfigPath);
+      if (globalParsed?.sync?.github?.enabled && !globalParsed?.sync?.github?.auto) {
+        configsToCheck.push({ path: globalConfigPath, label: "global" });
+      }
+    }
+
+    // Check project config
+    const projectConfigPath = storagePath ? getProjectConfigPath(storagePath) : null;
+    if (projectConfigPath && fs.existsSync(projectConfigPath)) {
+      const projectParsed = parseConfigFileRaw(projectConfigPath);
+      if (projectParsed?.sync?.github?.enabled && !projectParsed?.sync?.github?.auto) {
+        configsToCheck.push({ path: projectConfigPath, label: "project" });
+      }
+    }
+
+    for (const { path: configPath, label } of configsToCheck) {
       issues.push({
         type: "warning",
         category: "config",
-        message: `GitHub sync enabled but ${tokenEnv} environment variable not set`,
+        message: `Missing [sync.github.auto] in ${label} config (${configPath})`,
+        fix: async () => {
+          await addAutoSyncConfig(configPath);
+        },
       });
     }
   }
 
   return issues;
 }
 
+/**
+ * Parse a TOML config file and return raw parsed object.
+ */
+function parseConfigFileRaw(configPath: string): any | null {
+  if (!fs.existsSync(configPath)) {
+    return null;
+  }
+  try {
+    const content = fs.readFileSync(configPath, "utf-8");
+    return parseToml(content);
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Add auto-sync config section to an existing config file.
+ * Preserves existing content and appends the new section.
+ */
+async function addAutoSyncConfig(configPath: string): Promise<void> {
+  const content = fs.readFileSync(configPath, "utf-8");
+  const parsed = parseToml(content) as any;
+
+  // Ensure sync.github exists
+  if (!parsed.sync) {
+    parsed.sync = {};
+  }
+  if (!parsed.sync.github) {
+    parsed.sync.github = { enabled: true };
+  }
+
+  // Add auto section with defaults
+  parsed.sync.github.auto = { ...DEFAULT_AUTO_SYNC_CONFIG };
+
+  // Write back as TOML
+  const newContent = stringifyToml(parsed);
+  fs.writeFileSync(configPath, newContent, "utf-8");
+}
+
 async function checkStorage(
   options: CliOptions,
   service: ReturnType<typeof createService>