@gravity-rail/cli 0.7.0 → 0.7.1

package/dist/lib.js

@@ -1452,6 +1452,45 @@ var AdminApi = class extends BaseApiClient {
       `admin/temporal/workflows/${encoded}${qs ? `?${qs}` : ""}`
     );
   }
+  // ── Customer activity events (cross-workspace operator feed) ──────────────
+  async listCustomerActivityEvents(params = {}) {
+    const qs = new URLSearchParams();
+    if (params.page) qs.set("page", String(params.page));
+    if (params.pageSize) qs.set("pageSize", String(params.pageSize));
+    if (params.status) qs.set("status", params.status);
+    if (params.subjectType) qs.set("subjectType", params.subjectType);
+    if (params.source) qs.set("source", params.source);
+    if (params.severity) qs.set("severity", params.severity);
+    if (params.disposition) qs.set("disposition", params.disposition);
+    if (params.workspaceId !== void 0) qs.set("workspaceId", String(params.workspaceId));
+    if (params.organizationId !== void 0)
+      qs.set("organizationId", String(params.organizationId));
+    if (params.accountId !== void 0) qs.set("accountId", String(params.accountId));
+    const query = qs.toString();
+    return this.fetch(
+      `admin/customer-activity${query ? `?${query}` : ""}`
+    );
+  }
+  async getCustomerActivityEvent(uuid) {
+    return this.fetch(`admin/customer-activity/${uuid}`);
+  }
+  async setCustomerActivityEventDisposition(uuid, data) {
+    return this.fetch(`admin/customer-activity/${uuid}/disposition`, {
+      method: "POST",
+      body: JSON.stringify(data)
+    });
+  }
+  async setCustomerActivityEventStatus(uuid, data) {
+    return this.fetch(`admin/customer-activity/${uuid}/status`, {
+      method: "POST",
+      body: JSON.stringify(data)
+    });
+  }
+  async reclassifyCustomerActivityEvent(uuid) {
+    return this.fetch(`admin/customer-activity/${uuid}/reclassify`, {
+      method: "POST"
+    });
+  }
 };
 function appendTemporalWorkspaceParams(params, options) {
   const seen = /* @__PURE__ */ new Set();
@@ -1478,6 +1517,11 @@ function bindAdminMethods(target, admin) {
   target.createOutboundSupportRequestAsAdmin = admin.createOutboundSupportRequestAsAdmin.bind(admin);
   target.attachSupportRequestResourceAsAdmin = admin.attachSupportRequestResourceAsAdmin.bind(admin);
   target.revokeSupportRequestResourceAsAdmin = admin.revokeSupportRequestResourceAsAdmin.bind(admin);
+  target.listCustomerActivityEvents = admin.listCustomerActivityEvents.bind(admin);
+  target.getCustomerActivityEvent = admin.getCustomerActivityEvent.bind(admin);
+  target.setCustomerActivityEventDisposition = admin.setCustomerActivityEventDisposition.bind(admin);
+  target.setCustomerActivityEventStatus = admin.setCustomerActivityEventStatus.bind(admin);
+  target.reclassifyCustomerActivityEvent = admin.reclassifyCustomerActivityEvent.bind(admin);
   target.getAccounts = admin.getAccounts.bind(admin);
   target.getAccountDetails = admin.getAccountDetails.bind(admin);
   target.getAccountByUuid = admin.getAccountByUuid.bind(admin);
@@ -1653,6 +1697,11 @@ var ApiClient = class extends GravityRailClient {
   createOutboundSupportRequestAsAdmin;
   attachSupportRequestResourceAsAdmin;
   revokeSupportRequestResourceAsAdmin;
+  listCustomerActivityEvents;
+  getCustomerActivityEvent;
+  setCustomerActivityEventDisposition;
+  setCustomerActivityEventStatus;
+  reclassifyCustomerActivityEvent;
   getAccounts;
   getAccountDetails;
   getAccountByUuid;
@@ -2128,9 +2177,78 @@ This workspace requires organization SSO authentication.`);
   });
 }
 
+// src/lib/pinned-fetch.ts
+import { Agent, fetch as undiciFetch } from "undici";
+function createPinnedFetch(apiUrl, apiIp) {
+  if (!apiIp) return fetch;
+  let parsed;
+  try {
+    parsed = new URL(apiUrl);
+  } catch {
+    return fetch;
+  }
+  const hostname = parsed.hostname;
+  const dispatcher = new Agent({
+    connect: {
+      servername: hostname
+    }
+  });
+  return async (input, init) => {
+    const url = typeof input === "string" ? input : input instanceof URL ? input.href : input.url;
+    let reqUrl;
+    try {
+      reqUrl = new URL(url, apiUrl);
+    } catch {
+      return fetch(input, init);
+    }
+    const headers2 = new Headers(init?.headers);
+    if (reqUrl.hostname === hostname) {
+      headers2.set("Host", hostname);
+      reqUrl = new URL(reqUrl.href);
+      reqUrl.hostname = apiIp;
+    }
+    return undiciFetch(reqUrl, {
+      ...init,
+      headers: headers2,
+      dispatcher
+    });
+  };
+}
+function withAuditHeaders(fetchFn, headers2) {
+  const { chatId, sessionId, toolCallId } = headers2;
+  if (chatId === void 0 && !sessionId && !toolCallId) {
+    return fetchFn;
+  }
+  return async (input, init) => {
+    const reqHeaders = new Headers(init?.headers);
+    if (chatId !== void 0) {
+      reqHeaders.set("X-GR-Chat-Id", String(chatId));
+    }
+    if (sessionId) {
+      reqHeaders.set("X-GR-Session-Id", sessionId);
+    }
+    if (toolCallId) {
+      reqHeaders.set("X-GR-Tool-Call-Id", toolCallId);
+    }
+    return fetchFn(input, { ...init, headers: reqHeaders });
+  };
+}
+function createSandboxFetchFromEnv(apiUrl) {
+  const apiIp = process.env.GRAVITY_RAIL_API_IP;
+  let fetchFn = createPinnedFetch(apiUrl, apiIp);
+  const chatIdRaw = process.env.GRAVITY_RAIL_CHAT_ID;
+  const chatId = chatIdRaw ? Number(chatIdRaw) : void 0;
+  return withAuditHeaders(fetchFn, {
+    chatId: chatId !== void 0 && Number.isFinite(chatId) ? chatId : void 0,
+    sessionId: process.env.GRAVITY_RAIL_SESSION_ID,
+    toolCallId: process.env.GRAVITY_RAIL_TOOL_CALL_ID
+  });
+}
+
 // src/lib/context.ts
 function makeApiClient(accessToken, apiUrl) {
-  const apiClient = new ApiClient(accessToken, apiUrl);
+  const fetchFn = createSandboxFetchFromEnv(apiUrl);
+  const apiClient = new ApiClient(accessToken, apiUrl, fetchFn);
   registerOrgAuthHandler(apiClient, apiUrl, accessToken);
   return apiClient;
 }
@@ -2299,18 +2417,18 @@ function readStdinIfPiped() {
   return new Promise((resolve, reject) => {
     let data = "";
     let settled = false;
-    const finish = (value) => {
+    const finish2 = (value) => {
       if (settled) return;
       settled = true;
       resolve(value);
     };
     const flush = () => {
       if (!data.trim()) {
-        finish(void 0);
+        finish2(void 0);
         return;
       }
       try {
-        finish(JSON.parse(data));
+        finish2(JSON.parse(data));
       } catch {
         reject(new CLIError("Invalid JSON from stdin"));
       }
@@ -2330,7 +2448,7 @@ function readStdinIfPiped() {
         flush();
         return;
       }
-      finish(void 0);
+      finish2(void 0);
     });
   });
 }
@@ -2987,6 +3105,14 @@ var CommandRegistry = class {
     }
     return lines.join("\n") + "\n";
   }
+  /** All registered domains (for docs generation and introspection). */
+  getDomains() {
+    return this.domains;
+  }
+  /** All registered commands (for docs generation and introspection). */
+  getAllCommands() {
+    return [...this.commands.values()];
+  }
   getTopLevelHelp() {
     const lines = ["Usage: gr <command> [options]\n", "Commands:"];
     const seen = /* @__PURE__ */ new Set();
@@ -3697,6 +3823,31 @@ var membersDomain = {
   ]
 };
 
+// src/domains/member-roles.ts
+var ROLE_COLUMNS2 = [
+  { header: "ID", getValue: (item) => String(item.id ?? "") },
+  { header: "NAME", getValue: (item) => item.name ?? "" },
+  { header: "DESCRIPTION", getValue: (item) => String(item.description ?? "").slice(0, 40) }
+];
+var memberRolesDomain = {
+  name: "member-roles",
+  description: "Workspace member roles (alias for gr members roles). Use when resolving anonymousMemberRoleId / signupMemberRoleId.",
+  commands: crudCommands({
+    prefix: ["member-roles"],
+    entityName: "member role",
+    listMethod: "getMemberRoles",
+    getMethod: "getMemberRole",
+    createMethod: "createMemberRole",
+    updateMethod: "updateMemberRole",
+    deleteMethod: "deleteMemberRole",
+    columns: ROLE_COLUMNS2,
+    createExamples: [
+      "gr member-roles list -w $WID",
+      "gr member-roles get -w $WID --id 2"
+    ]
+  })
+};
+
 // src/domains/tasks.ts
 var COLUMNS4 = [
   COL.id(),
@@ -7899,9 +8050,9 @@ function toCamelMessage(raw) {
     id: raw.id,
     role: raw.role,
     content: raw.content ?? "",
-    createdAt: raw.created_at ?? null,
-    toolCalls: raw.tool_calls ?? null,
-    toolCallId: raw.tool_call_id ?? null
+    createdAt: raw.createdAt ?? raw.created_at ?? null,
+    toolCalls: raw.toolCalls ?? raw.tool_calls ?? null,
+    toolCallId: raw.toolCallId ?? raw.tool_call_id ?? null
   };
 }
 async function listConciergeChats(ctx) {
@@ -9132,27 +9283,780 @@ var orgPhoneNumbersDomain = {
   commands: commands2
 };
 
+// src/lib/phone-numbers/defaults.ts
+var PHONE_NUMBER_CREATE_DEFAULTS = {
+  allowSignup: false,
+  allowAnonymous: false,
+  restartDelay: 900,
+  enableSms: true,
+  enableVoice: true,
+  assistantEnabled: true,
+  voiceUnavailableMessage: "This phone number is not available for voice calls right now. Please try again later or send a text message.",
+  smsUnavailableMessage: "This phone number is not available for text messages right now. Please try again later.",
+  anonymousRejectionMessage: "Hello. Unfortunately we could not find your phone number in our system. Goodbye.",
+  voicemailGreeting: "Please leave a message after the tone."
+};
+function mergePhoneNumberCreateDefaults(data) {
+  return { ...PHONE_NUMBER_CREATE_DEFAULTS, ...data };
+}
+
+// src/lib/phone-numbers/field-help.ts
+var PHONE_NUMBER_FIELD_REFERENCE = `
+Field reference for --data JSON (create/update):
+
+Identity & branding
+  name (string)                         Display label
+  brandName, brandDescription, brandWebsite (string, optional)
+
+Inbound routing (phone_numbers.defaultWorkflowId = INBOUND workflow)
+  defaultWorkflowId (number|null)       Workflow for inbound voice/SMS chats (required for voice)
+  allowSignup (bool, default false)     Unknown callers can start signup flow
+  signupMemberRoleId (number)           Required when allowSignup=true
+  allowAnonymous (bool, default false)  Unknown callers get anonymous member per call
+  anonymousMemberRoleId (number)        Required when allowAnonymous=true
+  restartDelay (number|null, default 900) Seconds before a new inbound conversation starts
+  restartPrompt (string|null)
+
+Channels
+  enableVoice (bool, default true)
+  enableSms (bool, default true)
+  enableWhatsApp (bool, default false)
+  assistantEnabled (bool, default true)
+
+Caller-facing messages
+  voiceUnavailableMessage (string)      Played when voice cannot be handled
+  voiceGreetingMessage (string)         Played before AI connects
+  anonymousRejectionMessage (string)  Unknown caller denied (TTS)
+  smsUnavailableMessage (string)
+  voicemailGreeting (string)
+
+Work modes (voiceWorkMode / smsWorkMode)
+  always_forward | forward_off_hours | always_message | message_off_hours | voicemail | voicemail_off_hours
+  voiceForwardNumber, smsForwardNumber, voiceOffHoursMessage, smsOffHoursMessage
+
+Provider link
+  providerPhoneUuid (string)            Org provider phone UUID \u2014 use gr phone-numbers link after org assign
+
+Constraints
+  allowAnonymous=true  \u2192 anonymousMemberRoleId required
+  allowSignup=true     \u2192 signupMemberRoleId required
+
+Outbound (different field on workflows, not this resource):
+  workflows.defaultPhoneNumberId = OUTBOUND origin for that workflow
+  Event rules may reference phoneNumberUUID (workspace phone uuid string)
+
+List roles: gr member-roles list -w $WID
+Provisioning: gr phone-numbers setup --help
+`.trim();
+
+// src/lib/phone-numbers/validation-hints.ts
+var HINT_RULES = [
+  {
+    pattern: /anonymousMemberRoleId.*required/i,
+    hint: "Fix: set anonymousMemberRoleId (gr member-roles list -w $WID) or set allowAnonymous=false."
+  },
+  {
+    pattern: /signupMemberRoleId/i,
+    hint: "Fix: set signupMemberRoleId from gr member-roles list -w $WID, or disable allowSignup."
+  },
+  {
+    pattern: /memberRoleAccess/i,
+    hint: "Fix: memberRoleAccess entries need { memberRoleId, accessMode }. List roles: gr member-roles list -w $WID"
+  },
+  {
+    pattern: /defaultWorkflowId/i,
+    hint: "Fix: defaultWorkflowId is the INBOUND workflow id (gr workflows list -w $WID). Outbound uses workflows.defaultPhoneNumberId."
+  },
+  {
+    pattern: /providerPhoneUuid|provider_phone/i,
+    hint: "Fix: link org number \u2014 gr org phone-numbers assign \u2026 then gr phone-numbers link --provider-phone-uuid <uuid> --allow-write"
+  }
+];
+function enrichPhoneNumberApiError(err) {
+  const message = err instanceof Error ? err.message : String(err);
+  const extra = [];
+  for (const rule of HINT_RULES) {
+    if (rule.pattern.test(message)) {
+      extra.push(rule.hint);
+    }
+  }
+  if ("errors" in err && Array.isArray(err.errors)) {
+    for (const e of err.errors) {
+      for (const rule of HINT_RULES) {
+        if (rule.pattern.test(e)) {
+          extra.push(rule.hint);
+        }
+      }
+    }
+  }
+  const unique = [...new Set(extra)];
+  const body = unique.length > 0 ? `${message}
+
+${unique.map((h) => `${h}`).join("\n")}` : message;
+  throw new CLIError(body);
+}
+
+// src/lib/phone-numbers/warnings.ts
+function collectPhoneNumberWarnings(phone) {
+  const warnings = [];
+  const enableVoice = phone.enableVoice === true;
+  const defaultWorkflowId = phone.defaultWorkflowId;
+  const isMapped = phone.isMapped === true;
+  const allowAnonymous = phone.allowAnonymous === true;
+  const anonymousMemberRoleId = phone.anonymousMemberRoleId;
+  if (!isMapped) {
+    warnings.push({
+      severity: "warn",
+      code: "not_mapped",
+      message: "Phone line is not linked to an org provider number (isMapped=false). Inbound PSTN will not reach this workspace until linked.",
+      fixCommand: "gr org phone-numbers assign \u2026 then gr phone-numbers link -w $WID --id <id> --provider-phone-uuid <uuid> --allow-write"
+    });
+  }
+  if (enableVoice && (defaultWorkflowId === null || defaultWorkflowId === void 0)) {
+    warnings.push({
+      severity: "error",
+      code: "voice_no_inbound_workflow",
+      message: "Voice is enabled but defaultWorkflowId (inbound route) is unset. Known callers may hear a rejection message; misconfiguration can drop calls without a call log.",
+      fixCommand: `gr phone-numbers update --id <id> --data '{"defaultWorkflowId":<workflowId>}' --allow-write`
+    });
+  }
+  if (enableVoice && !phone.voiceUnavailableMessage) {
+    warnings.push({
+      severity: "warn",
+      code: "missing_voice_unavailable_message",
+      message: "voiceUnavailableMessage is unset. If voice cannot be handled, callers may get a generic or empty response."
+    });
+  }
+  if (allowAnonymous && (anonymousMemberRoleId === null || anonymousMemberRoleId === void 0)) {
+    warnings.push({
+      severity: "error",
+      code: "anonymous_missing_role",
+      message: "allowAnonymous=true requires anonymousMemberRoleId.",
+      fixCommand: "gr member-roles list -w $WID  # then set anonymousMemberRoleId in update JSON"
+    });
+  }
+  if (!allowAnonymous && !phone.allowSignup && enableVoice && !phone.anonymousRejectionMessage) {
+    warnings.push({
+      severity: "warn",
+      code: "missing_anonymous_rejection_message",
+      message: "Unknown callers are rejected (allowAnonymous=false, allowSignup=false) but anonymousRejectionMessage is unset (platform default TTS will be used)."
+    });
+  }
+  if (phone.allowSignup === true && !phone.signupMemberRoleId) {
+    warnings.push({
+      severity: "error",
+      code: "signup_missing_role",
+      message: "allowSignup=true requires signupMemberRoleId.",
+      fixCommand: "gr member-roles list -w $WID"
+    });
+  }
+  return warnings;
+}
+
+// src/lib/phone-numbers/routing-simulate.ts
+var VALID_CALLER_ROLES = /* @__PURE__ */ new Set([
+  "anonymous",
+  "member",
+  "operator",
+  "signup",
+  "unknown"
+]);
+function parseCallerRole(value) {
+  if (typeof value !== "string" || value === "") {
+    return void 0;
+  }
+  return VALID_CALLER_ROLES.has(value) ? value : void 0;
+}
+function inferCallerRole(phone, opts) {
+  if (opts.asRole) {
+    return opts.asRole;
+  }
+  if (opts.hasMemberMatch) {
+    return "member";
+  }
+  if (phone.allowAnonymous === true) {
+    return "anonymous";
+  }
+  if (phone.allowSignup === true && phone.signupMemberRoleId) {
+    return "signup";
+  }
+  return "anonymous";
+}
+function simulateInboundRouting(phone, opts = {}) {
+  const steps = [];
+  const recommendations = [];
+  const isBusinessHours = opts.isBusinessHours ?? true;
+  if (!phone.isMapped) {
+    steps.push({
+      step: "provider_mapping",
+      outcome: "reject",
+      detail: "Number not linked to org provider (isMapped=false)"
+    });
+    return finish("reject_unmapped", false, false, steps, recommendations, opts.asRole);
+  }
+  if (!phone.enableVoice) {
+    steps.push({
+      step: "channel_voice",
+      outcome: "reject",
+      detail: "enableVoice=false \u2014 plays voiceUnavailableMessage or default"
+    });
+    return finish(
+      "voice_disabled_message",
+      false,
+      false,
+      steps,
+      recommendations,
+      opts.asRole
+    );
+  }
+  steps.push({ step: "channel_voice", outcome: "ok" });
+  const callerRole = inferCallerRole(phone, opts);
+  steps.push({ step: "caller_resolution", outcome: callerRole });
+  if (callerRole === "member") {
+    steps.push({ step: "member_access", outcome: "proceed" });
+  } else if (callerRole === "anonymous") {
+    if (!phone.anonymousMemberRoleId) {
+      steps.push({
+        step: "anonymous_role",
+        outcome: "reject",
+        detail: "allowAnonymous without anonymousMemberRoleId"
+      });
+      recommendations.push(
+        "Set anonymousMemberRoleId or disable allowAnonymous (gr member-roles list -w $WID)"
+      );
+      return finish("misconfigured_anonymous", false, false, steps, recommendations, callerRole);
+    }
+    steps.push({ step: "anonymous_member", outcome: "create_ephemeral_member" });
+  } else if (callerRole === "signup") {
+    steps.push({ step: "signup_flow", outcome: "redirect_voice_consent" });
+    return finish("signup_consent_redirect", false, false, steps, recommendations, callerRole);
+  } else if (callerRole === "unknown" || callerRole === "operator") {
+    steps.push({
+      step: "caller_access",
+      outcome: "reject",
+      detail: "Unknown caller; anonymous and signup disabled"
+    });
+    return finish("anonymous_rejection_tts", false, false, steps, recommendations, callerRole);
+  }
+  const voiceWorkMode = phone.voiceWorkMode;
+  if (voiceWorkMode === "always_forward" && phone.voiceForwardNumber) {
+    steps.push({ step: "voice_work_mode", outcome: "forward", detail: voiceWorkMode });
+    return finish("forward_pstn", false, true, steps, recommendations, callerRole);
+  }
+  if (voiceWorkMode === "forward_off_hours" && !isBusinessHours && phone.voiceForwardNumber) {
+    steps.push({ step: "voice_work_mode", outcome: "forward_off_hours" });
+    return finish("forward_pstn", false, true, steps, recommendations, callerRole);
+  }
+  if (voiceWorkMode === "voicemail" || voiceWorkMode === "voicemail_off_hours" && !isBusinessHours) {
+    steps.push({ step: "voice_work_mode", outcome: "voicemail" });
+    return finish("voicemail_record", true, true, steps, recommendations, callerRole);
+  }
+  if ((voiceWorkMode === "always_message" || voiceWorkMode === "message_off_hours") && phone.voiceOffHoursMessage) {
+    steps.push({ step: "voice_work_mode", outcome: "play_message" });
+    return finish("play_message_hangup", false, false, steps, recommendations, callerRole);
+  }
+  steps.push({ step: "voice_work_mode", outcome: "ai_path" });
+  const workflowId = phone.defaultWorkflowId;
+  if (workflowId === null || workflowId === void 0) {
+    steps.push({
+      step: "inbound_workflow",
+      outcome: "reject",
+      detail: "defaultWorkflowId unset \u2014 plays unavailable message; call log should be created"
+    });
+    recommendations.push(
+      `Set defaultWorkflowId: gr phone-numbers update --id <id> --data '{"defaultWorkflowId":<wf>}' --allow-write`
+    );
+    return finish("no_inbound_workflow", false, true, steps, recommendations, callerRole);
+  }
+  steps.push({ step: "inbound_workflow", outcome: "ok", detail: `workflowId=${workflowId}` });
+  steps.push({ step: "chat_create", outcome: "create_phone_voice_chat" });
+  steps.push({ step: "assistant", outcome: "connect_media_stream" });
+  return finish("ai_voice_chat", true, true, steps, recommendations, callerRole);
+}
+function finish(code, createsChat, createsPhoneCall, steps, recommendations, callerRole) {
+  const labels = {
+    reject_unmapped: "Reject \u2014 not mapped to provider",
+    voice_disabled_message: "Play voice-unavailable message",
+    misconfigured_anonymous: "Reject \u2014 anonymous misconfigured",
+    signup_consent_redirect: "Redirect to voice signup consent",
+    anonymous_rejection_tts: "Play anonymous rejection TTS, hang up",
+    forward_pstn: "Forward to voiceForwardNumber",
+    voicemail_record: "Record voicemail",
+    play_message_hangup: "Play off-hours message, hang up",
+    no_inbound_workflow: "Play unavailable message (no inbound workflow)",
+    ai_voice_chat: "Create chat + connect AI voice"
+  };
+  return {
+    callerRole: callerRole ?? "unknown",
+    steps,
+    finalBehavior: labels[code] ?? code,
+    createsChat,
+    createsPhoneCall,
+    recommendations
+  };
+}
+function formatRoutingSimulation(sim, phone) {
+  const lines = [];
+  lines.push(`Phone ${phone.id} (${String(phone.number ?? "").slice(0, 6)}\u2026)`);
+  lines.push(`Caller role (simulated): ${sim.callerRole}`);
+  lines.push("");
+  lines.push("Routing trace:");
+  for (const s of sim.steps) {
+    const detail = s.detail ? ` \u2014 ${s.detail}` : "";
+    lines.push(`  \u2022 ${s.step}: ${s.outcome}${detail}`);
+  }
+  lines.push("");
+  lines.push(`Final: ${sim.finalBehavior}`);
+  lines.push(`Creates chat: ${sim.createsChat ? "yes" : "no"}`);
+  lines.push(`Creates phone call record: ${sim.createsPhoneCall ? "yes" : "no"}`);
+  if (sim.recommendations.length > 0) {
+    lines.push("");
+    lines.push("Recommendations:");
+    for (const r of sim.recommendations) {
+      lines.push(`  \u2192 ${r}`);
+    }
+  }
+  return lines.join("\n");
+}
+
+// src/lib/phone-numbers/behavior-matrix.ts
+var ROLE_ROWS = ["anonymous", "member", "signup", "operator"];
+function roleExperience(phone, role) {
+  const sim = simulateInboundRouting(phone, {
+    asRole: role,
+    hasMemberMatch: role === "member"
+  });
+  return sim.finalBehavior;
+}
+function formatPhoneNumberBehaviorMatrix(phone, outboundUsers, warnings = collectPhoneNumberWarnings(phone)) {
+  const lines = [];
+  const maskedNumber = typeof phone.number === "string" && phone.number.length > 4 ? `${phone.number.slice(0, 6)}\u2026` : "(no number)";
+  lines.push(`Phone number ${phone.id} \u2014 ${phone.name ?? "(unnamed)"} \u2014 ${maskedNumber}`);
+  lines.push(`UUID: ${phone.uuid}  |  Mapped: ${phone.isMapped ? "yes" : "no"}`);
+  lines.push("");
+  lines.push("## Channels");
+  lines.push(`  Voice: ${phone.enableVoice ? "on" : "off"}  SMS: ${phone.enableSms ? "on" : "off"}  WhatsApp: ${phone.enableWhatsApp ? "on" : "off"}`);
+  lines.push(`  Assistant: ${phone.assistantEnabled ? "on" : "off"}`);
+  lines.push("");
+  lines.push("## Inbound route");
+  lines.push(
+    `  defaultWorkflowId (inbound): ${phone.defaultWorkflowId ?? "null"}  restartDelay: ${phone.restartDelay ?? "null"}s`
+  );
+  lines.push(
+    `  allowAnonymous: ${phone.allowAnonymous} (role ${phone.anonymousMemberRoleId ?? "\u2014"})  allowSignup: ${phone.allowSignup} (role ${phone.signupMemberRoleId ?? "\u2014"})`
+  );
+  if (phone.voiceWorkMode) {
+    lines.push(`  voiceWorkMode: ${phone.voiceWorkMode}`);
+  }
+  lines.push("");
+  lines.push("## Outbound users");
+  if (outboundUsers.length === 0) {
+    lines.push("  (none \u2014 no workflow defaultPhoneNumberId or event rule phoneNumberUUID)");
+  } else {
+    for (const u of outboundUsers) {
+      lines.push(`  \u2022 [${u.kind}] ${u.name} (id ${u.id})${u.detail ? ` \u2014 ${u.detail}` : ""}`);
+    }
+  }
+  lines.push("");
+  lines.push("## Role experience (simulated inbound)");
+  for (const role of ROLE_ROWS) {
+    lines.push(`  ${role.padEnd(10)} \u2192 ${roleExperience(phone, role)}`);
+  }
+  lines.push("");
+  if (warnings.length > 0) {
+    lines.push("## Warnings");
+    for (const w of warnings) {
+      const tag = w.severity === "error" ? "ERROR" : "WARN";
+      lines.push(`  [${tag}] ${w.message}`);
+      if (w.fixCommand) {
+        lines.push(`         Fix: ${w.fixCommand}`);
+      }
+    }
+    lines.push("");
+  }
+  lines.push("Tip: gr phone-numbers diagnose --id <id> --as +1\u2026  |  --raw for full JSON");
+  return lines.join("\n");
+}
+
+// src/lib/phone-numbers/outbound-users.ts
+async function findOutboundPhoneUsers(client, workspace, phone) {
+  const phoneId = phone.id;
+  const phoneUuid = String(phone.uuid ?? "");
+  const users = [];
+  const workflows = await client.getWorkflows(workspace, false);
+  for (const wf of workflows) {
+    if (wf.defaultPhoneNumberId === phoneId) {
+      users.push({
+        kind: "workflow_default",
+        id: wf.id,
+        name: String(wf.name ?? `workflow ${wf.id}`),
+        detail: "workflows.defaultPhoneNumberId (outbound origin)"
+      });
+    }
+  }
+  let page = 1;
+  const pageSize = 100;
+  for (; ; ) {
+    const rulesPage = await client.getEventRules(workspace, { page, pageSize });
+    const list = rulesPage.items;
+    for (const rule of list) {
+      const params = rule.actionParams ?? rule.action_params;
+      if (!params) continue;
+      const pnUuid = params.phoneNumberUUID ?? params.phone_number_uuid;
+      const pnId = params.phoneNumberId ?? params.phone_number_id;
+      if (pnUuid === phoneUuid || pnId === phoneId) {
+        users.push({
+          kind: "event_rule",
+          id: rule.id,
+          name: String(rule.name ?? `rule ${rule.id}`),
+          detail: `action=${String(rule.actionType ?? rule.action_type ?? "")}`
+        });
+      }
+    }
+    if (!rulesPage.totalPages || page >= rulesPage.totalPages || list.length < pageSize) {
+      break;
+    }
+    page += 1;
+    if (page > 50) {
+      process.stderr.write(
+        "Warning: event-rules lookup truncated at 5000 results (50 pages)\n"
+      );
+      break;
+    }
+  }
+  return users;
+}
+
 // src/domains/phone-numbers.ts
+function asPhoneRecord(value) {
+  return value;
+}
+function requireCallerRole(args, flag) {
+  const role = parseCallerRole(args[flag]);
+  if (!role) {
+    throw new CLIError(
+      `Invalid --${flag}. Use one of: anonymous, member, operator, signup, unknown`
+    );
+  }
+  return role;
+}
 var COLUMNS25 = [
   COL.id(),
-  { header: "NUMBER", getValue: (item) => item.phone_number ?? "" },
-  { header: "LABEL", getValue: (item) => item.label ?? "" },
+  { header: "NUMBER", getValue: (item) => item.phone_number ?? item.number ?? "" },
+  { header: "LABEL", getValue: (item) => item.label ?? item.name ?? "" },
   COL.status()
 ];
+var PROVISIONING_HELP = `
+Provisioning chain (org \u2192 workspace):
+  1. gr org phone-numbers search --org <org-uuid> [--area-code 775]
+  2. gr org phone-numbers purchase --org <org-uuid> --data '{"phoneNumber":"+1\u2026"}' --allow-write
+  3. gr org phone-numbers assign --org <org-uuid> --data '{"providerPhoneUuid":"\u2026","workspaceUuid":"\u2026"}' --allow-write
+  4. gr phone-numbers create -w $WID --data '{"name":"\u2026","providerPhoneUuid":"\u2026"}' --allow-write
+     OR gr phone-numbers link -w $WID --id <id> --provider-phone-uuid <uuid> --allow-write
+  5. gr phone-numbers update --id <id> --data '{"defaultWorkflowId":<wf>}' --allow-write
+
+IDs: workspace phone id (numeric) vs uuid (string, used in event rules phoneNumberUUID).
+Inbound: phone_numbers.defaultWorkflowId  |  Outbound: workflows.defaultPhoneNumberId
+`.trim();
 var phoneNumbersDomain = {
   name: "phone-numbers",
-  description: "Manage phone numbers",
+  description: `Workspace phone numbers (inbound/outbound voice & SMS). ${PROVISIONING_HELP}`,
   commands: [
     ...crudCommands({
       prefix: ["phone-numbers"],
       entityName: "phone number",
       listMethod: "getPhoneNumbers",
-      getMethod: "getPhoneNumber",
-      createMethod: "createPhoneNumber",
-      updateMethod: "updatePhoneNumber",
       archiveMethod: "archivePhoneNumber",
       columns: COLUMNS25
     }),
+    {
+      path: ["phone-numbers", "get"],
+      description: "Get a phone number (behavior matrix; use --raw for JSON)",
+      requiresWorkspace: true,
+      args: [
+        { name: "id", description: "Phone number ID", required: true },
+        { name: "raw", description: "Output full JSON instead of behavior matrix", isFlag: true }
+      ],
+      handler: async ({ ctx, workspace, args }) => {
+        const client = requireAuth(ctx).apiClient;
+        const id = requireNumber(args, "id");
+        const phone = asPhoneRecord(await client.getPhoneNumber(workspace, id));
+        if (args.raw) {
+          process.stdout.write(`${JSON.stringify(phone, null, 2)}
+`);
+          return;
+        }
+        const outboundUsers = await findOutboundPhoneUsers(client, workspace, phone);
+        process.stdout.write(
+          `${formatPhoneNumberBehaviorMatrix(phone, outboundUsers)}
+`
+        );
+      }
+    },
+    {
+      path: ["phone-numbers", "create"],
+      description: `Create a phone number
+
+${PHONE_NUMBER_FIELD_REFERENCE}`,
+      mutates: true,
+      requiresWorkspace: true,
+      examples: [
+        "gr phone-numbers create -w $WID --allow-write -f /tmp/phone.json",
+        `gr phone-numbers create -w $WID --allow-write --data '{"name":"Line 1","defaultWorkflowId":1}'`
+      ],
+      handler: async ({ ctx, workspace, data }) => {
+        if (!data || typeof data !== "object") {
+          throw new CLIError("JSON data required (--data, --file, or stdin)");
+        }
+        const payload = mergePhoneNumberCreateDefaults(data);
+        try {
+          const result = await requireAuth(ctx).apiClient.createPhoneNumber(
+            workspace,
+            payload
+          );
+          const record = asPhoneRecord(result);
+          const warnings = collectPhoneNumberWarnings(record);
+          outputData([record], ctx, COLUMNS25);
+          if (warnings.length > 0) {
+            process.stderr.write("\nWarnings after create:\n");
+            for (const w of warnings) {
+              process.stderr.write(`  [${w.severity}] ${w.message}
+`);
+            }
+          }
+        } catch (err) {
+          return enrichPhoneNumberApiError(err);
+        }
+      }
+    },
+    {
+      path: ["phone-numbers", "update"],
+      description: `Update a phone number
+
+${PHONE_NUMBER_FIELD_REFERENCE}`,
+      mutates: true,
+      requiresWorkspace: true,
+      args: [{ name: "id", description: "Phone number ID", required: true }],
+      handler: async ({ ctx, workspace, args, data }) => {
+        if (!data || typeof data !== "object") {
+          throw new CLIError("JSON data required (--data, --file, or stdin)");
+        }
+        const id = requireNumber(args, "id");
+        try {
+          const result = await requireAuth(ctx).apiClient.updatePhoneNumber(
+            workspace,
+            id,
+            data
+          );
+          outputData([result], ctx, COLUMNS25);
+        } catch (err) {
+          return enrichPhoneNumberApiError(err);
+        }
+      }
+    },
+    {
+      path: ["phone-numbers", "setup"],
+      description: "Provision/link a workspace phone line with inbound defaults (happy-path wizard)",
+      mutates: true,
+      requiresWorkspace: true,
+      args: [
+        { name: "name", description: "Display name for the line" },
+        {
+          name: "inbound-workflow",
+          aliases: ["inbound-workflow-id"],
+          description: "Inbound defaultWorkflowId"
+        },
+        { name: "area-code", description: "Area code when requesting a new number" },
+        { name: "provider-phone-uuid", description: "Existing org provider phone UUID to link" },
+        { name: "enable-voice", description: "Enable voice (default true)", isFlag: true },
+        { name: "enable-sms", description: "Enable SMS (default true)", isFlag: true },
+        { name: "allow-anonymous", description: "Allow anonymous inbound callers", isFlag: true },
+        {
+          name: "anonymous-member-role-id",
+          description: "Role id when --allow-anonymous"
+        }
+      ],
+      examples: [
+        'gr phone-numbers setup -w $WID --allow-write --name "Main" --inbound-workflow 1',
+        "gr phone-numbers setup -w $WID --allow-write --provider-phone-uuid <uuid> --inbound-workflow 2"
+      ],
+      handler: async ({ ctx, workspace, args, data }) => {
+        const client = requireAuth(ctx).apiClient;
+        const payload = mergePhoneNumberCreateDefaults({
+          name: typeof args.name === "string" ? args.name : "Voice line",
+          enableVoice: args["enable-voice"] === false ? false : true,
+          enableSms: args["enable-sms"] === false ? false : true,
+          ...typeof args["inbound-workflow"] === "string" ? { defaultWorkflowId: Number(args["inbound-workflow"]) } : {},
+          ...args["allow-anonymous"] ? { allowAnonymous: true } : {},
+          ...typeof args["anonymous-member-role-id"] === "string" ? { anonymousMemberRoleId: Number(args["anonymous-member-role-id"]) } : {},
+          ...typeof args["provider-phone-uuid"] === "string" ? { providerPhoneUuid: args["provider-phone-uuid"] } : {},
+          ...data && typeof data === "object" ? data : {}
+        });
+        let phone;
+        try {
+          if (payload.providerPhoneUuid) {
+            phone = asPhoneRecord(
+              await client.createPhoneNumber(workspace, payload)
+            );
+          } else if (typeof args["area-code"] === "string") {
+            phone = asPhoneRecord(
+              await client.requestPhoneNumber(workspace, {
+                areaCode: args["area-code"],
+                name: payload.name
+              })
+            );
+            if (payload.defaultWorkflowId) {
+              phone = asPhoneRecord(
+                await client.updatePhoneNumber(workspace, phone.id, {
+                  defaultWorkflowId: payload.defaultWorkflowId,
+                  ...payload
+                })
+              );
+            }
+          } else {
+            throw new CLIError(
+              "Provide --provider-phone-uuid (link existing org number) or --area-code (request new number)"
+            );
+          }
+        } catch (err) {
+          return enrichPhoneNumberApiError(err);
+        }
+        process.stdout.write(`
+Setup complete: id=${phone.id} uuid=${phone.uuid}
+
+`);
+        const outboundUsers = await findOutboundPhoneUsers(client, workspace, phone);
+        process.stdout.write(
+          `${formatPhoneNumberBehaviorMatrix(phone, outboundUsers)}
+`
+        );
+      }
+    },
+    {
+      path: ["phone-numbers", "diagnose"],
+      description: "Simulate inbound routing for a caller number (no PSTN)",
+      requiresWorkspace: true,
+      args: [
+        { name: "id", description: "Phone number ID", required: true },
+        { name: "as", description: "Caller E.164 (e.g. +15551234567)" },
+        {
+          name: "as-role",
+          description: "Caller role: anonymous|member|operator|signup (skips number lookup)"
+        }
+      ],
+      examples: ["gr phone-numbers diagnose -w $WID --id 2 --as +15551234567"],
+      handler: async ({ ctx, workspace, args }) => {
+        const client = requireAuth(ctx).apiClient;
+        const id = requireNumber(args, "id");
+        const phone = asPhoneRecord(await client.getPhoneNumber(workspace, id));
+        const asRole = parseCallerRole(args["as-role"]);
+        let hasMemberMatch = asRole === "member";
+        if (!asRole && typeof args.as === "string") {
+          hasMemberMatch = false;
+        }
+        const sim = simulateInboundRouting(phone, { asRole, hasMemberMatch });
+        process.stdout.write(`${formatRoutingSimulation(sim, phone)}
+`);
+      }
+    },
+    {
+      path: ["phone-numbers", "experience"],
+      description: "Preview caller experience by role (no PSTN)",
+      requiresWorkspace: true,
+      args: [
+        { name: "id", description: "Phone number ID", required: true },
+        {
+          name: "as-role",
+          description: "anonymous|member|operator|signup",
+          required: true
+        }
+      ],
+      handler: async ({ ctx, workspace, args }) => {
+        const client = requireAuth(ctx).apiClient;
+        const id = requireNumber(args, "id");
+        const role = requireCallerRole(args, "as-role");
+        const phone = asPhoneRecord(await client.getPhoneNumber(workspace, id));
+        const sim = simulateInboundRouting(phone, {
+          asRole: role,
+          hasMemberMatch: role === "member"
+        });
+        process.stdout.write(
+          `If a caller in role "${role}" dials this line right now:
+  \u2192 ${sim.finalBehavior}
+
+${formatRoutingSimulation(sim, phone)}
+`
+        );
+      }
+    },
+    {
+      path: ["phone-numbers", "test-inbound"],
+      description: "Server-side inbound routing simulation (JSON; no Twilio call)",
+      requiresWorkspace: true,
+      args: [
+        { name: "id", description: "Phone number ID", required: true },
+        { name: "as", description: "Caller E.164" },
+        { name: "as-role", description: "anonymous|member|signup" }
+      ],
+      handler: async ({ ctx, workspace, args }) => {
+        const client = requireAuth(ctx).apiClient;
+        const id = requireNumber(args, "id");
+        const phone = asPhoneRecord(await client.getPhoneNumber(workspace, id));
+        const asRole = parseCallerRole(args["as-role"]);
+        const sim = simulateInboundRouting(phone, {
+          asRole,
+          hasMemberMatch: asRole === "member"
+        });
+        process.stdout.write(`${JSON.stringify({ phoneNumberId: id, simulation: sim }, null, 2)}
+`);
+      }
+    },
+    {
+      path: ["phone-numbers", "users"],
+      description: "List workflows and event rules using this number for outbound",
+      requiresWorkspace: true,
+      args: [{ name: "id", description: "Phone number ID", required: true }],
+      handler: async ({ ctx, workspace, args }) => {
+        const client = requireAuth(ctx).apiClient;
+        const id = requireNumber(args, "id");
+        const phone = asPhoneRecord(await client.getPhoneNumber(workspace, id));
+        const users = await findOutboundPhoneUsers(client, workspace, phone);
+        outputData(users, ctx);
+      }
+    },
+    {
+      path: ["phone-numbers", "inbound-log"],
+      description: "Recent inbound call activity for this line (use calls list; routing detail in status)",
+      requiresWorkspace: true,
+      args: [
+        {
+          name: "phone-number-id",
+          aliases: ["id"],
+          description: "Phone number ID",
+          required: true
+        },
+        { name: "page", description: "Page number" },
+        { name: "page-size", description: "Page size" }
+      ],
+      handler: async ({ ctx, workspace, args }) => {
+        const result = await requireAuth(ctx).apiClient.getPhoneNumberCalls(
+          workspace,
+          requireNumberFrom(args, "phone-number-id", "id"),
+          args.page ? Number(args.page) : 1,
+          args["page-size"] ? Number(args["page-size"]) : 20,
+          { inbound: true }
+        );
+        const inbound = result.items ?? [];
+        process.stdout.write(
+          `Inbound calls (most recent page): ${inbound.length} shown
+`
+        );
+        process.stdout.write(
+          "Tip: gr phone-numbers diagnose --id <id> --as +1\u2026 simulates routing without a live call.\n"
+        );
+        outputData(inbound, ctx);
+      }
+    },
     {
       path: ["phone-numbers", "available"],
       description: "List available phone numbers for purchase",
@@ -9189,7 +10093,7 @@ var phoneNumbersDomain = {
     },
     {
       path: ["phone-numbers", "request"],
-      description: "Request a phone number",
+      description: "Request a phone number from Twilio",
       mutates: true,
       requiresWorkspace: true,
       handler: async ({ ctx, workspace, data }) => {
@@ -11327,6 +12231,7 @@ function registerPublicDomains(registry) {
   registry.register(tasksDomain);
   registry.register(chatsDomain);
   registry.register(membersDomain);
+  registry.register(memberRolesDomain);
   registry.register(workspacesDomain);
   registry.register(workflowsDomain);
   registry.register(workflowVersionsDomain);