feat: add doctor command and auto-detect editors

.oxlintrc.json

@@ -5,6 +5,7 @@
     "perf": "error"
   },
   "rules": {
+    "max-lines": ["error", { "max": 500 }],
     "max-lines-per-function": "off",
     "max-nested-callbacks": "off",
     "max-depth": "off",

docs/public/llms-full.txt

@@ -3534,6 +3534,68 @@ Archgate upgraded to 0.4.0 successfully.
 
 ---
 
+## archgate doctor
+
+Check the system environment, installation method, and editor integrations. Useful for diagnosing configuration issues and sharing debug context in bug reports.
+
+```bash
+archgate doctor [options]
+```
+
+### Options
+
+| Option   | Description             |
+| -------- | ----------------------- |
+| `--json` | Machine-readable output |
+
+### Output sections
+
+- **System** — OS, architecture, WSL detection, Bun and Node versions
+- **Archgate** — CLI version, install method (binary, proto, local, global-pm), config directory, telemetry and login status
+- **Project** — Whether an `.archgate/` project exists, ADR count, domains
+- **Editor CLIs** — Whether `claude`, `cursor`, `code` (VS Code), `copilot`, and `git` are available on PATH
+- **Project Integrations** — Whether editor-specific plugin files exist in the current project (`.claude/settings.local.json`, `.cursor/rules/archgate-governance.mdc`, `.vscode/settings.json`, `.github/copilot/instructions.md`)
+
+### Example
+
+```bash
+archgate doctor
+```
+
+```
+System
+  OS:           win32/x64
+  Bun:          1.3.11
+  Node:         v24.3.0
+
+Archgate
+  Version:      0.25.1
+  Install:      binary
+  Exec path:    /home/user/.archgate/bin/archgate
+  Config dir:   /home/user/.archgate OK
+  Telemetry:    enabled
+  Logged in:    yes
+
+Project
+  ADRs:         5 (3 with rules)
+  Domains:      ARCH, GEN
+
+Editor CLIs
+  claude:       OK
+  cursor:       MISSING
+  code (vscode):OK
+  copilot:      MISSING
+  git:          OK
+
+Project Integrations
+  Claude:       OK (.claude/settings.local.json)
+  Cursor:       MISSING (.cursor/rules/archgate-governance.mdc)
+  VS Code:      OK (.vscode/settings.json)
+  Copilot:      MISSING (.github/copilot/instructions.md)
+```
+
+---
+
 ## archgate clean
 
 Remove the CLI cache directory.
@@ -3880,12 +3942,21 @@ Archgate collects **anonymous usage data** to help us understand how the CLI is
 
 When you run an Archgate command, we record:
 
-- **Command name** and **flags used** (e.g., `check --json`, not flag values)
-- **Exit code** (0, 1, or 2) and **execution duration**
-- **Environment**: OS, architecture, Bun version, Archgate version, CI detection, TTY detection
+- **Command name** and **which flags were used** (e.g., `check --json` — only flag presence, never flag values)
+- **Exit code** (0, 1, or 2) and **execution duration** (milliseconds)
+- **Environment**: OS, architecture, Bun version, Archgate version, CI detection, TTY detection, WSL detection
+- **Install context**: how the CLI was installed (binary, proto, local dev dependency, or global package manager)
+- **Project context**: whether an Archgate project exists in the current directory, how many ADRs it has, and how many have automated rules
 - **Coarse location**: country and region (resolved server-side from your IP, then the IP is discarded — see [IP anonymization](#ip-anonymization))
 - **Anonymous install ID**: a random UUID generated on first run — not derived from any personal data
 
+In addition to the general command lifecycle events (`command_executed` / `command_completed`), specific commands send enriched outcome events:
+
+- **`check`**: aggregate rule counts (total, passed, failed, warnings, errors), output format used, and whether filters were applied — no file paths or violation content
+- **`init`**: editor choice, whether the plugin was installed, and whether the project already existed
+- **`upgrade`**: version transition (from → to), install method, and success/failure
+- **`login`**: subcommand used (login, logout, refresh, status) and success/failure
+
 ### Error tracking (Sentry)
 
 When the CLI crashes (exit code 2), we send:

docs/src/content/docs/pt-br/reference/cli-commands.mdx

@@ -650,6 +650,68 @@ Archgate upgraded to 0.4.0 successfully.
 
 ---
 
+## archgate doctor
+
+Verifica o ambiente do sistema, o método de instalação e as integrações com editores. Útil para diagnosticar problemas de configuração e compartilhar contexto de depuração em relatórios de bugs.
+
+```bash
+archgate doctor [options]
+```
+
+### Opções
+
+| Opção    | Descrição                 |
+| -------- | ------------------------- |
+| `--json` | Saída legível por máquina |
+
+### Seções da saída
+
+- **System** — SO, arquitetura, detecção de WSL, versões do Bun e Node
+- **Archgate** — Versão da CLI, método de instalação (binary, proto, local, global-pm), diretório de configuração, status de telemetria e login
+- **Project** — Se existe um projeto `.archgate/`, contagem de ADRs, domínios
+- **Editor CLIs** — Se `claude`, `cursor`, `code` (VS Code), `copilot` e `git` estão disponíveis no PATH
+- **Project Integrations** — Se os arquivos de plugin específicos de cada editor existem no projeto atual (`.claude/settings.local.json`, `.cursor/rules/archgate-governance.mdc`, `.vscode/settings.json`, `.github/copilot/instructions.md`)
+
+### Exemplo
+
+```bash
+archgate doctor
+```
+
+```
+System
+  OS:           win32/x64
+  Bun:          1.3.11
+  Node:         v24.3.0
+
+Archgate
+  Version:      0.25.1
+  Install:      binary
+  Exec path:    /home/user/.archgate/bin/archgate
+  Config dir:   /home/user/.archgate OK
+  Telemetry:    enabled
+  Logged in:    yes
+
+Project
+  ADRs:         5 (3 with rules)
+  Domains:      ARCH, GEN
+
+Editor CLIs
+  claude:       OK
+  cursor:       MISSING
+  code (vscode):OK
+  copilot:      MISSING
+  git:          OK
+
+Project Integrations
+  Claude:       OK (.claude/settings.local.json)
+  Cursor:       MISSING (.cursor/rules/archgate-governance.mdc)
+  VS Code:      OK (.vscode/settings.json)
+  Copilot:      MISSING (.github/copilot/instructions.md)
+```
+
+---
+
 ## archgate clean
 
 Remove o diretório de cache da CLI.

docs/src/content/docs/pt-br/reference/telemetry.mdx

@@ -11,12 +11,21 @@ O Archgate coleta **dados de uso anônimos** para nos ajudar a entender como a C
 
 Quando você executa um comando do Archgate, registramos:
 
-- **Nome do comando** e **flags utilizadas** (ex: `check --json`, não os valores das flags)
-- **Código de saída** (0, 1 ou 2) e **duração da execução**
-- **Ambiente**: SO, arquitetura, versão do Bun, versão do Archgate, detecção de CI, detecção de TTY
+- **Nome do comando** e **quais flags foram usadas** (ex: `check --json` — apenas a presença da flag, nunca valores)
+- **Código de saída** (0, 1 ou 2) e **duração da execução** (milissegundos)
+- **Ambiente**: SO, arquitetura, versão do Bun, versão do Archgate, detecção de CI, detecção de TTY, detecção de WSL
+- **Contexto de instalação**: como a CLI foi instalada (binário, proto, dependência local ou gerenciador de pacotes global)
+- **Contexto do projeto**: se existe um projeto Archgate no diretório atual, quantas ADRs possui e quantas têm regras automatizadas
 - **Localização aproximada**: país e região (resolvidos no servidor a partir do seu IP, que é descartado em seguida — veja [Anonimização de IP](#anonimização-de-ip))
 - **ID de instalação anônimo**: um UUID aleatório gerado na primeira execução — não derivado de nenhum dado pessoal
 
+Além dos eventos gerais do ciclo de vida do comando (`command_executed` / `command_completed`), comandos específicos enviam eventos enriquecidos:
+
+- **`check`**: contagens agregadas de regras (total, aprovadas, reprovadas, avisos, erros), formato de saída usado e se filtros foram aplicados — sem caminhos de arquivo ou conteúdo de violação
+- **`init`**: escolha do editor, se o plugin foi instalado e se o projeto já existia
+- **`upgrade`**: transição de versão (de → para), método de instalação e sucesso/falha
+- **`login`**: subcomando usado (login, logout, refresh, status) e sucesso/falha
+
 ### Rastreamento de erros (Sentry)
 
 Quando a CLI falha (código de saída 2), enviamos:

docs/src/content/docs/reference/cli-commands.mdx

@@ -1,6 +1,6 @@
 ---
 title: CLI Commands
-description: "Complete reference for all Archgate CLI commands: init, check, adr create, adr list, adr show, adr update, login, review-context, and more."
+description: "Complete reference for all Archgate CLI commands: init, check, adr, login, plugin, review-context, session-context, upgrade, doctor, clean, and telemetry."
 ---
 
 ## Global options
@@ -652,6 +652,68 @@ Archgate upgraded to 0.4.0 successfully.
 
 ---
 
+## archgate doctor
+
+Check the system environment, installation method, and editor integrations. Useful for diagnosing configuration issues and sharing debug context in bug reports.
+
+```bash
+archgate doctor [options]
+```
+
+### Options
+
+| Option   | Description             |
+| -------- | ----------------------- |
+| `--json` | Machine-readable output |
+
+### Output sections
+
+- **System** — OS, architecture, WSL detection, Bun and Node versions
+- **Archgate** — CLI version, install method (binary, proto, local, global-pm), config directory, telemetry and login status
+- **Project** — Whether an `.archgate/` project exists, ADR count, domains
+- **Editor CLIs** — Whether `claude`, `cursor`, `code` (VS Code), `copilot`, and `git` are available on PATH
+- **Project Integrations** — Whether editor-specific plugin files exist in the current project (`.claude/settings.local.json`, `.cursor/rules/archgate-governance.mdc`, `.vscode/settings.json`, `.github/copilot/instructions.md`)
+
+### Example
+
+```bash
+archgate doctor
+```
+
+```
+System
+  OS:           win32/x64
+  Bun:          1.3.11
+  Node:         v24.3.0
+
+Archgate
+  Version:      0.25.1
+  Install:      binary
+  Exec path:    /home/user/.archgate/bin/archgate
+  Config dir:   /home/user/.archgate OK
+  Telemetry:    enabled
+  Logged in:    yes
+
+Project
+  ADRs:         5 (3 with rules)
+  Domains:      ARCH, GEN
+
+Editor CLIs
+  claude:       OK
+  cursor:       MISSING
+  code (vscode):OK
+  copilot:      MISSING
+  git:          OK
+
+Project Integrations
+  Claude:       OK (.claude/settings.local.json)
+  Cursor:       MISSING (.cursor/rules/archgate-governance.mdc)
+  VS Code:      OK (.vscode/settings.json)
+  Copilot:      MISSING (.github/copilot/instructions.md)
+```
+
+---
+
 ## archgate clean
 
 Remove the CLI cache directory.

docs/src/content/docs/reference/telemetry.mdx

@@ -11,12 +11,21 @@ Archgate collects **anonymous usage data** to help us understand how the CLI is
 
 When you run an Archgate command, we record:
 
-- **Command name** and **flags used** (e.g., `check --json`, not flag values)
-- **Exit code** (0, 1, or 2) and **execution duration**
-- **Environment**: OS, architecture, Bun version, Archgate version, CI detection, TTY detection
+- **Command name** and **which flags were used** (e.g., `check --json` — only flag presence, never flag values)
+- **Exit code** (0, 1, or 2) and **execution duration** (milliseconds)
+- **Environment**: OS, architecture, Bun version, Archgate version, CI detection, TTY detection, WSL detection
+- **Install context**: how the CLI was installed (binary, proto, local dev dependency, or global package manager)
+- **Project context**: whether an Archgate project exists in the current directory, how many ADRs it has, and how many have automated rules
 - **Coarse location**: country and region (resolved server-side from your IP, then the IP is discarded — see [IP anonymization](#ip-anonymization))
 - **Anonymous install ID**: a random UUID generated on first run — not derived from any personal data
 
+In addition to the general command lifecycle events (`command_executed` / `command_completed`), specific commands send enriched outcome events:
+
+- **`check`**: aggregate rule counts (total, passed, failed, warnings, errors), output format used, and whether filters were applied — no file paths or violation content
+- **`init`**: editor choice, whether the plugin was installed, and whether the project already existed
+- **`upgrade`**: version transition (from → to), install method, and success/failure
+- **`login`**: subcommand used (login, logout, refresh, status) and success/failure
+
 ### Error tracking (Sentry)
 
 When the CLI crashes (exit code 2), we send:

src/cli.ts

@@ -6,6 +6,7 @@ import packageJson from "../package.json";
 import { registerAdrCommand } from "./commands/adr/index";
 import { registerCheckCommand } from "./commands/check";
 import { registerCleanCommand } from "./commands/clean";
+import { registerDoctorCommand } from "./commands/doctor";
 import { registerInitCommand } from "./commands/init";
 import { registerLoginCommand } from "./commands/login";
 import { registerPluginCommand } from "./commands/plugin/index";
@@ -16,7 +17,7 @@ import { registerUpgradeCommand } from "./commands/upgrade";
 import { installGit } from "./helpers/git";
 import { logError } from "./helpers/log";
 import { createPathIfNotExists, paths } from "./helpers/paths";
-import { isSupportedPlatform } from "./helpers/platform";
+import { getPlatformInfo, isSupportedPlatform } from "./helpers/platform";
 import {
   addBreadcrumb,
   captureException,
@@ -31,16 +32,30 @@ import {
 } from "./helpers/telemetry";
 import { checkForUpdatesIfNeeded } from "./helpers/update-check";
 
+// Pre-main environment guards — these are user-facing errors (exit 1), not bugs.
+// The Bun check must throw (logError requires Bun APIs). The rest use logError
+// for clean output.
 if (typeof Bun === "undefined")
   throw new Error(
     "You need to run `archgate` with Bun. Do `bunx archgate [command]`"
   );
 
-if (!semver.satisfies(Bun.version, ">=1.2.21"))
-  throw new Error("You need to update Bun to version 1.2.21 or higher");
+if (!semver.satisfies(Bun.version, ">=1.2.21")) {
+  logError(
+    "You need to update Bun to version 1.2.21 or higher.",
+    `Current version: ${Bun.version}`
+  );
+  process.exit(1);
+}
 
-if (!isSupportedPlatform())
-  throw new Error("Archgate only supports macOS, Linux, and Windows");
+if (!isSupportedPlatform()) {
+  const { runtime } = getPlatformInfo();
+  logError(
+    "Archgate only supports macOS, Linux, and Windows.",
+    `Detected platform: ${runtime}/${process.arch}`
+  );
+  process.exit(1);
+}
 
 createPathIfNotExists(paths.cacheFolder);
 
@@ -61,7 +76,14 @@ async function main() {
   program.hook("preAction", (thisCommand) => {
     const fullCommand = getFullCommandName(thisCommand);
     addBreadcrumb("command", `Running: ${fullCommand}`);
-    trackCommand(fullCommand);
+    // Collect which options were used (presence only, no values)
+    const opts = thisCommand.opts() as Record<string, unknown>;
+    const optionFlags: Record<string, boolean> = {};
+    for (const key of Object.keys(opts)) {
+      const val = opts[key];
+      optionFlags[`opt_${key}`] = val !== undefined && val !== false;
+    }
+    trackCommand(fullCommand, optionFlags);
     commandStartTime = performance.now();
   });
 
@@ -80,6 +102,7 @@ async function main() {
   registerPluginCommand(program);
   registerUpgradeCommand(program);
   registerCleanCommand(program);
+  registerDoctorCommand(program);
   registerTelemetryCommand(program);
 
   const isUpgrade = process.argv.includes("upgrade");