@groundctl/cli 0.3.2 → 0.5.0

package/dist/index.js

@@ -2,12 +2,15 @@
 
 // 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 writeFileSync2, chmodSync, readFileSync as readFileSync3, appendFileSync } from "fs";
+import { existsSync as existsSync3, mkdirSync as mkdirSync2, writeFileSync as writeFileSync3, chmodSync, readFileSync as readFileSync3, appendFileSync } from "fs";
 import { join as join3 } from "path";
-import chalk from "chalk";
+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
 import initSqlJs from "sql.js";
@@ -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)]
@@ -352,8 +364,6 @@ function generateAgentsMd(db, projectName) {
 
 // src/ingest/git-import.ts
 import { execSync } from "child_process";
-import { existsSync as existsSync2, readFileSync as readFileSync2 } from "fs";
-import { join as join2 } from "path";
 function run(cmd, cwd) {
   try {
     return execSync(cmd, { cwd, encoding: "utf-8", stdio: ["ignore", "pipe", "ignore"] });
@@ -409,67 +419,10 @@ function parseGitLog(cwd) {
   }
   return commits.reverse();
 }
-function parseProjectStateMd(content) {
-  const features = [];
-  const lines = content.split("\n");
-  let section = "";
-  for (const line of lines) {
-    const trimmed = line.trim();
-    if (trimmed.startsWith("## ")) {
-      section = trimmed.toLowerCase();
-      continue;
-    }
-    if (section.includes("decision") || section.includes("session") || section.includes("debt") || section.includes("note")) continue;
-    if (!trimmed.startsWith("- ") && !trimmed.startsWith("* ")) continue;
-    const item = trimmed.slice(2).trim();
-    if (!item || item.length < 3) continue;
-    const name = item.split("(")[0].split("\u2192")[0].split("\u2014")[0].trim();
-    if (!name || name.length < 3 || name.length > 80) continue;
-    if (/^\d{4}-\d{2}-\d{2}/.test(name)) continue;
-    if (name.split(" ").length > 8) continue;
-    let status = "pending";
-    let priority = "medium";
-    if (section.includes("built") || section.includes("done") || section.includes("complete")) {
-      status = "done";
-    } else if (section.includes("claimed") || section.includes("in progress") || section.includes("current")) {
-      status = "in_progress";
-    } else if (section.includes("available") || section.includes("next")) {
-      status = "pending";
-    } else if (section.includes("blocked")) {
-      status = "blocked";
-    }
-    if (/priority:\s*critical|critical\)/i.test(item)) priority = "critical";
-    else if (/priority:\s*high|high\)/i.test(item)) priority = "high";
-    else if (/priority:\s*low|low\)/i.test(item)) priority = "low";
-    features.push({ name, status, priority });
-  }
-  return features;
-}
-function featureIdFromName(name) {
-  return name.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-|-$/g, "").slice(0, 60);
-}
 function importFromGit(db, projectPath) {
   let sessionsCreated = 0;
-  let featuresImported = 0;
-  const psMdPath = join2(projectPath, "PROJECT_STATE.md");
-  if (existsSync2(psMdPath)) {
-    const content = readFileSync2(psMdPath, "utf-8");
-    const features = parseProjectStateMd(content);
-    for (const feat of features) {
-      const id = featureIdFromName(feat.name);
-      if (!id) continue;
-      const exists = queryOne(db, "SELECT id FROM features WHERE id = ?", [id]);
-      if (!exists) {
-        db.run(
-          "INSERT INTO features (id, name, status, priority) VALUES (?, ?, ?, ?)",
-          [id, feat.name, feat.status, feat.priority]
-        );
-        featuresImported++;
-      }
-    }
-  }
   const commits = parseGitLog(projectPath);
-  if (commits.length === 0) return { sessionsCreated, featuresImported };
+  if (commits.length === 0) return { sessionsCreated };
   const SESSION_GAP_MS = 4 * 60 * 60 * 1e3;
   const sessions = [];
   let currentSession = [];
@@ -523,7 +476,294 @@ function importFromGit(db, projectPath) {
     }
   }
   saveDb();
