feat: add doctor command and overhaul global config workflow

- Add new `doctor` CLI command to inspect active configuration and its source locations
- Rewrite config loader to use global-first priority, with ~/.codeindex/.env as primary runtime config
- Add automatic migration of legacy global config.json to standardized .env format
- Update `setup` command to save both legacy config.json and new .env global files
- Revise all project and CLI documentation to recommend global setup over per-project .env
- Simplify `init` command by removing redundant setup prompts and using global config defaults
- Add comprehensive test coverage for the new config loading and migration logic

Author: pnftrading

README.md

@@ -70,9 +70,8 @@ After:  Paste 3 files (2KB)   → Same answer
 # 1. Install
 pnpm install -g @codeindex/cli
 
-# 2. Configure your project's .env
-cp .env.example .env
-# then edit .env with your API key
+# 2. Setup once globally
+codeindex setup
 
 # 3. Index your project
 cd your-project
@@ -82,14 +81,18 @@ codeindex index .
 codeindex query "How does the auth module work?"
 ```
 
-For NVIDIA, a minimal `.env` is enough:
+Global setup is stored under `~/.codeindex/` and reused for all future projects.
+
+If you prefer env-based global runtime config, `codeindex setup` also writes `~/.codeindex/.env`.
+
+For NVIDIA, a minimal global env looks like:
 
 ```env
 NVIDIA_API_KEY=nvapi-...
 CODEINDEX_BASE_URL=https://integrate.api.nvidia.com/v1
 ```
 
-**That's it.** Project-first config, no need to run global setup for every project.
+**That's it.** Run setup once, then `codeindex index` works across projects.
 
 ***
 

docs/API.md

@@ -168,7 +168,7 @@ Project-level configuration. Recommended: keep this file minimal and put API/pro
 
 ### `.env`
 
-Recommended per-project API configuration.
+Optional per-project override configuration.
 
 ```env
 NVIDIA_API_KEY=nvapi-...
@@ -180,9 +180,20 @@ CODEINDEX_BASE_URL=https://integrate.api.nvidia.com/v1
 
 If `NVIDIA_API_KEY` or the NVIDIA base URL is present, `codeindex` can infer the NVIDIA provider automatically.
 
+### `~/.codeindex/.env`
+
+Recommended global runtime configuration when you want to run `codeindex setup` once and reuse it across all projects.
+
+```env
+CODEINDEX_PROVIDER=nvidia
+CODEINDEX_API_KEY=nvapi-...
+CODEINDEX_MODEL=minimaxai/minimax-m3
+CODEINDEX_BASE_URL=https://integrate.api.nvidia.com/v1
+```
+
 ### `~/.codeindex/config.json`
 
-Optional global configuration (created by `codeindex setup`).
+Backward-compatible global configuration (also created by `codeindex setup`).
 
 ```json
 {

packages/cli/README.md

@@ -10,9 +10,8 @@
 # Install
 npm install -g @codeindex/cli
 
-# Configure your project's .env
-cp .env.example .env
-# then edit .env with your API key
+# Setup once globally
+codeindex setup
 
 # Index your project
 cd your-project
@@ -26,22 +25,24 @@ codeindex query "How does authentication work?"
 
 | Command | Description |
 |---------|-------------|
-| `codeindex setup` | Optional global configuration |
+| `codeindex setup` | Global runtime configuration (recommended) |
 | `codeindex init [path]` | Initialize project |
 | `codeindex index [path]` | Build/rebuild index |
 | `codeindex query "<text>"` | Query the index |
 | `codeindex update [path]` | Incremental update |
 | `codeindex status [path]` | Check index health |
 | `codeindex serve [path]` | HTTP server for IDE integration |
 
-## Recommended Project Config
+## Global Config
 
 ```env
