Give every advertised simbroker group a working --help page.

Why:
Global help told newcomers to run `simbroker <group> --help` for events,
pin, simulators, service, and doctor, but those names had no help handler
and failed with a JSON unknown-command error.

Changed:
Add help payloads and execute cases for events, pin, simulators, service,
and doctor. Treat doctor as a top-level command in global help. Route
`--help` before service start/stop/status. Skip the service probe for help
so `--help` stays local. Cover every advertised `--help` page plus
alias-unhealthy doctor prose. Specs now record the help/doctor human
default and `--json` machine payload.

Verification:
npm run test:client
npm run agent:verify -- --profile spec-only --paths client/command-dispatch.mjs,client/bin/simbroker.mjs,client/test/simbroker.test.mjs,spec/global-simulator-broker.md,spec/architecture.md --session-dir task-sessions/20260818-help-groups
npm run agent:verify -- --profile implementation --paths client/command-dispatch.mjs,client/bin/simbroker.mjs,client/test/simbroker.test.mjs,spec/global-simulator-broker.md,spec/architecture.md --session-dir task-sessions/20260818-help-groups

Affected:
client/command-dispatch.mjs
client/bin/simbroker.mjs
client/test/simbroker.test.mjs
spec/global-simulator-broker.md
spec/architecture.md

Refs:
#3

Session:
task-sessions/20260818-help-groups

Author: VladimirBrejcha

client/bin/simbroker.mjs

