shepherd-onboard 0.1.11 → 0.1.13

package/README.md

@@ -11,7 +11,7 @@ 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, 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.
+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`, opens a minimal searchable local webpage, and has the user select which contacts/groups 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
@@ -31,7 +31,7 @@ The command:
 - 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
-- shows the 20 most recent local Messages chats with contact/group names and only syncs the chats selected by the user
+- opens a minimal searchable local webpage 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
@@ -74,12 +74,16 @@ Shepherd must still enforce selected users and groups internally before imperson
 
 ## Messages Chat Selection
 
-List recent local Messages chats:
+Open the local Messages chat selector:
 
 ```sh
-npx -y shepherd-onboard@latest messages-chats --json
+npx -y shepherd-onboard@latest messages-chats
 ```
 
+Use `--json` for machine-readable chat metadata, or `--text` for a terminal list.
+
+The browser selector displays the first page of recent chats and lets the user search contacts or groups loaded from local Messages.
+
 Pass the selected chat IDs when finishing onboarding:
 
 ```sh

package/bin/shepherd-onboard.js

@@ -2,17 +2,22 @@
 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 { createServer } from "node:http";
 import { homedir, platform } from "node:os";
 import { dirname, join } from "node:path";
 import readline from "node:readline";
+import { fileURLToPath } from "node:url";
 
 const DEFAULT_API_URL = "https://brain-api-customer-facing.up.railway.app";
 const PACKAGE_NAME = "shepherd-onboard";
 const PACKAGE_SPEC = `${PACKAGE_NAME}@latest`;
+const PACKAGE_DIR = dirname(dirname(fileURLToPath(import.meta.url)));
 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 DEFAULT_MESSAGE_CHAT_SEARCH_LIMIT = 200;
+const INITIAL_MESSAGE_CHAT_ROWS = 20;
+const SHEPHERD_LOGO_PATH = join(PACKAGE_DIR, "assets", "shepherd_G_vector_136033.png");
 const GRANOLA_API_KEYS_PATH = "/settings/integrations/api-keys";
 const GOOGLE_WORKSPACE_DELEGATION_APP_NAME = "Shepherd";
 const GOOGLE_WORKSPACE_DELEGATION_SERVICE_ACCOUNT_EMAIL =