-NVIDIA_API_KEY=nvapi-...
+CODEINDEX_PROVIDER=nvidia
+CODEINDEX_API_KEY=nvapi-...
+CODEINDEX_MODEL=minimaxai/minimax-m3
 CODEINDEX_BASE_URL=https://integrate.api.nvidia.com/v1
 ```
 
-`codeindex` automatically reads `.env` from the project root, so in most cases you do not need `codeindex setup`.
+`codeindex setup` writes global config to `~/.codeindex/config.json` and `~/.codeindex/.env`, so in most cases you only need to configure it once.
 
 ## Features
 

packages/cli/src/cli.ts

@@ -19,6 +19,7 @@ import { registerStatusCommand } from "./commands/status.js"
 import { registerServeCommand } from "./commands/serve.js"
 import { registerInitCommand } from "./commands/init.js"
 import { registerSetupCommand } from "./commands/setup.js"
+import { registerDoctorCommand } from "./commands/doctor.js"
 
 const program = new Command()
 
@@ -37,5 +38,6 @@ registerQueryCommand(program)
 registerUpdateCommand(program)
 registerStatusCommand(program)
 registerServeCommand(program)
+registerDoctorCommand(program)
 
 program.parse()

packages/cli/src/commands/doctor.ts

@@ -0,0 +1,79 @@
+import type { Command } from "commander"
+import * as path from "path"
+import { type CodeIndexConfig, inspectConfig, resolveApiKey } from "../config.js"
+
+function formatValue(key: keyof CodeIndexConfig, value: unknown): string {
+  if (value === undefined || value === null || value === "") {
+    return "(unset)"
+  }
+  if (key === "apiKey" || key === "serverApiKey") {
+    return "(set)"
+  }
+  return String(value)
+}
+
+export function registerDoctorCommand(program: Command): void {
+  program
+    .command("doctor [path]")
+    .description("Hiển thị config hiệu lực và nguồn cấu hình đang được dùng")
+    .option("--provider <provider>", "Override provider khi kiểm tra")
+    .option("--model <model>", "Override model khi kiểm tra")
+    .option("--index-dir <dir>", "Override index dir khi kiểm tra")
+    .option("--json", "Output as JSON")
+    .action((targetPath: string | undefined, options: Record<string, string | boolean>) => {
+      const projectRoot = path.resolve(targetPath ?? ".")
+
+      const overrides: Partial<CodeIndexConfig> = {}
+      if (options["provider"]) overrides.provider = options["provider"] as CodeIndexConfig["provider"]
+      if (options["model"]) overrides.model = options["model"] as string
+      if (options["indexDir"]) overrides.indexDir = options["indexDir"] as string
+
+      const debug = inspectConfig(projectRoot, overrides)
+
+      if (options["json"] === true) {
+        let resolvedApiKey = false
+        try {
+          resolveApiKey(debug.effective)
+          resolvedApiKey = true
+        } catch {}
+
+        console.log(JSON.stringify({ ...debug, resolvedApiKey }, null, 2))
+        return
+      }
+
+      console.log(`🩺 codeindex doctor: ${debug.projectRoot}`)
+      console.log(`   Global dir : ${debug.globalConfigDir}`)
+      console.log("")
+
+      const orderedKeys: Array<keyof CodeIndexConfig> = [
+        "provider",
+        "model",
+        "apiKey",
+        "baseURL",
+        "indexDir",
+        "projectName",
+        "verbose",
+        "serverApiKey",
+        "serverCorsOrigin",
+        "serverMaxBodyBytes",
+        "serverRateLimitPerMinute",
+      ]
+
+      for (const key of orderedKeys) {
+        const source = debug.fields[key]
+        const value = debug.effective[key]
+        console.log(`${key.padEnd(24)} ${formatValue(key, value)}`)
+        if (source) {
+          const sourceText = source.key ? `${source.source} -> ${source.location} (${source.key})` : `${source.source} -> ${source.location}`
+          console.log(`   from                  ${sourceText}`)
+        }
+      }
+
+      try {
+        resolveApiKey(debug.effective)
+        console.log("\n✅ API key resolved successfully")
+      } catch (error) {
+        console.log(`\n❌ API key not resolved: ${(error as Error).message}`)
+      }
+    })
+}

packages/cli/src/commands/init.ts

@@ -30,8 +30,6 @@ export function registerInitCommand(program: Command): void {
       // Load global config để lấy defaults
       const currentConfig = loadConfig(projectRoot)
 
-      let provider = currentConfig.provider
-      let model = currentConfig.model
       let indexDir = currentConfig.indexDir
 
       // Nếu global config đã có đủ thông tin (apiKey + provider), skip hỏi
@@ -45,25 +43,7 @@ export function registerInitCommand(program: Command): void {
 
         console.log("\n🔧 codeindex project init\n")
         console.log(`⚠️  Chưa tìm thấy cấu hình toàn cục. Bạn nên chạy 'codeindex setup' trước.`)
-        console.log(`   Hoặc tạo file .env trong project root, ví dụ: NVIDIA_API_KEY=... \n`)
-
-        const providerInput = await ask(
-          rl,
-          `LLM provider [openai/anthropic/google/nvidia/custom/ollama] (mặc định: ${provider}): `
-        )
-        provider = (providerInput.trim() || provider) as any
-
-        const modelDefaults: Record<string, string> = {
-          openai: "gpt-4o",
-          anthropic: "claude-sonnet-4-5",
-          google: "gemini-1.5-flash",
-          nvidia: "minimaxai/minimax-m3",
-          custom: "gpt-4o-compatible",
-          ollama: "llama3.2",
-        }
-        const defaultModel = modelDefaults[provider] ?? "gpt-4o"
-        const modelInput = await ask(rl, `Model (mặc định: ${model || defaultModel}): `)
-        model = modelInput.trim() || model || defaultModel
+        console.log(`   Lệnh 'setup' sẽ lưu vào ~/.codeindex/.env và dùng cho mọi project sau này.\n`)
 
         const indexDirInput = await ask(rl, `Index directory (mặc định: ${indexDir}): `)
         indexDir = indexDirInput.trim() || indexDir
@@ -76,8 +56,6 @@ export function registerInitCommand(program: Command): void {
       }
 
       const config: any = {
-        provider,
-        model,
         indexDir,
       }
 
@@ -96,21 +74,11 @@ export function registerInitCommand(program: Command): void {
       console.log(`\n✅ Đã tạo .codeindex.json`)
       console.log(`\nNext steps:`)
 
-      const envMap: Record<string, string> = {
-        openai: "OPENAI_API_KEY",
-        anthropic: "ANTHROPIC_API_KEY",
-        google: "GOOGLE_API_KEY",
-        nvidia: "NVIDIA_API_KEY",
-        custom: "CUSTOM_API_KEY",
-        ollama: "(không cần key)",
-      }
-      const envVar = envMap[provider] ?? "OPENAI_API_KEY"
-
-      if (currentConfig.apiKey || provider === "ollama") {
+      if (currentConfig.apiKey || currentConfig.provider === "ollama") {
         console.log(`   1. Build the index : codeindex index .`)
         console.log(`   2. Query the index : codeindex query "how does auth work?"`)
       } else {
-        console.log(`   1. Set your API key: chạy 'codeindex setup', tạo file .env, hoặc 'export ${envVar}=<your-key>'`)
+        console.log(`   1. Chạy 'codeindex setup' để lưu cấu hình toàn cục vào ~/.codeindex/.env`)
         console.log(`   2. Build the index : codeindex index .`)
         console.log(`   3. Query the index : codeindex query "how does auth work?"`)
       }

packages/cli/src/commands/setup.ts

@@ -1,6 +1,6 @@
 import type { Command } from "commander"
 import * as readline from "readline"
-import { saveGlobalConfig } from "../config.js"
+import { saveGlobalConfig, saveGlobalEnv } from "../config.js"
 
 function ask(rl: readline.Interface, question: string): Promise<string> {
   return new Promise((resolve) => rl.question(question, resolve))
@@ -69,9 +69,11 @@ export function registerSetupCommand(program: Command): void {
       }
 
       saveGlobalConfig(config)
+      saveGlobalEnv(config)
 
       rl.close()
       console.log(`\n✅ Đã lưu cấu hình toàn cục vào ~/.codeindex/config.json`)
-      console.log(`\n✨ Xong! Bây giờ bạn có thể dùng 'codeindex init' hoặc 'codeindex index' ở bất kỳ đâu.`)
+      console.log(`✅ Đã lưu runtime env toàn cục vào ~/.codeindex/.env`)
+      console.log(`\n✨ Xong! Chạy setup một lần, các lần sau 'codeindex index' sẽ dùng cấu hình toàn cục này.`)
     })
 }