@indigoai-us/hq-cli 5.58.0 → 5.58.1

package/dist/commands/people.d.ts

@@ -6,21 +6,25 @@
  *   hq people search <keyword> [--company <slug>] [--json]
  *   hq people resolve <name>   [--company <slug>] [--json]
  *
- * Source of truth is `companies/<company>/people/<person>/meta.yaml`. Every
- * subcommand operates on exactly ONE company (the active company, or the one
- * named by `--company`); nothing reads across company boundaries.
+ * Local records from `companies/<company>/people/<person>/meta.yaml` are the
+ * curated primary source. On misses, commands may fall back to the membership
+ * roster for exactly ONE company (the active company, or the one named by
+ * `--company`); nothing reads across company boundaries.
  */
 import { Command } from "commander";
+import { type ActiveMember } from "./members.js";
 import { resolveNameToEmail, type PersonRecord } from "../utils/people.js";
-export type RefreshPeopleRoster = (hqRoot: string, companySlug: string) => Promise<void>;
+export type FetchPeopleRoster = (hqRoot: string, companySlug: string) => Promise<PersonRecord[]>;
 interface PeopleCommandDeps {
-    refreshRoster?: RefreshPeopleRoster;
+    fetchRoster?: FetchPeopleRoster;
 }
 interface PeopleLookupOpts {
     localOnly?: boolean;
     json?: boolean;
 }
-export declare function refreshPeopleRosterFromCloud(hqRoot: string, companySlug: string): Promise<void>;
+export declare function activeMemberToPersonRecord(m: ActiveMember): PersonRecord | null;
+export declare function fetchMembershipRoster(hqRoot: string, companySlug: string): Promise<PersonRecord[]>;
+export declare function mergePeople(primary: PersonRecord[], extra: PersonRecord[]): PersonRecord[];
 /**
  * Resolve the single company to operate on. Explicit `--company` always wins
  * (after a path-safety check). Otherwise the active company is inferred from
@@ -33,14 +37,14 @@ export declare function resolvePersonWithRosterFallback(input: {
     slug: string;
     name: string;
     opts?: PeopleLookupOpts;
-    refreshRoster?: RefreshPeopleRoster;
+    fetchRoster?: FetchPeopleRoster;
 }): Promise<ReturnType<typeof resolveNameToEmail>>;
 export declare function searchPeopleWithRosterFallback(input: {
     hqRoot: string;
     slug: string;
     keyword: string;
     opts?: PeopleLookupOpts;
-    refreshRoster?: RefreshPeopleRoster;
+    fetchRoster?: FetchPeopleRoster;
 }): Promise<PersonRecord[]>;
 export declare function registerPeopleCommand(program: Command, deps?: PeopleCommandDeps): void;
 export {};

package/dist/commands/people.js

@@ -6,35 +6,73 @@
  *   hq people search <keyword> [--company <slug>] [--json]
  *   hq people resolve <name>   [--company <slug>] [--json]
  *
- * Source of truth is `companies/<company>/people/<person>/meta.yaml`. Every
- * subcommand operates on exactly ONE company (the active company, or the one
- * named by `--company`); nothing reads across company boundaries.
+ * Local records from `companies/<company>/people/<person>/meta.yaml` are the
+ * curated primary source. On misses, commands may fall back to the membership
+ * roster for exactly ONE company (the active company, or the one named by
+ * `--company`); nothing reads across company boundaries.
  */
 
-!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]="79abc1f5-4f5a-5c95-b29b-10f04417355f")}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]="555055d9-98e2-5fcd-b736-4b1df12daf4d")}catch(e){}}();
 import * as fs from "fs";
 import { Option } from "commander";
 import chalk from "chalk";
-import { VaultClient } from "@indigoai-us/hq-cloud";
 import * as yaml from "js-yaml";
 import { findHqRoot } from "../utils/manifest.js";
 import { manifestPath } from "./cloud-provision.js";
-import { DEFAULT_COGNITO, buildVaultConfig, ensureCognitoToken, } from "../utils/cognito-session.js";
+import { ensureCognitoToken } from "../utils/cognito-session.js";
 import { getCompanyUid } from "../utils/vault-api.js";
-import { createCompanyPresignClient, runGet } from "./files-browse.js";
+import { listActiveMembers } from "./members.js";
 import { assertSafeCompanySlug, listCompanyPeople, searchPeople, resolveNameToEmail, companyPeopleDir, } from "../utils/people.js";
