@imdeadpool/guardex 7.0.27 → 7.0.34

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@imdeadpool/guardex",
-  "version": "7.0.27",
+  "version": "7.0.34",
   "description": "Guardian T-Rex for your multi-agent repo. Isolated worktrees, file locks, and PR-only merges stop parallel Codex & Claude agents from overwriting each other's work. Auto-wires Oh My Codex, Oh My Claude, OpenSpec, and Caveman.",
   "license": "MIT",
   "preferGlobal": true,

package/src/cli/main.js

@@ -146,8 +146,10 @@ const {
   colorizeDoctorOutput,
   statusDot,
   printToolLogsSummary,
+  getInvokedCliName,
   usage,
   formatElapsedDuration,
+  startTransientSpinner,
   compactAutoFinishPathSegments,
   detectRecoverableAutoFinishConflict,
   printAutoFinishSummary,
@@ -889,6 +891,80 @@ function parseBooleanLike(raw) {
   return null;
 }
 
+function autoDoctorEnabledForCurrentSession() {
+  const explicit = parseBooleanLike(process.env.GUARDEX_AUTO_DOCTOR);
+  if (explicit != null) {
+    return explicit;
+  }
+  return isInteractiveTerminal();
+}
+
+function shouldAutoRunDoctorFromStatus(statusPayload) {
+  const repo = statusPayload?.repo || {};
+  return Boolean(
+    autoDoctorEnabledForCurrentSession()
+    && repo.inGitRepo
+    && repo.guardexEnabled !== false
+    && repo.serviceStatus === 'degraded'
+    && repo.scan
+    && Number(repo.scan.findings || 0) > 0,
+  );
+}
+
+function runCliSubprocessWithSpinner(args, options = {}) {
+  return new Promise((resolve, reject) => {
+    const spinner = options.spinnerMessage
+      ? startTransientSpinner(options.spinnerMessage, {
+        prefix: options.spinnerPrefix || `[${TOOL_NAME}]`,
+      })
+      : { stop() {} };
+    const child = cp.spawn(process.execPath, [path.resolve(__filename), ...args], {
+      cwd: options.cwd || process.cwd(),
+      env: {
+        ...process.env,
+        GUARDEX_AUTO_DOCTOR: '0',
+      },
+      stdio: ['inherit', 'pipe', 'pipe'],
+    });
+
+    const stopSpinner = () => spinner.stop();
+    child.stdout.on('data', (chunk) => {
+      stopSpinner();
+      process.stdout.write(chunk);
+    });
+    child.stderr.on('data', (chunk) => {
+      stopSpinner();
+      process.stderr.write(chunk);
+    });
+    child.on('error', (error) => {
+      stopSpinner();
+      reject(error);
+    });
+    child.on('close', (code) => {
+      stopSpinner();
+      resolve(typeof code === 'number' ? code : 1);
+    });
+  });
+}
+
+async function maybeAutoRunDoctorFromDefaultStatus(statusPayload) {
+  if (!shouldAutoRunDoctorFromStatus(statusPayload)) {
+    return false;
+  }
+
+  const target = statusPayload?.repo?.target || process.cwd();
+  console.log(`[${TOOL_NAME}] Auto-repair: repo safety is degraded. Running '${SHORT_TOOL_NAME} doctor --current' now.`);
+  process.exitCode = await runCliSubprocessWithSpinner(
+    ['doctor', '--target', target, '--current'],
+    {
+      cwd: target,
+      spinnerPrefix: `[${TOOL_NAME}] Auto-repair:`,
+      spinnerMessage: 'preparing doctor workspace',
+    },
+  );
+  return true;
+}
+
 function parseDotenvAssignmentValue(raw) {
   let value = String(raw || '').trim();
   if (!value) return '';
@@ -1158,6 +1234,84 @@ function promptYesNoStrict(question) {
   }
 }
 
+const VSCODE_EXTENSION_ID = 'Recodee.gitguardex-active-agents';
+const VSCODE_EXTENSION_DISPLAY_NAME = 'GitGuardex Active Agents';
+
+function maybePromptInstallVscodeExtension(options) {
+  if (options.dryRun) {
+    console.log(
+      `[${TOOL_NAME}] (dry-run) Would offer to install VS Code extension '${VSCODE_EXTENSION_ID}'.`,
+    );
+    return;
+  }
+
+  if (envFlagIsTruthy(process.env.GUARDEX_SKIP_VSCODE_EXT_PROMPT)) {
+    return;
+  }
+
+  const codeProbe = cp.spawnSync('code', ['--version'], { stdio: 'ignore' });
+  if (codeProbe.error || codeProbe.status !== 0) {
+    return;
+  }
+
+  const listProbe = cp.spawnSync('code', ['--list-extensions'], {
+    encoding: 'utf8',
+    stdio: ['ignore', 'pipe', 'ignore'],
+  });
+  if (!listProbe.error && listProbe.status === 0) {
+    const alreadyInstalled = String(listProbe.stdout || '')
+      .split('\n')
+      .some((line) => line.trim().toLowerCase() === VSCODE_EXTENSION_ID.toLowerCase());
+    if (alreadyInstalled) {
+      console.log(
+        `[${TOOL_NAME}] ✅ VS Code extension '${VSCODE_EXTENSION_ID}' already installed.`,
+      );
+      return;
+    }
+  }
+
+  let approved;
+  if (options.yesGlobalInstall) {
+    approved = true;
+  } else if (options.noGlobalInstall) {
+    approved = false;
+  } else if (!isInteractiveTerminal()) {
+    console.log(
+      `[${TOOL_NAME}] Optional VS Code extension '${VSCODE_EXTENSION_ID}' ` +
+        `(${VSCODE_EXTENSION_DISPLAY_NAME}) not installed. ` +
+        `Install later: code --install-extension ${VSCODE_EXTENSION_ID}`,
+    );
+    return;
+  } else {
+    approved = promptYesNoStrict(
+      `Install VS Code extension '${VSCODE_EXTENSION_ID}' (${VSCODE_EXTENSION_DISPLAY_NAME}) now?`,
+    );
+  }
+
+  if (!approved) {
+    console.log(
+      `[${TOOL_NAME}] ⚠️ VS Code extension skipped. ` +
+        `Set GUARDEX_SKIP_VSCODE_EXT_PROMPT=1 to silence or run 'code --install-extension ${VSCODE_EXTENSION_ID}' later.`,
+    );
+    return;
+  }
+
+  const install = cp.spawnSync('code', ['--install-extension', VSCODE_EXTENSION_ID], {
+    stdio: 'inherit',
+  });
+  if (install.error || install.status !== 0) {
+    console.log(
+      `[${TOOL_NAME}] ⚠️ VS Code extension install failed. ` +
+        `Retry manually: code --install-extension ${VSCODE_EXTENSION_ID}`,
+    );
+    return;
+  }
+  console.log(
+    `[${TOOL_NAME}] ✅ VS Code extension '${VSCODE_EXTENSION_ID}' installed. ` +
+      `Reload the VS Code window to activate it.`,
+  );
+}
+
 function resolveGlobalInstallApproval(options) {
   if (options.yesGlobalInstall && options.noGlobalInstall) {
     throw new Error('Cannot use both --yes-global-install and --no-global-install');
@@ -1672,12 +1826,62 @@ function setExitCodeFromScan(scan) {
   process.exitCode = 0;
 }
 
-function status(rawArgs) {
-  const options = parseCommonArgs(rawArgs, {
-    target: process.cwd(),
-    json: false,
-  });
+function printStatusRepairHint(scanResult) {
+  if (!scanResult || scanResult.guardexEnabled === false) {
+    return;
+  }
+  if (scanResult.errors === 0 && scanResult.warnings === 0) {
+    return;
+  }
+
+  const scanHint = scanResult.errors === 0
+    ? `review warning details with '${SHORT_TOOL_NAME} scan'`
+    : `inspect detailed findings with '${SHORT_TOOL_NAME} scan'`;
+  console.log(
+    `[${TOOL_NAME}] Quick fix: run '${SHORT_TOOL_NAME} doctor' to repair drift, or ${scanHint}.`,
+  );
+}
+
+function countAgentWorktrees(repoRoot) {
+  if (!repoRoot || typeof repoRoot !== 'string') return 0;
+  const relPaths = ['.omc/agent-worktrees', '.omx/agent-worktrees'];
+  let count = 0;
+  for (const rel of relPaths) {
+    try {
+      const entries = fs.readdirSync(path.join(repoRoot, rel), { withFileTypes: true });
+      count += entries.filter((entry) => entry.isDirectory()).length;
+    } catch (_err) {
+      // missing dir or permission error; not an active-agent signal
+    }
+  }
+  return count;
+}
 
+function deriveNextStepHint({ scanResult, worktreeCount, invoked, inGitRepo }) {
+  if (!inGitRepo) {
+    return `${invoked} setup --target <path-to-git-repo>   # initialize guardrails in a repo`;
+  }
+  if (!scanResult) {
+    return `${invoked} setup   # bootstrap repo guardrails`;
+  }
+  if (scanResult.guardexEnabled === false) {
+    return `set GUARDEX_ON=1 in .env   # re-enable guardrails, then '${invoked} doctor'`;
+  }
+  const branch = scanResult.branch || '';
+  if (branch.startsWith('agent/')) {
+    return `${invoked} branch finish --branch "${branch}" --via-pr --wait-for-merge --cleanup`;
+  }
+  if (worktreeCount > 0) {
+    const plural = worktreeCount === 1 ? 'worktree' : 'worktrees';
+    return `${invoked} finish --all   # ${worktreeCount} active agent ${plural}`;
+  }
+  if (scanResult.errors > 0 || scanResult.warnings > 0) {
+    return `${invoked} doctor   # repair drift`;
+  }
+  return `${invoked} branch start "<task>" "<agent-name>"   # start a sandboxed agent task`;
+}
+
+function collectServicesSnapshot() {
   const toolchain = toolchainModule.detectGlobalToolchainPackages();
   const npmServices = GLOBAL_TOOLCHAIN_PACKAGES.map((pkg) => {
     const service = toolchainModule.getGlobalToolchainService(pkg);
@@ -1701,18 +1905,103 @@ function status(rawArgs) {
   const localCompanionServices = toolchainModule.detectOptionalLocalCompanionTools().map((tool) => ({
     name: tool.name,
     displayName: tool.displayName || tool.name,
+    installCommand: tool.installCommand,
+    installArgs: Array.isArray(tool.installArgs) ? [...tool.installArgs] : [],
     status: tool.status,
   }));
   const requiredSystemTools = toolchainModule.detectRequiredSystemTools();
   const services = [
     ...npmServices,
-    ...localCompanionServices,
+    ...localCompanionServices.map((tool) => ({
+      name: tool.name,
+      displayName: tool.displayName,
+      status: tool.status,
+    })),
     ...requiredSystemTools.map((tool) => ({
       name: tool.name,
       displayName: tool.displayName || tool.name,
       status: tool.status,
     })),
   ];
+  return { toolchain, npmServices, localCompanionServices, requiredSystemTools, services };
+}
+
+function maybePromptInstallMissingCompanions(snapshot) {
+  if (envFlagIsTruthy(process.env.GUARDEX_SKIP_COMPANION_PROMPT)) {
+    return { handled: false, installed: false };
+  }
+  const interactive = Boolean(process.stdout.isTTY) && Boolean(process.stdin.isTTY);
+  const autoApproval = toolchainModule.parseAutoApproval('GUARDEX_AUTO_COMPANION_APPROVAL');
+  if (!interactive && autoApproval == null) {
+    return { handled: false, installed: false };
+  }
+  if (!snapshot.toolchain.ok) {
+    return { handled: false, installed: false };
+  }
+
+  const missingPackages = snapshot.npmServices
+    .filter((service) => service.status !== 'active')
+    .map((service) => service.packageName);
+  const missingLocalTools = snapshot.localCompanionServices.filter((tool) => tool.status !== 'active');
+  if (missingPackages.length === 0 && missingLocalTools.length === 0) {
+    return { handled: false, installed: false };
+  }
+
+  const missingNames = [
+    ...missingPackages.map((pkg) => toolchainModule.formatGlobalToolchainServiceName(pkg)),
+    ...missingLocalTools.map((tool) => tool.displayName || tool.name),
+  ];
+  console.log(`[${TOOL_NAME}] Missing companion tools: ${missingNames.join(', ')}.`);
+
+  const promptText = toolchainModule.buildMissingCompanionInstallPrompt(missingPackages, missingLocalTools);
+  const approved = interactive
+    ? toolchainModule.promptYesNoStrict(promptText)
+    : autoApproval;
+
+  if (!approved) {
+    console.log(
+      `[${TOOL_NAME}] Skipped companion install. Set GUARDEX_SKIP_COMPANION_PROMPT=1 to silence this prompt, ` +
+      `or run '${getInvokedCliName()} setup --install-only' later to install manually.`,
+    );
+    return { handled: true, installed: false };
+  }
+
+  const result = toolchainModule.performCompanionInstall(missingPackages, missingLocalTools);
+  if (result.status === 'installed') {
+    console.log(
+      `[${TOOL_NAME}] ✅ Companion tools installed (${(result.packages || []).join(', ')}).`,
+    );
+    return { handled: true, installed: true };
+  }
+  if (result.status === 'failed') {
+    console.log(
+      `[${TOOL_NAME}] ⚠️ Companion install failed: ${result.reason}. ` +
+      `Retry with '${getInvokedCliName()} setup --install-only'.`,
+    );
+    return { handled: true, installed: false };
+  }
+  return { handled: true, installed: false };
+}
+
+function status(rawArgs) {
+  const { found: verboseFlag, remaining: afterVerbose } = extractFlag(rawArgs, '--verbose');
+  const options = parseCommonArgs(afterVerbose, {
+    target: process.cwd(),
+    json: false,
+  });
+  const forceCompact = envFlagIsTruthy(process.env.GUARDEX_COMPACT_STATUS);
+  const forceExpand = envFlagIsTruthy(process.env.GUARDEX_VERBOSE_STATUS) || verboseFlag;
+  const interactive = Boolean(process.stdout.isTTY);
+  const invokedBasename = getInvokedCliName();
+
+  let snapshot = collectServicesSnapshot();
+  if (!options.json) {
+    const result = maybePromptInstallMissingCompanions(snapshot);
+    if (result.installed) {
+      snapshot = collectServicesSnapshot();
+    }
+  }
+  let { toolchain, npmServices, localCompanionServices, requiredSystemTools, services } = snapshot;
 
   const targetPath = path.resolve(options.target);
   const inGitRepo = isGitRepo(targetPath);
@@ -1752,18 +2041,27 @@ function status(rawArgs) {
   if (options.json) {
     process.stdout.write(`${JSON.stringify(payload, null, 2)}\n`);
     process.exitCode = 0;
-    return;
+    return payload;
   }
 
+  const allServicesActive = toolchain.ok && services.every((service) => service.status === 'active');
+  const compact = !forceExpand && (forceCompact || (interactive && allServicesActive));
+
   console.log(`[${TOOL_NAME}] CLI: ${payload.cli.runtime}`);
   if (!toolchain.ok) {
     console.log(`[${TOOL_NAME}] ⚠️ Could not detect global services: ${toolchain.error}`);
   }
 
-  console.log(`[${TOOL_NAME}] Global services:`);
-  for (const service of services) {
-    const serviceLabel = service.displayName || service.name;
-    console.log(`  - ${statusDot(service.status)} ${serviceLabel}: ${service.status}`);
+  if (compact) {
+    console.log(
+      `[${TOOL_NAME}] Global services: ${services.length}/${services.length} ${statusDot('active')} active`,
+    );
+  } else {
+    console.log(`[${TOOL_NAME}] Global services:`);
+    for (const service of services) {
+      const serviceLabel = service.displayName || service.name;
+      console.log(`  - ${statusDot(service.status)} ${serviceLabel}: ${service.status}`);
+    }
   }
   const inactiveOptionalCompanions = [...npmServices, ...localCompanionServices]
     .filter((service) => service.status !== 'active')
@@ -1799,8 +2097,16 @@ function status(rawArgs) {
     console.log(
       `[${TOOL_NAME}] Repo safety service: ${statusDot('inactive')} inactive (no git repository at target).`,
     );
+    const inactiveHint = deriveNextStepHint({
+      scanResult: null,
+      worktreeCount: 0,
+      invoked: invokedBasename,
+      inGitRepo,
+    });
+    console.log(`[${TOOL_NAME}] Next: ${inactiveHint}`);
+    printToolLogsSummary({ invokedBasename, compact });
     process.exitCode = 0;
-    return;
+    return payload;
   }
 
   if (scanResult.guardexEnabled === false) {
@@ -1809,9 +2115,23 @@ function status(rawArgs) {
     );
     console.log(`[${TOOL_NAME}] Repo: ${scanResult.repoRoot}`);
     console.log(`[${TOOL_NAME}] Branch: ${scanResult.branch}`);
-    printToolLogsSummary();
+    const worktreeCountDisabled = countAgentWorktrees(scanResult.repoRoot);
+    if (worktreeCountDisabled > 0) {
+      const plural = worktreeCountDisabled === 1 ? 'worktree' : 'worktrees';
+      console.log(
+        `[${TOOL_NAME}] ⚠ ${worktreeCountDisabled} active agent ${plural} under .omc/agent-worktrees or .omx/agent-worktrees.`,
+      );
+    }
+    const disabledHint = deriveNextStepHint({
+      scanResult,
+      worktreeCount: worktreeCountDisabled,
+      invoked: invokedBasename,
+      inGitRepo,
+    });
+    console.log(`[${TOOL_NAME}] Next: ${disabledHint}`);
+    printToolLogsSummary({ invokedBasename, compact });
     process.exitCode = 0;
-    return;
+    return payload;
   }
 
   if (scanResult.errors === 0 && scanResult.warnings === 0) {
@@ -1820,23 +2140,36 @@ function status(rawArgs) {
     console.log(
       `[${TOOL_NAME}] Repo safety service: ${statusDot('degraded')} degraded (${scanResult.warnings} warning(s)).`,
     );
-    console.log(`[${TOOL_NAME}] Run '${TOOL_NAME} scan' to review warning details.`);
   } else if (scanResult.warnings === 0) {
     console.log(
       `[${TOOL_NAME}] Repo safety service: ${statusDot('degraded')} degraded (${scanResult.errors} error(s)).`,
     );
-    console.log(`[${TOOL_NAME}] Run '${TOOL_NAME} scan' for detailed findings.`);
   } else {
     console.log(
       `[${TOOL_NAME}] Repo safety service: ${statusDot('degraded')} degraded (${scanResult.errors} error(s), ${scanResult.warnings} warning(s)).`,
     );
-    console.log(`[${TOOL_NAME}] Run '${TOOL_NAME} scan' for detailed findings.`);
   }
+  printStatusRepairHint(scanResult);
   console.log(`[${TOOL_NAME}] Repo: ${scanResult.repoRoot}`);
   console.log(`[${TOOL_NAME}] Branch: ${scanResult.branch}`);
-  printToolLogsSummary();
+  const worktreeCountActive = countAgentWorktrees(scanResult.repoRoot);
+  if (worktreeCountActive > 0) {
+    const plural = worktreeCountActive === 1 ? 'worktree' : 'worktrees';
+    console.log(
+      `[${TOOL_NAME}] ⚠ ${worktreeCountActive} active agent ${plural} → ${invokedBasename} finish --all`,
+    );
+  }
+  const activeHint = deriveNextStepHint({
+    scanResult,
+    worktreeCount: worktreeCountActive,
+    invoked: invokedBasename,
+    inGitRepo,
+  });
+  console.log(`[${TOOL_NAME}] Next: ${activeHint}`);
+  printToolLogsSummary({ invokedBasename, compact });
 
   process.exitCode = 0;
+  return payload;
 }
 
 function install(rawArgs) {
@@ -2580,6 +2913,9 @@ function setup(rawArgs) {
       console.log(`[${TOOL_NAME}] ⚠️ ${warning}`);
     }
   }
+
+  maybePromptInstallVscodeExtension(options);
+
   const requiredSystemTools = toolchainModule.detectRequiredSystemTools();
   const missingSystemTools = requiredSystemTools.filter((tool) => tool.status !== 'active');
   if (missingSystemTools.length === 0) {
@@ -3246,13 +3582,14 @@ function protect(rawArgs) {
   throw new Error(`Unknown protect subcommand: ${subcommand}`);
 }
 
-function main() {
+async function main() {
   const args = process.argv.slice(2);
 
   if (args.length === 0) {
     toolchainModule.maybeSelfUpdateBeforeStatus();
     toolchainModule.maybeOpenSpecUpdateBeforeStatus();
-    status([]);
+    const statusPayload = status([]);
+    await maybeAutoRunDoctorFromDefaultStatus(statusPayload);
     return;
   }
 
@@ -3322,9 +3659,9 @@ function main() {
   throw new Error(`Unknown command: ${command}`);
 }
 
-function runFromBin() {
+async function runFromBin() {
   try {
-    main();
+    await main();
   } catch (error) {
     console.error(`[${TOOL_NAME}] ${error.message}`);
     process.exitCode = 1;
@@ -3332,7 +3669,7 @@ function runFromBin() {
 }
 
 if (require.main === module) {
-  runFromBin();
+  void runFromBin();
 }
 
 module.exports = {

package/src/context.js

@@ -363,27 +363,68 @@ const SUGGESTIBLE_COMMANDS = [
   'print-agents-snippet',
   'release',
 ];
-const CLI_COMMAND_DESCRIPTIONS = [
-  ['status', 'Show GitGuardex CLI + service health without modifying files'],
-  ['setup', 'Install, repair, and verify guardrails (flags: --repair, --install-only, --target, --current)'],
-  ['doctor', 'Repair drift + verify (flags: --target, --current; auto-sandboxes on protected main)'],
-  ['branch', 'CLI-owned branch workflow surface (start/finish/merge)'],
-  ['locks', 'CLI-owned file lock surface (claim/allow-delete/release/status/validate)'],
-  ['worktree', 'CLI-owned worktree cleanup surface (prune)'],
-  ['hook', 'Hook dispatch/install surface used by managed shims'],
-  ['migrate', 'Convert legacy repo-local installs to the zero-copy CLI-owned surface'],
-  ['install-agent-skills', 'Install Guardex Codex/Claude skills into the user home'],
-  ['protect', 'Manage protected branches (list/add/remove/set/reset)'],
-  ['merge', 'Create/reuse an integration lane and merge overlapping agent branches'],
-  ['sync', 'Sync agent branches with origin/<base>'],
-  ['finish', 'Commit + PR + merge completed agent branches (--all, --branch)'],
-  ['cleanup', 'Prune merged/stale agent branches and worktrees'],
-  ['release', 'Create or update the current GitHub release with README-generated notes'],
-  ['agents', 'Start/stop repo-scoped review + cleanup bots'],
-  ['prompt', 'Print AI setup checklist or named slices (--exec, --part, --list-parts, --snippet)'],
-  ['report', 'Security/safety reports (e.g. OpenSSF scorecard, session severity)'],
-  ['help', 'Show this help output'],
-  ['version', 'Print GitGuardex version'],
+// CLI_COMMAND_GROUPS is the grouped source of truth the `gx --help` /
+// `gx` no-args renderer uses. Each group is ordered roughly by how often a
+// user reaches for it so the help screen answers "what do I run first?"
+// before "what else can this do?". CLI_COMMAND_DESCRIPTIONS preserves the
+// flat export for callers that still want the ungrouped list.
+const CLI_COMMAND_GROUPS = [
+  {
+    label: 'Setup & health',
+    description: 'Install, repair, and check a repo. Run these first on a new clone.',
+    commands: [
+      ['setup', 'Install, repair, and verify guardrails (flags: --repair, --install-only, --target, --current)'],
+      ['doctor', 'Repair drift + verify (flags: --target, --current; auto-sandboxes on protected main)'],
+      ['status', 'Show GitGuardex CLI + service health without modifying files'],
+      ['migrate', 'Convert legacy repo-local installs to the zero-copy CLI-owned surface'],
+    ],
+  },
+  {
+    label: 'Branch workflow',
+    description: 'The sandbox → commit → PR → merge loop for agent-owned branches.',
+    commands: [
+      ['branch', 'CLI-owned branch workflow surface (start/finish/merge)'],
+      ['finish', 'Commit + PR + merge completed agent branches (--all, --branch)'],
+      ['merge', 'Create/reuse an integration lane and merge overlapping agent branches'],
+      ['sync', 'Sync agent branches with origin/<base>'],
+      ['cleanup', 'Prune merged/stale agent branches and worktrees'],
+    ],
+  },
+  {
+    label: 'Coordination',
+    description: 'File locks, worktrees, hooks, and protected-branch policy.',
+    commands: [
+      ['locks', 'CLI-owned file lock surface (claim/allow-delete/release/status/validate)'],
+      ['worktree', 'CLI-owned worktree cleanup surface (prune)'],
+      ['hook', 'Hook dispatch/install surface used by managed shims'],
+      ['protect', 'Manage protected branches (list/add/remove/set/reset)'],
+    ],
+  },
+  {
+    label: 'Agents & reports',
+    description: 'Review / cleanup bots, AI setup prompts, and safety reports.',
+    commands: [
+      ['agents', 'Start/stop repo-scoped review + cleanup bots'],
+      ['install-agent-skills', 'Install Guardex Codex/Claude skills into the user home'],
+      ['prompt', 'Print AI setup checklist or named slices (--exec, --part, --list-parts, --snippet)'],
+      ['report', 'Security/safety reports (e.g. OpenSSF scorecard, session severity)'],
+      ['release', 'Create or update the current GitHub release with README-generated notes'],
+    ],
+  },
+  {
+    label: 'Meta',
+    description: 'Version + help.',
+    commands: [
+      ['help', 'Show this help output'],
+      ['version', 'Print GitGuardex version'],
+    ],
+  },
+];
+const CLI_COMMAND_DESCRIPTIONS = CLI_COMMAND_GROUPS.flatMap((group) => group.commands);
+const CLI_QUICKSTART_STEPS = [
+  'gx setup',
+  'gx branch start "<task>" "<agent>"',
+  'gx branch finish --via-pr --wait-for-merge --cleanup',
 ];
 const DEPRECATED_COMMAND_ALIASES = new Map([
   ['init', { target: 'setup', hint: 'gx setup' }],
@@ -686,6 +727,8 @@ module.exports = {
   COMMAND_TYPO_ALIASES,
   SUGGESTIBLE_COMMANDS,
   CLI_COMMAND_DESCRIPTIONS,
+  CLI_COMMAND_GROUPS,
+  CLI_QUICKSTART_STEPS,
   DEPRECATED_COMMAND_ALIASES,
   AGENT_BOT_DESCRIPTIONS,
   DOCTOR_AUTO_FINISH_DETAIL_LIMIT,