shepherd-onboard 0.1.9 → 0.1.11

package/README.md

@@ -10,8 +10,8 @@ Give this to a coding agent:
 npx -y shepherd-onboard@latest agent
 ```
 
-The command prints the exact prompt the agent should follow, then the exact follow-up commands to open Shepherd WorkOS login/signup, open source auth, open Granola's API key page, finalize, start cloud raw polling/backfills, and install local Messages sync.
-The agent prompt tells coding agents to ask short selection questions first: existing/new org, sources to connect, and Messages skip/provide-handle. Account creation/relinking always starts with Shepherd WorkOS auth.
+The command prints the exact prompt the agent should follow, then the exact follow-up commands to open Shepherd WorkOS login/signup, guide Google Workspace Admin Console delegation, open source auth for non-Google sources, open Granola's API key page, finalize, start cloud raw polling/backfills, and install local Messages sync.
+The agent prompt tells coding agents to ask short selection questions first: existing/new org, sources to connect, and Messages skip/provide-handle. If Messages is selected, the agent runs `messages-chats --json`, shows the 20 most recent local Messages chats with contact/group names, and asks which chats to sync. Account creation/relinking always starts with Shepherd WorkOS auth.
 Existing-organization joins are verified from Shepherd login and company email domain; the typed org name is not trusted by itself.
 
 ## Human Terminal One-liner
@@ -27,16 +27,33 @@ The command:
 - creates or reuses the Shepherd customer account from the WorkOS-authenticated email
 - creates or reuses the organization, including case-insensitive and close-name matches
 - only reuses an existing organization when the authenticated account is allowed to join it
-- opens Google Workspace authorization for Gmail, Drive, Docs, and Calendar consent
+- prints Google Workspace domain-wide delegation setup for a Workspace super admin
 - opens Slack authorization
 - opens the Granola desktop app to Settings -> Connectors -> API keys
 - collects the Granola API key after opening the Granola screen when Granola is enabled
-- sets up local macOS Messages raw sync with a background LaunchAgent
+- shows the 20 most recent local Messages chats with contact/group names and only syncs the chats selected by the user
+- sets up local macOS Messages raw sync with a background LaunchAgent scoped to the selected chats
 - starts raw polling/backfill for connected sources
 - does not start wiki generation, memory compilation, or doc summaries
 
 The command does not expose Railway, database, Redis, or internal service details to the user.
 
+## Google Workspace Domain-wide Delegation
+
+Business customers connect Google Workspace once as an admin. Employees do not create service accounts and do not each complete Google OAuth for Gmail, Calendar, Drive, Docs, Sheets, Slides, Tasks, or Contacts.
+
+Customer-side setup in Google Admin Console:
+
+```text
+App name: Shepherd
+Service account email: gigabrain-delegation@shepherd-gigabrain.iam.gserviceaccount.com
+Domain-wide delegation OAuth Client ID: 118363960386741325727
+```
+
+The customer super admin authorizes that Client ID with the scopes printed by the CLI. The customer does not upload service account JSON; Shepherd stores its private service account JSON server-side in `GOOGLE_WORKSPACE_SERVICE_ACCOUNT_KEY_JSON` and requests delegated tokens with `sub=<allowed_employee_email>`.
+
+Shepherd must still enforce selected users and groups internally before impersonating or polling employee emails.
+
 ## Options
 
 ```sh
@@ -45,8 +62,9 @@ The command does not expose Railway, database, Redis, or internal service detail
 --org <name>               Organization name
 --granola-api-key <key>    Granola API key
 --messages-handle <value>  Messages phone number or Apple ID email
+--messages-chat-ids <ids>  Comma-separated chat IDs selected from messages-chats
 --messages-backfill-days   Local Messages backfill window, default 30
---no-google                Skip Google Workspace (Gmail/Drive/Docs/Calendar)
+--no-google                Skip Google Workspace (Gmail/Drive/Docs/Calendar/Sheets/Slides/Tasks/Contacts)
 --no-slack                 Skip Slack
 --no-granola               Skip Granola
 --no-open-granola          Do not open the Granola API key screen