-export async function refreshPeopleRosterFromCloud(hqRoot, companySlug) {
-    const accessToken = await ensureCognitoToken();
-    const client = new VaultClient(buildVaultConfig(accessToken));
-    await getCompanyUid(accessToken, companySlug);
-    await runGet({
-        path: `companies/${companySlug}/people/`,
-        hqRoot,
-        companySlug,
-        vaultClient: client,
-        companyClient: ({ companyUid }) => createCompanyPresignClient({ token: accessToken, companyUid }),
-        region: DEFAULT_COGNITO.region,
-    });
+function slugify(value) {
+    return value
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, "-")
+        .replace(/-+/g, "-")
+        .replace(/^-|-$/g, "");
+}
+export function activeMemberToPersonRecord(m) {
+    const name = m.personName?.trim() ||
+        m.personEmail?.trim() ||
+        m.personSlug?.trim() ||
+        "";
+    if (!name)
+        return null;
+    const email = m.personEmail?.trim() || undefined;
+    const slug = m.personSlug?.trim() || slugify(name) || m.personUid;
+    return {
+        slug,
+        name,
+        email,
+        role: m.role || undefined,
+        type: "internal",
+        source: `hq-pro membership: /membership/company/${m.companyUid}`,
+    };
+}
+export async function fetchMembershipRoster(hqRoot, companySlug) {
+    void hqRoot;
+    const token = await ensureCognitoToken();
+    const companyUid = await getCompanyUid(token, companySlug);
+    const members = await listActiveMembers(token, companyUid);
+    return members
+        .map(activeMemberToPersonRecord)
+        .filter((r) => r !== null);
+}
+function personIdentityKey(person) {
+    return (person.email?.toLowerCase() ||
+        person.slug?.toLowerCase() ||
+        person.name.toLowerCase());
+}
+export function mergePeople(primary, extra) {
+    const seen = new Set(primary.map(personIdentityKey));
+    const merged = [...primary];
+    for (const person of extra) {
+        const key = personIdentityKey(person);
+        if (seen.has(key))
+            continue;
+        seen.add(key);
+        merged.push(person);
+    }
+    return merged;
 }
 /** Companies that still exist (anything not explicitly `status: archived`). */
 function activeCompanySlugs(manifest) {
@@ -103,37 +141,38 @@ function fail(message) {
     console.error(chalk.red(message));
     process.exit(1);
 }
-function logRefreshFailure(companySlug, err) {
+function logRosterFetchFailure(companySlug, err) {
     const message = err instanceof Error ? err.message : String(err);
-    console.error(chalk.dim(`  Could not refresh people roster for '${companySlug}': ${message}`));
+    console.error(chalk.dim(`  Could not fetch people roster for '${companySlug}': ${message}`));
 }
-async function tryRefreshRoster(refreshRoster, hqRoot, slug) {
+async function tryFetchRoster(fetchRoster, hqRoot, slug) {
     try {
-        await refreshRoster(hqRoot, slug);
-        return true;
+        return await fetchRoster(hqRoot, slug);
     }
     catch (err) {
-        logRefreshFailure(slug, err);
-        return false;
+        logRosterFetchFailure(slug, err);
+        return null;
     }
 }
 export async function resolvePersonWithRosterFallback(input) {
-    const local = resolveNameToEmail(listCompanyPeople(input.hqRoot, input.slug), input.name);
+    const localPeople = listCompanyPeople(input.hqRoot, input.slug);
+    const local = resolveNameToEmail(localPeople, input.name);
     if (local.status !== "not_found" || input.opts?.localOnly)
         return local;
-    const refreshed = await tryRefreshRoster(input.refreshRoster ?? refreshPeopleRosterFromCloud, input.hqRoot, input.slug);
-    if (!refreshed)
+    const roster = await tryFetchRoster(input.fetchRoster ?? fetchMembershipRoster, input.hqRoot, input.slug);
+    if (!roster)
         return local;
-    return resolveNameToEmail(listCompanyPeople(input.hqRoot, input.slug), input.name);
+    return resolveNameToEmail(mergePeople(localPeople, roster), input.name);
 }
 export async function searchPeopleWithRosterFallback(input) {
-    const local = searchPeople(listCompanyPeople(input.hqRoot, input.slug), input.keyword);
+    const localPeople = listCompanyPeople(input.hqRoot, input.slug);
+    const local = searchPeople(localPeople, input.keyword);
     if (local.length > 0 || input.opts?.localOnly)
         return local;
-    const refreshed = await tryRefreshRoster(input.refreshRoster ?? refreshPeopleRosterFromCloud, input.hqRoot, input.slug);
-    if (!refreshed)
+    const roster = await tryFetchRoster(input.fetchRoster ?? fetchMembershipRoster, input.hqRoot, input.slug);
+    if (!roster)
         return local;
-    return searchPeople(listCompanyPeople(input.hqRoot, input.slug), input.keyword);
+    return searchPeople(mergePeople(localPeople, roster), input.keyword);
 }
 export function registerPeopleCommand(program, deps = {}) {
     const people = program
@@ -147,12 +186,19 @@ export function registerPeopleCommand(program, deps = {}) {
         .command("list")
         .description("List all people recorded for the company")
         .option("--json", "Output JSON instead of a table")
-        .action((opts) => {
+        .option("--local-only", "Skip network fallback; list only the local people roster")
+        .action(async (opts) => {
         try {
             const scope = people.opts();
             const hqRoot = resolveHqRoot(scope);
             const slug = resolveCompanySlug(hqRoot, scope.company);
-            const records = listCompanyPeople(hqRoot, slug);
+            let records = listCompanyPeople(hqRoot, slug);
+            if (!opts.localOnly) {
+                const roster = await tryFetchRoster(deps.fetchRoster ?? fetchMembershipRoster, hqRoot, slug);
+                if (roster)
+                    records = mergePeople(records, roster);
+            }
+            records = records.sort((a, b) => a.name.localeCompare(b.name));
             if (opts.json) {
                 console.log(JSON.stringify(records, null, 2));
                 return;
@@ -171,7 +217,7 @@ export function registerPeopleCommand(program, deps = {}) {
         .command("search <keyword>")
         .description("Keyword search over people names and emails")
         .option("--json", "Output JSON instead of a table")
-        .option("--local-only", "Skip cloud fallback; search only the local people roster")
+        .option("--local-only", "Skip network fallback; search only the local people roster")
         .action(async (keyword, opts) => {
         try {
             const scope = people.opts();
@@ -182,7 +228,7 @@ export function registerPeopleCommand(program, deps = {}) {
                 slug,
                 keyword,
                 opts,
-                refreshRoster: deps.refreshRoster,
+                fetchRoster: deps.fetchRoster,
             });
             if (opts.json) {
                 console.log(JSON.stringify(matches, null, 2));
@@ -202,7 +248,7 @@ export function registerPeopleCommand(program, deps = {}) {
         .command("resolve <name>")
         .description("Resolve a person name to their email address")
         .option("--json", "Output JSON instead of plain text")
-        .option("--local-only", "Skip cloud fallback; resolve only from the local people roster")
+        .option("--local-only", "Skip network fallback; resolve only from the local people roster")
         .action(async (name, opts) => {
         try {
             const scope = people.opts();
@@ -213,7 +259,7 @@ export function registerPeopleCommand(program, deps = {}) {
                 slug,
                 name,
                 opts,
-                refreshRoster: deps.refreshRoster,
+                fetchRoster: deps.fetchRoster,
             });
             if (opts.json) {
                 console.log(JSON.stringify(result, null, 2));
@@ -247,4 +293,4 @@ export function registerPeopleCommand(program, deps = {}) {
     });
 }
 //# sourceMappingURL=people.js.map
-//# debugId=79abc1f5-4f5a-5c95-b29b-10f04417355f
+//# debugId=555055d9-98e2-5fcd-b736-4b1df12daf4d

package/package.json

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

package/src/commands/people.test.ts

@@ -20,10 +20,13 @@ import {
   type PersonRecord,
 } from "../utils/people.js";
 import {
+  activeMemberToPersonRecord,
+  mergePeople,
   registerPeopleCommand,
   resolveCompanySlug,
-  type RefreshPeopleRoster,
+  type FetchPeopleRoster,
 } from "./people.js";
+import type { ActiveMember } from "./members.js";
 
 // ---------------------------------------------------------------------------
 // Filesystem fixture helpers
@@ -335,11 +338,119 @@ describe("companyPeopleDir", () => {
   });
 });
 
+// ---------------------------------------------------------------------------
+// Membership roster fallback helpers
+// ---------------------------------------------------------------------------
+
+function rosterPerson(overrides: Partial<PersonRecord>): PersonRecord {
+  return {
+    slug: "ada-lovelace",
+    name: "Ada Lovelace",
+    email: "ada@acme.com",
+    type: "internal",
+    source: "test roster",
+    ...overrides,
+  };
+}
+
+describe("activeMemberToPersonRecord", () => {
+  const base: ActiveMember = {
+    membershipKey: "m_1",
+    personUid: "prs_123",
+    companyUid: "co_123",
+    role: "admin",
+    status: "active",
+  };
+
+  it("maps membership person fields into an internal person record", () => {
+    expect(
+      activeMemberToPersonRecord({
+        ...base,
+        personName: " Ada Lovelace ",
+        personEmail: " ada@acme.com ",
+        personSlug: " ada ",
+      }),
+    ).toEqual({
+      slug: "ada",
+      name: "Ada Lovelace",
+      email: "ada@acme.com",
+      role: "admin",
+      type: "internal",
+      source: "hq-pro membership: /membership/company/co_123",
+    });
+  });
+
+  it("falls back from name to email to slug, and slugifies names", () => {
+    expect(
+      activeMemberToPersonRecord({
+        ...base,
+        personName: "Grace Hopper",
+        personEmail: "grace@acme.com",
+      }),
+    ).toMatchObject({ name: "Grace Hopper", slug: "grace-hopper" });
+
+    expect(
+      activeMemberToPersonRecord({
+        ...base,
+        personEmail: "only-email@acme.com",
+      }),
+    ).toMatchObject({ name: "only-email@acme.com", slug: "only-email-acme-com" });
+
+    expect(
+      activeMemberToPersonRecord({
+        ...base,
+        personSlug: "only-slug",
+      }),
+    ).toMatchObject({ name: "only-slug", slug: "only-slug" });
+  });
+
+  it("returns null when all name-like fields are empty", () => {
+    expect(
+      activeMemberToPersonRecord({
+        ...base,
+        personName: " ",
+        personEmail: "",
+        personSlug: "   ",
+      }),
+    ).toBeNull();
+  });
+});
+
+describe("mergePeople", () => {
+  it("deduplicates by email, slug, then name with primary records winning", () => {
+    const primary = [
+      rosterPerson({
+        slug: "local-email",
+        name: "Local Email",
+        email: "same@acme.com",
+        role: "CEO",
+      }),
+      rosterPerson({ slug: "same-slug", name: "Local Slug", email: undefined }),
+      rosterPerson({ slug: "", name: "Same Name", email: undefined }),
+    ];
+    const extra = [
+      rosterPerson({
+        slug: "remote-email",
+        name: "Remote Email",
+        email: "SAME@acme.com",
+      }),
+      rosterPerson({ slug: "SAME-SLUG", name: "Remote Slug", email: undefined }),
+      rosterPerson({ slug: "", name: "same name", email: undefined }),
+      rosterPerson({ slug: "new-person", name: "New Person", email: undefined }),
+    ];
+
+    expect(mergePeople(primary, extra)).toEqual([
+      ...primary,
+      rosterPerson({ slug: "new-person", name: "New Person", email: undefined }),
+    ]);
+  });
+});
+
 // ---------------------------------------------------------------------------
 // Wired CLI surface (list / search / resolve)
 // ---------------------------------------------------------------------------
 
-function buildProgram(deps?: { refreshRoster?: RefreshPeopleRoster }): Command {
+function buildProgram(deps?: { fetchRoster?: FetchPeopleRoster }): Command {
   const program = new Command();
   program.exitOverride(); // throw instead of process.exit on commander errors
   registerPeopleCommand(program, deps);
@@ -348,8 +459,8 @@ function buildProgram(deps?: { refreshRoster?: RefreshPeopleRoster }): Command {
 
 async function run(
   args: string[],
-  deps: { refreshRoster?: RefreshPeopleRoster } = {
-    refreshRoster: async () => {},
+  deps: { fetchRoster?: FetchPeopleRoster } = {
+    fetchRoster: async () => [],
   },
 ): Promise<void> {
   await buildProgram(deps).parseAsync(["node", "hq", ...args]);
@@ -389,6 +500,68 @@ describe("hq people (wired)", () => {
     ]);
   });
 
+  it("list includes roster people, sorts them, and deduplicates with local winning", async () => {
+    const fetchRoster = vi.fn<FetchPeopleRoster>(async () => [
+      rosterPerson({
+        slug: "remote-jane",
+        name: "Remote Jane",
+        email: "JANE@acme.com",
+        role: "member",
+      }),
+      rosterPerson({
+        slug: "ada-lovelace",
+        name: "Ada Lovelace",
+        email: "ada@acme.com",
+        role: "admin",
+      }),
+    ]);
+
+    await run(
+      ["people", "list", "--company", "acme", "--hq-root", tmpRoot, "--json"],
+      { fetchRoster },
+    );
+
+    expect(fetchRoster).toHaveBeenCalledTimes(1);
+    expect(fetchRoster).toHaveBeenCalledWith(tmpRoot, "acme");
+    const out = JSON.parse(logSpy.mock.calls[0][0] as string);
+    expect(out.map((p: PersonRecord) => p.name)).toEqual([
+      "Ada Lovelace",
+      "Jane Smith",
+      "John Doe",
+    ]);
+    expect(out.find((p: PersonRecord) => p.email === "jane@acme.com")).toMatchObject({
+      name: "Jane Smith",
+      role: "CEO",
+    });
+  });
+
+  it("list --local-only skips roster fetch", async () => {
+    const fetchRoster = vi.fn<FetchPeopleRoster>(async () => [
+      rosterPerson({ slug: "ada-lovelace", name: "Ada Lovelace" }),
+    ]);
+
+    await run(
+      [
+        "people",
+        "list",
+        "--company",
+        "acme",
+        "--hq-root",
+        tmpRoot,
+        "--json",
+        "--local-only",
+      ],
+      { fetchRoster },
+    );
+
+    expect(fetchRoster).not.toHaveBeenCalled();
+    const out = JSON.parse(logSpy.mock.calls[0][0] as string);
+    expect(out.map((p: PersonRecord) => p.name).sort()).toEqual([
+      "Jane Smith",
+      "John Doe",
+    ]);
+  });
+
   it("search narrows to the matching person", async () => {
     await run([
       "people",
@@ -405,8 +578,8 @@ describe("hq people (wired)", () => {
     expect(out[0].email).toBe("jane@acme.com");
   });
 
-  it("search local hit does not refresh the roster", async () => {
-    const refreshRoster = vi.fn<RefreshPeopleRoster>();
+  it("search local hit does not fetch the roster", async () => {
+    const fetchRoster = vi.fn<FetchPeopleRoster>();
     await run(
       [
         "people",
@@ -418,19 +591,15 @@ describe("hq people (wired)", () => {
         tmpRoot,
         "--json",
       ],
-      { refreshRoster },
+      { fetchRoster },
     );
-    expect(refreshRoster).not.toHaveBeenCalled();
+    expect(fetchRoster).not.toHaveBeenCalled();
   });
 
-  it("search local miss refreshes once and retries from the refreshed roster", async () => {
-    const refreshRoster = vi.fn<RefreshPeopleRoster>(async () => {
-      makePerson("acme", "ada-lovelace", {
-        name: "Ada Lovelace",
-        email: "ada@acme.com",
-        type: "internal",
-      });
-    });
+  it("search finds a teammate from the roster on a local miss", async () => {
+    const fetchRoster = vi.fn<FetchPeopleRoster>(async () => [
+      rosterPerson({ slug: "ada-lovelace", name: "Ada Lovelace" }),
+    ]);
 
     await run(
       [
@@ -443,11 +612,11 @@ describe("hq people (wired)", () => {
         tmpRoot,
         "--json",
       ],
-      { refreshRoster },
+      { fetchRoster },
     );
 
-    expect(refreshRoster).toHaveBeenCalledTimes(1);
-    expect(refreshRoster).toHaveBeenCalledWith(tmpRoot, "acme");
+    expect(fetchRoster).toHaveBeenCalledTimes(1);
+    expect(fetchRoster).toHaveBeenCalledWith(tmpRoot, "acme");
     const out = JSON.parse(logSpy.mock.calls[0][0] as string);
     expect(out).toHaveLength(1);
     expect(out[0]).toMatchObject({
@@ -456,8 +625,8 @@ describe("hq people (wired)", () => {
     });
   });
 
-  it("search local miss with refresh failure reports the original empty JSON and logs a note", async () => {
-    const refreshRoster = vi.fn<RefreshPeopleRoster>(async () => {
+  it("search local miss with fetch failure reports the original empty JSON and logs a note", async () => {
+    const fetchRoster = vi.fn<FetchPeopleRoster>(async () => {
       throw new Error("offline");
     });
 
@@ -472,18 +641,18 @@ describe("hq people (wired)", () => {
         tmpRoot,
         "--json",
       ],
-      { refreshRoster },
+      { fetchRoster },
     );
 
-    expect(refreshRoster).toHaveBeenCalledTimes(1);
+    expect(fetchRoster).toHaveBeenCalledTimes(1);
     expect(JSON.parse(logSpy.mock.calls[0][0] as string)).toEqual([]);
     expect(errSpy).toHaveBeenCalledWith(
-      expect.stringContaining("Could not refresh people roster"),
+      expect.stringContaining("Could not fetch people roster"),
     );
   });
 
-  it("search --local-only skips refresh on a miss", async () => {
-    const refreshRoster = vi.fn<RefreshPeopleRoster>();
+  it("search --local-only skips fetch on a miss", async () => {
+    const fetchRoster = vi.fn<FetchPeopleRoster>();
     await run(
       [
         "people",
@@ -496,10 +665,10 @@ describe("hq people (wired)", () => {
         "--json",
         "--local-only",
       ],
-      { refreshRoster },
+      { fetchRoster },
     );
 
-    expect(refreshRoster).not.toHaveBeenCalled();
+    expect(fetchRoster).not.toHaveBeenCalled();
     expect(JSON.parse(logSpy.mock.calls[0][0] as string)).toEqual([]);
   });
 
@@ -516,8 +685,8 @@ describe("hq people (wired)", () => {
     expect(logSpy).toHaveBeenCalledWith("jane@acme.com");
   });
 
-  it("resolve local hit does not refresh the roster", async () => {
-    const refreshRoster = vi.fn<RefreshPeopleRoster>();
+  it("resolve local hit does not fetch the roster", async () => {
+    const fetchRoster = vi.fn<FetchPeopleRoster>();
     await run(
       [
         "people",
@@ -528,19 +697,15 @@ describe("hq people (wired)", () => {
         "--hq-root",
         tmpRoot,
       ],
-      { refreshRoster },
+      { fetchRoster },
     );
-    expect(refreshRoster).not.toHaveBeenCalled();
+    expect(fetchRoster).not.toHaveBeenCalled();
   });
 
-  it("resolve local miss refreshes once and retries from the refreshed roster", async () => {
-    const refreshRoster = vi.fn<RefreshPeopleRoster>(async () => {
-      makePerson("acme", "ada-lovelace", {
-        name: "Ada Lovelace",
-        email: "ada@acme.com",
-        type: "internal",
-      });
-    });
+  it("resolve finds a teammate that exists only in the fetched roster", async () => {
+    const fetchRoster = vi.fn<FetchPeopleRoster>(async () => [
+      rosterPerson({ slug: "ada-lovelace", name: "Ada Lovelace" }),
+    ]);
 
     await run(
       [
@@ -552,16 +717,16 @@ describe("hq people (wired)", () => {
         "--hq-root",
         tmpRoot,
       ],
-      { refreshRoster },
+      { fetchRoster },
     );
 
-    expect(refreshRoster).toHaveBeenCalledTimes(1);
-    expect(refreshRoster).toHaveBeenCalledWith(tmpRoot, "acme");
+    expect(fetchRoster).toHaveBeenCalledTimes(1);
+    expect(fetchRoster).toHaveBeenCalledWith(tmpRoot, "acme");
     expect(logSpy).toHaveBeenCalledWith("ada@acme.com");
   });
 
-  it("resolve local miss with refresh failure reports unchanged not_found JSON and logs a note", async () => {
-    const refreshRoster = vi.fn<RefreshPeopleRoster>(async () => {
+  it("resolve local miss with fetch failure reports unchanged not_found JSON and logs a note", async () => {
+    const fetchRoster = vi.fn<FetchPeopleRoster>(async () => {
       throw new Error("not signed in");
     });
 
@@ -577,22 +742,22 @@ describe("hq people (wired)", () => {
           tmpRoot,
           "--json",
         ],
-        { refreshRoster },
+        { fetchRoster },
       ),
     ).rejects.toThrow("__exit__");
 
-    expect(refreshRoster).toHaveBeenCalledTimes(1);
+    expect(fetchRoster).toHaveBeenCalledTimes(1);
     expect(JSON.parse(logSpy.mock.calls[0][0] as string)).toEqual({
       status: "not_found",
     });
     expect(errSpy).toHaveBeenCalledWith(
-      expect.stringContaining("Could not refresh people roster"),
+      expect.stringContaining("Could not fetch people roster"),
     );
     expect(exitSpy).toHaveBeenCalledWith(1);
   });
 
-  it("resolve --local-only skips refresh on a miss", async () => {
-    const refreshRoster = vi.fn<RefreshPeopleRoster>();
+  it("resolve --local-only skips fetch on a miss", async () => {
+    const fetchRoster = vi.fn<FetchPeopleRoster>();
     await expect(
       run(
         [
@@ -606,11 +771,11 @@ describe("hq people (wired)", () => {
           "--json",
           "--local-only",
         ],
-        { refreshRoster },
+        { fetchRoster },
       ),
     ).rejects.toThrow("__exit__");
 
-    expect(refreshRoster).not.toHaveBeenCalled();
+    expect(fetchRoster).not.toHaveBeenCalled();
     expect(JSON.parse(logSpy.mock.calls[0][0] as string)).toEqual({
       status: "not_found",
     });

package/src/commands/people.ts

@@ -6,25 +6,21 @@
  *   hq people search <keyword> [--company <slug>] [--json]
  *   hq people resolve <name>   [--company <slug>] [--json]
  *
- * Source of truth is `companies/<company>/people/<person>/meta.yaml`. Every
- * subcommand operates on exactly ONE company (the active company, or the one
- * named by `--company`); nothing reads across company boundaries.
+ * Local records from `companies/<company>/people/<person>/meta.yaml` are the
+ * curated primary source. On misses, commands may fall back to the membership
+ * roster for exactly ONE company (the active company, or the one named by
+ * `--company`); nothing reads across company boundaries.
  */
 
 import * as fs from "fs";
 import { Command, Option } from "commander";
 import chalk from "chalk";
-import { VaultClient } from "@indigoai-us/hq-cloud";
 import * as yaml from "js-yaml";
 import { findHqRoot } from "../utils/manifest.js";
 import { manifestPath, type ManifestDoc } from "./cloud-provision.js";
-import {
-  DEFAULT_COGNITO,
-  buildVaultConfig,
-  ensureCognitoToken,
-} from "../utils/cognito-session.js";
+import { ensureCognitoToken } from "../utils/cognito-session.js";
 import { getCompanyUid } from "../utils/vault-api.js";
-import { createCompanyPresignClient, runGet } from "./files-browse.js";
+import { listActiveMembers, type ActiveMember } from "./members.js";
 import {
   assertSafeCompanySlug,
   listCompanyPeople,
@@ -39,13 +35,13 @@ interface PeopleScopeOpts {
   hqRoot?: string;
 }
 
-export type RefreshPeopleRoster = (
+export type FetchPeopleRoster = (
   hqRoot: string,
   companySlug: string,
-) => Promise<void>;
+) => Promise<PersonRecord[]>;
 
 interface PeopleCommandDeps {
-  refreshRoster?: RefreshPeopleRoster;
+  fetchRoster?: FetchPeopleRoster;
 }
 
 interface PeopleLookupOpts {
@@ -53,23 +49,71 @@ interface PeopleLookupOpts {
   json?: boolean;
 }
 
-export async function refreshPeopleRosterFromCloud(
+function slugify(value: string): string {
+  return value
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/-+/g, "-")
+    .replace(/^-|-$/g, "");
+}
+
+export function activeMemberToPersonRecord(
+  m: ActiveMember,
+): PersonRecord | null {
+  const name =
+    m.personName?.trim() ||
+    m.personEmail?.trim() ||
+    m.personSlug?.trim() ||
+    "";
+  if (!name) return null;
+
+  const email = m.personEmail?.trim() || undefined;
+  const slug = m.personSlug?.trim() || slugify(name) || m.personUid;
+
+  return {
+    slug,
+    name,
+    email,
+    role: m.role || undefined,
+    type: "internal",
+    source: `hq-pro membership: /membership/company/${m.companyUid}`,
+  };
+}
+
+export async function fetchMembershipRoster(
   hqRoot: string,
   companySlug: string,
-): Promise<void> {
-  const accessToken = await ensureCognitoToken();
-  const client = new VaultClient(buildVaultConfig(accessToken));
-  await getCompanyUid(accessToken, companySlug);
-
-  await runGet({
-    path: `companies/${companySlug}/people/`,
-    hqRoot,
-    companySlug,
-    vaultClient: client,
-    companyClient: ({ companyUid }) =>
-      createCompanyPresignClient({ token: accessToken, companyUid }),
-    region: DEFAULT_COGNITO.region,
-  });
+): Promise<PersonRecord[]> {
+  void hqRoot;
+  const token = await ensureCognitoToken();
+  const companyUid = await getCompanyUid(token, companySlug);
+  const members = await listActiveMembers(token, companyUid);
+  return members
+    .map(activeMemberToPersonRecord)
+    .filter((r): r is PersonRecord => r !== null);
+}
+
+function personIdentityKey(person: PersonRecord): string {
+  return (
+    person.email?.toLowerCase() ||
+    person.slug?.toLowerCase() ||
+    person.name.toLowerCase()
+  );
+}
+
+export function mergePeople(
+  primary: PersonRecord[],
+  extra: PersonRecord[],
+): PersonRecord[] {
+  const seen = new Set(primary.map(personIdentityKey));
+  const merged = [...primary];
+  for (const person of extra) {
+    const key = personIdentityKey(person);
+    if (seen.has(key)) continue;
+    seen.add(key);
+    merged.push(person);
+  }
+  return merged;
 }
 
 /** Companies that still exist (anything not explicitly `status: archived`). */
@@ -159,26 +203,25 @@ function fail(message: string): never {
   process.exit(1);
 }
 
-function logRefreshFailure(companySlug: string, err: unknown): void {
+function logRosterFetchFailure(companySlug: string, err: unknown): void {
   const message = err instanceof Error ? err.message : String(err);
   console.error(
     chalk.dim(
-      `  Could not refresh people roster for '${companySlug}': ${message}`,
+      `  Could not fetch people roster for '${companySlug}': ${message}`,
     ),
   );
 }
 
-async function tryRefreshRoster(
-  refreshRoster: RefreshPeopleRoster,
+async function tryFetchRoster(
+  fetchRoster: FetchPeopleRoster,
   hqRoot: string,
   slug: string,
-): Promise<boolean> {
+): Promise<PersonRecord[] | null> {
   try {
-    await refreshRoster(hqRoot, slug);
-    return true;
+    return await fetchRoster(hqRoot, slug);
   } catch (err) {
-    logRefreshFailure(slug, err);
-    return false;
+    logRosterFetchFailure(slug, err);
+    return null;
   }
 }
 
@@ -188,25 +231,20 @@ export async function resolvePersonWithRosterFallback(
     slug: string;
     name: string;
     opts?: PeopleLookupOpts;
-    refreshRoster?: RefreshPeopleRoster;
+    fetchRoster?: FetchPeopleRoster;
   },
 ): Promise<ReturnType<typeof resolveNameToEmail>> {
-  const local = resolveNameToEmail(
-    listCompanyPeople(input.hqRoot, input.slug),
-    input.name,
-  );
+  const localPeople = listCompanyPeople(input.hqRoot, input.slug);
+  const local = resolveNameToEmail(localPeople, input.name);
   if (local.status !== "not_found" || input.opts?.localOnly) return local;
 
-  const refreshed = await tryRefreshRoster(
-    input.refreshRoster ?? refreshPeopleRosterFromCloud,
+  const roster = await tryFetchRoster(
+    input.fetchRoster ?? fetchMembershipRoster,
     input.hqRoot,
     input.slug,
   );
-  if (!refreshed) return local;
-  return resolveNameToEmail(
-    listCompanyPeople(input.hqRoot, input.slug),
-    input.name,
-  );
+  if (!roster) return local;
+  return resolveNameToEmail(mergePeople(localPeople, roster), input.name);
 }
 
 export async function searchPeopleWithRosterFallback(input: {
@@ -214,21 +252,19 @@ export async function searchPeopleWithRosterFallback(input: {
   slug: string;
   keyword: string;
   opts?: PeopleLookupOpts;
-  refreshRoster?: RefreshPeopleRoster;
+  fetchRoster?: FetchPeopleRoster;
 }): Promise<PersonRecord[]> {
-  const local = searchPeople(
-    listCompanyPeople(input.hqRoot, input.slug),
-    input.keyword,
-  );
+  const localPeople = listCompanyPeople(input.hqRoot, input.slug);
+  const local = searchPeople(localPeople, input.keyword);
   if (local.length > 0 || input.opts?.localOnly) return local;
 
-  const refreshed = await tryRefreshRoster(
-    input.refreshRoster ?? refreshPeopleRosterFromCloud,
+  const roster = await tryFetchRoster(
+    input.fetchRoster ?? fetchMembershipRoster,
     input.hqRoot,
     input.slug,
   );
-  if (!refreshed) return local;
-  return searchPeople(listCompanyPeople(input.hqRoot, input.slug), input.keyword);
+  if (!roster) return local;
+  return searchPeople(mergePeople(localPeople, roster), input.keyword);
 }
 
 export function registerPeopleCommand(
@@ -257,12 +293,26 @@ export function registerPeopleCommand(
     .command("list")
     .description("List all people recorded for the company")
     .option("--json", "Output JSON instead of a table")
-    .action((opts: { json?: boolean }) => {
+    .option(
+      "--local-only",
+      "Skip network fallback; list only the local people roster",
+    )
+    .action(async (opts: PeopleLookupOpts) => {
       try {
         const scope = people.opts() as PeopleScopeOpts;
         const hqRoot = resolveHqRoot(scope);
         const slug = resolveCompanySlug(hqRoot, scope.company);
-        const records = listCompanyPeople(hqRoot, slug);
+        let records = listCompanyPeople(hqRoot, slug);
+
+        if (!opts.localOnly) {
+          const roster = await tryFetchRoster(
+            deps.fetchRoster ?? fetchMembershipRoster,
+            hqRoot,
+            slug,
+          );
+          if (roster) records = mergePeople(records, roster);
+        }
+        records = records.sort((a, b) => a.name.localeCompare(b.name));
 
         if (opts.json) {
           console.log(JSON.stringify(records, null, 2));
@@ -288,7 +338,7 @@ export function registerPeopleCommand(
     .option("--json", "Output JSON instead of a table")
     .option(
       "--local-only",
-      "Skip cloud fallback; search only the local people roster",
+      "Skip network fallback; search only the local people roster",
     )
     .action(async (keyword: string, opts: PeopleLookupOpts) => {
       try {
@@ -300,7 +350,7 @@ export function registerPeopleCommand(
           slug,
           keyword,
           opts,
-          refreshRoster: deps.refreshRoster,
+          fetchRoster: deps.fetchRoster,
         });
 
         if (opts.json) {
@@ -323,7 +373,7 @@ export function registerPeopleCommand(
     .option("--json", "Output JSON instead of plain text")
     .option(
       "--local-only",
-      "Skip cloud fallback; resolve only from the local people roster",
+      "Skip network fallback; resolve only from the local people roster",
     )
     .action(async (name: string, opts: PeopleLookupOpts) => {
       try {
@@ -335,7 +385,7 @@ export function registerPeopleCommand(
           slug,
           name,
           opts,
-          refreshRoster: deps.refreshRoster,
+          fetchRoster: deps.fetchRoster,
         });
 
         if (opts.json) {