@imdeadpool/guardex 7.0.26 → 7.0.31

package/README.md

@@ -111,6 +111,16 @@ gx setup
 
 That's it. Install and update via `@imdeadpool/guardex`. Setup installs the minimal repo footprint: managed hook shims, repo-local state, AGENTS wiring, OpenSpec/caveman/OMX scaffolding, and a small set of repo-local helper assets. Aliases: `gx` (preferred), `gitguardex` (full), `guardex` (legacy compatibility).
 
+### Install surfaces at a glance
+
+| Goal | Command | Installs |
+| --- | --- | --- |
+| Global Guardex CLI | `npm i -g @imdeadpool/guardex` | `gx`, `gitguardex`, `guardex`, and the CLI runtime |
+| User-level Codex/Claude companions | `gx install-agent-skills` | `~/.codex/skills/gitguardex/SKILL.md`, `~/.codex/skills/guardex-merge-skills-to-dev/SKILL.md`, and `~/.claude/commands/gitguardex.md` |
+| Generic repo skill catalog | `npx skills add recodee/` or `npx skills add recodee/gitguardex` | the repo-root `skills/` catalog for agents that support the generic installer |
+
+These paths are complementary, not chained together. `npm i -g @imdeadpool/guardex` does not auto-run `npx skills add ...`.
+
 ---
 
 ## How `AGENTS.md` and `CLAUDE.md` are handled
@@ -140,7 +150,14 @@ That's it. Install and update via `@imdeadpool/guardex`. Setup installs the mini
 </div>
 
 > [!NOTE]
-> In this repo, `CLAUDE.md` is a symlink to `AGENTS.md`, so Claude reads the same contract. Optional Codex/Claude companion files still install at the user level with `gx install-agent-skills`, while the generic repo skill catalog is available through `npx skills add recodeee/` or directly via `npx skills add recodeee/gitguardex`.
+> In this repo, `CLAUDE.md` is a symlink to `AGENTS.md`, so Claude reads the same contract as Codex.
+>
+> Keep the install paths separate:
+> - `npm i -g @imdeadpool/guardex` installs the Guardex CLI.
+> - `gx install-agent-skills` installs the user-level Codex/Claude companion files.
+> - `npx skills add recodee/` or `npx skills add recodee/gitguardex` installs the generic repo skill catalog.
+>
+> The global npm install does not auto-run the generic `npx skills add ...` flow.
 
 ### Decision flow
 
@@ -461,17 +478,19 @@ Repo: <https://github.com/Yeachan-Heo/oh-my-claudecode>
 
 ### GitGuardex skills - install the repo skill catalog through `npx skills`
 
-For agents that already support the generic `skills` installer flow, GitGuardex now exposes its repo skill catalog directly. You can start from the broader `recodeee` source or jump straight into this repo's catalog.
+For agents that already support the generic `skills` installer flow, GitGuardex exposes its repo skill catalog directly. Use it as a separate install path after the CLI install. You can start from the broader `recodee` source or jump straight into this repo's catalog.
 
 ```sh
-npx skills add recodeee/
+npx skills add recodee/
 ```
 
 ```sh
-npx skills add recodeee/gitguardex
+npx skills add recodee/gitguardex
 ```
 