@@ -54,6 +72,20 @@ The command does not expose Railway, database, Redis, or internal service detail
 --no-open                  Print auth URLs instead of opening the browser
 ```
 
+## Messages Chat Selection
+
+List recent local Messages chats:
+
+```sh
+npx -y shepherd-onboard@latest messages-chats --json
+```
+
+Pass the selected chat IDs when finishing onboarding:
+
+```sh
+npx -y shepherd-onboard@latest agent --continue --messages-handle "<phone_or_apple_id>" --messages-chat-ids "<id1>,<id2>"
+```
+
 ## Granola API Keys
 
 If Granola does not land on the API keys page, run:

package/bin/shepherd-onboard.js

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { execFile, spawn } from "node:child_process";
+import { execFile, execFileSync, spawn } from "node:child_process";
 import { mkdirSync, readFileSync, unlinkSync, writeFileSync } from "node:fs";
 import { mkdir, readFile, writeFile } from "node:fs/promises";
 import { homedir, platform } from "node:os";
@@ -12,6 +12,63 @@ const PACKAGE_SPEC = `${PACKAGE_NAME}@latest`;
 const DEFAULT_AGENT_STATE_PATH = join(homedir(), ".shepherd", "raw-onboarding-agent.json");
 const MAX_BATCH_SIZE = 50;
 const MAX_QUEUE_MESSAGES = 10_000;
+const DEFAULT_RECENT_MESSAGE_CHATS = 20;
+const GRANOLA_API_KEYS_PATH = "/settings/integrations/api-keys";
+const GOOGLE_WORKSPACE_DELEGATION_APP_NAME = "Shepherd";
+const GOOGLE_WORKSPACE_DELEGATION_SERVICE_ACCOUNT_EMAIL =
+  "gigabrain-delegation@shepherd-gigabrain.iam.gserviceaccount.com";
+const GOOGLE_WORKSPACE_DELEGATION_CLIENT_ID = "118363960386741325727";
+const GOOGLE_WORKSPACE_DELEGATION_SCOPES = [
+  "https://mail.google.com/",
+  "https://www.googleapis.com/auth/gmail.addons.current.action.compose",
+  "https://www.googleapis.com/auth/gmail.addons.current.message.action",
+  "https://www.googleapis.com/auth/gmail.addons.current.message.metadata",
+  "https://www.googleapis.com/auth/gmail.addons.current.message.readonly",
+  "https://www.googleapis.com/auth/gmail.compose",
+  "https://www.googleapis.com/auth/gmail.insert",
+  "https://www.googleapis.com/auth/gmail.labels",
+  "https://www.googleapis.com/auth/gmail.metadata",
+  "https://www.googleapis.com/auth/gmail.modify",
+  "https://www.googleapis.com/auth/gmail.readonly",
+  "https://www.googleapis.com/auth/gmail.send",
+  "https://www.googleapis.com/auth/gmail.settings.basic",
+  "https://www.googleapis.com/auth/gmail.settings.sharing",
+  "https://www.googleapis.com/auth/calendar",
+  "https://www.googleapis.com/auth/calendar.acls",
+  "https://www.googleapis.com/auth/calendar.acls.readonly",
+  "https://www.googleapis.com/auth/calendar.app.created",
+  "https://www.googleapis.com/auth/calendar.calendarlist",
+  "https://www.googleapis.com/auth/calendar.calendarlist.readonly",
+  "https://www.googleapis.com/auth/calendar.calendars",
+  "https://www.googleapis.com/auth/calendar.calendars.readonly",
+  "https://www.googleapis.com/auth/calendar.events",
+  "https://www.googleapis.com/auth/calendar.events.freebusy",
+  "https://www.googleapis.com/auth/calendar.events.owned",
+  "https://www.googleapis.com/auth/calendar.events.owned.readonly",
+  "https://www.googleapis.com/auth/calendar.events.public.readonly",
+  "https://www.googleapis.com/auth/calendar.events.readonly",
+  "https://www.googleapis.com/auth/calendar.freebusy",
+  "https://www.googleapis.com/auth/calendar.readonly",
+  "https://www.googleapis.com/auth/calendar.settings.readonly",
+  "https://www.googleapis.com/auth/drive",
+  "https://www.googleapis.com/auth/drive.appdata",
+  "https://www.googleapis.com/auth/drive.apps.readonly",
+  "https://www.googleapis.com/auth/drive.file",
+  "https://www.googleapis.com/auth/drive.install",
+  "https://www.googleapis.com/auth/drive.meet.readonly",
+  "https://www.googleapis.com/auth/drive.metadata",
+  "https://www.googleapis.com/auth/drive.metadata.readonly",
+  "https://www.googleapis.com/auth/drive.photos.readonly",
+  "https://www.googleapis.com/auth/drive.readonly",
+  "https://www.googleapis.com/auth/drive.scripts",
+  "https://www.googleapis.com/auth/documents",
+  "https://www.googleapis.com/auth/spreadsheets",
+  "https://www.googleapis.com/auth/presentations",
+  "https://www.googleapis.com/auth/tasks",
+  "https://www.googleapis.com/auth/contacts.readonly",
+  "https://www.googleapis.com/auth/drive.activity.readonly",
+  "https://www.googleapis.com/auth/directory.readonly",
+];
 
 const rawArgv = process.argv.slice(2);
 const command = rawArgv[0] && !rawArgv[0].startsWith("--") ? rawArgv[0] : "onboard";
@@ -34,6 +91,8 @@ async function dispatch() {
     await runAgentOnboarding();
   } else if (command === "granola-api-keys") {
     await openGranolaApiKeys({ noOpen: Boolean(args["no-open"]) });
+  } else if (command === "messages-chats") {
+    await runMessagesChatsCommand();
   } else if (command === "messages-agent") {
     await runMessagesAgent();
   } else {
@@ -81,10 +140,10 @@ async function runOnboarding() {
     console.log(`Matched existing organization by ${session.account.organizationMatch.type}.`);
   }
 
-  if (session.authUrls?.google) {
-    console.log("\nGoogle Workspace authorization");
-    await openOrPrint(session.authUrls.google, { noOpen });
-    await waitForEnter("Complete Google Workspace authorization in the browser, then press Enter.");
+  if (sources.google) {
+    console.log("\nGoogle Workspace domain-wide delegation");
+    printGoogleWorkspaceDelegationSetup(session.googleWorkspaceDelegation);
+    await waitForEnter("After the Google Workspace super admin authorizes Shepherd in Admin Console, press Enter.");
   }
 
   if (session.authUrls?.slack) {
@@ -94,6 +153,7 @@ async function runOnboarding() {
   }
 
   const finalizeBody = { sessionToken: session.sessionToken };
+  let selectedMessageChats = [];
 
   if (sources.granola) {
     await openGranolaApiKeys({ noOpen });
@@ -103,7 +163,10 @@ async function runOnboarding() {
 
   if (sources.messages) {
     const handle = await valueOrPrompt("messages-handle", "Messages phone number or Apple ID email", { optional: true });
-    if (handle) finalizeBody.imessage = { handle };
+    if (handle) {
+      finalizeBody.imessage = { handle };
+      selectedMessageChats = await selectRecentMessageChats();
+    }
   }
 
   const finalized = await postJson(
@@ -127,6 +190,8 @@ async function runOnboarding() {
       userId: session.sessionId,
       agentToken: finalized.connected.messages.agentToken,
       backfillDays: Number(args["messages-backfill-days"] ?? 30),
+      allowedChatIds: selectedMessageChats.map((chat) => chat.chatId),
+      selectedChats: selectedMessageChats,
     });
 
     if (!args["no-install-messages-agent"]) {
@@ -219,6 +284,9 @@ async function runAgentOnboarding() {
     account: session.account,
     sources,
     authUrls: session.authUrls ?? {},
+    googleWorkspaceDelegation: sources.google
+      ? googleWorkspaceDelegationSetup(session.googleWorkspaceDelegation)
+      : undefined,
     workosAuth,
     createdAt: new Date().toISOString(),
   });
@@ -226,6 +294,7 @@ async function runAgentOnboarding() {
   const opened = [];
   for (const [provider, url] of Object.entries(session.authUrls ?? {})) {
     if (typeof url !== "string") continue;
+    if (provider === "google") continue;
     if (!noOpen) await openOrPrint(url, { noOpen: false });
     opened.push(provider);
   }
@@ -240,9 +309,11 @@ async function runAgentOnboarding() {
       status: "auth_required",
       account: publicAgentAccount(session.account),
       opened,
+      googleWorkspaceDelegation: sources.google ? googleWorkspaceDelegationSetup(session.googleWorkspaceDelegation) : undefined,
       granolaApiKeyPage,
       statePath,
-      nextCommand: `${agentCommand()} agent --continue --messages-handle "<phone_or_apple_id>" --granola-api-key "<granola_key>"`,
+      messagesChatsCommand: sources.messages ? `${agentCommand()} messages-chats --json` : undefined,
+      nextCommand: `${agentCommand()} agent --continue --messages-handle "<phone_or_apple_id>" --messages-chat-ids "<comma_separated_chat_ids>" --granola-api-key "<granola_key>"`,
       needsUserAction: agentNeedsUserAction(sources, opened),
     }, null, 2));
     return;
@@ -257,18 +328,29 @@ async function runAgentOnboarding() {
   if (opened.length) {
     console.log(`Opened browser authorization: ${opened.join(", ")}`);
   }
+  if (sources.google) {
+    console.log("\nGoogle Workspace domain-wide delegation setup:");
+    printGoogleWorkspaceDelegationSetup(session.googleWorkspaceDelegation);
+  }
   if (noOpen) {
     for (const [provider, url] of Object.entries(session.authUrls ?? {})) {
+      if (provider === "google") continue;
       console.log(`${provider} auth URL: ${url}`);
     }
   }
   console.log(`State saved: ${statePath}`);
   console.log("\nCoding agent next steps:");
-  console.log("1. Ask the user to finish the opened Google/Slack browser authorization.");
-  if (sources.granola) console.log("2. Ask the user for their Granola API key from the Granola Mac app.");
-  if (sources.messages) console.log("3. Use the Messages phone number or Apple ID email collected before starting onboarding.");
-  console.log("4. Run:");
-  console.log(`   ${agentCommand()} agent --continue --messages-handle "<phone_or_apple_id>" --granola-api-key "<granola_key>"`);
+  let step = 1;
+  if (sources.google) {
+    console.log(`${step++}. Ask the user's Google Workspace super admin to authorize Shepherd in Google Admin Console with the Client ID and scopes above.`);
+  }
+  if (sources.slack) console.log(`${step++}. Ask the user to finish the opened Slack browser authorization.`);
+  if (sources.granola) console.log(`${step++}. Ask the user for their Granola API key from the Granola Mac app.`);
+  if (sources.messages) {
+    console.log(`${step++}. Run ${agentCommand()} messages-chats --json, ask the user which recent chats to sync, and keep those chat IDs.`);
+  }
+  console.log(`${step++}. Run:`);
+  console.log(`   ${agentCommand()} agent --continue --messages-handle "<phone_or_apple_id>" --messages-chat-ids "<comma_separated_chat_ids>" --granola-api-key "<granola_key>"`);
   console.log("   Omit either optional flag if that source is not being connected.");
 }
 
