feat: dashboard UX improvements and remote remediation fixes (v0.3.2)

- Fix exit code semantics: NOT_FOUND libraries no longer trigger exit code 1
  in `check --json`, so remote commands show as done instead of failed
- Dashboard auto-refreshes machine diagnostics 1.5s after a queued command completes
- Add bearer token auth module for dashboard API
- Add CustomCommandBox and Login components
- Bump version to 0.3.2

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

Author: mitulgarg

.gitignore

@@ -192,3 +192,4 @@ src/env_doctor/web/*
 !src/env_doctor/web/.gitkeep
 PR_SUMMARY.md
 CHANGES-cuda-install-run.md
+*.stackdump

CHANGELOG.md

@@ -5,6 +5,16 @@ All notable changes to env-doctor will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.3.2] - 2026-05-02
+
+### Fixed
+- **Exit code semantics for `check --json`**: `NOT_FOUND` library status no longer triggers exit code 1. Previously, having torch/tensorflow/jax uninstalled caused `env-doctor check --json` to exit 1 (warning), making remote remediation commands show as "failed" on the dashboard even when the check ran successfully. New exit codes: `0` = pass (no issues or only missing libraries), `1` = warnings (installed components with version conflicts), `2` = errors (broken components).
+
+### Changed
+- **Dashboard auto-refresh after remote command**: After a queued command completes on a machine, the Machine Detail page now automatically re-fetches and re-renders the diagnostics panel (1.5 s after the command finishes) — no manual page refresh needed.
+
+---
+
 ## [0.3.1] - 2026-04-15
 
 ### Added

CHANGES-cuda-install-run.md

@@ -184,20 +184,29 @@ There are two roles — the **dashboard host** (receives and displays reports) a
 pip install "env-doctor[dashboard]"
 env-doctor dashboard
 # → Serving at http://localhost:8765
+# → 🔐 Generated new API token at ~/.env-doctor/api-token
+#    Token: <copy this — paste into the browser login + share with hosts>
 ```
 
+On first launch the dashboard generates a shared API token (saved at `~/.env-doctor/api-token`, mode 0600). The browser login screen and every host CLI need that token. Override the location with `ENV_DOCTOR_API_TOKEN=<token>` in the dashboard's environment.
+
 **Step 2 — Report from each GPU machine** (only needs the core CLI, not the `[dashboard]` extra):
 
 ```bash
 pip install env-doctor
 
 # One-time report
-env-doctor check --report-to http://<dashboard-host>:8765
+env-doctor check --report-to http://<dashboard-host>:8765 --token <token>
 
 # Or: set up automatic reporting every 2 minutes
-env-doctor report install --url http://<dashboard-host>:8765 --interval 2m
+env-doctor report install \
+    --url http://<dashboard-host>:8765 \
+    --token <token> \
+    --interval 2m
 ```
 
+The token is saved in `~/.env-doctor/report-config.json` so the scheduled cron / Task Scheduler entry stays clean (no secrets in `crontab -l`).
+
 `report install` creates a scheduled task on the GPU machine — a **cron job** on Linux/macOS or a **Windows Task Scheduler** entry on Windows. That task runs `env-doctor check --report-to <url>` on the configured interval.
 
 ### Smart Change Detection
@@ -248,9 +257,19 @@ For machines behind NAT (different networks), use [Tailscale](https://tailscale.
 
 ```bash
 # Install Tailscale on each machine, then use the Tailscale IP
-env-doctor report install --url http://100.x.x.x:8765
+env-doctor report install --url http://100.x.x.x:8765 --token <token>
 ```
 
+### Deploying to a Shared Host
+
+If you're hosting one dashboard for a small team rather than running it on a single laptop:
+
+1. **Use the API token.** Generated automatically on first launch (see Step 1 above), or pin a known value with `ENV_DOCTOR_API_TOKEN`. All `/api/*` routes require `Authorization: Bearer <token>`.
+2. **Put TLS in front.** The dashboard speaks plain HTTP. Terminate TLS in nginx, Caddy, or a cloud load balancer and forward to `127.0.0.1:8765`. Tokens travel in the `Authorization` header — they need TLS to stay private outside trusted networks.
+3. **Restrict CORS.** Set `ENV_DOCTOR_CORS_ORIGINS=https://dashboard.example.com` on the dashboard process so the browser only honours requests from your origin (defaults to `*` for backward compatibility with local use).
+4. **Tune staleness.** A machine is flagged "stale" once its `last_seen` is older than `ENV_DOCTOR_STALE_SECONDS` seconds (default 3600 = 1 hour, ≈ 2× the default heartbeat).
+5. **Rotating the token.** Edit `~/.env-doctor/api-token` (or update `ENV_DOCTOR_API_TOKEN` and restart). Each host CLI needs `env-doctor report install --token <new>` re-run, or its `~/.env-doctor/report-config.json` updated, before the next check-in.
+
 ### What the Dashboard Shows
 
 The web UI at `http://<dashboard-host>:8765` displays:
@@ -269,11 +288,11 @@ The dashboard can queue `env-doctor` CLI commands to run on remote machines —
 ```
   Dashboard                           GPU Machine
   ┌────────────┐                     ┌──────────────────┐
-  │ Operator    │                     │ Scheduled check  │
-  │ clicks      │                     │ (cron / Task     │
-  │ "▶ Run" on  │                     │  Scheduler)      │
-  │ Fleet page  │                     │                  │
-  └──────┬──────┘                     └────────┬─────────┘
+  │ Operator   │                     │ Scheduled check  │
+  │ clicks     │                     │ (cron / Task     │
+  │ "▶ Run" on │                     │  Scheduler)      │
+  │ Fleet page │                     │                  │
+  └──────┬─────┘                     └────────┬─────────┘
          │                                     │
          ▼                                     ▼
   Queue command                        env-doctor check
@@ -662,6 +681,14 @@ env-doctor check --json
 env-doctor check --ci
 ```
 
+**Exit code semantics for `check --json` / `check --ci`:**
+
+| Code | Meaning |
+|------|---------|
+| `0` | All detected components are compatible (uninstalled libraries do not count as failures) |
+| `1` | Installed components have warnings or version conflicts |
+| `2` | One or more components are in an error state |
+
 **GitHub Actions example:**
 ```yaml
 - run: pip install env-doctor

README.md

@@ -125,9 +125,12 @@ The dashboard exposes a REST API that machines post to:
 
 | Endpoint | Method | Description |
 |----------|--------|-------------|
-| `/api/report` | POST | Receive a check report |
+| `/api/report` | POST | Receive a check report; returns `pending_commands[]` for the machine |
 | `/api/machines` | GET | List all machines with latest status |
 | `/api/machines/{id}` | GET | Full machine detail and latest report |
 | `/api/machines/{id}/history` | GET | Snapshot timeline |
+| `/api/machines/{id}/commands` | POST | Queue a remediation command (must start with `env-doctor` or `doctor`) |
+| `/api/machines/{id}/commands` | GET | List recent commands with status and output |
+| `/api/machines/{id}/commands/{cmd_id}/result` | POST | Machine posts execution result `{output, exit_code}` |
 
 See the [Fleet Monitoring Guide](../guides/fleet-monitoring.md) for full setup instructions.

docs/commands/dashboard.md

@@ -271,6 +271,44 @@ env-doctor check --report-to http://10.0.1.50:8765
 
 ---
 
+## Remote Remediation
+
+The dashboard can queue `env-doctor` commands to run on remote machines — no SSH required.
+
+### How it works
+
+1. **Operator** opens a machine's detail page in the dashboard and types a command in the "Run a command" box (e.g. `env-doctor install torch --execute`).
+2. The command is stored in the database with status `pending`.
+3. On the **next check-in** (`POST /api/report`), the server returns the pending command in the response.
+4. The **GPU machine CLI** executes the command, captures stdout/stderr, and POSTs the result back to `/api/machines/{id}/commands/{cmd_id}/result`.
+5. The CLI then re-runs `env-doctor check --report-to <url>` to verify the fix and post a fresh diagnostic snapshot.
+6. The **dashboard auto-refreshes** the machine detail page 1.5 s after the command completes, showing updated diagnostics without a manual page reload.
+
+### Security
+
+Only commands prefixed with `env-doctor` or `doctor` are accepted by the server. Arbitrary shell commands are rejected with HTTP 400.
+
+### Command lifecycle
+
+| Status | Meaning |
+|--------|---------|
+| `pending` | Queued, waiting for machine to check in |
+| `running` | Machine picked it up, executing now |
+| `done` | Completed with exit code 0 |
+| `failed` | Completed with non-zero exit code |
+
+### Exit codes for `env-doctor check --json`
+
+When `env-doctor check --json` is queued as a remote command, exit code 1 does **not** mean the check failed — it means there are installed components with warnings. Uninstalled libraries alone do not produce a non-zero exit code.
+
+| Exit code | Meaning |
+|-----------|---------|
+| `0` | All detected components compatible; uninstalled libraries ignored |
+| `1` | Installed components have warnings or version conflicts |
+| `2` | One or more components in error state |
+
+---
+
 ## Data Storage
 
 **On the dashboard host:**

docs/guides/fleet-monitoring.md

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "env-doctor"
-version = "0.3.1"
+version = "0.3.2"
 description = "A CLI tool to verify and fix AI/ML environment compatibility (Driver <-> CUDA <-> Wheels) with platform-specific installation guides."
 readme = "README.md"
 license = { file = "LICENSE" }

pyproject.toml

@@ -1 +1 @@
-__version__ = "0.3.1"
+__version__ = "0.3.2"