@@ -312,7 +317,7 @@ async function runAgentOnboarding() {
       googleWorkspaceDelegation: sources.google ? googleWorkspaceDelegationSetup(session.googleWorkspaceDelegation) : undefined,
       granolaApiKeyPage,
       statePath,
-      messagesChatsCommand: sources.messages ? `${agentCommand()} messages-chats --json` : undefined,
+      messagesChatsCommand: sources.messages ? `${agentCommand()} messages-chats` : 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));
@@ -347,7 +352,7 @@ async function runAgentOnboarding() {
   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 ${agentCommand()} messages-chats, have the user select chats in the browser page, and keep the printed 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>"`);
@@ -440,7 +445,7 @@ async function continueAgentOnboarding() {
   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>".`);
+    throw new Error(`Messages sync requires selected chat IDs. Run ${agentCommand()} messages-chats, have the user select chats in the browser page, then rerun --continue with --messages-chat-ids "<id1>,<id2>".`);
   }
 
   const finalized = await postJson(
@@ -514,7 +519,7 @@ async function printAgentStatus() {
 
 async function runMessagesChatsCommand() {
   const chats = await listRecentMessageChats({
-    limit: clampInt(Number(args.limit ?? DEFAULT_RECENT_MESSAGE_CHATS), 1, 100),
+    limit: clampInt(Number(args.limit ?? DEFAULT_MESSAGE_CHAT_SEARCH_LIMIT), 1, 500),
   });
 
   if (args.json) {
@@ -522,6 +527,16 @@ async function runMessagesChatsCommand() {
     return;
   }
 
+  if (!args.text && !args.list) {
+    const selected = await selectChatsInBrowser(chats, { noOpen: Boolean(args["no-open"]) });
+    const selectedIds = selected.map((chat) => chat.chatId).join(",");
+    console.log(`\nSelected ${selected.length} Messages chat(s).`);
+    console.log(`messages-chat-ids=${selectedIds}`);
+    console.log("\nContinue with:");
+    console.log(`  ${agentCommand()} agent --continue --messages-handle "<phone_or_apple_id>" --messages-chat-ids "${selectedIds}"`);
+    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])}`);
@@ -602,7 +617,7 @@ 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 messages-chats --json
+  npx -y ${PACKAGE_NAME}@latest messages-chats
   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
@@ -636,7 +651,9 @@ Usage:
   npx -y ${PACKAGE_NAME}@latest messages-chats --json
 
 Options:
-  --limit <n>                Number of recent chats to show. Defaults to ${DEFAULT_RECENT_MESSAGE_CHATS}.
+  --limit <n>                Number of recent chats to load for search. Defaults to ${DEFAULT_MESSAGE_CHAT_SEARCH_LIMIT}.
+  --text                     Print a terminal list instead of opening the selector page.
+  --no-open                  Print the local selector URL instead of opening it.
   --json                     Print machine-readable chat IDs and labels.
   --help                     Show this help.
 `);
@@ -689,7 +706,7 @@ function printAgentContract() {
       "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.",
+      "If Messages is selected, run the recent-chat command. It opens a browser selector with recent chats and search. Never sync all Messages chats by default.",
     ],
     selectionQuestions: [
       {
@@ -713,7 +730,7 @@ 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",
+      "Selected local Messages chats from the browser selector, if they want local Messages connected",
     ],
     afterStartCommand: [
       "For Google Workspace, have a super admin authorize the Shepherd Client ID and scopes in Google Admin Console.",
@@ -739,7 +756,7 @@ function printAgentContract() {
       "--granola-api-key \"<granola_key>\" if Granola is being connected",
     ],
     statusCommand: `${command} agent --status`,
-    messagesChatsCommand: `${command} messages-chats --json`,
+    messagesChatsCommand: `${command} messages-chats`,
     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.",
@@ -785,7 +802,7 @@ If they are joining an existing org, ask for the org name they believe they belo
 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.
+This opens a minimal local webpage with recent local Messages chats and search. Have the user select which contacts/groups Shepherd should sync. Do not select all chats by default. When the command returns, keep the printed comma-separated chat IDs.
 
 Then run:
   ${payload.startCommand}
@@ -923,7 +940,7 @@ function agentNeedsUserAction(sources, opened) {
   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("Run messages-chats, ask the user which recent local Messages chats to sync, then pass the selected chat IDs with the Messages handle.");
+  if (sources.messages) actions.push("Run messages-chats, have the user select local Messages contacts/groups in the browser, then pass the printed chat IDs with the Messages handle.");
   return actions;
 }
 
@@ -1191,14 +1208,18 @@ async function selectRecentMessageChats() {
   }
 
   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>".`);
+    throw new Error(`Messages sync requires selected chat IDs. Run ${agentCommand()} messages-chats and pass --messages-chat-ids "<id1>,<id2>".`);
   }
 
-  const chats = await listRecentMessageChats({ limit: DEFAULT_RECENT_MESSAGE_CHATS });
+  const chats = await listRecentMessageChats({ limit: clampInt(Number(args.limit ?? DEFAULT_MESSAGE_CHAT_SEARCH_LIMIT), 1, 500) });
   if (chats.length === 0) {
     throw new Error("No recent local Messages chats were found on this Mac.");
   }
 
+  if (!args.text && !args.list) {
+    return selectChatsInBrowser(chats, { noOpen: Boolean(args["no-open"]) });
+  }
+
   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++) {
@@ -1211,6 +1232,504 @@ async function selectRecentMessageChats() {
   return indexes.map((idx) => chats[idx]);
 }
 
+async function selectChatsInBrowser(chats, opts = {}) {
+  if (!chats.length) throw new Error("No recent local Messages chats were found on this Mac.");
+
+  const token = Math.random().toString(36).slice(2) + Math.random().toString(36).slice(2);
+  let settled = false;
+  let server;
+
+  return new Promise((resolve, reject) => {
+    const timeout = setTimeout(() => {
+      if (settled) return;
+      settled = true;
+      server?.close();
+      reject(new Error("Messages chat selection timed out."));
+    }, 20 * 60 * 1000);
+
+    server = createServer(async (req, res) => {
+      try {
+        const url = new URL(req.url ?? "/", `http://${req.headers.host ?? "127.0.0.1"}`);
+
+        if (req.method === "GET" && url.pathname === "/") {
+          sendHtml(res, renderMessagesSelectorPage(chats, token));
+          return;
+        }
+
+        if (req.method === "POST" && url.pathname === "/select") {
+          const body = await readRequestBody(req);
+          const form = new URLSearchParams(body);
+          if (form.get("token") !== token) {
+            sendHtml(res, renderMessagesDonePage("Invalid selection session.", true), 403);
+            return;
+          }
+          const selectedIds = form.getAll("chatId").filter(Boolean);
+          const selectedSet = new Set(selectedIds);
+          const selected = chats.filter((chat) => selectedSet.has(chat.chatId));
+          if (selected.length === 0) {
+            sendHtml(res, renderMessagesSelectorPage(chats, token, "Select at least one chat."));
+            return;
+          }
+
+          sendHtml(res, renderMessagesDonePage(`${selected.length} chat${selected.length === 1 ? "" : "s"} selected.`));
+          if (!settled) {
+            settled = true;
+            clearTimeout(timeout);
+            setTimeout(() => server.close(), 100);
+            resolve(selected);
+          }
+          return;
+        }
+
+        sendHtml(res, renderMessagesDonePage("Not found.", true), 404);
+      } catch (err) {
+        if (!settled) {
+          settled = true;
+          clearTimeout(timeout);
+          server?.close();
+          reject(err);
+        }
+      }
+    });
+
+    server.on("error", (err) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timeout);
+      reject(err);
+    });
+
+    server.listen(0, "127.0.0.1", async () => {
+      const address = server.address();
+      const port = typeof address === "object" && address ? address.port : null;
+      if (!port) {
+        settled = true;
+        clearTimeout(timeout);
+        server.close();
+        reject(new Error("Could not start local Messages selector."));
+        return;
+      }
+      const url = `http://127.0.0.1:${port}/`;
+      console.log(`\nOpening Messages chat selector: ${url}`);
+      await openOrPrint(url, { noOpen: Boolean(opts.noOpen) });
+      console.log("Select the Messages chats to sync in the browser.");
+    });
+  });
+}
+
+function renderMessagesSelectorPage(chats, token, error = "") {
+  const logo = shepherdLogoDataUri();
+  const rows = chats.map((chat, index) => {
+    const people = chatPeopleLine(chat);
+    const when = formatMessageChatMeta(chat);
+    const searchText = [
+      chat.label,
+      chat.kind,
+      people,
+      when,
+      ...(chat.participants ?? []).flatMap((participant) => [participant.name, participant.handle]),
+    ]
+      .filter(Boolean)
+      .join(" ")
+      .toLowerCase();
+
+    return `
+      <label class="chat-row" data-index="${index}" data-search="${htmlAttr(searchText)}">
+        <input type="checkbox" name="chatId" value="${htmlAttr(chat.chatId)}">
+        <span class="box" aria-hidden="true"></span>
+        <span class="chat-main">
+          <span class="chat-top">
+            <span class="chat-name">${html(chat.label)}</span>
+            <span class="chat-kind">${html(chat.kind === "group" ? "Group" : chat.kind === "dm" ? "Contact" : "Chat")}</span>
+          </span>
+          ${people ? `<span class="chat-people">${html(people)}</span>` : ""}
+          ${when ? `<span class="chat-meta">${html(when)}</span>` : ""}
+        </span>
+      </label>`;
+  }).join("");
+
+  return `<!doctype html>
+<html lang="en">
+<head>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <title>Select Messages Chats</title>
+  <style>
+    :root {
+      color-scheme: light dark;
+      --bg: #FCFCFC;
+      --fg: #111111;
+      --muted: #6D726D;
+      --line: #E8ECE8;
+      --panel: #FFFFFF;
+      --button: #136033;
+      --button-text: #FFFFFF;
+      --link: #136033;
+      --radius: 10px;
+    }
+    @media (prefers-color-scheme: dark) {
+      :root {
+        --bg: #000000;
+        --fg: #F8F8F8;
+        --muted: #A2A8A2;
+        --line: #202520;
+        --panel: #070907;
+        --button: #FFFFFF;
+        --button-text: #000000;
+        --link: #136033;
+      }
+    }
+    * { box-sizing: border-box; }
+    body {
+      margin: 0;
+      background: var(--bg);
+      color: var(--fg);
+      font-family: Geist, "Geist Sans", ui-sans-serif, system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif;
+      letter-spacing: 0;
+    }
+    main {
+      width: min(700px, calc(100vw - 32px));
+      margin: 36px auto;
+    }
+    header {
+      display: flex;
+      justify-content: space-between;
+      gap: 16px;
+      align-items: center;
+      padding-bottom: 18px;
+      border-bottom: 1px solid var(--line);
+    }
+    .brand {
+      display: flex;
+      gap: 10px;
+      align-items: center;
+      min-width: 0;
+    }
+    .logo {
+      width: 30px;
+      height: 30px;
+      border-radius: 8px;
+      object-fit: contain;
+      flex: none;
+    }
+    .logo-fallback {
+      width: 30px;
+      height: 30px;
+      border-radius: 8px;
+      display: grid;
+      place-items: center;
+      color: #FFFFFF;
+      background: #136033;
+      font-weight: 700;
+      flex: none;
+    }
+    h1 {
+      margin: 0;
+      font-size: 22px;
+      line-height: 1.1;
+      font-weight: 650;
+    }
+    form {
+      margin-top: 18px;
+    }
+    .search {
+      width: 100%;
+      margin: 0 0 12px;
+      border: 1px solid var(--line);
+      border-radius: var(--radius);
+      background: var(--panel);
+      color: var(--fg);
+      padding: 11px 12px;
+      font: inherit;
+      font-size: 14px;
+      outline: none;
+    }
+    .search:focus {
+      border-color: #136033;
+      box-shadow: 0 0 0 3px color-mix(in srgb, #136033 16%, transparent);
+    }
+    .search::placeholder {
+      color: var(--muted);
+    }
+    .error {
+      margin: 0 0 12px;
+      color: #9B1C1C;
+      font-size: 14px;
+    }
+    .chat-list {
+      display: grid;
+      gap: 8px;
+      margin: 0 0 18px;
+    }
+    .chat-row {
+      display: grid;
+      grid-template-columns: 24px 1fr;
+      gap: 12px;
+      align-items: start;
+      padding: 13px 14px;
+      background: var(--panel);
+      border: 1px solid var(--line);
+      border-radius: var(--radius);
+      cursor: pointer;
+    }
+    .chat-row:hover {
+      border-color: color-mix(in srgb, var(--link) 45%, var(--line));
+    }
+    input[type="checkbox"] {
+      position: absolute;
+      opacity: 0;
+      pointer-events: none;
+    }
+    .box {
+      width: 18px;
+      height: 18px;
+      margin-top: 2px;
+      border: 1.5px solid var(--muted);
+      border-radius: 5px;
+      display: inline-grid;
+      place-items: center;
+    }
+    input[type="checkbox"]:checked + .box {
+      background: var(--button);
+      border-color: var(--button);
+    }
+    input[type="checkbox"]:checked + .box::after {
+      content: "";
+      width: 7px;
+      height: 4px;
+      border-left: 2px solid var(--button-text);
+      border-bottom: 2px solid var(--button-text);
+      transform: rotate(-45deg) translateY(-1px);
+    }
+    .chat-main {
+      min-width: 0;
+      display: grid;
+      gap: 4px;
+    }
+    .chat-top {
+      display: flex;
+      gap: 10px;
+      align-items: center;
+      min-width: 0;
+    }
+    .chat-name {
+      overflow: hidden;
+      text-overflow: ellipsis;
+      white-space: nowrap;
+      font-size: 15px;
+      font-weight: 600;
+    }
+    .chat-kind {
+      color: var(--link);
+      font-size: 12px;
+      flex: none;
+    }
+    .chat-people,
+    .chat-meta {
+      color: var(--muted);
+      font-size: 13px;
+      line-height: 1.35;
+      overflow-wrap: anywhere;
+    }
+    [hidden] {
+      display: none !important;
+    }
+    .empty {
+      margin: 18px 0 28px;
+      color: var(--muted);
+      font-size: 14px;
+      text-align: center;
+    }
+    .actions {
+      display: flex;
+      justify-content: space-between;
+      align-items: center;
+      gap: 12px;
+      position: sticky;
+      bottom: 0;
+      padding: 14px 0 0;
+      background: linear-gradient(to top, var(--bg) 70%, transparent);
+    }
+    .selection-count {
+      color: var(--muted);
+      font-size: 13px;
+    }
+    button {
+      appearance: none;
+      border: 0;
+      border-radius: var(--radius);
+      background: var(--button);
+      color: var(--button-text);
+      padding: 10px 14px;
+      font: inherit;
+      font-weight: 620;
+      cursor: pointer;
+    }
+    a { color: var(--link); }
+  </style>
+</head>
+<body>
+  <main>
+    <header>
+      <div class="brand">
+        ${logo ? `<img class="logo" src="${htmlAttr(logo)}" alt="">` : `<span class="logo-fallback" aria-hidden="true">G</span>`}
+        <h1>Select chats</h1>
+      </div>
+    </header>
+    <form method="post" action="/select">
+      <input type="hidden" name="token" value="${htmlAttr(token)}">
+      <input class="search" id="search" type="search" placeholder="Search contacts or groups" autocomplete="off">
+      ${error ? `<p class="error">${html(error)}</p>` : ""}
+      <div class="chat-list">${rows}</div>
+      <p class="empty" id="empty" hidden>No chats found.</p>
+      <div class="actions">
+        <span class="selection-count" id="selection-count">Select one or more</span>
+        <button type="submit">return</button>
+      </div>
+    </form>
+  </main>
+  <script>
+    const initialRows = ${INITIAL_MESSAGE_CHAT_ROWS};
+    const rows = Array.from(document.querySelectorAll(".chat-row"));
+    const search = document.getElementById("search");
+    const empty = document.getElementById("empty");
+    const selected = document.getElementById("selection-count");
+    const checks = Array.from(document.querySelectorAll('input[name="chatId"]'));
+
+    function updateRows() {
+      const query = search.value.trim().toLowerCase();
+      let visible = 0;
+      for (const row of rows) {
+        const matches = query
+          ? row.dataset.search.includes(query)
+          : Number(row.dataset.index) < initialRows;
+        row.hidden = !matches;
+        if (matches) visible += 1;
+      }
+      empty.hidden = visible !== 0;
+    }
+
+    function updateSelected() {
+      const count = checks.filter((check) => check.checked).length;
+      selected.textContent = count ? count + " selected" : "Select one or more";
+    }
+
+    search.addEventListener("input", updateRows);
+    for (const check of checks) check.addEventListener("change", updateSelected);
+    updateRows();
+    updateSelected();
+  </script>
+</body>
+</html>`;
+}
+
+function renderMessagesDonePage(message, isError = false) {
+  return `<!doctype html>
+<html lang="en">
+<head>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <title>Messages Selection</title>
+  <style>
+    :root { color-scheme: light dark; --bg: #FCFCFC; --fg: #111; --muted: #6D726D; --button: #136033; --button-text: #FFFFFF; --radius: 10px; }
+    @media (prefers-color-scheme: dark) { :root { --bg: #000; --fg: #F8F8F8; --muted: #A2A8A2; --button: #FFFFFF; --button-text: #000; } }
+    body { margin: 0; min-height: 100vh; display: grid; place-items: center; background: var(--bg); color: var(--fg); font-family: Geist, "Geist Sans", ui-sans-serif, system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif; letter-spacing: 0; }
+    main { width: min(420px, calc(100vw - 32px)); }
+    h1 { margin: 0 0 8px; font-size: 24px; line-height: 1.1; font-weight: 650; }
+    p { margin: 0; color: var(--muted); font-size: 14px; line-height: 1.45; }
+    .mark { width: 34px; height: 34px; border-radius: var(--radius); display: grid; place-items: center; margin-bottom: 14px; background: var(--button); color: var(--button-text); font-weight: 700; }
+  </style>
+</head>
+<body>
+  <main>
+    <div class="mark">${isError ? "!" : "OK"}</div>
+    <h1>${html(message)}</h1>
+    <p>${isError ? "Return to the terminal and retry." : "You can close this tab and return to the terminal."}</p>
+  </main>
+</body>
+</html>`;
+}
+
+function renderChatPeople(chat) {
+  const people = chatPeopleLine(chat);
+  if (!people) return "";
+  return `<span class="chat-people">${html(people)}</span>`;
+}
+
+function chatPeopleLine(chat) {
+  if (chat.kind !== "group") return "";
+  const names = chat.participants?.map((participant) => participant.name ?? participant.handle).filter(Boolean) ?? [];
+  const line = names.slice(0, 6).join(", ");
+  if (!line || normalizeDisplayText(line) === normalizeDisplayText(chat.label)) return "";
+  return line;
+}
+
+function formatMessageChatMeta(chat) {
+  return formatShortChatTime(chat.lastMessageAt);
+}
+
+function formatShortChatTime(value) {
+  if (!value) return "";
+  const date = new Date(value);
+  if (Number.isNaN(date.getTime())) return "";
+
+  const now = new Date();
+  const today = new Date(now.getFullYear(), now.getMonth(), now.getDate());
+  const day = new Date(date.getFullYear(), date.getMonth(), date.getDate());
+  const diffDays = Math.round((today.getTime() - day.getTime()) / (24 * 60 * 60 * 1000));
+  const time = new Intl.DateTimeFormat(undefined, { hour: "numeric", minute: "2-digit" })
+    .format(date)
+    .replace(":00", "")
+    .replace(/\s/g, "")
+    .toLowerCase();
+
+  if (diffDays === 0) return `Today ${time}`;
+  if (diffDays === 1) return `Yesterday ${time}`;
+  if (diffDays >= 0 && diffDays < 7) {
+    const weekday = new Intl.DateTimeFormat(undefined, { weekday: "long" }).format(date);
+    return `${weekday} ${time}`;
+  }
+  const monthDay = new Intl.DateTimeFormat(undefined, { month: "short", day: "numeric" }).format(date);
+  return `${monthDay} ${time}`;
+}
+
+function normalizeDisplayText(value) {
+  return String(value ?? "").trim().replace(/\s+/g, " ").toLowerCase();
+}
+
+function shepherdLogoDataUri() {
+  try {
+    const bytes = readFileSync(SHEPHERD_LOGO_PATH);
+    return `data:image/png;base64,${bytes.toString("base64")}`;
+  } catch {
+    return null;
+  }
+}
+
+function sendHtml(res, body, status = 200) {
+  res.writeHead(status, {
+    "Content-Type": "text/html; charset=utf-8",
+    "Cache-Control": "no-store",
+  });
+  res.end(body);
+}
+
+function readRequestBody(req) {
+  return new Promise((resolve, reject) => {
+    let body = "";
+    req.setEncoding("utf8");
+    req.on("data", (chunk) => {
+      body += chunk;
+      if (body.length > 64_000) {
+        reject(new Error("Request body too large."));
+        req.destroy();
+      }
+    });
+    req.on("end", () => resolve(body));
+    req.on("error", reject);
+  });
+}
+
 async function listRecentMessageChats({ limit }) {
   if (platform() !== "darwin") {
     throw new Error("local Messages chat discovery is only supported on macOS");
@@ -1222,7 +1741,7 @@ async function listRecentMessageChats({ limit }) {
   try {
     const chats = await sdk.listChats({
       sortBy: "recent",
-      limit: Math.max(limit, DEFAULT_RECENT_MESSAGE_CHATS),
+      limit: Math.max(limit, INITIAL_MESSAGE_CHAT_ROWS),
     });
     const visible = chats
       .filter((chat) => typeof chat.chatId === "string" && chat.chatId.trim())
@@ -1247,10 +1766,12 @@ async function enrichMessageChat(sdk, chat, contactLookup) {
     : 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");
+  const chatName = cleanChatName(chat.name);
+  const label = chat.kind === "dm"
+    ? dmName ?? nonHandleChatName(chatName) ?? dmHandle ?? "Contact"
+    : nonHandleChatName(chatName)
+      ?? (groupNames.length ? groupNames.slice(0, 4).join(", ") : null)
+      ?? "Group";
 
   return {
     chatId: chat.chatId,
@@ -1280,11 +1801,10 @@ function uniqueParticipants(messages, contactLookup) {
 }
 
 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}`;
+  const kind = chat.kind === "group" ? "Group" : chat.kind === "dm" ? "Contact" : "Chat";
+  const people = chatPeopleLine(chat);
+  const when = formatMessageChatMeta(chat);
+  return [chat.label, kind, people, when].filter(Boolean).join(" · ");
 }
 
 function publicMessageChat(chat) {
@@ -1641,6 +2161,27 @@ function cleanChatName(name) {
   return trimmed || null;
 }
 
+function nonHandleChatName(name) {
+  if (!name) return null;
+  return looksLikeHandleList(name) ? null : name;
+}
+
+function looksLikeHandleList(value) {
+  const text = String(value ?? "").trim();
+  if (!text) return false;
+  const tokens = text
+    .split(/[,;/&\s]+/)
+    .map((token) => token.trim())
+    .filter(Boolean);
+  if (!tokens.length) return false;
+  return tokens.every((token) => {
+    if (token.includes("@")) return true;
+    const digits = token.replace(/\D/g, "");
+    if (digits.length >= 4 && /^[+()\-\d.\s]+$/.test(token)) return true;
+    return /^\d{4,}$/.test(token);
+  });
+}
+
 function parseDmHandleFromChatId(chatId) {
   const parts = String(chatId ?? "").split(";");
   if (parts.length >= 3 && parts[1] === "-") return parts.slice(2).join(";") || null;
@@ -1675,6 +2216,17 @@ function parseAllowedChatIds(value) {
   return [...new Set(raw.map((chatId) => String(chatId).trim()).filter(Boolean))];
 }
 
+function html(value) {
+  return String(value ?? "")
+    .replace(/&/g, "&amp;")
+    .replace(/</g, "&lt;")
+    .replace(/>/g, "&gt;");
+}
+
+function htmlAttr(value) {
+  return html(value).replace(/"/g, "&quot;");
+}
+
 class MessagesBatchSender {
   constructor(apiUrl, agentToken, userId) {
     this.apiUrl = trimTrailingSlash(apiUrl);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "shepherd-onboard",
-  "version": "0.1.11",
+  "version": "0.1.13",
   "description": "Customer-facing Shepherd raw sync onboarding CLI",
   "type": "module",
   "bin": {
@@ -10,6 +10,7 @@
     "@photon-ai/imessage-kit": "^3.0.0"
   },
   "files": [
+    "assets",
     "bin",
     "README.md"
   ],