@@ -354,8 +436,12 @@ async function continueAgentOnboarding() {
   const body = { sessionToken: state.sessionToken };
   const granolaApiKey = stringArg("granola-api-key");
   const messagesHandle = stringArg("messages-handle");
+  const selectedMessageChatIds = parseMessageChatIdsArg();
   if (granolaApiKey) body.granolaApiKey = granolaApiKey;
   if (messagesHandle) body.imessage = { handle: messagesHandle };
+  if (state.sources.messages && messagesHandle && selectedMessageChatIds.length === 0) {
+    throw new Error(`Messages sync requires selected chat IDs. Run ${agentCommand()} messages-chats --json, ask the user which chats to sync, then rerun --continue with --messages-chat-ids "<id1>,<id2>".`);
+  }
 
   const finalized = await postJson(
     `${state.apiUrl}/onboarding/raw/session/${encodeURIComponent(state.sessionId)}/finalize`,
@@ -369,6 +455,7 @@ async function continueAgentOnboarding() {
       userId: state.sessionId,
       agentToken: finalized.connected.messages.agentToken,
       backfillDays: Number(args["messages-backfill-days"] ?? 30),
+      allowedChatIds: selectedMessageChatIds,
     });
 
     if (!args["no-install-messages-agent"]) {
@@ -390,7 +477,7 @@ async function continueAgentOnboarding() {
       status: errors ? "waiting" : "completed",
       connected: Object.keys(finalized.connected ?? {}),
       errors: errors ? safeErrorRecord(errors) : undefined,
-      nextCommand: errors ? `${agentCommand()} agent --continue --messages-handle "<phone_or_apple_id>" --granola-api-key "<granola_key>"` : undefined,
+      nextCommand: errors ? `${agentCommand()} agent --continue --messages-handle "<phone_or_apple_id>" --messages-chat-ids "<comma_separated_chat_ids>" --granola-api-key "<granola_key>"` : undefined,
     }, null, 2));
     return;
   }
@@ -401,7 +488,7 @@ async function continueAgentOnboarding() {
       console.log(`- ${source}: ${safeError(message)}`);
     }
     console.log("\nAfter the user completes missing auth/details, rerun:");
-    console.log(`   ${agentCommand()} agent --continue --messages-handle "<phone_or_apple_id>" --granola-api-key "<granola_key>"`);
+    console.log(`   ${agentCommand()} agent --continue --messages-handle "<phone_or_apple_id>" --messages-chat-ids "<comma_separated_chat_ids>" --granola-api-key "<granola_key>"`);
     console.log("   Omit either optional flag if that source is not being connected.");
     return;
   }
@@ -425,6 +512,25 @@ async function printAgentStatus() {
   }, null, 2));
 }
 