@@ -446,7 +446,7 @@ async function stopService(paths) {
 }
 
 async function runServiceAwareRequest(paths, request) {
-  const canUseService = !localOnlyMode(process.env);
+  const canUseService = !localOnlyMode(process.env) && request.group !== "help";
   let service = canUseService
     ? await probeService(paths, { timeoutMs: serviceCommandTimeoutMs(request) })
     : null;
@@ -572,6 +572,11 @@ async function main() {
   const [group, command] = positionals;
   const paths = buildPaths(flags);
 
+  if (flags.has("help") || group === "help" || command === "help") {
+    const request = createCommandRequest(paths, group, command, flags);
+    return runServiceAwareRequest(paths, request);
+  }
+
   switch (`${group ?? ""}:${command ?? ""}`) {
     case "service:start":
       rejectUnknownServiceControlFlags(flags);

client/command-dispatch.mjs

@@ -325,14 +325,23 @@ function formatHelpText(payload) {
   ];
 
   if (payload.group === "global") {
+    const topLevel = new Set(["doctor"]);
+    const groups = payload.commands.filter((command) => !topLevel.has(command));
+    const topLevelCommands = payload.commands.filter((command) => topLevel.has(command));
     lines.push("Command groups:");
-    for (const command of payload.commands) {
+    for (const command of groups) {
       lines.push(`  ${command}`);
     }
+    if (topLevelCommands.length > 0) {
+      lines.push("", "Top-level commands:");
+      for (const command of topLevelCommands) {
+        lines.push(`  ${command}`);
+      }
+    }
     lines.push(
       "",
       "Use `simbroker <group> --help` for the commands in a group.",
-      "Use `simbroker doctor` to check this Mac.",
+      "Use `simbroker doctor --help` for doctor usage.",
     );
   } else {
     lines.push("Commands:");
@@ -625,6 +634,49 @@ function helpPayload(group) {
       group: "lease",
       usage: "simbroker lease <command>",
     },
+    events: {
+      commands: [
+        "events watch [--follow] [--json-lines] [--limit <n>] [--after-event-id <id>]",
+      ],
+      group: "events",
+      usage: "simbroker events <command>",
+    },
+    pin: {
+      commands: [
+        "pin create --purpose <purpose> --alias <alias> [--repo-root <repo>] [--note <note>]",
+        "pin clear --alias <alias>",
+      ],
+      group: "pin",
+      usage: "simbroker pin <command>",
+    },
+    simulators: {
+      commands: [
+        "simulators list",
+        "simulators boot --alias <alias>",
+        "simulators shutdown --alias <alias>",
+        "simulators erase --alias <alias>",
+        "simulators repair --alias <alias>",
+      ],
+      group: "simulators",
+      usage: "simbroker simulators <command>",
+    },
+    service: {
+      commands: [
+        "service start",
+        "service status",
+        "service stop",
+      ],
+      group: "service",
+      usage: "simbroker service <command>",
+    },
+    doctor: {
+      commands: [
+        "doctor",
+        "doctor --json",
+      ],
+      group: "doctor",
+      usage: "simbroker doctor [--json]",
+    },
   };
   return {
     ok: true,
@@ -1129,6 +1181,11 @@ export function executeBrokerCommand(paths, request) {
     case "help:lease":
     case "help:capacity":
     case "help:idle":
+    case "help:events":
+    case "help:pin":
+    case "help:simulators":
+    case "help:service":
+    case "help:doctor":
       return helpPayload(request.command);
     case "doctor:status":
       payload = doctorBroker(paths, options);

client/test/simbroker.test.mjs

@@ -7,7 +7,7 @@ import path from "node:path";
 import { spawn, spawnSync } from "node:child_process";
 import { EventEmitter } from "node:events";
 
-import { createCommandRequest, executeBrokerCommand, parseArgs, streamEventsLocal } from "../command-dispatch.mjs";
+import { createCommandRequest, executeBrokerCommand, format, parseArgs, streamEventsLocal } from "../command-dispatch.mjs";
 import {
   executeServiceCommand,
   probeService,
@@ -535,7 +535,10 @@ test("bare help and doctor print human text by default and JSON with --json", ()
     assert.notEqual(result.stdout.trimStart()[0], "{");
     assert.match(result.stdout, /Usage:/);
     assert.match(result.stdout, /host/);
+    assert.match(result.stdout, /Top-level commands:/);
     assert.match(result.stdout, /doctor/);
+    assert.match(result.stdout, /simbroker <group> --help/);
+    assert.match(result.stdout, /simbroker doctor --help/);
     assert.match(result.stdout, /--json/);
   }
 
@@ -573,6 +576,54 @@ test("bare help and doctor print human text by default and JSON with --json", ()
   assert.equal(typeof doctorJson.json.stateRoot, "string");
 });
 
+test("every advertised group and doctor have a working --help page", () => {
+  const fixture = makeFixture();
+  const advertised = [
+    ["host", "host status"],
+    ["project", "project forget"],
+    ["lease", "lease contain"],
+    ["capacity", "capacity check"],
+    ["idle", "idle status"],
+    ["events", "events watch"],
+    ["pin", "pin create"],
+    ["simulators", "simulators repair"],
+    ["service", "service start"],
+    ["doctor", "doctor --json"],
+  ];
+
+  for (const [group, expectedCommand] of advertised) {
+    const human = spawnCli(fixture, group, "--help");
+    assert.equal(human.status, 0, human.stderr || human.stdout);
+    assert.notEqual(human.stdout.trimStart()[0], "{");
+    assert.match(human.stdout, /Usage:/);
+    assert.match(human.stdout, new RegExp(expectedCommand.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")));
+
+    const machine = runCli(fixture, group, "--help", "--json");
+    assert.equal(machine.status, 0, machine.stderr);
+    assert.equal(machine.json.ok, true);
+    assert.equal(machine.json.group, group);
+    assert.ok(machine.json.commands.some((command) => command.includes(expectedCommand)));
+  }
+});
+
+test("doctor human formatter names unhealthy aliases and next commands", () => {
+  const text = format({
+    hostConfigPath: "/tmp/host-config.json",
+    issues: [{
+      alias: "ui-1",
+      health: "repair-needed",
+      reasonCode: "alias-unhealthy",
+    }],
+    ok: false,
+    stateRoot: "/tmp/state",
+  });
+
+  assert.notEqual(text.trimStart()[0], "{");
+  assert.match(text, /Status: needs attention/);
+  assert.match(text, /Alias ui-1: repair-needed/);
+  assert.match(text, /simbroker simulators repair --alias ui-1/);
+});
+
 test("doctor human output reports missing registry and next commands", () => {
   const fixture = makeFixture();
 

spec/architecture.md

@@ -84,7 +84,8 @@ Does not own:
 Owns:
 
 - CLI surface for humans, agents, and shell scripts
-- stable JSON output
+- stable JSON output for mutating and status commands; `help` and `doctor`
+  default to human-readable text and keep the same payload behind `--json`
 - repo project discovery and validation
 - repo project scaffolding through `project init`
 - explicit removal of inactive local project registrations through `project forget`

spec/global-simulator-broker.md

@@ -2,8 +2,8 @@
 Related: `spec/README.md`, `spec/architecture.md`, `spec/implementation-plan.md`, `spec/build-and-test.md`, `spec/project-structure.md`, `spec/tasks/public-safe-on-demand-simulator-lifecycle.md`, `references/README.md`
 
 > **Document ID:** `GSB-001`
-> **Version:** `0.14.0`
-> **Last Updated:** `2026-08-10`
+> **Version:** `0.14.1`
+> **Last Updated:** `2026-08-18`
 > **Status:** `Draft`
 > **Owner:** `spec-steward`
 > **Implementation owners:** `spec-steward`, `ios-dev`
@@ -175,7 +175,8 @@ Current implementation slice:
 Must own:
 
 - stable human and agent CLI
-- stable JSON output
+- stable JSON output for mutating and status commands; `help` and `doctor`
+  default to human-readable text and keep the same payload behind `--json`
 - repo project discovery and validation
 - structured explain and denial reporting
 - compatibility shims for repo-owned wrappers
@@ -536,6 +537,7 @@ This repo is ready for public-source collaboration only if:
 
 | Version | Date | Summary |
 | --- | --- | --- |
+| 0.14.1 | 2026-08-18 | Help and doctor default to human-readable text; `--json` keeps the stable machine payload. |
 | 0.14.0 | 2026-08-10 | Replaced lease rotation with deterministic warm reuse, required boot-on-acquire, and added opt-in public-safe idle lifecycle, scheduler, cleanup, app, and verification contracts. |
 | 0.13.13 | 2026-08-10 | Added locked, explicit, idempotent cleanup for inactive local project registrations with lease/pin conflict protection and snapshot refresh. |
 | 0.13.12 | 2026-08-04 | Clarified startup-lock sampler timeout coverage, per-state-load stale containment budget retries, deterministic snapshot host-config fixtures, and non-remediable erase conflicts. |