-  return { sessionsCreated, featuresImported };
+  return { sessionsCreated };
+}
+
+// src/ingest/feature-detector.ts
+import { existsSync as existsSync2, readFileSync as readFileSync2, writeFileSync as writeFileSync2 } from "fs";
+import { join as join2 } from "path";
+import { tmpdir } from "os";
+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"] });
+  } catch {
+    return "";
+  }
+}
+function collectContextParts(projectPath) {
+  const gitLog = run2("git log --oneline --no-merges", projectPath);
+  const fileTree = run2(
+    [
+      "find . -type f",
+      "-not -path '*/node_modules/*'",
+      "-not -path '*/.git/*'",
+      "-not -path '*/dist/*'",
+      "-not -path '*/.groundctl/*'",
+      "-not -path '*/build/*'",
+      "-not -path '*/coverage/*'",
+      "-not -path '*/.venv/*'",
+      "-not -path '*/__pycache__/*'",
+      "-not -path '*/.pytest_cache/*'",
+      "-not -path '*/vendor/*'",
+      "-not -path '*/.next/*'",
+      "-not -name '*.lock'",
+      "-not -name '*.log'",
+      "-not -name '*.pyc'",
+      "| sort | head -120"
+    ].join(" "),
+    projectPath
+  );
+  const readmePath = join2(projectPath, "README.md");
+  const readme = existsSync2(readmePath) ? readFileSync2(readmePath, "utf-8").slice(0, 3e3) : void 0;
+  const psPath = join2(projectPath, "PROJECT_STATE.md");
+  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]);
+  }
+  if (!Array.isArray(obj.features)) throw new Error("Response missing 'features' array");
+  return normaliseFeatures(obj.features);
+}
+function httpsPost(url, body, extraHeaders) {
+  return new Promise((resolve3, reject) => {
+    const bodyStr = JSON.stringify(body);
+    const parsed = new URL(url);
+    const req = httpsRequest(
+      {
+        hostname: parsed.hostname,
+        path: parsed.pathname + parsed.search,
+        method: "POST",
+        headers: {
+          "content-type": "application/json",
+          "content-length": Buffer.byteLength(bodyStr),
+          "user-agent": USER_AGENT,
+          ...extraHeaders
+        }
+      },
+      (res) => {
+        let data = "";
+        res.on("data", (c) => {
+          data += c.toString();
+        });
+        res.on("end", () => {
+          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(bodyStr);
+    req.end();
+  });
+}
+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);
+}
+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 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, (a) => {
+      rl.close();
+      resolve3(a.trim().toLowerCase());
+    });
+  });
+}
+async function editInEditor(features) {
+  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} "${tmp}"`, { stdio: "inherit" });
+  } catch {
+    return features;
+  }
+  try {
+    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'`);
+  for (const f of features) {
+    const status = f.status === "done" ? "done" : "pending";
+    if (!queryOne(db, "SELECT id FROM features WHERE id = ?", [f.name])) {
+      db.run(
+        "INSERT INTO features (id, name, status, priority, description) VALUES (?, ?, ?, ?, ?)",
+        [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, 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;
+  let features = [];
+  let source = "";
+  try {
+    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 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] "));
+    if (answer === "y" || answer === "yes") {
+      importFeatures(db, pending);
+      console.log(chalk.green(`
+  \u2713 ${pending.length} features imported
+`));
+      return true;
+    }
+    if (answer === "n" || answer === "no") {
+      console.log(chalk.gray("  Skipped.\n"));
+      return false;
+    }
+    if (answer === "e" || answer === "edit") {
+      const edited = await editInEditor(pending);
+      if (edited && edited.length > 0) {
+        pending = edited;
+        renderFeatureList(pending);
+      } else console.log(chalk.yellow("  No valid features after edit.\n"));
+      continue;
+    }
+    console.log(chalk.gray("  Please answer y, n, or edit."));
+  }
 }
 
 // src/commands/init.ts
@@ -560,56 +800,139 @@ 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";
-  console.log(chalk.bold(`
+  console.log(chalk2.bold(`
 groundctl init \u2014 ${projectName}
 `));
-  console.log(chalk.gray("  Creating SQLite database..."));
+  console.log(chalk2.gray("  Creating SQLite database..."));
   const db = await openDb();
   if (options.importFromGit) {
     const isGitRepo = existsSync3(join3(cwd, ".git"));
     if (!isGitRepo) {
-      console.log(chalk.yellow("  \u26A0 Not a git repo \u2014 skipping --import-from-git"));
+      console.log(chalk2.yellow("  \u26A0 Not a git repo \u2014 skipping --import-from-git"));
     } else {
-      console.log(chalk.gray("  Importing from git history..."));
+      console.log(chalk2.gray("  Importing sessions from git history..."));
       const result = importFromGit(db, cwd);
       console.log(
-        chalk.green(
-          `  \u2713 Git import: ${result.sessionsCreated} sessions, ${result.featuresImported} features`
-        )
+        chalk2.green(`  \u2713 Git import: ${result.sessionsCreated} sessions`)
       );
+      await detectAndImportFeatures(db, cwd);
     }
   }
   const projectState = generateProjectState(db, projectName);
   const agentsMd = generateAgentsMd(db, projectName);
   closeDb();
-  console.log(chalk.green("  \u2713 Database ready"));
+  console.log(chalk2.green("  \u2713 Database ready"));
   const claudeHooksDir = join3(cwd, ".claude", "hooks");
   if (!existsSync3(claudeHooksDir)) {
     mkdirSync2(claudeHooksDir, { recursive: true });
   }
-  writeFileSync2(join3(claudeHooksDir, "pre-session.sh"), PRE_SESSION_HOOK);
+  writeFileSync3(join3(claudeHooksDir, "pre-session.sh"), PRE_SESSION_HOOK);
   chmodSync(join3(claudeHooksDir, "pre-session.sh"), 493);
-  writeFileSync2(join3(claudeHooksDir, "post-session.sh"), POST_SESSION_HOOK);
+  writeFileSync3(join3(claudeHooksDir, "post-session.sh"), POST_SESSION_HOOK);
   chmodSync(join3(claudeHooksDir, "post-session.sh"), 493);
-  console.log(chalk.green("  \u2713 Claude Code hooks installed"));
+  console.log(chalk2.green("  \u2713 Claude Code hooks installed"));
   const codexHooksDir = join3(cwd, ".codex", "hooks");
   if (!existsSync3(codexHooksDir)) {
     mkdirSync2(codexHooksDir, { recursive: true });
   }
   const codexPre = PRE_SESSION_HOOK.replace("Claude Code", "Codex");
   const codexPost = POST_SESSION_HOOK.replace("Claude Code", "Codex").replace("claude-code", "codex");
-  writeFileSync2(join3(codexHooksDir, "pre-session.sh"), codexPre);
+  writeFileSync3(join3(codexHooksDir, "pre-session.sh"), codexPre);
   chmodSync(join3(codexHooksDir, "pre-session.sh"), 493);
-  writeFileSync2(join3(codexHooksDir, "post-session.sh"), codexPost);
+  writeFileSync3(join3(codexHooksDir, "post-session.sh"), codexPost);
   chmodSync(join3(codexHooksDir, "post-session.sh"), 493);
-  console.log(chalk.green("  \u2713 Codex hooks installed"));
-  writeFileSync2(join3(cwd, "PROJECT_STATE.md"), projectState);
-  writeFileSync2(join3(cwd, "AGENTS.md"), agentsMd);
-  console.log(chalk.green("  \u2713 PROJECT_STATE.md generated"));
-  console.log(chalk.green("  \u2713 AGENTS.md generated"));
+  console.log(chalk2.green("  \u2713 Codex hooks installed"));
+  writeFileSync3(join3(cwd, "PROJECT_STATE.md"), projectState);
+  writeFileSync3(join3(cwd, "AGENTS.md"), agentsMd);
+  console.log(chalk2.green("  \u2713 PROJECT_STATE.md generated"));
+  console.log(chalk2.green("  \u2713 AGENTS.md generated"));
   const gitignorePath = join3(cwd, ".gitignore");
   const gitignoreEntry = "\n# groundctl local state\n.groundctl/\n";
   if (existsSync3(gitignorePath)) {
@@ -618,80 +941,251 @@ groundctl init \u2014 ${projectName}
       appendFileSync(gitignorePath, gitignoreEntry);
     }
   }
-  console.log(chalk.bold.green(`
+  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}
 `));
   if (!options.importFromGit) {
-    console.log(chalk.gray("  Next steps:"));
-    console.log(chalk.gray("    groundctl add feature -n 'my-feature' -p high"));
-    console.log(chalk.gray("    groundctl status"));
-    console.log(chalk.gray("    groundctl claim my-feature"));
-    console.log(chalk.gray("\n  Or bootstrap from git history:"));
-    console.log(chalk.gray("    groundctl init --import-from-git\n"));
+    console.log(chalk2.gray("  Next steps:"));
+    console.log(chalk2.gray("    groundctl add feature -n 'my-feature' -p high"));
+    console.log(chalk2.gray("    groundctl status"));
+    console.log(chalk2.gray("    groundctl claim my-feature"));
+    console.log(chalk2.gray("\n  Or bootstrap from git history:"));
+    console.log(chalk2.gray("    groundctl init --import-from-git\n"));
   } else {
-    console.log(chalk.gray("  Next steps:"));
-    console.log(chalk.gray("    groundctl status"));
-    console.log(chalk.gray("    groundctl next\n"));
+    console.log(chalk2.gray("  Next steps:"));
+    console.log(chalk2.gray("    groundctl status"));
+    console.log(chalk2.gray("    groundctl next\n"));
   }
 }
 
 // src/commands/status.ts
-import chalk2 from "chalk";
-var BAR_W = 14;
+import chalk3 from "chalk";
+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) {
-  if (total <= 0) return chalk2.gray("\u2591".repeat(width));
+  if (total <= 0) return chalk3.gray("\u2591".repeat(width));
   const filled = Math.min(width, Math.round(done / total * width));
-  return chalk2.green("\u2588".repeat(filled)) + chalk2.gray("\u2591".repeat(width - filled));
+  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 chalk2.red("\u2591".repeat(BAR_W));
+      return chalk3.red("\u2591".repeat(width));
     default:
-      return chalk2.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() {
+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" : ""})`)
+  );
+  console.log("");
+  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("");
+  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  ${progressBar(done, total, AGG_BAR_W)}${aggSuffix}`);
+  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);
+  for (const f of features) {
+    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 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 el = f.claimed_at ? timeSince(f.claimed_at) : "";
+      claimed = chalk3.yellow(` \u2192 ${f.claimed_session}${el ? ` (${el})` : ""}`);
+    }
+    console.log(`  ${iconCh(icon)} ${nameCh(nameRaw)} ${bar2}  ${prog}${descStr}${claimed}`);
+    if (f.items) {
+      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(
@@ -699,12 +1193,17 @@ async function statusCommand() {
     `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
+       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 claims c
-       ON c.feature_id = f.id AND c.released_at IS NULL
+     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
@@ -712,80 +1211,40 @@ async function statusCommand() {
          WHEN 'done'        THEN 3
        END,
        CASE f.priority
-         WHEN 'critical' THEN 0
-         WHEN 'high'     THEN 1
-         WHEN 'medium'   THEN 2
-         WHEN 'low'      THEN 3
+         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();
-  console.log("");
   if (features.length === 0) {
-    console.log(chalk2.bold(`  ${projectName} \u2014 no features tracked yet
+    console.log("");
+    console.log(chalk3.bold(`  ${projectName} \u2014 no features tracked yet
 `));
-    console.log(chalk2.gray("  Add features with: groundctl add feature -n 'my-feature'"));
-    console.log(chalk2.gray("  Then run: groundctl status\n"));
+    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 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(
-    chalk2.bold(`  ${projectName} \u2014 ${pct}% implemented`) + chalk2.gray(` (${sessionCount} session${sessionCount !== 1 ? "s" : ""})`)
-  );
-  console.log("");
-  const aggBar = progressBar(done, total, 20);
-  let aggSuffix = chalk2.white(`  ${done}/${total} done`);
-  if (inProg > 0) aggSuffix += chalk2.yellow(`  ${inProg} in progress`);
-  if (blocked > 0) aggSuffix += chalk2.red(`  ${blocked} blocked`);
-  console.log(`  Features  ${aggBar}${aggSuffix}`);
-  console.log("");
-  const maxNameLen = Math.min(NAME_W, Math.max(...features.map((f) => f.name.length)));
-  const nameW = Math.max(maxNameLen, 12);
-  const contIndent = " ".repeat(4 + nameW + 1);
-  const itemsMaxW = Math.max(40, 76 - contIndent.length);
-  for (const f of features) {
-    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 iconChalk = isDone ? chalk2.green : isActive ? chalk2.yellow : isBlocked ? chalk2.red : chalk2.gray;
-    const nameRaw = f.name.slice(0, nameW).padEnd(nameW);
-    const nameChalk = isDone ? chalk2.dim : isActive ? chalk2.white : isBlocked ? chalk2.red : chalk2.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 ? chalk2.gray(`  ${descTrunc}`) : "";
-    let claimedStr = "";
-    if (isActive && f.claimed_session) {
-      const elapsed = f.claimed_at ? timeSince(f.claimed_at) : "";
-      claimedStr = chalk2.yellow(` \u2192 ${f.claimed_session}${elapsed ? ` (${elapsed})` : ""}`);
-    }
-    console.log(
-      `  ${iconChalk(icon)} ${nameChalk(nameRaw)} ${bar2}  ${prog}${descStr}${claimedStr}`
-    );
-    if (f.items) {
-      const lines = wrapItems(f.items, itemsMaxW);
-      for (const line of lines) {
-        console.log(chalk2.dim(`${contIndent}${line}`));
-      }
-    }
+  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);
   }
-  console.log("");
 }
 
 // src/commands/claim.ts
-import chalk3 from "chalk";
+import chalk4 from "chalk";
 import { randomUUID } from "crypto";
 function findFeature(db, term) {
   return queryOne(
@@ -822,15 +1281,15 @@ async function claimCommand(featureIdOrName, options) {
   const db = await openDb();
   const feature = findFeature(db, featureIdOrName);
   if (!feature) {
-    console.log(chalk3.red(`
+    console.log(chalk4.red(`
   Feature "${featureIdOrName}" not found.
 `));
-    console.log(chalk3.gray("  Add it with: groundctl add feature -n '" + featureIdOrName + "'"));
+    console.log(chalk4.gray("  Add it with: groundctl add feature -n '" + featureIdOrName + "'"));
     closeDb();
     process.exit(1);
   }
   if (feature.status === "done") {
-    console.log(chalk3.yellow(`
+    console.log(chalk4.yellow(`
   Feature "${feature.name}" is already done.
 `));
     closeDb();
@@ -844,7 +1303,7 @@ async function claimCommand(featureIdOrName, options) {
   );
   if (existingClaim) {
     console.log(
-      chalk3.red(`
+      chalk4.red(`
   Feature "${feature.name}" is already claimed by session ${existingClaim.session_id}`)
     );
     const alternatives = query(
@@ -859,9 +1318,9 @@ async function claimCommand(featureIdOrName, options) {
        LIMIT 3`
     );
     if (alternatives.length > 0) {
-      console.log(chalk3.gray("\n  Available instead:"));
+      console.log(chalk4.gray("\n  Available instead:"));
       for (const alt of alternatives) {
-        console.log(chalk3.gray(`    \u25CB ${alt.name}`));
+        console.log(chalk4.gray(`    \u25CB ${alt.name}`));
       }
     }
     console.log("");
@@ -891,7 +1350,7 @@ async function claimCommand(featureIdOrName, options) {
   saveDb();
   closeDb();
   console.log(
-    chalk3.green(`
+    chalk4.green(`
   \u2713 Claimed "${feature.name}" \u2192 session ${sessionId}
 `)
   );
@@ -900,7 +1359,7 @@ async function completeCommand(featureIdOrName) {
   const db = await openDb();
   const feature = findFeature(db, featureIdOrName);
   if (!feature) {
-    console.log(chalk3.red(`
+    console.log(chalk4.red(`
   Feature "${featureIdOrName}" not found.
 `));
     closeDb();
@@ -916,15 +1375,15 @@ async function completeCommand(featureIdOrName) {
   );
   saveDb();
   closeDb();
-  console.log(chalk3.green(`
+  console.log(chalk4.green(`
   \u2713 Completed "${feature.name}"
 `));
 }
 
 // src/commands/sync.ts
-import { writeFileSync as writeFileSync3 } from "fs";
+import { writeFileSync as writeFileSync4 } from "fs";
 import { join as join4 } from "path";
-import chalk4 from "chalk";
+import chalk5 from "chalk";
 async function syncCommand(opts) {
   const db = await openDb();
   const projectName = process.cwd().split("/").pop() ?? "unknown";
@@ -932,16 +1391,16 @@ async function syncCommand(opts) {
   const agentsMd = generateAgentsMd(db, projectName);
   closeDb();
   const cwd = process.cwd();
-  writeFileSync3(join4(cwd, "PROJECT_STATE.md"), projectState);
-  writeFileSync3(join4(cwd, "AGENTS.md"), agentsMd);
+  writeFileSync4(join4(cwd, "PROJECT_STATE.md"), projectState);
+  writeFileSync4(join4(cwd, "AGENTS.md"), agentsMd);
   if (!opts?.silent) {
-    console.log(chalk4.green("\n  \u2713 PROJECT_STATE.md regenerated"));
-    console.log(chalk4.green("  \u2713 AGENTS.md regenerated\n"));
+    console.log(chalk5.green("\n  \u2713 PROJECT_STATE.md regenerated"));
+    console.log(chalk5.green("  \u2713 AGENTS.md regenerated\n"));
   }
 }
 
 // src/commands/next.ts
-import chalk5 from "chalk";
+import chalk6 from "chalk";
 async function nextCommand() {
   const db = await openDb();
   const available = query(
@@ -961,26 +1420,26 @@ async function nextCommand() {
   );
   closeDb();
   if (available.length === 0) {
-    console.log(chalk5.yellow("\n  No available features to claim.\n"));
+    console.log(chalk6.yellow("\n  No available features to claim.\n"));
     return;
   }
-  console.log(chalk5.bold("\n  Next available features:\n"));
+  console.log(chalk6.bold("\n  Next available features:\n"));
   for (let i = 0; i < available.length; i++) {
     const feat = available[i];
-    const pColor = feat.priority === "critical" || feat.priority === "high" ? chalk5.red : chalk5.gray;
-    const marker = i === 0 ? chalk5.green("\u2192") : " ";
+    const pColor = feat.priority === "critical" || feat.priority === "high" ? chalk6.red : chalk6.gray;
+    const marker = i === 0 ? chalk6.green("\u2192") : " ";
     console.log(`  ${marker} ${feat.name} ${pColor(`(${feat.priority})`)}`);
     if (feat.description) {
-      console.log(chalk5.gray(`      ${feat.description}`));
+      console.log(chalk6.gray(`      ${feat.description}`));
     }
   }
-  console.log(chalk5.gray(`
+  console.log(chalk6.gray(`
   Claim with: groundctl claim "${available[0].name}"
 `));
 }
 
 // src/commands/log.ts
-import chalk6 from "chalk";
+import chalk7 from "chalk";
 async function logCommand(options) {
   const db = await openDb();
   if (options.session) {
@@ -989,18 +1448,18 @@ async function logCommand(options) {
       `%${options.session}%`
     ]);
     if (!session) {
-      console.log(chalk6.red(`
+      console.log(chalk7.red(`
   Session "${options.session}" not found.
 `));
       closeDb();
       return;
     }
-    console.log(chalk6.bold(`
+    console.log(chalk7.bold(`
   Session ${session.id}`));
-    console.log(chalk6.gray(`  Agent: ${session.agent}`));
-    console.log(chalk6.gray(`  Started: ${session.started_at}`));
+    console.log(chalk7.gray(`  Agent: ${session.agent}`));
+    console.log(chalk7.gray(`  Started: ${session.started_at}`));
     if (session.ended_at) {
-      console.log(chalk6.gray(`  Ended: ${session.ended_at}`));
+      console.log(chalk7.gray(`  Ended: ${session.ended_at}`));
     }
     if (session.summary) {
       console.log(`
@@ -1012,11 +1471,11 @@ async function logCommand(options) {
       [session.id]
     );
     if (decisions.length > 0) {
-      console.log(chalk6.bold("\n  Decisions:"));
+      console.log(chalk7.bold("\n  Decisions:"));
       for (const d of decisions) {
         console.log(`    \u2022 ${d.description}`);
         if (d.rationale) {
-          console.log(chalk6.gray(`      ${d.rationale}`));
+          console.log(chalk7.gray(`      ${d.rationale}`));
         }
       }
     }
@@ -1026,10 +1485,10 @@ async function logCommand(options) {
       [session.id]
     );
     if (files.length > 0) {
-      console.log(chalk6.bold(`
+      console.log(chalk7.bold(`
   Files modified (${files.length}):`));
       for (const f of files) {
-        const op = f.operation === "created" ? chalk6.green("+") : f.operation === "deleted" ? chalk6.red("-") : chalk6.yellow("~");
+        const op = f.operation === "created" ? chalk7.green("+") : f.operation === "deleted" ? chalk7.red("-") : chalk7.yellow("~");
         console.log(`    ${op} ${f.path} (${f.lines_changed} lines)`);
       }
     }
@@ -1037,18 +1496,18 @@ async function logCommand(options) {
   } else {
     const sessions = query(db, "SELECT * FROM sessions ORDER BY started_at DESC LIMIT 20");
     if (sessions.length === 0) {
-      console.log(chalk6.yellow("\n  No sessions recorded yet.\n"));
+      console.log(chalk7.yellow("\n  No sessions recorded yet.\n"));
       closeDb();
       return;
     }
-    console.log(chalk6.bold("\n  Session timeline:\n"));
+    console.log(chalk7.bold("\n  Session timeline:\n"));
     for (const s of sessions) {
-      const status = s.ended_at ? chalk6.green("done") : chalk6.yellow("active");
+      const status = s.ended_at ? chalk7.green("done") : chalk7.yellow("active");
       console.log(
-        `  ${chalk6.bold(s.id)}  ${chalk6.gray(s.started_at)}  ${status}  ${chalk6.gray(s.agent)}`
+        `  ${chalk7.bold(s.id)}  ${chalk7.gray(s.started_at)}  ${status}  ${chalk7.gray(s.agent)}`
       );
       if (s.summary) {
-        console.log(chalk6.gray(`    ${s.summary}`));
+        console.log(chalk7.gray(`    ${s.summary}`));
       }
     }
     console.log("");
@@ -1057,7 +1516,7 @@ async function logCommand(options) {
 }
 
 // src/commands/add.ts
-import chalk7 from "chalk";
+import chalk8 from "chalk";
 import { randomUUID as randomUUID2 } from "crypto";
 function parseProgress(s) {
   const m = s.match(/^(\d+)\/(\d+)$/);
@@ -1068,7 +1527,7 @@ async function addCommand(type, options) {
   const db = await openDb();
   if (type === "feature") {
     if (!options.name) {
-      console.log(chalk7.red("\n  --name is required for features.\n"));
+      console.log(chalk8.red("\n  --name is required for features.\n"));
       closeDb();
       process.exit(1);
     }
@@ -1081,9 +1540,7 @@ async function addCommand(type, options) {
       if (p) {
         progressDone = p.done;
         progressTotal = p.total;
-      } else {
-        console.log(chalk7.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(
@@ -1105,9 +1562,39 @@ async function addCommand(type, options) {
     const extras = [];
     if (progressDone !== null) extras.push(`${progressDone}/${progressTotal}`);
     if (items) extras.push(`${items.split(",").length} items`);
-    const suffix = extras.length ? chalk7.gray(` \u2014 ${extras.join(", ")}`) : "";
-    console.log(chalk7.green(`
+    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);
@@ -1115,12 +1602,12 @@ async function addCommand(type, options) {
     db.run("INSERT INTO sessions (id, agent) VALUES (?, ?)", [id, agent]);
     saveDb();
     closeDb();
-    console.log(chalk7.green(`
+    console.log(chalk8.green(`
   \u2713 Session created: ${id} (${agent})
 `));
   } else {
-    console.log(chalk7.red(`
-  Unknown type "${type}". Use "feature" or "session".
+    console.log(chalk8.red(`
+  Unknown type "${type}". Use "feature", "group", or "session".
 `));
     closeDb();
     process.exit(1);
@@ -1130,8 +1617,8 @@ 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 chalk8 from "chalk";
+import { homedir as homedir3 } from "os";
+import chalk9 from "chalk";
 
 // src/ingest/claude-parser.ts
 import { readFileSync as readFileSync4 } from "fs";
@@ -1366,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);
@@ -1401,11 +1888,11 @@ async function ingestCommand(options) {
     transcriptPath = findLatestTranscript(projectPath) ?? void 0;
   }
   if (!transcriptPath || !existsSync4(transcriptPath)) {
-    console.log(chalk8.yellow("\n  No transcript found. Skipping ingest.\n"));
+    console.log(chalk9.yellow("\n  No transcript found. Skipping ingest.\n"));
     if (!options.noSync) await syncCommand();
     return;
   }
-  console.log(chalk8.gray(`
+  console.log(chalk9.gray(`
   Parsing transcript: ${transcriptPath.split("/").slice(-2).join("/")}`));
   const parsed = parseTranscript(transcriptPath, options.sessionId ?? "auto", projectPath);
   const db = await openDb();
@@ -1455,16 +1942,16 @@ async function ingestCommand(options) {
   saveDb();
   closeDb();
   console.log(
-    chalk8.green(
+    chalk9.green(
       `  \u2713 Ingested session ${sessionId}: ${newFiles} files, ${parsed.commits.length} commits, ${newDecisions} decisions`
     )
   );
   if (parsed.decisions.length > 0 && newDecisions > 0) {
-    console.log(chalk8.gray(`
+    console.log(chalk9.gray(`
   Decisions captured:`));
     for (const d of parsed.decisions.slice(0, 5)) {
-      const conf = d.confidence === "low" ? chalk8.gray(" (low confidence)") : "";
-      console.log(chalk8.gray(`    \u2022 ${d.description.slice(0, 80)}${conf}`));
+      const conf = d.confidence === "low" ? chalk9.gray(" (low confidence)") : "";
+      console.log(chalk9.gray(`    \u2022 ${d.description.slice(0, 80)}${conf}`));
     }
   }
   if (!options.noSync) {
@@ -1474,9 +1961,9 @@ async function ingestCommand(options) {
 }
 
 // src/commands/report.ts
-import { writeFileSync as writeFileSync4 } from "fs";
+import { writeFileSync as writeFileSync5 } from "fs";
 import { join as join6 } from "path";
-import chalk9 from "chalk";
+import chalk10 from "chalk";
 function formatDuration(start, end) {
   if (!end) return "ongoing";
   const startMs = new Date(start).getTime();
@@ -1571,7 +2058,7 @@ async function reportCommand(options) {
       [options.session, `%${options.session}%`]
     );
     if (!s) {
-      console.log(chalk9.red(`
+      console.log(chalk10.red(`
   Session "${options.session}" not found.
 `));
       closeDb();
@@ -1584,7 +2071,7 @@ async function reportCommand(options) {
       "SELECT * FROM sessions ORDER BY started_at DESC LIMIT 1"
     );
     if (!s) {
-      console.log(chalk9.yellow("\n  No sessions found. Run groundctl init first.\n"));
+      console.log(chalk10.yellow("\n  No sessions found. Run groundctl init first.\n"));
       closeDb();
       return;
     }
@@ -1626,8 +2113,8 @@ async function reportCommand(options) {
     }
     closeDb();
     const outPath2 = join6(cwd, "SESSION_HISTORY.md");
-    writeFileSync4(outPath2, fullReport);
-    console.log(chalk9.green(`
+    writeFileSync5(outPath2, fullReport);
+    console.log(chalk10.green(`
   \u2713 SESSION_HISTORY.md written (${sessions.length} sessions)
 `));
     return;
@@ -1653,16 +2140,16 @@ async function reportCommand(options) {
     activeClaims
   );
   const outPath = join6(cwd, "SESSION_REPORT.md");
-  writeFileSync4(outPath, report);
-  console.log(chalk9.green(`
+  writeFileSync5(outPath, report);
+  console.log(chalk10.green(`
   \u2713 SESSION_REPORT.md written (session ${session.id})
 `));
-  console.log(chalk9.gray(`  ${files.length} files \xB7 ${decisions.length} arch log entries \xB7 ${completedFeatures.length} features completed`));
+  console.log(chalk10.gray(`  ${files.length} files \xB7 ${decisions.length} arch log entries \xB7 ${completedFeatures.length} features completed`));
   console.log("");
 }
 
 // src/commands/health.ts
-import chalk10 from "chalk";
+import chalk11 from "chalk";
 async function healthCommand() {
   const db = await openDb();
   const projectName = process.cwd().split("/").pop() ?? "unknown";
@@ -1713,32 +2200,32 @@ async function healthCommand() {
   closeDb();
   const totalScore = featureScore + testScore + decisionScore + claimScore + deployScore;
   console.log("");
-  console.log(chalk10.bold(`  ${projectName} \u2014 Health Score: ${totalScore}/100
+  console.log(chalk11.bold(`  ${projectName} \u2014 Health Score: ${totalScore}/100
 `));
-  const featureColor = featurePct >= 0.7 ? chalk10.green : featurePct >= 0.4 ? chalk10.yellow : chalk10.red;
+  const featureColor = featurePct >= 0.7 ? chalk11.green : featurePct >= 0.4 ? chalk11.yellow : chalk11.red;
   const featureMark = featurePct >= 0.4 ? "\u2705" : "\u26A0\uFE0F ";
   console.log(
-    `  ${featureMark} Features    ${String(counts.done).padStart(2)}/${total} complete` + featureColor(`  (${Math.round(featurePct * 100)}%)`) + chalk10.gray(`  +${featureScore}pts`)
+    `  ${featureMark} Features    ${String(counts.done).padStart(2)}/${total} complete` + featureColor(`  (${Math.round(featurePct * 100)}%)`) + chalk11.gray(`  +${featureScore}pts`)
   );
   const testMark = testFiles > 0 ? "\u2705" : "\u26A0\uFE0F ";
-  const testColor = testFiles > 0 ? chalk10.green : chalk10.red;
+  const testColor = testFiles > 0 ? chalk11.green : chalk11.red;
   console.log(
-    `  ${testMark} Tests       ${testColor(String(testFiles) + " test files")}` + (testFiles === 0 ? chalk10.red("  (-20pts)") : chalk10.gray(`  +${testScore}pts`))
+    `  ${testMark} Tests       ${testColor(String(testFiles) + " test files")}` + (testFiles === 0 ? chalk11.red("  (-20pts)") : chalk11.gray(`  +${testScore}pts`))
   );
   const decMark = decisionCount > 0 ? "\u2705" : "\u26A0\uFE0F ";
-  const decColor = decisionCount > 0 ? chalk10.green : chalk10.yellow;
+  const decColor = decisionCount > 0 ? chalk11.green : chalk11.yellow;
   console.log(
-    `  ${decMark} Arch log    ${decColor(decisionCount + " entries")}` + chalk10.gray(`  +${decisionScore}pts`)
+    `  ${decMark} Arch log    ${decColor(decisionCount + " entries")}` + chalk11.gray(`  +${decisionScore}pts`)
   );
   const claimMark = staleClaims === 0 ? "\u2705" : "\u26A0\uFE0F ";
-  const claimColor = staleClaims === 0 ? chalk10.green : chalk10.red;
+  const claimColor = staleClaims === 0 ? chalk11.green : chalk11.red;
   console.log(
-    `  ${claimMark} Claims      ${claimColor(staleClaims > 0 ? staleClaims + " stale (>24h)" : "0 stale")}` + chalk10.gray(`  +${claimScore}pts`)
+    `  ${claimMark} Claims      ${claimColor(staleClaims > 0 ? staleClaims + " stale (>24h)" : "0 stale")}` + chalk11.gray(`  +${claimScore}pts`)
   );
   const deployMark = deployScore > 0 ? "\u2705" : "\u26A0\uFE0F ";
-  const deployLabel = deployScore > 0 ? chalk10.green("detected") : chalk10.gray("not detected");
+  const deployLabel = deployScore > 0 ? chalk11.green("detected") : chalk11.gray("not detected");
   console.log(
-    `  ${deployMark} Deploy      ${deployLabel}` + (deployScore > 0 ? chalk10.gray(`  +${deployScore}pts`) : chalk10.gray("  +0pts"))
+    `  ${deployMark} Deploy      ${deployLabel}` + (deployScore > 0 ? chalk11.gray(`  +${deployScore}pts`) : chalk11.gray("  +0pts"))
   );
   console.log("");
   const recommendations = [];
@@ -1747,9 +2234,9 @@ async function healthCommand() {
   if (decisionCount === 0) recommendations.push("Log architecture decisions during sessions so agents understand the why.");
   if (featurePct < 0.5 && total > 0) recommendations.push(`${counts.pending} features pending \u2014 run groundctl next to pick one.`);
   if (recommendations.length > 0) {
-    console.log(chalk10.bold("  Recommendations:"));
+    console.log(chalk11.bold("  Recommendations:"));
     for (const r of recommendations) {
-      console.log(chalk10.yellow(`    \u2192 ${r}`));
+      console.log(chalk11.yellow(`    \u2192 ${r}`));
     }
     console.log("");
   }
@@ -1760,7 +2247,7 @@ import { createServer } from "http";
 import { existsSync as existsSync5, readFileSync as readFileSync5 } from "fs";
 import { join as join7, dirname as dirname2 } from "path";
 import { exec } from "child_process";
-import chalk11 from "chalk";
+import chalk12 from "chalk";
 import initSqlJs2 from "sql.js";
 function findDbPath(startDir = process.cwd()) {
   let dir = startDir;
@@ -1923,9 +2410,9 @@ async function dashboardCommand(options) {
     }
   });
   server.listen(port, "127.0.0.1", () => {
-    console.log(chalk11.bold(`
-  groundctl dashboard \u2192 `) + chalk11.blue(`http://localhost:${port}`) + "\n");
-    console.log(chalk11.gray("  Auto-refreshes every 10s. Press Ctrl+C to stop.\n"));
+    console.log(chalk12.bold(`
+  groundctl dashboard \u2192 `) + chalk12.blue(`http://localhost:${port}`) + "\n");
+    console.log(chalk12.gray("  Auto-refreshes every 10s. Press Ctrl+C to stop.\n"));
     exec(`open http://localhost:${port} 2>/dev/null || xdg-open http://localhost:${port} 2>/dev/null || true`);
   });
   await new Promise((_, reject) => {
@@ -1938,22 +2425,22 @@ import {
   existsSync as existsSync6,
   readdirSync as readdirSync2,
   statSync,
-  writeFileSync as writeFileSync5,
+  writeFileSync as writeFileSync6,
   readFileSync as readFileSync6,
   mkdirSync as mkdirSync3,
   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 chalk12 from "chalk";
+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;
 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);
@@ -1978,7 +2465,7 @@ function fileSize(p) {
 function writePidFile(groundctlDir, pid) {
   try {
     mkdirSync3(groundctlDir, { recursive: true });
-    writeFileSync5(join8(groundctlDir, "watch.pid"), String(pid), "utf8");
+    writeFileSync6(join8(groundctlDir, "watch.pid"), String(pid), "utf8");
   } catch {
   }
 }
@@ -2001,8 +2488,8 @@ function processAlive(pid) {
 async function runIngest(transcriptPath, projectPath) {
   const filename = transcriptPath.split("/").slice(-2).join("/");
   console.log(
-    chalk12.gray(`
-  [${(/* @__PURE__ */ new Date()).toLocaleTimeString()}] `) + chalk12.cyan(`Transcript stable \u2192 ingesting ${filename}`)
+    chalk13.gray(`
+  [${(/* @__PURE__ */ new Date()).toLocaleTimeString()}] `) + chalk13.cyan(`Transcript stable \u2192 ingesting ${filename}`)
   );
   try {
     const parsed = parseTranscript(transcriptPath, "auto", projectPath);
@@ -2058,11 +2545,11 @@ async function runIngest(transcriptPath, projectPath) {
     if (parsed.commits.length > 0) parts.push(`${parsed.commits.length} commit${parsed.commits.length !== 1 ? "s" : ""}`);
     if (newDecisions > 0) parts.push(`${newDecisions} decision${newDecisions !== 1 ? "s" : ""} captured`);
     const summary = parts.length > 0 ? parts.join(", ") : "no new data";
-    console.log(chalk12.green(`  \u2713 Session ingested \u2014 ${summary}`));
+    console.log(chalk13.green(`  \u2713 Session ingested \u2014 ${summary}`));
     await syncCommand({ silent: true });
-    console.log(chalk12.gray("  \u21B3 PROJECT_STATE.md + AGENTS.md updated"));
+    console.log(chalk13.gray("  \u21B3 PROJECT_STATE.md + AGENTS.md updated"));
   } catch (err) {
-    console.log(chalk12.red(`  \u2717 Ingest failed: ${err.message}`));
+    console.log(chalk13.red(`  \u2717 Ingest failed: ${err.message}`));
   }
 }
 function startWatcher(transcriptDir, projectPath) {
@@ -2110,47 +2597,47 @@ function startWatcher(transcriptDir, projectPath) {
       schedule(fp);
     }
   });
-  console.log(chalk12.bold("\n  groundctl watch") + chalk12.gray(" \u2014 auto-ingest on session end\n"));
+  console.log(chalk13.bold("\n  groundctl watch") + chalk13.gray(" \u2014 auto-ingest on session end\n"));
   console.log(
-    chalk12.gray("  Watching: ") + chalk12.blue(transcriptDir.replace(homedir3(), "~"))
+    chalk13.gray("  Watching: ") + chalk13.blue(transcriptDir.replace(homedir4(), "~"))
   );
-  console.log(chalk12.gray("  Stability threshold: ") + chalk12.white(`${DEBOUNCE_MS / 1e3}s`));
-  console.log(chalk12.gray("  Press Ctrl+C to stop.\n"));
+  console.log(chalk13.gray("  Stability threshold: ") + chalk13.white(`${DEBOUNCE_MS / 1e3}s`));
+  console.log(chalk13.gray("  Press Ctrl+C to stop.\n"));
 }
 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"
     });
     child.unref();
     const groundctlDir2 = join8(projectPath, ".groundctl");
     writePidFile(groundctlDir2, child.pid);
-    console.log(chalk12.green(`
+    console.log(chalk13.green(`
   \u2713 groundctl watch running in background (PID ${child.pid})`));
-    console.log(chalk12.gray(`  PID saved to .groundctl/watch.pid`));
-    console.log(chalk12.gray(`  To stop: kill ${child.pid}
+    console.log(chalk13.gray(`  PID saved to .groundctl/watch.pid`));
+    console.log(chalk13.gray(`  To stop: kill ${child.pid}
 `));
     process.exit(0);
   }
   const groundctlDir = join8(projectPath, ".groundctl");
   const existingPid = readPidFile(groundctlDir);
   if (existingPid && processAlive(existingPid)) {
-    console.log(chalk12.yellow(`
+    console.log(chalk13.yellow(`
   \u26A0  A watcher is already running (PID ${existingPid}).`));
-    console.log(chalk12.gray(`  To stop it: kill ${existingPid}
+    console.log(chalk13.gray(`  To stop it: kill ${existingPid}
 `));
     process.exit(1);
   }
   let transcriptDir = findTranscriptDir(projectPath);
   if (!transcriptDir) {
-    console.log(chalk12.bold("\n  groundctl watch\n"));
+    console.log(chalk13.bold("\n  groundctl watch\n"));
     console.log(
-      chalk12.yellow("  No Claude Code transcript directory found for this project yet.")
+      chalk13.yellow("  No Claude Code transcript directory found for this project yet.")
     );
-    console.log(chalk12.gray("  Waiting for first session to start...\n"));
+    console.log(chalk13.gray("  Waiting for first session to start...\n"));
     await new Promise((resolve3) => {
       const interval = setInterval(() => {
         const dir = findTranscriptDir(projectPath);
@@ -2165,7 +2652,7 @@ async function watchCommand(options) {
   startWatcher(transcriptDir, projectPath);
   await new Promise(() => {
     process.on("SIGINT", () => {
-      console.log(chalk12.gray("\n  Watcher stopped.\n"));
+      console.log(chalk13.gray("\n  Watcher stopped.\n"));
       process.exit(0);
     });
     process.on("SIGTERM", () => {
@@ -2175,7 +2662,7 @@ async function watchCommand(options) {
 }
 
 // src/commands/update.ts
-import chalk13 from "chalk";
+import chalk14 from "chalk";
 function parseProgress2(s) {
   const m = s.match(/^(\d+)\/(\d+)$/);
   if (!m) return null;
@@ -2183,7 +2670,7 @@ function parseProgress2(s) {
 }
 async function updateCommand(type, nameOrId, options) {
   if (type !== "feature") {
-    console.log(chalk13.red(`
+    console.log(chalk14.red(`
   Unknown type "${type}". Use "feature".
 `));
     process.exit(1);
@@ -2199,7 +2686,7 @@ async function updateCommand(type, nameOrId, options) {
     [nameOrId, `%${nameOrId}%`]
   );
   if (!feature) {
-    console.log(chalk13.red(`
+    console.log(chalk14.red(`
   Feature "${nameOrId}" not found.
 `));
     closeDb();
@@ -2219,7 +2706,7 @@ async function updateCommand(type, nameOrId, options) {
   if (options.progress !== void 0) {
     const p = parseProgress2(options.progress);
     if (!p) {
-      console.log(chalk13.yellow(`  \u26A0  --progress "${options.progress}" ignored (expected N/N format)
+      console.log(chalk14.yellow(`  \u26A0  --progress "${options.progress}" ignored (expected N/N format)
 `));
     } else {
       sets.push("progress_done = ?", "progress_total = ?");
@@ -2234,8 +2721,31 @@ 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(chalk13.yellow("\n  Nothing to update \u2014 pass at least one option.\n"));
+    console.log(chalk14.yellow("\n  Nothing to update \u2014 pass at least one option.\n"));
     closeDb();
     return;
   }
@@ -2247,22 +2757,170 @@ async function updateCommand(type, nameOrId, options) {
   );
   saveDb();
   closeDb();
-  console.log(chalk13.green(`  \u2713 Updated: ${feature.name}`));
+  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,
@@ -2281,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();