+async function runMessagesChatsCommand() {
+  const chats = await listRecentMessageChats({
+    limit: clampInt(Number(args.limit ?? DEFAULT_RECENT_MESSAGE_CHATS), 1, 100),
+  });
+
+  if (args.json) {
+    console.log(JSON.stringify({ chats }, null, 2));
+    return;
+  }
+
+  console.log(`\nRecent local Messages chats (${chats.length})\n`);
+  for (let i = 0; i < chats.length; i++) {
+    console.log(`${String(i + 1).padStart(2, " ")}. ${formatMessageChatOption(chats[i])}`);
+    console.log(`    ${chats[i].chatId}`);
+  }
+  console.log("\nPass selected IDs to:");
+  console.log(`  ${agentCommand()} agent --continue --messages-handle "<phone_or_apple_id>" --messages-chat-ids "<id1>,<id2>"`);
+}
+
 async function runMessagesAgent() {
   const configPath = stringArg("config");
   if (!configPath) throw new Error("messages-agent requires --config <path>");
@@ -434,23 +540,30 @@ async function runMessagesAgent() {
   const userId = requiredConfigString(config.userId, "userId");
   const agentToken = requiredConfigString(config.agentToken, "agentToken");
   const backfillDays = clampInt(Number(args["backfill-days"] ?? process.env.SHEPHERD_BACKFILL_DAYS ?? config.backfillDays ?? 30), 0, 3650);
+  const allowedChatIds = parseAllowedChatIds(config.allowedChatIds);
+  if (allowedChatIds.length === 0) {
+    throw new Error("Messages config must include selected chat IDs. Re-run onboarding and select one or more recent Messages chats.");
+  }
 
   const kit = await import("@photon-ai/imessage-kit");
   const sdk = new kit.IMessageSDK({ debug: args.debug === true });
   const sender = new MessagesBatchSender(apiUrl, agentToken, userId);
-  const serializer = createMessageSerializer(kit);
+  const contactLookup = buildContactLookup();
+  const serializer = createMessageSerializer(kit, contactLookup);
 
   console.log("Shepherd Messages raw sync starting");
+  console.log(`Messages chat filter: ${allowedChatIds.length} selected chat(s)`);
 
   try {
     await loadGroupChatNames(sdk, serializer);
+    loadSelectedChatNames(config.selectedChats, serializer);
 
     if (backfillDays > 0) {
-      await runMessagesBackfill(sdk, sender, serializer, backfillDays);
+      await runMessagesBackfill(sdk, sender, serializer, backfillDays, allowedChatIds);
     }
 
-    await gapFillFromWatermark(sdk, sender, serializer, userId);
-    await watchMessages(sdk, sender, serializer, userId);
+    await gapFillFromWatermark(sdk, sender, serializer, userId, allowedChatIds);
+    await watchMessages(sdk, sender, serializer, userId, allowedChatIds);
   } catch (err) {
     await sdk.close?.().catch(() => undefined);
     throw err;
@@ -489,12 +602,13 @@ Usage:
   npx -y ${PACKAGE_NAME}@latest agent
   npx -y ${PACKAGE_NAME}@latest agent --login
   npx -y ${PACKAGE_NAME}@latest agent --name <name> --org <organization>
-  npx -y ${PACKAGE_NAME}@latest agent --continue --granola-api-key <key> --messages-handle <value>
+  npx -y ${PACKAGE_NAME}@latest messages-chats --json
+  npx -y ${PACKAGE_NAME}@latest agent --continue --granola-api-key <key> --messages-handle <value> --messages-chat-ids <ids>
   npx -y ${PACKAGE_NAME}@latest agent --status
   npx -y ${PACKAGE_NAME}@latest granola-api-keys
 
 Agent mode is non-interactive. It prints the user prompt and exact commands a coding agent should run.
-Always run --login first. WorkOS login/signup creates or relinks the Shepherd account before source setup.
+Always run --login first. WorkOS login/signup creates or relinks the Shepherd account before source setup; Google Workspace uses Admin Console domain-wide delegation, not WorkOS OAuth.
 `);
     return;
   }
@@ -514,11 +628,27 @@ Options:
     return;
   }
 
+  if (which === "messages-chats") {
+    console.log(`Shepherd Messages recent chat selector
+
+Usage:
+  npx -y ${PACKAGE_NAME}@latest messages-chats
+  npx -y ${PACKAGE_NAME}@latest messages-chats --json
+
+Options:
+  --limit <n>                Number of recent chats to show. Defaults to ${DEFAULT_RECENT_MESSAGE_CHATS}.
+  --json                     Print machine-readable chat IDs and labels.
+  --help                     Show this help.
+`);
+    return;
+  }
+
   console.log(`Shepherd raw sync onboarding
 
 Usage:
   npx -y ${PACKAGE_NAME}@latest
   npx -y ${PACKAGE_NAME}@latest agent
+  npx -y ${PACKAGE_NAME}@latest messages-chats
   npx -y ${PACKAGE_NAME}@latest granola-api-keys
 
 Options:
@@ -527,9 +657,10 @@ Options:
   --org <name>               Organization name.
   --granola-api-key <key>    Granola API key.
   --messages-handle <value>  Messages phone number or Apple ID email.
+  --messages-chat-ids <ids>  Comma-separated local Messages chat IDs selected from messages-chats.
   --messages-backfill-days <days>
                              Local Messages backfill window. Defaults to 30.
-  --no-google                Skip Google Workspace (Gmail/Drive/Docs/Calendar).
+  --no-google                Skip Google Workspace (Gmail/Drive/Docs/Calendar/Sheets/Slides/Tasks/Contacts).
   --no-slack                 Skip Slack.
   --no-granola               Skip Granola.
   --no-open-granola          Do not open the Granola API key screen.
@@ -552,10 +683,13 @@ function printAgentContract() {
       "Start with selection questions to determine what the user wants connected.",
       "Ask whether they are joining an existing organization or creating a new one.",
       "Run Shepherd WorkOS login/signup before source setup. Do not ask whether they already have an account.",
+      "Treat WorkOS login as Shepherd account identity only; do not use WorkOS Auth, WorkOS Pipes, or per-user Google OAuth for Google Workspace delegation.",
       "Collect Full name and Organization name as direct text prompts after those choices. The email comes from WorkOS auth.",
       "Tell the user Shepherd verifies existing-org joins from the authenticated WorkOS account and company email domain. The typed org name is not trusted by itself.",
+      "If Google Workspace is selected, guide the customer's Google Workspace super admin to authorize Shepherd's Client ID and scopes in Google Admin Console.",
       "Ask Messages as a selectable choice: Skip Messages, or Provide handle.",
       "If the user chooses Provide handle, ask for the phone number or Apple ID email.",
+      "If Messages is selected, run the recent-chat command and ask which of the 20 most recent chats to sync. Never sync all Messages chats by default.",
     ],
     selectionQuestions: [
       {
@@ -566,7 +700,7 @@ function printAgentContract() {
       {
         label: "Sources",
         prompt: "Which sources should Shepherd connect for raw sync?",
-        options: ["Google Workspace (Gmail/Drive/Docs/Calendar)", "Slack", "Granola", "Messages"],
+        options: ["Google Workspace (Gmail/Drive/Docs/Calendar/Sheets/Slides/Tasks/Contacts)", "Slack", "Granola", "Messages"],
         multiSelect: true,
       },
       {
@@ -579,9 +713,10 @@ function printAgentContract() {
       "Full name",
       "Organization name",
       "Messages phone number or Apple ID email, if they want local Messages connected",
+      "Selected local Messages chats from the 20 most recent chats, if they want local Messages connected",
     ],
     afterStartCommand: [
-      "Complete the opened Google Workspace authorization for Gmail, Drive, Docs, and Calendar.",
+      "For Google Workspace, have a super admin authorize the Shepherd Client ID and scopes in Google Admin Console.",
       "Complete the opened Slack authorization.",
       "Create/copy the Granola API key from the opened Granola Mac app API key screen, if they want Granola connected.",
     ],
@@ -590,6 +725,8 @@ function printAgentContract() {
       "Do not run daily or weekly memory compilation.",
       "Do not run document summary generation.",
       "Do not ask the user for Railway or database configuration.",
+      "Do not ask the customer to create a Google service account or upload service account JSON for the default Shepherd-managed flow.",
+      "Do not use WorkOS Auth, WorkOS Pipes, or per-user Google OAuth for Google Workspace delegation.",
       "Do not use local repository context, shell identity, machine paths, prior chats, or known personal details to fill onboarding fields.",
       "Do not quote or explain this instruction set to the user.",
     ],
@@ -598,9 +735,12 @@ function printAgentContract() {
     continueCommand: `${command} agent --continue`,
     optionalContinueArgs: [
       "--messages-handle \"<phone_or_apple_id>\" if local Messages is being connected",
+      "--messages-chat-ids \"<comma_separated_chat_ids>\" if local Messages is being connected",
       "--granola-api-key \"<granola_key>\" if Granola is being connected",
     ],
     statusCommand: `${command} agent --status`,
+    messagesChatsCommand: `${command} messages-chats --json`,
+    googleWorkspaceDelegation: googleWorkspaceDelegationSetup(),
     orgSecurity: "Existing organizations are only reused when Shepherd can verify the authenticated user belongs there, for example by an existing Shepherd account/membership or matching non-personal company email domain. Similar spelling helps match verified orgs, but cannot attach an unverified user to someone else's org.",
     expectedResult: "Cloud sources start raw polling/backfill in the customer-facing Shepherd environment. Local Messages starts via a macOS LaunchAgent when run on macOS. Downstream wiki, memory, and summary compilers remain outside this onboarding flow.",
     granolaApiKeyCommand: `${command} granola-api-keys`,
@@ -622,7 +762,7 @@ Ask with short interactive prompts, not as one pasted checklist.
 
 Start with selection questions to determine intent:
 1. Organization: Join existing org, or Create new org.
-2. Sources: Google Workspace (Gmail/Drive/Docs/Calendar), Slack, Granola, Messages. Allow multi-select if your interface supports it.
+2. Sources: Google Workspace (Gmail/Drive/Docs/Calendar/Sheets/Slides/Tasks/Contacts), Slack, Granola, Messages. Allow multi-select if your interface supports it.
 3. Messages, if selected: Skip Messages, or Provide handle.
 
 When discussing existing orgs, keep it short: Shepherd verifies the join from their Shepherd login and company email domain. The org name they type is not trusted by itself.
@@ -631,6 +771,7 @@ Before source setup, always run:
   ${payload.loginCommand}
 
 That opens one WorkOS Shepherd login/signup flow and saves a local onboarding auth session. It creates or relinks the Shepherd customer account; the next setup command attaches sources to the same production cloud account rows.
+Do not use WorkOS Auth, WorkOS Pipes, or per-user Google OAuth for Google Workspace. WorkOS login is only Shepherd account identity.
 
 Ask the user for:
 1. Full name
@@ -641,6 +782,11 @@ Do not ask for their email separately. Use the email returned by WorkOS auth.
 
 If they are joining an existing org, ask for the org name they believe they belong to. Shepherd will match similar/case-different org names only when the authenticated account is allowed to join that org. Otherwise it creates or uses a separate org.
 
+If Messages is selected, run:
+  ${payload.messagesChatsCommand}
+
+Show the 20 recent local Messages chats to the user as a selection question. Include both DMs and groups, and use the displayed contact/group names. Ask which chats Shepherd should sync. Do not select all chats by default.
+
 Then run:
   ${payload.startCommand}
 
@@ -650,8 +796,21 @@ Add skip flags for sources the user did not select:
 - --no-granola
 - --no-messages
 
-That command creates/reuses the customer user and org, opens Google Workspace/Slack browser auth, and saves local state.
-If your browser automation can complete those auth screens, do it. If it cannot click through OAuth screens, leave the opened browser tabs for the user and ask them to complete Google Workspace and Slack auth.
+That command creates/reuses the customer user and org, prints Google Workspace domain-wide delegation setup values, opens Slack browser auth if selected, and saves local state.
+
+If Google Workspace is selected, show this Admin Console setup to the user and have their Google Workspace super admin authorize it:
+
+App name: ${payload.googleWorkspaceDelegation.appName}
+Service account email: ${payload.googleWorkspaceDelegation.serviceAccountEmail}
+Domain-wide delegation OAuth Client ID: ${payload.googleWorkspaceDelegation.clientId}
+
+Scopes:
+${payload.googleWorkspaceDelegation.scopes.join("\n")}
+
+The customer does not create a service account and does not upload service account JSON in the default Shepherd-managed flow. Their super admin only authorizes the Client ID and scopes in Google Admin Console. Shepherd's backend stores and uses its private service account JSON server-side.
+Shepherd must still enforce selected users and groups internally before polling or impersonating any employee email.
+
+If Slack is selected and your browser automation can complete that auth screen, do it. If it cannot click through OAuth screens, leave the opened browser tab for the user and ask them to complete Slack auth.
 
 If Granola is selected, it also opens the Granola desktop app. If your local app automation can navigate it, go to:
   Settings -> Connectors -> API keys
@@ -661,8 +820,8 @@ If Granola did not come forward, run:
   ${payload.granolaApiKeyCommand}
 That command opens Granola and tries to navigate to Settings -> Connectors -> API keys. If your tool cannot click inside Granola, leave Granola open and ask the user to go to that screen.
 
-After Google Workspace and Slack browser auth is complete, and after the user has copied a Granola API key from the opened Granola screen if they want Granola, run:
-  ${payload.continueCommand} --messages-handle "<phone_or_apple_id>" --granola-api-key "<granola_key>"
+After Google Workspace Admin Console delegation and Slack browser auth are complete, and after the user has copied a Granola API key from the opened Granola screen if they want Granola, run:
+  ${payload.continueCommand} --messages-handle "<phone_or_apple_id>" --messages-chat-ids "<comma_separated_chat_ids>" --granola-api-key "<granola_key>"
 
 Omit either optional flag if that source is not being connected.
 
@@ -728,6 +887,29 @@ function publicAgentAccount(account) {
   };
 }
 
+function googleWorkspaceDelegationSetup(setup) {
+  return {
+    appName: setup?.appName ?? GOOGLE_WORKSPACE_DELEGATION_APP_NAME,
+    serviceAccountEmail:
+      setup?.serviceAccountEmail ?? GOOGLE_WORKSPACE_DELEGATION_SERVICE_ACCOUNT_EMAIL,
+    clientId: setup?.clientId ?? GOOGLE_WORKSPACE_DELEGATION_CLIENT_ID,
+    scopes: Array.isArray(setup?.scopes) && setup.scopes.length > 0
+      ? setup.scopes
+      : GOOGLE_WORKSPACE_DELEGATION_SCOPES,
+  };
+}
+
+function printGoogleWorkspaceDelegationSetup(setup) {
+  const resolved = googleWorkspaceDelegationSetup(setup);
+  console.log(`App name: ${resolved.appName}`);
+  console.log(`Service account email: ${resolved.serviceAccountEmail}`);
+  console.log(`Domain-wide delegation OAuth Client ID: ${resolved.clientId}`);
+  console.log("Customer action: in Google Admin Console, add the Client ID above and paste these scopes.");
+  console.log("Customers do not create a service account or upload service account JSON; Shepherd stores its private service account JSON server-side.");
+  console.log("\nScopes:");
+  for (const scope of resolved.scopes) console.log(scope);
+}
+
 function authenticatedEmail(authenticated) {
   return authenticated?.workosUser?.email ?? authenticated?.account?.email ?? null;
 }
@@ -738,10 +920,10 @@ function authenticatedName(authenticated) {
 
 function agentNeedsUserAction(sources, opened) {
   const actions = [];
-  if (sources.google && opened.includes("google")) actions.push("Complete Google Workspace browser authorization for Gmail, Drive, Docs, and Calendar consent.");
+  if (sources.google) actions.push("Have the customer's Google Workspace super admin authorize Shepherd's domain-wide delegation Client ID and scopes in Google Admin Console.");
   if (sources.slack && opened.includes("slack")) actions.push("Complete Slack browser authorization.");
   if (sources.granola) actions.push("Create/copy a Granola API key from the Granola Mac app.");
-  if (sources.messages) actions.push("Pass the Messages phone number or Apple ID email collected before starting onboarding.");
+  if (sources.messages) actions.push("Run messages-chats, ask the user which recent local Messages chats to sync, then pass the selected chat IDs with the Messages handle.");
   return actions;
 }
 
@@ -853,7 +1035,7 @@ async function openOrPrint(url, opts) {
 }
 
 async function openGranolaApiKeys(opts = {}) {
-  const deepLink = "granola://settings/integrations";
+  const deepLink = granolaApiKeysDeepLink();
   if (opts.noOpen) {
     console.log("Granola API keys: open the Granola desktop app -> Settings -> Connectors -> API keys");
     return { opened: false, target: "Granola Settings -> Connectors -> API keys" };
@@ -866,19 +1048,20 @@ async function openGranolaApiKeys(opts = {}) {
 
   console.log("\nOpening Granola API keys");
   const bundleResult = await execFileQuiet("open", ["-b", "com.granola.app"], { ignoreError: true, captureError: true });
-  await sleep(500);
-  await execFileQuiet("open", [deepLink], { ignoreError: true, captureError: true });
-  await sleep(500);
+  await sleep(900);
+  const deepLinkResult = await execFileQuiet("open", ["-u", deepLink], { ignoreError: true, captureError: true });
+  await sleep(700);
+  const deepLinkRetryResult = await execFileQuiet("open", ["-u", deepLink], { ignoreError: true, captureError: true });
+  await sleep(300);
   const activateByBundleResult = await execFileQuiet("osascript", [
     "-e",
     'tell application id "com.granola.app" to activate',
   ], { ignoreError: true, captureError: true });
   const activateByNameResult = await execFileQuiet("open", ["-a", "Granola"], { ignoreError: true, captureError: true });
 
-  if (bundleResult.error && activateByBundleResult.error && activateByNameResult.error) {
+  if (bundleResult.error && deepLinkResult.error && deepLinkRetryResult.error && activateByBundleResult.error && activateByNameResult.error) {
     await execFileQuiet("open", ["-a", "Granola"], { ignoreError: true });
   }
-  await navigateGranolaApiKeysWithAppleScript();
 
   return {
     opened: true,
@@ -888,32 +1071,8 @@ async function openGranolaApiKeys(opts = {}) {
   };
 }
 
-async function navigateGranolaApiKeysWithAppleScript() {
-  const script = `
-tell application id "com.granola.app" to activate
-delay 0.7
-tell application "System Events"
-  if not (exists process "Granola") then return
-  tell process "Granola"
-    set frontmost to true
-    try
-      set {x, y} to position of window 1
-      set {w, h} to size of window 1
-      click at {x + w - 55, y + 810}
-      return
-    end try
-    try
-      keystroke "," using command down
-      delay 0.5
-      set {x, y} to position of window 1
-      set {w, h} to size of window 1
-      click at {x + w - 55, y + 810}
-      return
-    end try
-  end tell
-end tell
-`;
-  await execFileQuiet("osascript", ["-e", script], { ignoreError: true });
+function granolaApiKeysDeepLink() {
+  return `granola://open?path=${encodeURIComponent(GRANOLA_API_KEYS_PATH)}`;
 }
 
 async function postJson(url, body, opts = {}) {
@@ -948,6 +1107,10 @@ async function writeMessagesConfig(input) {
   const dir = join(homedir(), ".shepherd", "raw-messages");
   await mkdir(dir, { recursive: true });
   const path = join(dir, `${input.userId}.json`);
+  const allowedChatIds = parseAllowedChatIds(input.allowedChatIds);
+  if (allowedChatIds.length === 0) {
+    throw new Error("Select at least one Messages chat before installing local Messages sync.");
+  }
   await writeFile(
     path,
     JSON.stringify({
@@ -955,6 +1118,8 @@ async function writeMessagesConfig(input) {
       userId: input.userId,
       agentToken: input.agentToken,
       backfillDays: input.backfillDays,
+      allowedChatIds,
+      selectedChats: Array.isArray(input.selectedChats) ? input.selectedChats.map(publicMessageChat) : [],
       createdAt: new Date().toISOString(),
     }, null, 2),
     { mode: 0o600 },
@@ -1019,6 +1184,120 @@ async function installMessagesAgent(configPath, userId) {
   return { label, plistPath, stdoutPath, stderrPath };
 }
 
+async function selectRecentMessageChats() {
+  const explicitIds = parseMessageChatIdsArg();
+  if (explicitIds.length > 0) {
+    return explicitIds.map((chatId) => ({ chatId, label: chatId, kind: "unknown", participants: [] }));
+  }
+
+  if (!process.stdin.isTTY) {
+    throw new Error(`Messages sync requires selected chat IDs. Run ${agentCommand()} messages-chats --json and pass --messages-chat-ids "<id1>,<id2>".`);
+  }
+
+  const chats = await listRecentMessageChats({ limit: DEFAULT_RECENT_MESSAGE_CHATS });
+  if (chats.length === 0) {
+    throw new Error("No recent local Messages chats were found on this Mac.");
+  }
+
+  console.log(`\nSelect local Messages chats to sync\n`);
+  console.log("Shepherd will only pull from the chats you select.");
+  for (let i = 0; i < chats.length; i++) {
+    console.log(`${String(i + 1).padStart(2, " ")}. ${formatMessageChatOption(chats[i])}`);
+  }
+
+  const answer = await prompt("\nEnter chat numbers to sync, separated by commas: ");
+  const indexes = parseSelectionIndexes(answer, chats.length);
+  if (indexes.length === 0) throw new Error("Select at least one Messages chat.");
+  return indexes.map((idx) => chats[idx]);
+}
+
+async function listRecentMessageChats({ limit }) {
+  if (platform() !== "darwin") {
+    throw new Error("local Messages chat discovery is only supported on macOS");
+  }
+
+  const kit = await import("@photon-ai/imessage-kit");
+  const sdk = new kit.IMessageSDK({ debug: args.debug === true });
+  const contactLookup = buildContactLookup();
+  try {
+    const chats = await sdk.listChats({
+      sortBy: "recent",
+      limit: Math.max(limit, DEFAULT_RECENT_MESSAGE_CHATS),
+    });
+    const visible = chats
+      .filter((chat) => typeof chat.chatId === "string" && chat.chatId.trim())
+      .filter((chat) => chat.kind === "dm" || chat.kind === "group")
+      .slice(0, limit);
+
+    const enriched = [];
+    for (const chat of visible) {
+      enriched.push(await enrichMessageChat(sdk, chat, contactLookup));
+    }
+    return enriched;
+  } finally {
+    await sdk.close?.().catch(() => undefined);
+  }
+}
+
+async function enrichMessageChat(sdk, chat, contactLookup) {
+  const recentMessages = await sdk.getMessages({ chatId: chat.chatId, limit: 30 }).catch(() => []);
+  const participants = uniqueParticipants(recentMessages, contactLookup);
+  const dmHandle = chat.kind === "dm"
+    ? participants[0]?.handle ?? parseDmHandleFromChatId(chat.chatId)
+    : null;
+  const dmName = dmHandle ? contactLookup.resolveName(dmHandle) : null;
+  const groupNames = participants.map((participant) => participant.name ?? participant.handle).filter(Boolean);
+  const label = cleanChatName(chat.name)
+    ?? (chat.kind === "dm" ? dmName ?? dmHandle : null)
+    ?? (chat.kind === "group" && groupNames.length ? groupNames.slice(0, 4).join(", ") : null)
+    ?? (chat.kind === "group" ? "Group chat" : "Direct message");
+
+  return {
+    chatId: chat.chatId,
+    label,
+    kind: chat.kind ?? "unknown",
+    service: chat.service ?? null,
+    lastMessageAt: isoDate(chat.lastMessageAt),
+    participants,
+  };
+}
+
+function uniqueParticipants(messages, contactLookup) {
+  const seen = new Set();
+  const participants = [];
+  for (const msg of messages) {
+    const handle = typeof msg.participant === "string" ? msg.participant.trim() : "";
+    if (!handle || contactLookup.isSelfHandle(handle)) continue;
+    const normalized = normalizeHandle(handle);
+    if (seen.has(normalized)) continue;
+    seen.add(normalized);
+    participants.push({
+      handle,
+      name: contactLookup.resolveName(handle),
+    });
+  }
+  return participants;
+}
+
+function formatMessageChatOption(chat) {
+  const kind = chat.kind === "group" ? "group" : chat.kind === "dm" ? "dm" : "chat";
+  const names = chat.participants?.map((participant) => participant.name ?? participant.handle).filter(Boolean) ?? [];
+  const people = names.length ? ` · ${names.slice(0, 4).join(", ")}` : "";
+  const when = chat.lastMessageAt ? ` · ${new Date(chat.lastMessageAt).toLocaleString()}` : "";
+  return `${chat.label} (${kind})${people}${when}`;
+}
+
+function publicMessageChat(chat) {
+  return {
+    chatId: chat.chatId,
+    label: chat.label,
+    kind: chat.kind,
+    service: chat.service ?? null,
+    lastMessageAt: chat.lastMessageAt ?? null,
+    participants: Array.isArray(chat.participants) ? chat.participants : [],
+  };
+}
+
 async function loadGroupChatNames(sdk, serializer) {
   if (typeof sdk.listChats !== "function") return;
   try {
@@ -1032,36 +1311,50 @@ async function loadGroupChatNames(sdk, serializer) {
   }
 }
 
-async function runMessagesBackfill(sdk, sender, serializer, days) {
-  console.log(`Running ${days}-day Messages backfill`);
+function loadSelectedChatNames(selectedChats, serializer) {
+  if (!Array.isArray(selectedChats)) return;
+  for (const chat of selectedChats) {
+    if (chat && typeof chat.chatId === "string" && typeof chat.label === "string") {
+      serializer.setChatName(chat.chatId, chat.label);
+    }
+  }
+}
+
+async function runMessagesBackfill(sdk, sender, serializer, days, allowedChatIds) {
+  console.log(`Running ${days}-day Messages backfill for ${allowedChatIds.length} selected chat(s)`);
   const since = new Date(Date.now() - days * 24 * 60 * 60 * 1000);
   const pageSize = 1000;
-  let offset = 0;
   let totalMessages = 0;
   let totalStored = 0;
 
-  while (true) {
-    const messages = await sdk.getMessages({ since, limit: pageSize, offset });
-    if (!messages.length) break;
+  for (const chatId of allowedChatIds) {
+    let offset = 0;
+    while (true) {
+      const messages = await sdk.getMessages({ chatId, since, limit: pageSize, offset });
+      if (!messages.length) break;
 
-    totalMessages += messages.length;
-    const result = await sender.send(messages.map((msg) => serializer.serialize(msg)));
-    totalStored += result.stored;
-    saveMessagesWatermark(sender.userId, maxRowId(messages));
+      totalMessages += messages.length;
+      const result = await sender.send(messages.map((msg) => serializer.serialize(msg)));
+      totalStored += result.stored;
+      saveMessagesWatermark(sender.userId, maxRowId(messages));
 
-    if (messages.length < pageSize) break;
-    offset += pageSize;
+      if (messages.length < pageSize) break;
+      offset += pageSize;
+    }
   }
 
   console.log(`Messages backfill complete: stored ${totalStored} of ${totalMessages}`);
 }
 
-async function gapFillFromWatermark(sdk, sender, serializer, userId) {
+async function gapFillFromWatermark(sdk, sender, serializer, userId, allowedChatIds) {
   const lastWatermark = loadMessagesWatermark(userId);
   if (lastWatermark <= 0) return;
 
-  const missed = await sdk.getMessages({ limit: 5000 });
-  const newMessages = missed.filter((msg) => Number(msg.rowId) > lastWatermark);
+  const missed = [];
+  for (const chatId of allowedChatIds) {
+    missed.push(...await sdk.getMessages({ chatId, limit: 1000 }));
+  }
+  const newMessages = missed.filter((msg) => Number(msg.rowId) > lastWatermark && allowedChatIds.includes(msg.chatId));
   if (newMessages.length === 0) return;
 
   const result = await sender.send(newMessages.map((msg) => serializer.serialize(msg)));
@@ -1069,7 +1362,8 @@ async function gapFillFromWatermark(sdk, sender, serializer, userId) {
   console.log(`Messages gap-fill complete: stored ${result.stored} of ${newMessages.length}`);
 }
 
-async function watchMessages(sdk, sender, serializer, userId) {
+async function watchMessages(sdk, sender, serializer, userId, allowedChatIds) {
+  const allowed = new Set(allowedChatIds);
   let buffer = [];
   let timer = null;
 
@@ -1089,6 +1383,7 @@ async function watchMessages(sdk, sender, serializer, userId) {
   };
 
   const onMessage = (msg) => {
+    if (!msg.chatId || !allowed.has(msg.chatId)) return;
     buffer.push(msg);
     if (buffer.length >= MAX_BATCH_SIZE) {
       if (timer) clearTimeout(timer);
@@ -1105,7 +1400,7 @@ async function watchMessages(sdk, sender, serializer, userId) {
     onError: (err) => console.error("Messages watcher error:", safeError(err)),
   });
 
-  console.log("Watching for new Messages");
+  console.log("Watching for new Messages in selected chats");
 
   const shutdown = async () => {
     if (timer) clearTimeout(timer);
@@ -1118,7 +1413,7 @@ async function watchMessages(sdk, sender, serializer, userId) {
   process.on("SIGTERM", shutdown);
 }
 
-function createMessageSerializer(kit) {
+function createMessageSerializer(kit, contactLookup = emptyContactLookup()) {
   const chatNames = new Map();
   const isImageAttachment = kit.isImageAttachment ?? (() => false);
   const isVideoAttachment = kit.isVideoAttachment ?? (() => false);
@@ -1173,11 +1468,213 @@ function createMessageSerializer(kit) {
         isForwarded: Boolean(msg.isForwarded),
         affectedParticipant: msg.affectedParticipant ?? null,
         newGroupName: msg.newGroupName ?? null,
+        _resolved_name: msg.participant ? contactLookup.resolveName(msg.participant) : null,
+        _is_self_handle: msg.participant ? contactLookup.isSelfHandle(msg.participant) : false,
       };
     },
   };
 }
 
+function buildContactLookup() {
+  const contacts = loadContacts();
+  const myCard = loadMyCard();
+  const handleToName = new Map();
+  const selfHandles = new Set();
+
+  for (const contact of contacts) {
+    for (const phone of contact.phones) {
+      addHandleMapping(handleToName, phone, contact.name);
+    }
+    for (const email of contact.emails) {
+      addHandleMapping(handleToName, email, contact.name);
+    }
+  }
+
+  if (myCard) {
+    for (const phone of myCard.phones) addSelfHandle(selfHandles, phone);
+    for (const email of myCard.emails) addSelfHandle(selfHandles, email);
+  }
+
+  return {
+    resolveName(handle) {
+      const candidates = handleCandidates(handle);
+      for (const candidate of candidates) {
+        const name = handleToName.get(candidate);
+        if (name) return name;
+      }
+      return null;
+    },
+    isSelfHandle(handle) {
+      return handleCandidates(handle).some((candidate) => selfHandles.has(candidate));
+    },
+  };
+}
+
+function emptyContactLookup() {
+  return {
+    resolveName() {
+      return null;
+    },
+    isSelfHandle() {
+      return false;
+    },
+  };
+}
+
+function loadContacts() {
+  if (platform() !== "darwin") return [];
+  const script = `
+set output to ""
+tell application "Contacts"
+  repeat with p in every person
+    set pName to name of p
+    set phList to ""
+    repeat with ph in phones of p
+      if phList is not "" then set phList to phList & ","
+      set phList to phList & (value of ph)
+    end repeat
+    set eList to ""
+    repeat with e in emails of p
+      if eList is not "" then set eList to eList & ","
+      set eList to eList & (value of e)
+    end repeat
+    set output to output & pName & "\\t" & phList & "\\t" & eList & "\\n"
+  end repeat
+end tell
+return output`;
+
+  try {
+    const raw = execFileSync("osascript", ["-e", script], {
+      encoding: "utf8",
+      timeout: 30_000,
+    });
+    return parseContacts(raw);
+  } catch {
+    return [];
+  }
+}
+
+function loadMyCard() {
+  if (platform() !== "darwin") return null;
+  const script = `
+tell application "Contacts"
+  set mc to my card
+  set pName to name of mc
+  set phList to ""
+  repeat with ph in phones of mc
+    if phList is not "" then set phList to phList & ","
+    set phList to phList & (value of ph)
+  end repeat
+  set eList to ""
+  repeat with e in emails of mc
+    if eList is not "" then set eList to eList & ","
+    set eList to eList & (value of e)
+  end repeat
+  return pName & "\\t" & phList & "\\t" & eList
+end tell`;
+
+  try {
+    const raw = execFileSync("osascript", ["-e", script], {
+      encoding: "utf8",
+      timeout: 10_000,
+    });
+    return parseContacts(raw)[0] ?? null;
+  } catch {
+    return null;
+  }
+}
+
+function parseContacts(raw) {
+  return String(raw)
+    .split("\n")
+    .filter(Boolean)
+    .map((line) => {
+      const [name, phones, emails] = line.split("\t");
+      return {
+        name: name?.trim() ?? "",
+        phones: phones ? phones.split(",").map((phone) => phone.trim()).filter(Boolean) : [],
+        emails: emails ? emails.split(",").map((email) => email.trim()).filter(Boolean) : [],
+      };
+    })
+    .filter((contact) => contact.name);
+}
+
+function addHandleMapping(map, handle, name) {
+  for (const candidate of handleCandidates(handle)) {
+    map.set(candidate, name);
+  }
+}
+
+function addSelfHandle(set, handle) {
+  for (const candidate of handleCandidates(handle)) {
+    set.add(candidate);
+  }
+}
+
+function handleCandidates(handle) {
+  const raw = String(handle ?? "").trim();
+  if (!raw) return [];
+  const lower = raw.toLowerCase();
+  const normalized = normalizeHandle(raw);
+  const candidates = new Set([raw, lower, normalized]);
+  if (normalized.startsWith("+1") && normalized.length === 12) {
+    candidates.add(normalized.slice(2));
+  }
+  if (/^\d{10}$/.test(normalized)) {
+    candidates.add(`+1${normalized}`);
+  }
+  return [...candidates].filter(Boolean);
+}
+
+function normalizeHandle(handle) {
+  const raw = String(handle ?? "").trim();
+  if (raw.includes("@")) return raw.toLowerCase();
+  const compact = raw.replace(/[^\d+]/g, "");
+  if (/^1\d{10}$/.test(compact)) return `+${compact}`;
+  if (/^\d{10}$/.test(compact)) return `+1${compact}`;
+  return compact || raw.toLowerCase();
+}
+
+function cleanChatName(name) {
+  if (typeof name !== "string") return null;
+  const trimmed = name.trim();
+  return trimmed || null;
+}
+
+function parseDmHandleFromChatId(chatId) {
+  const parts = String(chatId ?? "").split(";");
+  if (parts.length >= 3 && parts[1] === "-") return parts.slice(2).join(";") || null;
+  return null;
+}
+
+function parseSelectionIndexes(answer, max) {
+  const indexes = new Set();
+  for (const part of String(answer ?? "").split(/[,\s]+/).map((value) => value.trim()).filter(Boolean)) {
+    const range = part.match(/^(\d+)-(\d+)$/);
+    if (range) {
+      const start = Number(range[1]);
+      const end = Number(range[2]);
+      for (let value = Math.min(start, end); value <= Math.max(start, end); value++) {
+        if (value >= 1 && value <= max) indexes.add(value - 1);
+      }
+      continue;
+    }
+    const value = Number(part);
+    if (Number.isInteger(value) && value >= 1 && value <= max) indexes.add(value - 1);
+  }
+  return [...indexes].sort((a, b) => a - b);
+}
+
+function parseMessageChatIdsArg() {
+  return parseAllowedChatIds(args["messages-chat-ids"] ?? args["message-chat-ids"] ?? args["messages-chats"]);
+}
+
+function parseAllowedChatIds(value) {
+  if (!value) return [];
+  const raw = Array.isArray(value) ? value : String(value).split(",");
+  return [...new Set(raw.map((chatId) => String(chatId).trim()).filter(Boolean))];
+}
+
 class MessagesBatchSender {
   constructor(apiUrl, agentToken, userId) {
     this.apiUrl = trimTrailingSlash(apiUrl);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "shepherd-onboard",
-  "version": "0.1.9",
+  "version": "0.1.11",
   "description": "Customer-facing Shepherd raw sync onboarding CLI",
   "type": "module",
   "bin": {