@indigoai-us/hq-cli 5.50.1 → 5.51.0

package/dist/utils/version-gate.js

@@ -28,17 +28,66 @@
  * to silence both check + gate).
  */
 
-!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="d7d58261-f0e4-56bc-b6eb-4117731744f9")}catch(e){}}();
+!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="0f613895-ad4a-5211-bf75-a2e843782c47")}catch(e){}}();
 import { spawnSync } from "node:child_process";
+import { readFileSync } from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
 import chalk from "chalk";
-import { CLI_VERSION } from "../cli-version.js";
+import { CLI_NAME, CLI_VERSION } from "../cli-version.js";
 import { DEFAULT_VAULT_API_URL } from "./cognito-session.js";
 const CLIENT_ID = "hq-cli";
 const ENDPOINT_PATH = "/v1/client-version/check";
 const FETCH_TIMEOUT_MS = 3_000;
+const LATEST_PACKAGE_SPEC = `${CLI_NAME}@latest`;
 function isOptedOut() {
     return process.env.HQ_NO_UPDATE_CHECK === "1";
 }
+function findRunningPackageRoot() {
+    let dir = path.dirname(fileURLToPath(import.meta.url));
+    while (true) {
+        try {
+            const pkg = JSON.parse(readFileSync(path.join(dir, "package.json"), "utf-8"));
+            if (pkg.name === CLI_NAME)
+                return dir;
+        }
+        catch {
+            // Keep walking; compiled installs usually start under dist/.
+        }
+        const parent = path.dirname(dir);
+        if (parent === dir)
+            return null;
+        dir = parent;
+    }
+}
+export function npmPrefixFromPackageDir(pkgDir) {
+    const normalized = pkgDir.replace(/\\/g, "/").replace(/\/+$/, "");
+    const segments = normalized.split("/");
+    const nodeModulesIndex = segments.lastIndexOf("node_modules");
+    if (nodeModulesIndex === -1)
+        return null;
+    const prefixEnd = segments[nodeModulesIndex - 1] === "lib"
+        ? nodeModulesIndex - 1
+        : nodeModulesIndex;
+    const prefix = segments.slice(0, prefixEnd).join("/");
+    if (prefix === "" && normalized.startsWith("/"))
+        return "/";
+    return prefix || null;
+}
+export function resolveRunningPrefix() {
+    try {
+        const pkgRoot = findRunningPackageRoot();
+        if (!pkgRoot)
+            return null;
+        return npmPrefixFromPackageDir(pkgRoot);
+    }
+    catch {
+        return null;
+    }
+}
+export function buildPrefixedInstallArgv(prefix) {
+    return ["install", "-g", "--prefix", prefix, LATEST_PACKAGE_SPEC];
+}
 /**
  * Hit POST /v1/client-version/check. Returns the parsed body on 200, or
  * `null` on any failure (caller treats as "no gate"). Tight 3s timeout —
@@ -74,18 +123,7 @@ async function fetchVersionDecision() {
         return null;
     }
 }
-/**
- * Run the upgrade command in a blocking subprocess. Inherits stdio so the
- * user sees the npm progress. We do NOT auto-rerun the CLI on completion —
- * forcing a re-invocation would run twice on the same process and feel
- * janky; instead we print a clear "rerun your command" message and exit.
- */
-function performUpdate(command) {
-    const parts = command.split(/\s+/).filter(Boolean);
-    if (parts.length === 0)
-        return { ok: false, detail: "empty command" };
-    const cmd = parts[0];
-    const args = parts.slice(1);
+function runUpdateCommand(cmd, args) {
     try {
         const result = spawnSync(cmd, args, { stdio: "inherit" });
         if (result.status !== 0) {
@@ -100,6 +138,17 @@ function performUpdate(command) {
         return { ok: false, detail: err instanceof Error ? err.message : String(err) };
     }
 }
+function performUpdateCommand(cmd, args, runner = runUpdateCommand) {
+    return runner(cmd, args);
+}
+function performUpdate(command, runner = runUpdateCommand) {
+    const parts = command.split(/\s+/).filter(Boolean);
+    if (parts.length === 0)
+        return { ok: false, detail: "empty command" };
+    const cmd = parts[0];
+    const args = parts.slice(1);
+    return performUpdateCommand(cmd, args, runner);
+}
 /**
  * Soft notify when the server says we're below `latestVersion` but still ≥
  * `minVersion`. Single chalk-yellow line on stderr; never blocks.
@@ -121,24 +170,40 @@ function nudgeUpdateRecommended(decision) {
  *   0 — update succeeded; user must rerun their command
  *   75 — update failed (EX_TEMPFAIL; common for sudo/EACCES on system npm)
  */
-function enforceUpdateRequired(decision) {
+function enforceUpdateRequired(decision, deps = {}) {
     const banner = chalk.red.bold(`✗ hq-cli ${decision.currentVersion} is below the minimum required version (${decision.minVersion}).`);
     console.error(banner);
     if (decision.message)
         console.error(chalk.dim(`  ${decision.message}`));
     const command = decision.updateCommand;
-    if (!command) {
+    const prefix = (deps.resolvePrefix ?? resolveRunningPrefix)();
+    if (!command && !prefix) {
         console.error(chalk.red("  No updateCommand provided by hq-pro — see https://hq.indigo.ai/docs/cli-update for manual steps."));
         if (decision.downloadUrl) {
             console.error(chalk.dim(`  Download: ${decision.downloadUrl}`));
         }
         process.exit(75);
     }
-    console.error(chalk.dim(`  Running: ${command}`));
-    const result = performUpdate(command);
+    const runner = deps.runner ?? runUpdateCommand;
+    const result = prefix
+        ? (() => {
+            const args = buildPrefixedInstallArgv(prefix);
+            console.error(chalk.dim(`  Installing into npm prefix: ${prefix}`));
+            console.error(chalk.dim(`  Running: npm ${args.join(" ")}`));
+            return performUpdateCommand("npm", args, runner);
+        })()
+        : (() => {
+            console.error(chalk.dim(`  Running: ${command}`));
+            return deps.performUpdateString
+                ? deps.performUpdateString(command)
+                : performUpdate(command, runner);
+        })();
     if (!result.ok) {
         console.error(chalk.red(`✗ Update failed${result.detail ? `: ${result.detail}` : ""}.`));
-        console.error(chalk.dim(`  Try manually: ${command}`));
+        const manual = prefix
+            ? `npm ${buildPrefixedInstallArgv(prefix).join(" ")}`
+            : command;
+        console.error(chalk.dim(`  Try manually: ${manual}`));
         process.exit(75);
     }
     console.error(chalk.green(`✓ Updated to hq-cli ${decision.latestVersion}. Rerun your command.`));
@@ -179,7 +244,13 @@ export const __test__ = {
     CLIENT_ID,
     ENDPOINT_PATH,
     FETCH_TIMEOUT_MS,
+    buildPrefixedInstallArgv,
+    enforceUpdateRequired,
+    npmPrefixFromPackageDir,
     performUpdate,
+    performUpdateCommand,
+    runUpdateCommand,
+    resolveRunningPrefix,
 };
 //# sourceMappingURL=version-gate.js.map
-//# debugId=d7d58261-f0e4-56bc-b6eb-4117731744f9
+//# debugId=0f613895-ad4a-5211-bf75-a2e843782c47

package/e2e/cli.test.ts

@@ -41,6 +41,31 @@ function runHq(args: string[], options: { cwd?: string; env?: NodeJS.ProcessEnv
   });
 }
 
+// Spawn the built CLI with its stdout read-end closed immediately, so the
+// child's first write to stdout hits EPIPE — the `hq … | head` / `source <(hq
+// …)` scenario behind HQ-6B. Returns the child's own exit code + stderr.
+function runHqWithClosedStdout(args: string[]) {
+  return new Promise<{ code: number | null; stderr: string }>(
+    (resolve, reject) => {
+      const child = spawn(process.execPath, [cliEntry, ...args], {
+        env: { ...process.env, HQ_NO_UPDATE_CHECK: "1" },
+        stdio: ["ignore", "pipe", "pipe"],
+      });
+      let stderr = "";
+      child.stderr.setEncoding("utf8");
+      child.stderr.on("data", (chunk) => {
+        stderr += chunk;
+      });
+      // Close the read end up front (and again on any byte that slips through)
+      // so subsequent writes by the child fail with EPIPE.
+      child.stdout.on("data", () => child.stdout.destroy());
+      child.stdout.destroy();
+      child.on("error", reject);
+      child.on("close", (code) => resolve({ code, stderr }));
+    },
+  );
+}
+
 async function makeTempDir(prefix: string) {
   const dir = await mkdtemp(path.join(tmpdir(), prefix));
   tempDirs.push(dir);
@@ -62,6 +87,16 @@ describe("built hq CLI", () => {
     expect(result.stdout).toContain("whoami");
   });
 
+  it("exits cleanly when the downstream reader closes the pipe (HQ-6B)", async () => {
+    // Regression for HQ-6B: a closed stdout reader must NOT crash the CLI with
+    // a fatal `write EPIPE`. The process should exit 0 with no EPIPE traceback.
+    const { code, stderr } = await runHqWithClosedStdout(["--help"]);
+
+    expect(code).toBe(0);
+    expect(stderr).not.toMatch(/EPIPE/);
+    expect(stderr).not.toMatch(/Error:/);
+  });
+
   it("prints the package version from the built entrypoint", async () => {
     const result = await runHq(["--version"]);
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@indigoai-us/hq-cli",
-  "version": "5.50.1",
+  "version": "5.51.0",
   "description": "HQ by Indigo management CLI — modules and cloud sync",
   "main": "dist/index.js",
   "bin": {

package/src/bin/hq-auth-refresh.ts

@@ -12,6 +12,9 @@
  * non-interactively.
  */
 
+// MUST be first: guard the Node version before any dependency that needs a
+// Node 20+ API (e.g. util.styleText) or a newer native ABI is evaluated.
+import "../node-preflight.js";
 import { initSentry, Sentry } from "../sentry.js";
 import { refreshCachedSession } from "../utils/cognito-session.js";
 

package/src/commands/members.test.ts

@@ -38,6 +38,7 @@ import {
   formatInviteHttpError,
   getCallerPersonUid,
   inviteMember,
+  listActiveMembers,
   listPendingInvites,
   registerMembersCommand,
   resendInvite,
@@ -743,6 +744,181 @@ describe("listPendingInvites", () => {
   });
 });
 
+// ---------------------------------------------------------------------------
+// listActiveMembers
+// ---------------------------------------------------------------------------
+
+describe("listActiveMembers", () => {
+  it("GETs /membership/company/{uid} and returns the members array", async () => {
+    fetchSpy.mockResolvedValueOnce(
+      jsonResponse(200, {
+        members: [
+          {
+            membershipKey: "k1",
+            personUid: "prs_alice",
+            companyUid: "cmp_acme",
+            role: "owner",
+            status: "active",
+            personEmail: "alice@example.com",
+            personName: "Alice",
+          },
+        ],
+      }),
+    );
+
+    const members = await listActiveMembers("test-token", "cmp_acme");
+
+    const call = fetchSpy.mock.calls[0];
+    expect(String(call[0])).toMatch(/\/membership\/company\/cmp_acme$/);
+    expect(members).toHaveLength(1);
+    expect(members[0].personEmail).toBe("alice@example.com");
+    expect(members[0].role).toBe("owner");
+  });
+
+  it("returns [] when the members key is missing", async () => {
+    fetchSpy.mockResolvedValueOnce(jsonResponse(200, {}));
+    await expect(
+      listActiveMembers("test-token", "cmp_acme"),
+    ).resolves.toEqual([]);
+  });
+
+  it("returns [] when members is null", async () => {
+    fetchSpy.mockResolvedValueOnce(jsonResponse(200, { members: null }));
+    await expect(
+      listActiveMembers("test-token", "cmp_acme"),
+    ).resolves.toEqual([]);
+  });
+
+  it("throws InviteHttpError on non-ok", async () => {
+    fetchSpy.mockResolvedValueOnce(jsonResponse(403, { error: "forbidden" }));
+    await expect(
+      listActiveMembers("test-token", "cmp_acme"),
+    ).rejects.toBeInstanceOf(InviteHttpError);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// registerMembersCommand list
+// ---------------------------------------------------------------------------
+
+describe("registerMembersCommand list", () => {
+  it("defaults to ACTIVE members: renders EMAIL/ROLE/NAME + the share hint", async () => {
+    fetchSpy.mockResolvedValueOnce(
+      jsonResponse(200, {
+        members: [
+          {
+            membershipKey: "k1",
+            personUid: "prs_alice",
+            companyUid: "cmp_acme",
+            role: "owner",
+            status: "active",
+            personEmail: "alice@example.com",
+            personName: "Alice",
+          },
+          {
+            membershipKey: "k2",
+            personUid: "prs_bob",
+            companyUid: "cmp_acme",
+            role: "member",
+            status: "active",
+            personSlug: "bob",
+          },
+        ],
+      }),
+    );
+    const logSpy = vi.spyOn(console, "log").mockImplementation(() => undefined);
+    const errSpy = vi.spyOn(console, "error").mockImplementation(() => undefined);
+
+    await buildMembersProgram().parseAsync(
+      ["members", "--company", "acme", "list"],
+      { from: "user" },
+    );
+
+    const call = fetchSpy.mock.calls[0];
+    expect(String(call[0])).toMatch(/\/membership\/company\/cmp_acme$/);
+    const output = logSpy.mock.calls.map((c) => String(c[0])).join("\n");
+    expect(output).toContain("EMAIL");
+    expect(output).toContain("ROLE");
+    expect(output).toContain("NAME");
+    expect(output).toContain("alice@example.com");
+    expect(output).toContain("owner");
+    expect(output).toContain("Alice");
+    // unresolved email falls back to personUid; name falls back to slug
+    expect(output).toContain("prs_bob");
+    expect(output).toContain("bob");
+    expect(output).toContain(
+      "hq secrets share <path> --with <email>",
+    );
+    expect(errSpy).not.toHaveBeenCalled();
+  });
+
+  it("default active: empty roster prints the no-active-members message", async () => {
+    fetchSpy.mockResolvedValueOnce(jsonResponse(200, { members: [] }));
+    const logSpy = vi.spyOn(console, "log").mockImplementation(() => undefined);
+
+    await buildMembersProgram().parseAsync(
+      ["members", "--company", "acme", "list"],
+      { from: "user" },
+    );
+
+    expect(logSpy).toHaveBeenCalledWith(
+      expect.stringContaining("No active members found for this company."),
+    );
+  });
+
+  it("--pending preserves the OLD pending-invites table verbatim", async () => {
+    fetchSpy.mockResolvedValueOnce(
+      jsonResponse(200, {
+        pending: [
+          {
+            membershipKey: "email:alice@example.com#cmp_acme",
+            inviteeEmail: "alice@example.com",
+            companyUid: "cmp_acme",
+            role: "member",
+            status: "pending",
+            invitedBy: "prs_admin",
+            invitedAt: "2026-05-21T12:00:00Z",
+          },
+        ],
+      }),
+    );
+    const logSpy = vi.spyOn(console, "log").mockImplementation(() => undefined);
+    const errSpy = vi.spyOn(console, "error").mockImplementation(() => undefined);
+
+    await buildMembersProgram().parseAsync(
+      ["members", "--company", "acme", "list", "--pending"],
+      { from: "user" },
+    );
+
+    const call = fetchSpy.mock.calls[0];
+    expect(String(call[0])).toMatch(
+      /\/membership\/company\/cmp_acme\/pending$/,
+    );
+    const output = logSpy.mock.calls.map((c) => String(c[0])).join("\n");
+    expect(output).toContain("TARGET");
+    expect(output).toContain("INVITED_BY");
+    expect(output).toContain("MEMBERSHIP_KEY");
+    expect(output).toContain("alice@example.com");
+    // the active-only share hint must NOT appear in the pending view
+    expect(output).not.toContain("hq secrets share");
+    expect(errSpy).not.toHaveBeenCalled();
+  });
+
+  it("--pending: empty invites prints the no-pending-invites message", async () => {
+    fetchSpy.mockResolvedValueOnce(jsonResponse(200, { pending: [] }));
+    const logSpy = vi.spyOn(console, "log").mockImplementation(() => undefined);
+
+    await buildMembersProgram().parseAsync(
+      ["members", "--company", "acme", "list", "--pending"],
+      { from: "user" },
+    );
+
+    expect(logSpy).toHaveBeenCalledWith(
+      expect.stringContaining("No pending invites for this company."),
+    );
+  });
+});
+
 // ---------------------------------------------------------------------------
 // revokeInvite
 // ---------------------------------------------------------------------------

package/src/commands/members.ts

@@ -31,6 +31,23 @@ interface MyMembership {
   status: string;
 }
 
+/**
+ * An ACTIVE member of a company, as returned by
+ * `GET /membership/company/{companyUid}`. The server filters to
+ * `status: "active"` and enriches each row with resolved person metadata
+ * (`personEmail` / `personName` / `personSlug`) when available.
+ */
+export interface ActiveMember {
+  membershipKey: string;
+  personUid: string;
+  companyUid: string;
+  role: string;
+  status: string;
+  personEmail?: string;
+  personName?: string;
+  personSlug?: string;
+}
+
 export interface InviteOptions {
   target: string;
   role: string;
@@ -374,6 +391,30 @@ export async function listPendingInvites(
   return data?.pending ?? data?.invites ?? [];
 }
 
+export async function listActiveMembers(
+  token: string,
+  companyUid: string,
+): Promise<ActiveMember[]> {
+  const res = await vaultApiFetch({
+    token,
+    path: `/membership/company/${encodeURIComponent(companyUid)}`,
+  });
+  if (!res.ok) {
+    const err = (await res.json().catch(() => ({}))) as Record<string, string>;
+    throw new InviteHttpError(
+      res.status,
+      err.message ?? err.error ?? res.statusText,
+      err.code,
+    );
+  }
+  // Server schema: `{ members: [...] }` — active members only, enriched with
+  // resolved person metadata (personEmail / personName / personSlug).
+  const data = (await res.json()) as {
+    members?: ActiveMember[] | null;
+  };
+  return data?.members ?? [];
+}
+
 /**
  * Resolve a `revoke` CLI argument into the canonical `membershipKey` shape
  * the server requires. Accepts three input forms:
@@ -746,55 +787,99 @@ export function registerMembersCommand(program: Command): void {
 
   members
     .command("list")
-    .description("List pending invites for the company")
-    .action(async () => {
+    .description(
+      "List the company's active members (use --pending for pending invites)",
+    )
+    .option("--pending", "List pending invites instead of active members")
+    .action(async (opts: { pending?: boolean }) => {
       try {
         const token = await ensureCognitoToken();
         const companySlug = members.opts().company as string | undefined;
         const companyUid = await getCompanyUid(token, companySlug);
 
-        const invites = await listPendingInvites(token, companyUid);
+        if (opts.pending) {
+          // --pending: preserve the original pending-invites view verbatim.
+          const invites = await listPendingInvites(token, companyUid);
+
+          if (invites.length === 0) {
+            console.log(chalk.gray("No pending invites for this company."));
+            return;
+          }
 
-        if (invites.length === 0) {
-          console.log(chalk.gray("No pending invites for this company."));
+          const targetW = Math.max(
+            6,
+            ...invites.map((i) => (i.inviteeEmail ?? i.personUid ?? "").length),
+          );
+          const roleW = Math.max(4, ...invites.map((i) => i.role.length));
+          const byW = Math.max(10, ...invites.map((i) => i.invitedBy.length));
+          const keyW = Math.max(
+            14,
+            ...invites.map((i) => i.membershipKey.length),
+          );
+          console.log(
+            chalk.bold(
+              [
+                "TARGET".padEnd(targetW),
+                "ROLE".padEnd(roleW),
+                "INVITED_BY".padEnd(byW),
+                "INVITED_AT",
+                "MEMBERSHIP_KEY".padEnd(keyW),
+              ].join("  "),
+            ),
+          );
+          for (const inv of invites) {
+            const target = inv.inviteeEmail ?? inv.personUid ?? "";
+            console.log(
+              [
+                target.padEnd(targetW),
+                inv.role.padEnd(roleW),
+                inv.invitedBy.padEnd(byW),
+                shortDate(inv.invitedAt),
+                inv.membershipKey.padEnd(keyW),
+              ].join("  "),
+            );
+          }
           return;
         }
 
-        const targetW = Math.max(
-          6,
-          ...invites.map((i) => (i.inviteeEmail ?? i.personUid ?? "").length),
+        // Default: list ACTIVE members so their emails drop straight into
+        // `hq secrets share <path> --with <email>`.
+        const activeMembers = await listActiveMembers(token, companyUid);
+
+        if (activeMembers.length === 0) {
+          console.log(chalk.gray("No active members found for this company."));
+          return;
+        }
+
+        const emailW = Math.max(
+          5,
+          ...activeMembers.map((m) => (m.personEmail ?? m.personUid).length),
         );
-        const roleW = Math.max(4, ...invites.map((i) => i.role.length));
-        const byW = Math.max(10, ...invites.map((i) => i.invitedBy.length));
-        const keyW = Math.max(14, ...invites.map((i) => i.membershipKey.length));
+        const roleW = Math.max(4, ...activeMembers.map((m) => m.role.length));
         console.log(
           chalk.bold(
-            [
-              "TARGET".padEnd(targetW),
-              "ROLE".padEnd(roleW),
-              "INVITED_BY".padEnd(byW),
-              "INVITED_AT",
-              "MEMBERSHIP_KEY".padEnd(keyW),
-            ].join("  "),
+            ["EMAIL".padEnd(emailW), "ROLE".padEnd(roleW), "NAME"].join("  "),
           ),
         );
-        for (const inv of invites) {
-          const target = inv.inviteeEmail ?? inv.personUid ?? "";
+        for (const m of activeMembers) {
+          const email = m.personEmail ?? m.personUid;
+          const name = m.personName ?? m.personSlug ?? "";
           console.log(
-            [
-              target.padEnd(targetW),
-              inv.role.padEnd(roleW),
-              inv.invitedBy.padEnd(byW),
-              shortDate(inv.invitedAt),
-              inv.membershipKey.padEnd(keyW),
-            ].join("  "),
+            [email.padEnd(emailW), m.role.padEnd(roleW), name].join("  "),
           );
         }
+        console.log(
+          chalk.gray(
+            "Share a secret with a member: hq secrets share <path> --with <email>",
+          ),
+        );
       } catch (err) {
         if (err instanceof InviteHttpError) {
           const msg =
             err.status === 403
-              ? "Not authorized — only admins and owners can list invites"
+              ? opts.pending
+                ? "Not authorized — only admins and owners can list invites"
+                : "Not authorized — only company members can list members"
               : formatInviteHttpError(err.status, err.message);
           console.error(chalk.red(msg));
           process.exit(1);

package/src/commands/onboard-warning.test.ts

@@ -0,0 +1,26 @@
+import { describe, expect, it } from "vitest";
+
+import { buildCreateCompanyWarning } from "./onboard-warning.js";
+
+describe("buildCreateCompanyWarning", () => {
+  it("documents the warning shown on the create-company path", () => {
+    const warning = buildCreateCompanyWarning();
+    expect(warning).toContain("NEW company");
+    expect(warning).toMatch(/does NOT join an existing one/i);
+  });
+
+  it("advises existing-company users to ask an admin or owner for an invite", () => {
+    const warning = buildCreateCompanyWarning();
+    expect(warning).toMatch(/ask your admin or owner.*invite/i);
+  });
+
+  it("tells invitees to run hq sync after accepting", () => {
+    const warning = buildCreateCompanyWarning();
+    expect(warning).toContain("accept it and run `hq sync`");
+  });
+
+  it("warns that duplicate creation leaves the user alone in a separate company", () => {
+    const warning = buildCreateCompanyWarning();
+    expect(warning).toMatch(/separate one you'd be alone in/i);
+  });
+});

package/src/commands/onboard-warning.ts

@@ -0,0 +1,12 @@
+/**
+ * Builds the static create-time warning surfaced by both `create-company` and
+ * `dry-run`, because users may accidentally create duplicate companies instead
+ * of joining the existing company they were invited to.
+ */
+export function buildCreateCompanyWarning(): string {
+  return (
+    "  This creates a NEW company that you own — it does NOT join an existing one.\n" +
+    "  If your company already uses HQ, do NOT create it again: ask your admin or owner to send you an invite, then accept it and run `hq sync` to pull the existing company.\n" +
+    "  Creating a same-named company makes a separate one you'd be alone in.\n"
+  );
+}

package/src/commands/onboard.ts

@@ -32,6 +32,7 @@ import {
 import { createDefaultVaultClient } from "./cloud-provision.js";
 import { detectOnboardingIdentityMismatch } from "./onboard-identity-guard.js";
 import { planOnboardJoin } from "./onboard-join.js";
+import { buildCreateCompanyWarning } from "./onboard-warning.js";
 
 // ---------------------------------------------------------------------------
 // Command registration
@@ -70,13 +71,7 @@ export function registerOnboardCommand(program: Command): void {
         console.log(`  Company:  ${options.name} (${options.slug})`);
         console.log(`  Person:   ${options.personName} <${options.email}>`);
         console.log(`  HQ root:  ${options.hqRoot}\n`);
-        console.log(
-          chalk.gray(
-            "  This creates a NEW company you own. Joining a teammate's existing\n" +
-              "  company? Stop — accept your invite, then run `hq sync` to pull it.\n" +
-              "  Creating a same-named company leaves you alone in a separate one.\n",
-          ),
-        );
+        console.log(chalk.gray(buildCreateCompanyWarning()));
 
         const accessToken = await ensureCognitoToken();
         const result = await runOnboardCli({
@@ -248,6 +243,8 @@ export function registerOnboardCommand(program: Command): void {
     )
     .action(async (options: { hqRoot: string }) => {
       try {
+        console.log(chalk.gray(buildCreateCompanyWarning()));
+
         // No auth needed for dry-run — runOnboardCli handles this branch
         // without touching the vault-service.
         const result = await runOnboardCli({