@groundctl/cli 0.4.0 → 0.5.0

package/dist/index.js

@@ -2,11 +2,14 @@
 
 // src/index.ts
 import { Command } from "commander";
-import { createRequire } from "module";
+import { createRequire as createRequire2 } from "module";
 
 // src/commands/init.ts
 import { existsSync as existsSync3, mkdirSync as mkdirSync2, writeFileSync as writeFileSync3, chmodSync, readFileSync as readFileSync3, appendFileSync } from "fs";
 import { join as join3 } from "path";
+import { homedir as homedir2 } from "os";
+import { spawn, execSync as execSync3 } from "child_process";
+import { createInterface as createInterface2 } from "readline";
 import chalk2 from "chalk";
 
 // src/storage/db.ts
@@ -98,6 +101,14 @@ function applySchema(db) {
   db.run("CREATE INDEX IF NOT EXISTS idx_claims_active ON claims(feature_id) WHERE released_at IS NULL");
   db.run("CREATE INDEX IF NOT EXISTS idx_files_session ON files_modified(session_id)");
   db.run("CREATE INDEX IF NOT EXISTS idx_decisions_session ON decisions(session_id)");
+  db.run(`
+    CREATE TABLE IF NOT EXISTS feature_groups (
+      id          INTEGER PRIMARY KEY AUTOINCREMENT,
+      name        TEXT NOT NULL UNIQUE,
+      label       TEXT NOT NULL,
+      order_index INTEGER NOT NULL DEFAULT 0
+    )
+  `);
   const tryAlter = (sql) => {
     try {
       db.run(sql);
@@ -107,6 +118,7 @@ function applySchema(db) {
   tryAlter("ALTER TABLE features ADD COLUMN progress_done  INTEGER");
   tryAlter("ALTER TABLE features ADD COLUMN progress_total INTEGER");
   tryAlter("ALTER TABLE features ADD COLUMN items          TEXT");
+  tryAlter("ALTER TABLE features ADD COLUMN group_id       INTEGER REFERENCES feature_groups(id)");
   db.run(
     "INSERT OR REPLACE INTO meta (key, value) VALUES ('schema_version', ?)",
     [String(SCHEMA_VERSION)]
@@ -475,6 +487,10 @@ import { execSync as execSync2 } from "child_process";
 import { request as httpsRequest } from "https";
 import { createInterface } from "readline";
 import chalk from "chalk";
+var PROXY_URL = "https://detect.groundctl.org/detect";
+var USER_AGENT = "groundctl-cli/0.5.0 Node.js";
+var MODEL = "claude-haiku-4-5-20251001";
+var SYSTEM_PROMPT = "You are a product analyst. Analyze this project and identify the main product features.";
 function run2(cmd, cwd) {
   try {
     return execSync2(cmd, { cwd, encoding: "utf-8", stdio: ["ignore", "pipe", "ignore"] });
@@ -482,20 +498,9 @@ function run2(cmd, cwd) {
     return "";
   }
 }
-function collectContext(projectPath) {
-  const parts = [];
+function collectContextParts(projectPath) {
   const gitLog = run2("git log --oneline --no-merges", projectPath);
-  if (gitLog.trim()) {
-    const lines = gitLog.trim().split("\n").slice(0, 150).join("\n");
-    parts.push(`## Git history (${lines.split("\n").length} commits)
-${lines}`);
-  }
-  const diffStat = run2("git log --stat --no-merges --oneline -30", projectPath);
-  if (diffStat.trim()) {
-    parts.push(`## Recent commit file changes
-${diffStat.trim().slice(0, 3e3)}`);
-  }
-  const find = run2(
+  const fileTree = run2(
     [
       "find . -type f",
       "-not -path '*/node_modules/*'",
@@ -516,211 +521,228 @@ ${diffStat.trim().slice(0, 3e3)}`);
     ].join(" "),
     projectPath
   );
-  if (find.trim()) {
-    parts.push(`## Project file structure
-${find.trim()}`);
-  }
   const readmePath = join2(projectPath, "README.md");
-  if (existsSync2(readmePath)) {
-    const readme = readFileSync2(readmePath, "utf-8").slice(0, 3e3);
-    parts.push(`## README.md
-${readme}`);
-  }
+  const readme = existsSync2(readmePath) ? readFileSync2(readmePath, "utf-8").slice(0, 3e3) : void 0;
   const psPath = join2(projectPath, "PROJECT_STATE.md");
-  if (existsSync2(psPath)) {
-    const ps = readFileSync2(psPath, "utf-8").slice(0, 2e3);
-    parts.push(`## Existing PROJECT_STATE.md
-${ps}`);
+  const projectState = existsSync2(psPath) ? readFileSync2(psPath, "utf-8").slice(0, 2e3) : void 0;
+  return {
+    gitLog: gitLog.trim().split("\n").slice(0, 150).join("\n") || void 0,
+    fileTree: fileTree.trim() || void 0,
+    readme,
+    projectState
+  };
+}
+function buildContextString(parts) {
+  const sections = [];
+  if (parts.gitLog) sections.push(`## Git history
+${parts.gitLog}`);
+  if (parts.fileTree) sections.push(`## File structure
+${parts.fileTree}`);
+  if (parts.readme) sections.push(`## README
+${parts.readme}`);
+  if (parts.projectState) sections.push(`## Existing PROJECT_STATE.md
+${parts.projectState}`);
+  return sections.join("\n\n");
+}
+function normaliseFeatures(raw) {
+  return raw.map((f) => ({
+    name: String(f.name ?? "").toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-|-$/g, ""),
+    status: f.status === "done" ? "done" : "open",
+    priority: ["critical", "high", "medium", "low"].includes(f.priority) ? f.priority : "medium",
+    description: String(f.description ?? "").slice(0, 120)
+  })).filter((f) => f.name.length >= 2);
+}
+function parseFeatureJson(text) {
+  const stripped = text.replace(/^```[^\n]*\n?/, "").replace(/\n?```$/, "").trim();
+  let obj;
+  try {
+    obj = JSON.parse(stripped);
+  } catch {
+    const m = stripped.match(/\{[\s\S]*\}/);
+    if (!m) throw new Error("No JSON found in response");
+    obj = JSON.parse(m[0]);
   }
-  return parts.join("\n\n");
+  if (!Array.isArray(obj.features)) throw new Error("Response missing 'features' array");
+  return normaliseFeatures(obj.features);
 }
-var SYSTEM_PROMPT = "You are a product analyst. Analyze this project and identify the main product features.";
-var USER_TEMPLATE = (context) => `Based on this git history and project structure, identify the product features with their status and priority.
-
-Rules:
-- Features are functional capabilities, not technical tasks
-- Maximum 12 features
-- status: "done" if all related commits are old and nothing is open, otherwise "open"
-- priority: critical/high/medium/low
-- name: short, kebab-case, human-readable (e.g. "user-auth", "data-pipeline")
-- description: one sentence, what the feature does for the user
-
-Respond ONLY with valid JSON, no markdown, no explanation:
-{"features":[{"name":"...","status":"done","priority":"high","description":"..."}]}
-
-Project context:
-${context}`;
-function httpsPost(opts) {
+function httpsPost(url, body, extraHeaders) {
   return new Promise((resolve3, reject) => {
-    const body = JSON.stringify({
-      model: opts.model,
-      max_tokens: opts.maxTokens ?? 1024,
-      system: opts.system,
-      messages: [{ role: "user", content: opts.userMessage }]
-    });
+    const bodyStr = JSON.stringify(body);
+    const parsed = new URL(url);
     const req = httpsRequest(
       {
-        hostname: "api.anthropic.com",
-        path: "/v1/messages",
+        hostname: parsed.hostname,
+        path: parsed.pathname + parsed.search,
         method: "POST",
         headers: {
-          "x-api-key": opts.apiKey,
-          "anthropic-version": "2023-06-01",
           "content-type": "application/json",
-          "content-length": Buffer.byteLength(body)
+          "content-length": Buffer.byteLength(bodyStr),
+          "user-agent": USER_AGENT,
+          ...extraHeaders
         }
       },
       (res) => {
         let data = "";
-        res.on("data", (chunk) => {
-          data += chunk.toString();
+        res.on("data", (c) => {
+          data += c.toString();
         });
         res.on("end", () => {
-          resolve3(data);
+          if ((res.statusCode ?? 200) >= 400) {
+            reject(new Error(`HTTP ${res.statusCode}: ${data.slice(0, 200)}`));
+          } else {
+            resolve3(data);
+          }
         });
       }
     );
+    req.setTimeout(15e3, () => {
+      req.destroy(new Error("Request timeout"));
+    });
     req.on("error", reject);
-    req.write(body);
+    req.write(bodyStr);
     req.end();
   });
 }
-function extractText(raw) {
-  const json = JSON.parse(raw);
-  if (json.error) throw new Error(`API error: ${json.error.message}`);
-  const block = (json.content ?? []).find((b) => b.type === "text");
-  if (!block) throw new Error("No text block in API response");
-  return block.text;
+async function callProxy(parts) {
+  const raw = await httpsPost(PROXY_URL, parts);
+  const resp = JSON.parse(raw);
+  if (resp.error) throw new Error(resp.error);
+  if (!Array.isArray(resp.features)) throw new Error("No features in proxy response");
+  return normaliseFeatures(resp.features);
 }
-function parseFeatureJson(text) {
-  const stripped = text.replace(/^```[^\n]*\n?/, "").replace(/\n?```$/, "").trim();
-  let obj;
-  try {
-    obj = JSON.parse(stripped);
-  } catch {
-    const match = stripped.match(/\{[\s\S]*\}/);
-    if (!match) throw new Error("Could not parse JSON from model response");
-    obj = JSON.parse(match[0]);
-  }
-  if (!Array.isArray(obj.features)) throw new Error("Response missing 'features' array");
-  return obj.features.map((f) => ({
-    name: String(f.name ?? "").toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-|-$/g, ""),
-    status: f.status === "done" ? "done" : "open",
-    priority: ["critical", "high", "medium", "low"].includes(f.priority) ? f.priority : "medium",
-    description: String(f.description ?? "").slice(0, 120)
-  })).filter((f) => f.name.length >= 2);
-}
-async function callClaude(apiKey, context) {
-  const raw = await httpsPost({
-    apiKey,
-    model: "claude-haiku-4-5-20251001",
-    system: SYSTEM_PROMPT,
-    userMessage: USER_TEMPLATE(context),
-    maxTokens: 1024
-  });
-  const text = extractText(raw);
-  return parseFeatureJson(text);
+async function callDirectApi(apiKey, parts) {
+  const userMsg = `Based on this project context, identify the product features.
+
+Rules:
+- Features are functional capabilities, not technical tasks
+- Maximum 12 features
+- status: "done" if clearly shipped, otherwise "open"
+- priority: critical/high/medium/low
+- name: short, kebab-case
+
+Respond ONLY with valid JSON, no markdown:
+{"features":[{"name":"...","status":"done","priority":"high","description":"..."}]}
+
+${buildContextString(parts)}`;
+  const raw = await httpsPost(
+    "https://api.anthropic.com/v1/messages",
+    { model: MODEL, max_tokens: 1024, system: SYSTEM_PROMPT, messages: [{ role: "user", content: userMsg }] },
+    { "x-api-key": apiKey, "anthropic-version": "2023-06-01" }
+  );
+  const resp = JSON.parse(raw);
+  if (resp.error) throw new Error(resp.error.message);
+  const block = (resp.content ?? []).find((b) => b.type === "text");
+  if (!block) throw new Error("Empty response from API");
+  return parseFeatureJson(block.text);
+}
+function basicHeuristic(projectPath) {
+  const log = run2("git log --oneline --no-merges", projectPath);
+  if (!log.trim()) return [];
+  const seen = /* @__PURE__ */ new Set();
+  const features = [];
+  for (const line of log.trim().split("\n").slice(0, 60)) {
+    const msg = line.replace(/^[a-f0-9]+ /, "").toLowerCase();
+    const m = msg.match(/(?:feat(?:ure)?[:,\s]+|add\s+|implement\s+|build\s+|create\s+|setup\s+)([a-z][\w\s-]{2,40})/);
+    if (!m) continue;
+    const raw = m[1].trim().replace(/\s+/g, "-").replace(/[^a-z0-9-]/g, "").replace(/-+/g, "-").replace(/^-|-$/g, "");
+    const name = raw.slice(0, 30);
+    if (!name || seen.has(name)) continue;
+    seen.add(name);
+    features.push({ name, status: "done", priority: "medium", description: `Detected from: ${line.slice(8, 80)}` });
+    if (features.length >= 10) break;
+  }
+  return features;
 }
 function renderFeatureList(features) {
   console.log(chalk.bold(`
   Detected ${features.length} features:
 `));
   for (const f of features) {
-    const statusIcon = f.status === "done" ? chalk.green("\u2713") : chalk.gray("\u25CB");
-    const prioColor = f.priority === "critical" || f.priority === "high" ? chalk.red : chalk.gray;
-    console.log(
-      `  ${statusIcon} ${chalk.white(f.name.padEnd(28))}` + prioColor(`(${f.priority}, ${f.status})`.padEnd(18)) + chalk.gray(f.description)
-    );
+    const icon = f.status === "done" ? chalk.green("\u2713") : chalk.gray("\u25CB");
+    const prioCh = f.priority === "critical" || f.priority === "high" ? chalk.red : chalk.gray;
+    const meta = prioCh(`(${f.priority}, ${f.status})`.padEnd(16));
+    console.log(`  ${icon} ${chalk.white(f.name.padEnd(28))}${meta}  ${chalk.gray(f.description)}`);
   }
   console.log("");
 }
 function readLine(prompt) {
   const rl = createInterface({ input: process.stdin, output: process.stdout });
   return new Promise((resolve3) => {
-    rl.question(prompt, (answer) => {
+    rl.question(prompt, (a) => {
       rl.close();
-      resolve3(answer.trim().toLowerCase());
+      resolve3(a.trim().toLowerCase());
     });
   });
 }
 async function editInEditor(features) {
-  const tmpPath = join2(tmpdir(), `groundctl-features-${Date.now()}.json`);
-  writeFileSync2(tmpPath, JSON.stringify({ features }, null, 2), "utf-8");
+  const tmp = join2(tmpdir(), `groundctl-features-${Date.now()}.json`);
+  writeFileSync2(tmp, JSON.stringify({ features }, null, 2), "utf-8");
   const editor = process.env.EDITOR ?? process.env.VISUAL ?? "vi";
   try {
-    execSync2(`${editor} "${tmpPath}"`, { stdio: "inherit" });
+    execSync2(`${editor} "${tmp}"`, { stdio: "inherit" });
   } catch {
-    console.log(chalk.red("  Editor exited with error \u2014 using original features."));
     return features;
   }
   try {
-    const edited = readFileSync2(tmpPath, "utf-8");
-    return parseFeatureJson(edited);
-  } catch (err) {
-    console.log(chalk.red(`  Could not parse edited JSON: ${err.message}`));
+    return parseFeatureJson(readFileSync2(tmp, "utf-8"));
+  } catch (e) {
+    console.log(chalk.red(`  Parse error: ${e.message}`));
     return null;
   }
 }
 function importFeatures(db, features) {
-  db.run(
-    `DELETE FROM features
-     WHERE id NOT IN (SELECT DISTINCT feature_id FROM claims)
-       AND status = 'pending'`
-  );
+  db.run(`DELETE FROM features WHERE id NOT IN (SELECT DISTINCT feature_id FROM claims) AND status = 'pending'`);
   for (const f of features) {
-    const id = f.name;
     const status = f.status === "done" ? "done" : "pending";
-    const exists = queryOne(db, "SELECT id FROM features WHERE id = ?", [id]);
-    if (!exists) {
+    if (!queryOne(db, "SELECT id FROM features WHERE id = ?", [f.name])) {
       db.run(
         "INSERT INTO features (id, name, status, priority, description) VALUES (?, ?, ?, ?, ?)",
-        [id, f.name, status, f.priority, f.description]
+        [f.name, f.name, status, f.priority, f.description]
       );
     } else {
       db.run(
-        `UPDATE features
-         SET description = ?, priority = ?, updated_at = datetime('now')
-         WHERE id = ?`,
-        [f.description, f.priority, id]
+        "UPDATE features SET description = ?, priority = ?, updated_at = datetime('now') WHERE id = ?",
+        [f.description, f.priority, f.name]
       );
     }
   }
   saveDb();
 }
 async function detectAndImportFeatures(db, projectPath) {
+  process.stdout.write(chalk.gray("  Detecting features..."));
+  const parts = collectContextParts(projectPath);
   const apiKey = process.env.ANTHROPIC_API_KEY;
-  if (!apiKey) {
-    console.log(chalk.yellow(
-      "\n  Smart feature detection disabled \u2014 ANTHROPIC_API_KEY not set."
-    ));
-    console.log(chalk.gray("  To enable:"));
-    console.log(chalk.gray("    export ANTHROPIC_API_KEY=sk-ant-..."));
-    console.log(chalk.gray(
-      "\n  Or add features manually:\n    groundctl add feature -n 'my-feature'\n"
-    ));
-    return false;
-  }
-  console.log(chalk.gray("  Collecting project context..."));
-  const context = collectContext(projectPath);
-  console.log(chalk.gray("  Asking Claude to detect features..."));
-  let features;
+  let features = [];
+  let source = "";
   try {
-    features = await callClaude(apiKey, context);
-  } catch (err) {
-    console.log(chalk.red(`  \u2717 Feature detection failed: ${err.message}`));
-    console.log(chalk.gray("  Add features manually with: groundctl add feature -n 'my-feature'\n"));
-    return false;
+    features = await callProxy(parts);
+    source = "proxy";
+  } catch {
+    if (apiKey) {
+      try {
+        features = await callDirectApi(apiKey, parts);
+        source = "api";
+      } catch {
+        features = basicHeuristic(projectPath);
+        source = "heuristic";
+      }
+    } else {
+      features = basicHeuristic(projectPath);
+      source = "heuristic";
+    }
   }
+  process.stdout.write("\r" + " ".repeat(30) + "\r");
   if (features.length === 0) {
-    console.log(chalk.yellow("  No features detected \u2014 add them manually.\n"));
+    console.log(chalk.yellow("  No features detected \u2014 add them manually with groundctl add feature.\n"));
     return false;
   }
+  const sourceLabel = source === "proxy" ? chalk.green("(via detect.groundctl.org)") : source === "api" ? chalk.green("(via ANTHROPIC_API_KEY)") : chalk.yellow("(basic heuristic \u2014 set ANTHROPIC_API_KEY for better results)");
   renderFeatureList(features);
+  console.log(chalk.gray(`  Source: ${sourceLabel}
+`));
   let pending = features;
   while (true) {
-    const answer = await readLine(
-      chalk.bold("  Import these features? ") + chalk.gray("[y/n/edit] ") + ""
-    );
+    const answer = await readLine(chalk.bold("  Import these features? ") + chalk.gray("[y/n/edit] "));
     if (answer === "y" || answer === "yes") {
       importFeatures(db, pending);
       console.log(chalk.green(`
@@ -729,7 +751,7 @@ async function detectAndImportFeatures(db, projectPath) {
       return true;
     }
     if (answer === "n" || answer === "no") {
-      console.log(chalk.gray("  Skipped \u2014 no features imported.\n"));
+      console.log(chalk.gray("  Skipped.\n"));
       return false;
     }
     if (answer === "e" || answer === "edit") {
@@ -737,9 +759,7 @@ async function detectAndImportFeatures(db, projectPath) {
       if (edited && edited.length > 0) {
         pending = edited;
         renderFeatureList(pending);
-      } else {
-        console.log(chalk.yellow("  No valid features after edit \u2014 try again.\n"));
-      }
+      } else console.log(chalk.yellow("  No valid features after edit.\n"));
       continue;
     }
     console.log(chalk.gray("  Please answer y, n, or edit."));
@@ -780,6 +800,90 @@ groundctl ingest \\
 groundctl sync 2>/dev/null || true
 echo "--- groundctl: Product state updated ---"
 `;
+var LAUNCH_AGENT_ID = "org.groundctl.watch";
+var LAUNCH_AGENT_PLIST_PATH = join3(homedir2(), "Library", "LaunchAgents", `${LAUNCH_AGENT_ID}.plist`);
+function buildLaunchAgentPlist(projectPath) {
+  const binPath = process.argv[1];
+  return `<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+  <key>Label</key>
+  <string>${LAUNCH_AGENT_ID}</string>
+  <key>ProgramArguments</key>
+  <array>
+    <string>${process.execPath}</string>
+    <string>${binPath}</string>
+    <string>watch</string>
+    <string>--project-path</string>
+    <string>${projectPath}</string>
+  </array>
+  <key>RunAtLoad</key>
+  <true/>
+  <key>KeepAlive</key>
+  <false/>
+  <key>StandardOutPath</key>
+  <string>${join3(projectPath, ".groundctl", "watch.log")}</string>
+  <key>StandardErrorPath</key>
+  <string>${join3(projectPath, ".groundctl", "watch.log")}</string>
+</dict>
+</plist>
+`;
+}
+function readLine2(prompt) {
+  const rl = createInterface2({ input: process.stdin, output: process.stdout });
+  return new Promise((resolve3) => {
+    rl.question(prompt, (a) => {
+      rl.close();
+      resolve3(a.trim().toLowerCase());
+    });
+  });
+}
+function startWatchDaemon(projectPath) {
+  try {
+    const args = [process.argv[1], "watch", "--project-path", projectPath];
+    const child = spawn(process.execPath, args, {
+      detached: true,
+      stdio: "ignore"
+    });
+    child.unref();
+    const pid = child.pid ?? null;
+    if (pid) {
+      const groundctlDir = join3(projectPath, ".groundctl");
+      mkdirSync2(groundctlDir, { recursive: true });
+      writeFileSync3(join3(groundctlDir, "watch.pid"), String(pid), "utf8");
+    }
+    return pid;
+  } catch {
+    return null;
+  }
+}
+function watchDaemonRunning(projectPath) {
+  try {
+    const pidPath = join3(projectPath, ".groundctl", "watch.pid");
+    if (!existsSync3(pidPath)) return false;
+    const pid = parseInt(readFileSync3(pidPath, "utf8").trim());
+    if (!pid) return false;
+    process.kill(pid, 0);
+    return true;
+  } catch {
+    return false;
+  }
+}
+function installLaunchAgent(projectPath) {
+  try {
+    const laDir = join3(homedir2(), "Library", "LaunchAgents");
+    mkdirSync2(laDir, { recursive: true });
+    writeFileSync3(LAUNCH_AGENT_PLIST_PATH, buildLaunchAgentPlist(projectPath), "utf8");
+    try {
+      execSync3(`launchctl load "${LAUNCH_AGENT_PLIST_PATH}"`, { stdio: "ignore" });
+    } catch {
+    }
+    return true;
+  } catch {
+    return false;
+  }
+}
 async function initCommand(options) {
   const cwd = process.cwd();
   const projectName = cwd.split("/").pop() ?? "unknown";
@@ -837,6 +941,37 @@ groundctl init \u2014 ${projectName}
       appendFileSync(gitignorePath, gitignoreEntry);
     }
   }
+  console.log("");
+  if (watchDaemonRunning(cwd)) {
+    console.log(chalk2.green("  \u2713 Watch daemon already running"));
+  } else {
+    const pid = startWatchDaemon(cwd);
+    if (pid) {
+      console.log(chalk2.green(`  \u2713 Watch daemon started`) + chalk2.gray(` (PID ${pid})`));
+    } else {
+      console.log(chalk2.yellow("  \u26A0  Could not start watch daemon \u2014 run: groundctl watch --daemon"));
+    }
+  }
+  if (process.platform === "darwin") {
+    const laInstalled = existsSync3(LAUNCH_AGENT_PLIST_PATH);
+    if (!laInstalled) {
+      const answer = await readLine2(
+        chalk2.bold("  Start groundctl watch on login? (recommended) ") + chalk2.gray("[y/n] ")
+      );
+      if (answer === "y" || answer === "yes") {
+        const ok2 = installLaunchAgent(cwd);
+        if (ok2) {
+          console.log(chalk2.green("  \u2713 LaunchAgent installed") + chalk2.gray(` (${LAUNCH_AGENT_PLIST_PATH.replace(homedir2(), "~")})`));
+        } else {
+          console.log(chalk2.yellow("  \u26A0  LaunchAgent install failed \u2014 run: groundctl doctor"));
+        }
+      } else {
+        console.log(chalk2.gray("  Skipped. You can install later: groundctl doctor"));
+      }
+    } else {
+      console.log(chalk2.green("  \u2713 LaunchAgent already installed"));
+    }
+  }
   console.log(chalk2.bold.green(`
   \u2713 groundctl initialized for ${projectName}
 `));
@@ -856,7 +991,9 @@ groundctl init \u2014 ${projectName}
 
 // src/commands/status.ts
 import chalk3 from "chalk";
-var BAR_W = 14;
+var AGG_BAR_W = 20;
+var GRP_BAR_W = 20;
+var FEAT_BAR_W = 14;
 var NAME_W = 22;
 var PROG_W = 6;
 function progressBar(done, total, width) {
@@ -864,110 +1001,162 @@ function progressBar(done, total, width) {
   const filled = Math.min(width, Math.round(done / total * width));
   return chalk3.green("\u2588".repeat(filled)) + chalk3.gray("\u2591".repeat(width - filled));
 }
-function featureBar(status, progressDone, progressTotal) {
-  if (progressTotal != null && progressTotal > 0) {
-    return progressBar(progressDone ?? 0, progressTotal, BAR_W);
-  }
+function featureBar(status, pd, pt, width = FEAT_BAR_W) {
+  if (pt != null && pt > 0) return progressBar(pd ?? 0, pt, width);
   switch (status) {
     case "done":
-      return progressBar(1, 1, BAR_W);
+      return progressBar(1, 1, width);
     case "in_progress":
-      return progressBar(1, 2, BAR_W);
+      return progressBar(1, 2, width);
     case "blocked":
-      return chalk3.red("\u2591".repeat(BAR_W));
+      return chalk3.red("\u2591".repeat(width));
     default:
-      return chalk3.gray("\u2591".repeat(BAR_W));
-  }
-}
-function featureProgress(progressDone, progressTotal) {
-  if (progressDone != null && progressTotal != null) {
-    return `${progressDone}/${progressTotal}`;
+      return chalk3.gray("\u2591".repeat(width));
   }
-  return "";
 }
-function wrapItems(itemsCsv, maxWidth) {
-  const items = itemsCsv.split(",").map((s) => s.trim()).filter(Boolean);
+function wrapItems(csv, maxWidth) {
+  const items = csv.split(",").map((s) => s.trim()).filter(Boolean);
   const lines = [];
-  let current = "";
+  let cur = "";
   for (const item of items) {
-    const next = current ? `${current} \xB7 ${item}` : item;
-    if (next.length > maxWidth && current.length > 0) {
-      lines.push(current);
-      current = item;
-    } else {
-      current = next;
-    }
+    const next = cur ? `${cur} \xB7 ${item}` : item;
+    if (next.length > maxWidth && cur.length > 0) {
+      lines.push(cur);
+      cur = item;
+    } else cur = next;
   }
-  if (current) lines.push(current);
+  if (cur) lines.push(cur);
   return lines;
 }
-function timeSince(isoDate) {
-  const then = (/* @__PURE__ */ new Date(isoDate + "Z")).getTime();
-  const ms = Date.now() - then;
-  const mins = Math.floor(ms / 6e4);
-  if (mins < 60) return `${mins}m`;
-  const h = Math.floor(mins / 60);
-  const m = mins % 60;
-  return `${h}h${m > 0 ? String(m).padStart(2, "0") : ""}`;
+function timeSince(iso) {
+  const ms = Date.now() - (/* @__PURE__ */ new Date(iso + "Z")).getTime();
+  const m = Math.floor(ms / 6e4);
+  if (m < 60) return `${m}m`;
+  const h = Math.floor(m / 60);
+  return `${h}h${m % 60 > 0 ? String(m % 60).padStart(2, "0") : ""}`;
 }
-async function statusCommand() {
-  const db = await openDb();
-  const projectName = process.cwd().split("/").pop() ?? "unknown";
-  const features = query(
-    db,
-    `SELECT
-       f.id, f.name, f.status, f.priority,
-       f.description, f.progress_done, f.progress_total, f.items,
-       c.session_id  AS claimed_session,
-       c.claimed_at  AS claimed_at
-     FROM features f
-     LEFT JOIN claims c
-       ON c.feature_id = f.id AND c.released_at IS NULL
-     ORDER BY
-       CASE f.status
-         WHEN 'in_progress' THEN 0
-         WHEN 'blocked'     THEN 1
-         WHEN 'pending'     THEN 2
-         WHEN 'done'        THEN 3
-       END,
-       CASE f.priority
-         WHEN 'critical' THEN 0
-         WHEN 'high'     THEN 1
-         WHEN 'medium'   THEN 2
-         WHEN 'low'      THEN 3
-       END,
-       f.created_at`
+function renderGroupSummary(features, groups, sessionCount, projectName) {
+  const total = features.length;
+  const done = features.filter((f) => f.status === "done").length;
+  const pct = total > 0 ? Math.round(done / total * 100) : 0;
+  console.log("");
+  console.log(
+    chalk3.bold(`  ${projectName} \u2014 ${pct}% implemented`) + chalk3.gray(` (${sessionCount} session${sessionCount !== 1 ? "s" : ""})`)
   );
-  const sessionCount = queryOne(
-    db,
-    "SELECT COUNT(*) as count FROM sessions"
-  )?.count ?? 0;
-  closeDb();
   console.log("");
-  if (features.length === 0) {
-    console.log(chalk3.bold(`  ${projectName} \u2014 no features tracked yet
-`));
-    console.log(chalk3.gray("  Add features with: groundctl add feature -n 'my-feature'"));
-    console.log(chalk3.gray("  Then run: groundctl status\n"));
-    return;
+  const maxLabelW = Math.max(...groups.map((g) => g.label.length), 14);
+  for (const grp of groups) {
+    const gFeatures = features.filter((f) => f.group_id === grp.id);
+    if (gFeatures.length === 0) continue;
+    const gDone = gFeatures.filter((f) => f.status === "done").length;
+    const gActive = gFeatures.filter((f) => f.status === "in_progress").length;
+    const bar2 = progressBar(gDone, gFeatures.length, GRP_BAR_W);
+    const frac = chalk3.white(`  ${gDone}/${gFeatures.length} done`);
+    const inProg = gActive > 0 ? chalk3.yellow(`  ${gActive} active`) : "";
+    const label = grp.label.padEnd(maxLabelW);
+    console.log(`  ${chalk3.bold(label)}  ${bar2}${frac}${inProg}`);
+  }
+  const ungrouped = features.filter((f) => f.group_id == null);
+  if (ungrouped.length > 0) {
+    const uDone = ungrouped.filter((f) => f.status === "done").length;
+    const bar2 = progressBar(uDone, ungrouped.length, GRP_BAR_W);
+    const label = "Other".padEnd(maxLabelW);
+    console.log(`  ${chalk3.gray(label)}  ${bar2}  ${chalk3.gray(`${uDone}/${ungrouped.length} done`)}`);
   }
+  console.log("");
+  const claimed = features.filter((f) => f.status === "in_progress" && f.claimed_session);
+  if (claimed.length > 0) {
+    console.log(chalk3.bold("  Claimed:"));
+    for (const f of claimed) {
+      const grpLabel = f.group_label ? chalk3.gray(` (${f.group_label})`) : "";
+      const elapsed = f.claimed_at ? timeSince(f.claimed_at) : "";
+      console.log(chalk3.yellow(`    \u25CF ${f.name}${grpLabel} \u2192 ${f.claimed_session}${elapsed ? ` (${elapsed})` : ""}`));
+    }
+    console.log("");
+  }
+  const next = features.find((f) => f.status === "pending" && !f.claimed_session);
+  if (next) {
+    const grpLabel = next.group_label ? chalk3.gray(` (${next.group_label})`) : "";
+    console.log(chalk3.bold("  Next:    ") + chalk3.white(`${next.name}${grpLabel}`));
+    console.log("");
+  }
+}
+function renderDetail(features, groups, sessionCount, projectName) {
+  const total = features.length;
+  const done = features.filter((f) => f.status === "done").length;
+  const pct = Math.round(done / total * 100);
+  console.log("");
+  console.log(
+    chalk3.bold(`  ${projectName} \u2014 ${pct}% implemented`) + chalk3.gray(` (${sessionCount} session${sessionCount !== 1 ? "s" : ""})`)
+  );
+  console.log("");
+  console.log(`  Features  ${progressBar(done, total, AGG_BAR_W)}  ${done}/${total} done`);
+  console.log("");
+  const nameW = Math.min(NAME_W, Math.max(12, ...features.map((f) => f.name.length)));
+  const contIndent = " ".repeat(4 + nameW + 1);
+  const itemsMaxW = Math.max(40, 76 - contIndent.length);
+  const renderFeature = (f, indent = "  ") => {
+    const isDone = f.status === "done";
+    const isActive = f.status === "in_progress";
+    const isBlocked = f.status === "blocked";
+    const icon = isDone ? "\u2713" : isActive ? "\u25CF" : isBlocked ? "\u2717" : "\u25CB";
+    const iconCh = isDone ? chalk3.green : isActive ? chalk3.yellow : isBlocked ? chalk3.red : chalk3.gray;
+    const nameCh = isDone ? chalk3.dim : isActive ? chalk3.white : isBlocked ? chalk3.red : chalk3.gray;
+    const nameRaw = f.name.slice(0, nameW).padEnd(nameW);
+    const bar2 = featureBar(f.status, f.progress_done ?? null, f.progress_total ?? null);
+    const prog = (f.progress_done != null ? `${f.progress_done}/${f.progress_total}` : "").padEnd(PROG_W);
+    const descRaw = f.description ?? "";
+    const descStr = descRaw ? chalk3.gray(`  ${descRaw.length > 38 ? descRaw.slice(0, 36) + "\u2026" : descRaw}`) : "";
+    let claimed = "";
+    if (isActive && f.claimed_session) {
+      const el = f.claimed_at ? timeSince(f.claimed_at) : "";
+      claimed = chalk3.yellow(` \u2192 ${f.claimed_session}${el ? ` (${el})` : ""}`);
+    }
+    process.stdout.write(`${indent}${iconCh(icon)} ${nameCh(nameRaw)} ${bar2}  ${prog}${descStr}${claimed}
+`);
+    if (f.items) {
+      for (const line of wrapItems(f.items, itemsMaxW)) {
+        console.log(chalk3.dim(`${indent}  ${" ".repeat(nameW + 2)}${line}`));
+      }
+    }
+  };
+  for (const grp of groups) {
+    const gFeatures = features.filter((f) => f.group_id === grp.id);
+    if (gFeatures.length === 0) continue;
+    const gDone = gFeatures.filter((f) => f.status === "done").length;
+    const gActive = gFeatures.filter((f) => f.status === "in_progress").length;
+    const bar2 = progressBar(gDone, gFeatures.length, GRP_BAR_W);
+    const inProg = gActive > 0 ? chalk3.yellow(`  ${gActive} active`) : "";
+    console.log(
+      chalk3.bold.white(`  ${grp.label.toUpperCase().padEnd(NAME_W + 1)} `) + `${bar2}  ${gDone}/${gFeatures.length} done${inProg}`
+    );
+    for (const f of gFeatures) renderFeature(f, "    ");
+    console.log("");
+  }
+  const ungrouped = features.filter((f) => f.group_id == null);
+  if (ungrouped.length > 0) {
+    console.log(chalk3.bold.gray("  OTHER"));
+    for (const f of ungrouped) renderFeature(f, "    ");
+    console.log("");
+  }
+}
+function renderFlat(features, sessionCount, projectName) {
   const total = features.length;
   const done = features.filter((f) => f.status === "done").length;
   const inProg = features.filter((f) => f.status === "in_progress").length;
   const blocked = features.filter((f) => f.status === "blocked").length;
   const pct = Math.round(done / total * 100);
+  console.log("");
   console.log(
     chalk3.bold(`  ${projectName} \u2014 ${pct}% implemented`) + chalk3.gray(` (${sessionCount} session${sessionCount !== 1 ? "s" : ""})`)
   );
   console.log("");
-  const aggBar = progressBar(done, total, 20);
   let aggSuffix = chalk3.white(`  ${done}/${total} done`);
   if (inProg > 0) aggSuffix += chalk3.yellow(`  ${inProg} in progress`);
   if (blocked > 0) aggSuffix += chalk3.red(`  ${blocked} blocked`);
-  console.log(`  Features  ${aggBar}${aggSuffix}`);
+  console.log(`  Features  ${progressBar(done, total, AGG_BAR_W)}${aggSuffix}`);
   console.log("");
-  const maxNameLen = Math.min(NAME_W, Math.max(...features.map((f) => f.name.length)));
-  const nameW = Math.max(maxNameLen, 12);
+  const nameW = Math.min(NAME_W, Math.max(12, ...features.map((f) => f.name.length)));
   const contIndent = " ".repeat(4 + nameW + 1);
   const itemsMaxW = Math.max(40, 76 - contIndent.length);
   for (const f of features) {
@@ -975,33 +1164,84 @@ async function statusCommand() {
     const isActive = f.status === "in_progress";
     const isBlocked = f.status === "blocked";
     const icon = isDone ? "\u2713" : isActive ? "\u25CF" : isBlocked ? "\u2717" : "\u25CB";
-    const iconChalk = isDone ? chalk3.green : isActive ? chalk3.yellow : isBlocked ? chalk3.red : chalk3.gray;
+    const iconCh = isDone ? chalk3.green : isActive ? chalk3.yellow : isBlocked ? chalk3.red : chalk3.gray;
+    const nameCh = isDone ? chalk3.dim : isActive ? chalk3.white : isBlocked ? chalk3.red : chalk3.gray;
     const nameRaw = f.name.slice(0, nameW).padEnd(nameW);
-    const nameChalk = isDone ? chalk3.dim : isActive ? chalk3.white : isBlocked ? chalk3.red : chalk3.gray;
-    const pd = f.progress_done ?? null;
-    const pt = f.progress_total ?? null;
-    const bar2 = featureBar(f.status, pd, pt);
-    const prog = featureProgress(pd, pt).padEnd(PROG_W);
-    const descRaw = f.description ?? "";
-    const descTrunc = descRaw.length > 38 ? descRaw.slice(0, 36) + "\u2026" : descRaw;
-    const descStr = descTrunc ? chalk3.gray(`  ${descTrunc}`) : "";
-    let claimedStr = "";
+    const bar2 = featureBar(f.status, f.progress_done ?? null, f.progress_total ?? null);
+    const prog = (f.progress_done != null ? `${f.progress_done}/${f.progress_total}` : "").padEnd(PROG_W);
+    const desc = (f.description ?? "").slice(0, 38);
+    const descStr = desc ? chalk3.gray(`  ${desc.length < (f.description?.length ?? 0) ? desc + "\u2026" : desc}`) : "";
+    let claimed = "";
     if (isActive && f.claimed_session) {
-      const elapsed = f.claimed_at ? timeSince(f.claimed_at) : "";
-      claimedStr = chalk3.yellow(` \u2192 ${f.claimed_session}${elapsed ? ` (${elapsed})` : ""}`);
+      const el = f.claimed_at ? timeSince(f.claimed_at) : "";
+      claimed = chalk3.yellow(` \u2192 ${f.claimed_session}${el ? ` (${el})` : ""}`);
     }
-    console.log(
-      `  ${iconChalk(icon)} ${nameChalk(nameRaw)} ${bar2}  ${prog}${descStr}${claimedStr}`
-    );
+    console.log(`  ${iconCh(icon)} ${nameCh(nameRaw)} ${bar2}  ${prog}${descStr}${claimed}`);
     if (f.items) {
-      const lines = wrapItems(f.items, itemsMaxW);
-      for (const line of lines) {
+      for (const line of wrapItems(f.items, itemsMaxW)) {
         console.log(chalk3.dim(`${contIndent}${line}`));
       }
     }
   }
   console.log("");
 }
+async function statusCommand(opts) {
+  const db = await openDb();
+  const projectName = process.cwd().split("/").pop() ?? "unknown";
+  const features = query(
+    db,
+    `SELECT
+       f.id, f.name, f.status, f.priority,
+       f.description, f.progress_done, f.progress_total, f.items,
+       f.group_id,
+       g.name  AS group_name,
+       g.label AS group_label,
+       g.order_index AS group_order,
+       c.session_id AS claimed_session,
+       c.claimed_at AS claimed_at
+     FROM features f
+     LEFT JOIN feature_groups g ON f.group_id = g.id
+     LEFT JOIN claims c ON c.feature_id = f.id AND c.released_at IS NULL
+     ORDER BY
+       COALESCE(g.order_index, 9999),
+       CASE f.status
+         WHEN 'in_progress' THEN 0
+         WHEN 'blocked'     THEN 1
+         WHEN 'pending'     THEN 2
+         WHEN 'done'        THEN 3
+       END,
+       CASE f.priority
+         WHEN 'critical' THEN 0 WHEN 'high' THEN 1
+         WHEN 'medium'   THEN 2 WHEN 'low'  THEN 3
+       END,
+       f.created_at`
+  );
+  const groups = query(
+    db,
+    "SELECT id, name, label, order_index FROM feature_groups ORDER BY order_index"
+  );
+  const sessionCount = queryOne(
+    db,
+    "SELECT COUNT(*) as count FROM sessions"
+  )?.count ?? 0;
+  closeDb();
+  if (features.length === 0) {
+    console.log("");
+    console.log(chalk3.bold(`  ${projectName} \u2014 no features tracked yet
+`));
+    console.log(chalk3.gray("  Add features: groundctl add feature -n 'my-feature'"));
+    console.log(chalk3.gray("  Add groups:   groundctl add group -n 'core' --label 'Core'\n"));
+    return;
+  }
+  const hasGroups = groups.length > 0 && features.some((f) => f.group_id != null);
+  if (opts?.detail || opts?.all) {
+    renderDetail(features, groups, sessionCount, projectName);
+  } else if (hasGroups) {
+    renderGroupSummary(features, groups, sessionCount, projectName);
+  } else {
+    renderFlat(features, sessionCount, projectName);
+  }
+}
 
 // src/commands/claim.ts
 import chalk4 from "chalk";
@@ -1300,9 +1540,7 @@ async function addCommand(type, options) {
       if (p) {
         progressDone = p.done;
         progressTotal = p.total;
-      } else {
-        console.log(chalk8.yellow(`  \u26A0  --progress "${options.progress}" ignored (expected N/N format)`));
-      }
+      } else console.log(chalk8.yellow(`  \u26A0  --progress "${options.progress}" ignored (expected N/N format)`));
     }
     const items = options.items ? options.items.split(",").map((s) => s.trim()).filter(Boolean).join(",") : null;
     db.run(
@@ -1327,6 +1565,36 @@ async function addCommand(type, options) {
     const suffix = extras.length ? chalk8.gray(` \u2014 ${extras.join(", ")}`) : "";
     console.log(chalk8.green(`
   \u2713 Feature added: ${options.name} (${priority})${suffix}
+`));
+  } else if (type === "group") {
+    if (!options.name) {
+      console.log(chalk8.red("\n  --name is required for groups.\n"));
+      closeDb();
+      process.exit(1);
+    }
+    if (!options.label) {
+      console.log(chalk8.red("\n  --label is required for groups (display name).\n"));
+      closeDb();
+      process.exit(1);
+    }
+    const name = options.name.toLowerCase().replace(/[^a-z0-9-]+/g, "-").replace(/^-|-$/g, "");
+    const maxOrder = queryOne(db, "SELECT COALESCE(MAX(order_index),0) as m FROM feature_groups")?.m ?? 0;
+    const exists = queryOne(db, "SELECT id FROM feature_groups WHERE name = ?", [name]);
+    if (exists) {
+      console.log(chalk8.yellow(`
+  Group "${name}" already exists.
+`));
+      closeDb();
+      return;
+    }
+    db.run(
+      "INSERT INTO feature_groups (name, label, order_index) VALUES (?, ?, ?)",
+      [name, options.label, maxOrder + 1]
+    );
+    saveDb();
+    closeDb();
+    console.log(chalk8.green(`
+  \u2713 Group added: ${options.label} (${name})
 `));
   } else if (type === "session") {
     const id = options.name ?? randomUUID2().slice(0, 8);
@@ -1339,7 +1607,7 @@ async function addCommand(type, options) {
 `));
   } else {
     console.log(chalk8.red(`
-  Unknown type "${type}". Use "feature" or "session".
+  Unknown type "${type}". Use "feature", "group", or "session".
 `));
     closeDb();
     process.exit(1);
@@ -1349,7 +1617,7 @@ async function addCommand(type, options) {
 // src/commands/ingest.ts
 import { existsSync as existsSync4, readdirSync } from "fs";
 import { join as join5, resolve } from "path";
-import { homedir as homedir2 } from "os";
+import { homedir as homedir3 } from "os";
 import chalk9 from "chalk";
 
 // src/ingest/claude-parser.ts
@@ -1585,7 +1853,7 @@ function claudeEncode(p) {
   return p.replace(/[^a-zA-Z0-9]/g, "-");
 }
 function findLatestTranscript(projectPath) {
-  const projectsDir = join5(homedir2(), ".claude", "projects");
+  const projectsDir = join5(homedir3(), ".claude", "projects");
   if (!existsSync4(projectsDir)) return null;
   let transcriptDir = null;
   const projectKey = claudeEncode(projectPath);
@@ -2163,8 +2431,8 @@ import {
   watch as fsWatch
 } from "fs";
 import { join as join8, resolve as resolve2 } from "path";
-import { homedir as homedir3 } from "os";
-import { spawn } from "child_process";
+import { homedir as homedir4 } from "os";
+import { spawn as spawn2 } from "child_process";
 import chalk13 from "chalk";
 var DEBOUNCE_MS = 8e3;
 var DIR_POLL_MS = 5e3;
@@ -2172,7 +2440,7 @@ function claudeEncode2(p) {
   return p.replace(/[^a-zA-Z0-9]/g, "-");
 }
 function findTranscriptDir(projectPath) {
-  const projectsDir = join8(homedir3(), ".claude", "projects");
+  const projectsDir = join8(homedir4(), ".claude", "projects");
   if (!existsSync6(projectsDir)) return null;
   const projectKey = claudeEncode2(projectPath);
   const direct = join8(projectsDir, projectKey);
@@ -2331,7 +2599,7 @@ function startWatcher(transcriptDir, projectPath) {
   });
   console.log(chalk13.bold("\n  groundctl watch") + chalk13.gray(" \u2014 auto-ingest on session end\n"));
   console.log(
-    chalk13.gray("  Watching: ") + chalk13.blue(transcriptDir.replace(homedir3(), "~"))
+    chalk13.gray("  Watching: ") + chalk13.blue(transcriptDir.replace(homedir4(), "~"))
   );
   console.log(chalk13.gray("  Stability threshold: ") + chalk13.white(`${DEBOUNCE_MS / 1e3}s`));
   console.log(chalk13.gray("  Press Ctrl+C to stop.\n"));
@@ -2340,7 +2608,7 @@ async function watchCommand(options) {
   const projectPath = options.projectPath ? resolve2(options.projectPath) : process.cwd();
   if (options.daemon) {
     const args = [process.argv[1], "watch", "--project-path", projectPath];
-    const child = spawn(process.execPath, args, {
+    const child = spawn2(process.execPath, args, {
       detached: true,
       stdio: "ignore"
     });
@@ -2453,6 +2721,29 @@ async function updateCommand(type, nameOrId, options) {
     sets.push("status = ?");
     params.push(options.status);
   }
+  if (options.group !== void 0) {
+    if (options.group === "" || options.group === "none") {
+      sets.push("group_id = ?");
+      params.push(null);
+    } else {
+      const slug = options.group.toLowerCase().replace(/[^a-z0-9-]+/g, "-").replace(/^-|-$/g, "");
+      const grp = queryOne(
+        db,
+        "SELECT id, label FROM feature_groups WHERE name = ? OR label = ? LIMIT 1",
+        [slug, options.group]
+      );
+      if (!grp) {
+        console.log(chalk14.red(`
+  Group "${options.group}" not found. Create it first:
+  groundctl add group -n "${slug}" --label "${options.group}"
+`));
+        closeDb();
+        process.exit(1);
+      }
+      sets.push("group_id = ?");
+      params.push(grp.id);
+    }
+  }
   if (sets.length === 0) {
     console.log(chalk14.yellow("\n  Nothing to update \u2014 pass at least one option.\n"));
     closeDb();
@@ -2469,19 +2760,167 @@ async function updateCommand(type, nameOrId, options) {
   console.log(chalk14.green(`  \u2713 Updated: ${feature.name}`));
 }
 
-// src/index.ts
+// src/commands/doctor.ts
+import { existsSync as existsSync7, readFileSync as readFileSync7 } from "fs";
+import { join as join9 } from "path";
+import { homedir as homedir5 } from "os";
+import { createRequire } from "module";
+import { request as httpsRequest2 } from "https";
+import chalk15 from "chalk";
 var require2 = createRequire(import.meta.url);
 var pkg = require2("../package.json");
+var LAUNCH_AGENT_PLIST = join9(homedir5(), "Library", "LaunchAgents", "org.groundctl.watch.plist");
+function ok(msg) {
+  console.log(chalk15.green("  \u2713 ") + msg);
+}
+function warn(msg) {
+  console.log(chalk15.yellow("  \u26A0  ") + msg);
+}
+function info(msg) {
+  console.log(chalk15.gray("    " + msg));
+}
+function processAlive2(pid) {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch {
+    return false;
+  }
+}
+function getWatchPid(projectPath) {
+  try {
+    const raw = readFileSync7(join9(projectPath, ".groundctl", "watch.pid"), "utf8").trim();
+    return parseInt(raw) || null;
+  } catch {
+    return null;
+  }
+}
+function httpsGet(url, timeoutMs = 5e3) {
+  return new Promise((resolve3) => {
+    const req = httpsRequest2(url, { method: "HEAD" }, (res) => {
+      resolve3(res.statusCode ?? 0);
+    });
+    req.setTimeout(timeoutMs, () => {
+      req.destroy();
+      resolve3(0);
+    });
+    req.on("error", () => resolve3(0));
+    req.end();
+  });
+}
+function fetchNpmVersion(pkgName) {
+  return new Promise((resolve3) => {
+    const url = `https://registry.npmjs.org/${encodeURIComponent(pkgName)}/latest`;
+    const req = httpsRequest2(url, { headers: { accept: "application/json" } }, (res) => {
+      let data = "";
+      res.on("data", (c) => {
+        data += c.toString();
+      });
+      res.on("end", () => {
+        try {
+          const obj = JSON.parse(data);
+          resolve3(obj.version ?? null);
+        } catch {
+          resolve3(null);
+        }
+      });
+    });
+    req.setTimeout(8e3, () => {
+      req.destroy();
+      resolve3(null);
+    });
+    req.on("error", () => resolve3(null));
+    req.end();
+  });
+}
+function compareVersions(a, b) {
+  const pa = a.split(".").map(Number);
+  const pb = b.split(".").map(Number);
+  for (let i = 0; i < 3; i++) {
+    const diff = (pa[i] ?? 0) - (pb[i] ?? 0);
+    if (diff !== 0) return diff;
+  }
+  return 0;
+}
+async function doctorCommand() {
+  const cwd = process.cwd();
+  const current = pkg.version;
+  console.log(chalk15.bold("\n  groundctl doctor\n"));
+  const [latest, proxyStatus] = await Promise.all([
+    fetchNpmVersion("groundctl"),
+    httpsGet("https://detect.groundctl.org/health")
+  ]);
+  if (!latest) {
+    warn(`Version: ${current} (could not reach npm registry)`);
+  } else if (compareVersions(current, latest) < 0) {
+    warn(`Version: ${current} \u2014 update available: ${chalk15.cyan(latest)}`);
+    info(`npm install -g groundctl@latest`);
+  } else {
+    ok(`Version: ${current} (up to date)`);
+  }
+  const pid = getWatchPid(cwd);
+  if (!pid) {
+    warn("Watch daemon: not started");
+    info("groundctl watch --daemon");
+  } else if (!processAlive2(pid)) {
+    warn(`Watch daemon: PID ${pid} is no longer running`);
+    info("groundctl watch --daemon");
+  } else {
+    ok(`Watch daemon: running (PID ${pid})`);
+  }
+  if (proxyStatus === 200) {
+    ok("detect.groundctl.org: reachable");
+  } else if (proxyStatus === 0) {
+    warn("detect.groundctl.org: unreachable (no internet or proxy down)");
+    info("Feature detection will fall back to ANTHROPIC_API_KEY or heuristic");
+  } else {
+    warn(`detect.groundctl.org: HTTP ${proxyStatus}`);
+  }
+  const groundctlDir = join9(cwd, ".groundctl");
+  if (!existsSync7(groundctlDir)) {
+    warn("Not initialized in this directory \u2014 run: groundctl init");
+  } else {
+    const db = await openDb();
+    const groupCount = queryOne(db, "SELECT COUNT(*) as n FROM feature_groups")?.n ?? 0;
+    const featureCount = queryOne(db, "SELECT COUNT(*) as n FROM features")?.n ?? 0;
+    closeDb();
+    if (featureCount === 0) {
+      warn("No features tracked \u2014 run: groundctl init --import-from-git");
+    } else {
+      ok(`Features: ${featureCount} tracked`);
+    }
+    if (groupCount === 0) {
+      warn("No feature groups configured");
+      info(`groundctl add group -n "core" --label "Core"`);
+    } else {
+      ok(`Feature groups: ${groupCount} configured`);
+    }
+  }
+  if (process.platform === "darwin") {
+    if (existsSync7(LAUNCH_AGENT_PLIST)) {
+      ok(`LaunchAgent: installed (${LAUNCH_AGENT_PLIST.replace(homedir5(), "~")})`);
+    } else {
+      warn("LaunchAgent: not installed (watch won't auto-start on login)");
+      info("Re-run: groundctl init   to install");
+    }
+  }
+  console.log("");
+}
+
+// src/index.ts
+import chalk16 from "chalk";
+var require3 = createRequire2(import.meta.url);
+var pkg2 = require3("../package.json");
 var program = new Command();
-program.name("groundctl").description("The shared memory your agents and you actually need.").version(pkg.version);
+program.name("groundctl").description("The shared memory your agents and you actually need.").version(pkg2.version);
 program.command("init").description("Setup hooks + initial state for the current project").option("--import-from-git", "Bootstrap sessions and features from git history").action((opts) => initCommand({ importFromGit: opts.importFromGit }));
-program.command("status").description("Show macro view of the product state").action(statusCommand);
+program.command("status").description("Show macro view of the product state").option("--detail", "Show full feature list with progress bars").option("--all", "Alias for --detail").action((opts) => statusCommand({ detail: opts.detail, all: opts.all }));
 program.command("claim <feature>").description("Reserve a feature for the current session").option("-s, --session <id>", "Session ID (auto-generated if omitted)").action(claimCommand);
 program.command("complete <feature>").description("Mark a feature as done and release the claim").action(completeCommand);
 program.command("sync").description("Regenerate PROJECT_STATE.md and AGENTS.md from SQLite").action(syncCommand);
 program.command("next").description("Show next available (unclaimed) feature").action(nextCommand);
 program.command("log").description("Show session timeline").option("-s, --session <id>", "Show details for a specific session").action(logCommand);
-program.command("add <type>").description("Add a feature or session (type: feature, session)").option("-n, --name <name>", "Name").option("-p, --priority <priority>", "Priority (critical, high, medium, low)").option("-d, --description <desc>", "Description").option("--agent <agent>", "Agent type for sessions").option("--items <items>", "Comma-separated list of sub-items (features only)").option("--progress <N/N>", "Progress fraction e.g. 11/11 (features only)").action(addCommand);
+program.command("add <type>").description("Add a feature, group, or session (type: feature, group, session)").option("-n, --name <name>", "Name").option("-p, --priority <priority>", "Priority (critical, high, medium, low)").option("-d, --description <desc>", "Description").option("--agent <agent>", "Agent type for sessions").option("--items <items>", "Comma-separated list of sub-items (features only)").option("--progress <N/N>", "Progress fraction e.g. 11/11 (features only)").option("--label <label>", "Display label for groups").action(addCommand);
 program.command("ingest").description("Parse a transcript and write session data to SQLite").option("--source <source>", "Source agent (claude-code, codex)", "claude-code").option("--session-id <id>", "Session ID").option("--transcript <path>", "Path to transcript JSONL file (auto-detected if omitted)").option("--project-path <path>", "Project path (defaults to cwd)").option("--no-sync", "Skip regenerating markdown after ingest").action(
   (opts) => ingestCommand({
     source: opts.source,
@@ -2500,13 +2939,24 @@ program.command("watch").description("Watch for session end and auto-ingest tran
     projectPath: opts.projectPath
   })
 );
-program.command("update <type> <name>").description("Update a feature's description, items, progress, or priority").option("-d, --description <desc>", "New description").option("--items <items>", "Comma-separated sub-items").option("--progress <N/N>", "Progress fraction e.g. 3/5").option("-p, --priority <priority>", "New priority").option("--status <status>", "New status (pending|in_progress|done|blocked)").action(
+program.command("update <type> <name>").description("Update a feature's fields (type: feature)").option("-d, --description <desc>", "New description").option("--items <items>", "Comma-separated sub-items").option("--progress <N/N>", "Progress fraction e.g. 3/5").option("-p, --priority <priority>", "New priority").option("--status <status>", "New status (pending|in_progress|done|blocked)").option("--group <group>", 'Assign to group by name or label (use "none" to ungroup)').action(
   (type, name, opts) => updateCommand(type, name, {
     description: opts.description,
     items: opts.items,
     progress: opts.progress,
     priority: opts.priority,
-    status: opts.status
+    status: opts.status,
+    group: opts.group
   })
 );
+program.command("doctor").description("Check groundctl health: version, daemon, proxy, groups").action(doctorCommand);
+program.on("command:*", (operands) => {
+  const unknown = operands[0];
+  console.error(chalk16.red(`
+  Unknown command: ${unknown}
+`));
+  console.error(`  Run ${chalk16.cyan("groundctl --help")} to see available commands.
+`);
+  process.exit(1);
+});
 program.parse();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@groundctl/cli",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "Always know what to build next.",
   "license": "MIT",
   "bin": {