-This repo currently exposes `gitguardex` and `guardex-merge-skills-to-dev` through that flow. If the picker does not show a separate `guardex` skill, that is expected: `guardex` remains the legacy CLI alias, while the repo skill itself is named `gitguardex`. Use `gx install-agent-skills` when you want the Codex/Claude user-home startup files instead of the generic `skills` catalog.
+This repo currently exposes `gitguardex` and `guardex-merge-skills-to-dev` through that flow. If the picker does not show a separate `guardex` skill, that is expected: `guardex` remains the legacy CLI alias, while the repo skill itself is named `gitguardex`.
+
+Need the Codex/Claude user-home startup files instead? Run `gx install-agent-skills`. Need the generic repo catalog? Run `npx skills add ...`. They solve different setup surfaces.
 
 Repo: <https://github.com/recodeee/gitguardex>
 [![GitHub stars](https://img.shields.io/github/stars/recodeee/gitguardex?style=social)](https://github.com/recodeee/gitguardex)
@@ -626,7 +645,7 @@ vscode/guardex-active-agents/README.md
 
 Legacy compatibility note: older repos may still contain repo-local workflow scripts under `scripts/`. Direct `gx branch ...`, `gx locks ...`, `gx finish`, `gx cleanup`, `gx merge`, and `gx migrate` do not require them. `gx migrate` removes those leftover workflow shims by default. The CLI still honors repo-local `scripts/review-bot-watch.sh` and `scripts/codex-agent.sh` when they are already present so older repos can keep working during migration.
 
-Optional Codex/Claude user-level companions still install with `gx install-agent-skills`; the generic repo skill catalog is available with `npx skills add recodeee/` or directly via `npx skills add recodeee/gitguardex`. Neither path copies those user-home files into each repo.
+Optional Codex/Claude user-level companions still install with `gx install-agent-skills`; the generic repo skill catalog is available with `npx skills add recodee/` or directly via `npx skills add recodee/gitguardex`. Neither path copies those user-home files into each repo, and the global Guardex npm install does not trigger the `npx skills add ...` path for you.
 
 ---
 
@@ -689,9 +708,21 @@ npm pack --dry-run
 <details>
 <summary><strong>v7.x</strong></summary>
 
+### v7.0.28
+- Bumped `@imdeadpool/guardex` from `7.0.27` to `7.0.28` so the CLI help redesign can ship on a fresh npm version.
+- `gx --help` and `gx` (no args) now render commands as a grouped catalog (Setup & health / Branch workflow / Coordination / Agents & reports / Meta) with short group descriptions, so the top of the help screen shows the newcomer path instead of a flat 20-row list.
+- Added a three-step Quickstart block (`gx setup` → `gx branch start "<task>" "<agent>"` → `gx branch finish --via-pr --wait-for-merge --cleanup`) to both help surfaces so the intended install/setup sequence is visible before the full command reference.
+- Exposed `CLI_COMMAND_GROUPS` and `CLI_QUICKSTART_STEPS` from `src/context.js` (with `CLI_COMMAND_DESCRIPTIONS` derived from the grouped source of truth), giving future help tooling and integrations a structured way to iterate the catalog without re-parsing flat rows.
+
+### v7.0.27
+- Bumped `@imdeadpool/guardex` from `7.0.26` to `7.0.27` so npm can publish a fresh version after `7.0.26` was already taken on the registry.
+- The shipped `agent-branch-start.sh` copies now keep the startup auto-transfer path alive under `set -o pipefail`, so Guardex can still restore moved changes back to the protected checkout when branch startup hits a later failure.
+- The shipped `agent-branch-finish.sh` copies now keep PR-only finish runs from opening temporary integration repos, so maintainers can finish directly through the existing PR lane without extra temp-repo churn.
+- Keep the release scoped to version metadata for the already-merged `main` payload; no additional runtime behavior changes are introduced in this release lane.
+
 ### v7.0.26
 - Bumped `@imdeadpool/guardex` from `7.0.25` to `7.0.26` so npm can publish a fresh version after `v7.0.25` reached GitHub Releases while the registry stayed on `7.0.24`.
-- README now documents both `npx skills add recodeee/` and `npx skills add recodeee/gitguardex`, and explains why the picker shows `gitguardex` instead of a separate `guardex` skill.
+- README now documents both `npx skills add recodee/` and `npx skills add recodee/gitguardex`, clarifies that the global Guardex npm install does not auto-run the generic skills installer, and explains why the picker shows `gitguardex` instead of a separate `guardex` skill.
 - Keep the release scoped to version metadata plus the already-merged README installer guidance on `main`; no additional CLI/runtime behavior changed in this lane.
 
 ### v7.0.25

package/SECURITY.md

@@ -8,7 +8,7 @@ Only the latest published GitGuardex CLI build is supported for security fixes.
 
 Please report security issues privately by opening a GitHub security advisory:
 
-- https://github.com/recodeecom/multiagent-safety/security/advisories/new
+- https://github.com/recodeee/gitguardex/security/advisories/new
 
 If advisories are unavailable, open a private report via GitHub issue contact details and avoid posting exploit details publicly.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@imdeadpool/guardex",
-  "version": "7.0.26",
+  "version": "7.0.31",
   "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,
@@ -68,10 +68,10 @@
     "access": "public"
   },
   "devDependencies": {
-    "fast-check": "^3.23.2"
+    "fast-check": "3.23.2"
   },
   "dependencies": {
-    "jsonc-parser": "^3.3.1",
-    "semver": "^7.7.4"
+    "jsonc-parser": "3.3.1",
+    "semver": "7.7.4"
   }
 }

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 '';
@@ -1672,12 +1748,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 +1827,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 +1963,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 +2019,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 +2037,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 +2062,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) {
@@ -3246,13 +3501,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 +3578,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 +3588,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,