@velaro/cli 1.4.105 → 1.4.107

package/lib/commands/ops-groups.js

@@ -0,0 +1,188 @@
+// MCP parity command groups: ai-followups, business-action, call, conversation, conversion, email, ivr.
+// Each subcommand calls the same REST route as the MCP tool of the same name (mcp/server.js).
+import { get, post, put, request, messagingGet, messagingPost, messagingPut } from '../api.js';
+import { show, qs, needYes, group } from '../parity-util.js';
+
+const exclusiveEnd = (d) => { const x = new Date(`${d}T00:00:00Z`); x.setUTCDate(x.getUTCDate() + 1); return x.toISOString().slice(0, 10); };
+const rangeQs = (a, extra = {}) => qs({ start: a.start, end: a.end ? exclusiveEnd(a.end) : undefined, ...extra });
+const rangeOpts = (y) => y.option('start', { type: 'string', describe: 'yyyy-MM-dd' }).option('end', { type: 'string', describe: 'yyyy-MM-dd (inclusive)' });
+
+export const aiFollowupsCommand = { command: 'ai-followups', ...group('AI follow-ups site setting', [
+  ['get', 'Show whether AI follow-ups are enabled for this site', null,
+    async () => { const r = await messagingGet('/SiteSettings/AiFollowUps'); show({ enabled: r?.enabled ?? null }); }],
+  ['set', 'Enable/disable AI follow-ups (omit --enabled to clear back to the default)',
+    (y) => y.option('enabled', { type: 'boolean' }),
+    async (a) => {
+      await messagingPut('/SiteSettings/AiFollowUps', { enabled: typeof a.enabled === 'boolean' ? a.enabled : null });
+      const r = await messagingGet('/SiteSettings/AiFollowUps');
+      show({ enabled: r?.enabled ?? null });
+    }],
+]) };
+
+export const businessActionCommand = { command: 'business-action', ...group('Business actions (list, route free text, execute)', [
+  ['list', 'List available business actions', null, async () => show(await messagingGet('/BusinessActions'))],
+  ['route', 'Route free text to the best matching business actions',
+    (y) => y.option('text', { type: 'string', demandOption: true }).option('max', { type: 'number' }),
+    async (a) => show(await messagingPost('/BusinessActions/Route', { text: a.text, max: a.max }))],
+  ['execute <name>', 'Execute a business action (needs --yes)',
+    (y) => y.positional('name', { type: 'string' })
+      .option('request', { type: 'string', demandOption: true, describe: 'Request body as a JSON object' })
+      .option('idempotency-key', { type: 'string' })
+      .option('conversation-id', { type: 'string' })
+      .option('yes', { type: 'boolean' }),
+    async (a) => {
+      needYes(a, `execute business action ${a.name}`);
+      const body = JSON.parse(a.request);
+      if (!body || typeof body !== 'object') throw new Error('--request must be a JSON object.');
+      show(await messagingPost(`/BusinessActions/${encodeURIComponent(a.name)}/Execute${qs({ idempotencyKey: a['idempotency-key'], conversationId: a['conversation-id'] })}`, body));
+    }],
+]) };
+
+export const callCommand = { command: 'call', ...group('Call center analytics and call activity', [
+  ['center-report', 'Call center report: volume, speed, abandon, bot', rangeOpts,
+    async (a) => show(await get(`/CallCenterAnalytics/Report${rangeQs(a)}`))],
+  ['team-breakdown', 'Per-team call center breakdown (Advanced Analytics add-on)',
+    (y) => rangeOpts(y).option('sla-threshold-seconds', { type: 'number' }),
+    async (a) => show(await get(`/CallCenterAnalytics/TeamBreakdown${rangeQs(a, { slaThresholdSeconds: a['sla-threshold-seconds'] })}`))],
+  ['channel-breakdown', 'Per-channel call center breakdown (Advanced Analytics add-on)',
+    (y) => rangeOpts(y).option('sla-threshold-seconds', { type: 'number' }),
+    async (a) => show(await get(`/CallCenterAnalytics/ChannelBreakdown${rangeQs(a, { slaThresholdSeconds: a['sla-threshold-seconds'] })}`))],
+  ['activity', 'Call activity history (voice call records plus auto-dialer campaign calls)',
+    (y) => y.option('agent-id', { type: 'number' }).option('direction', { type: 'string' }).option('origin', { type: 'string' })
+      .option('provider-slug', { type: 'string' }).option('disposition', { type: 'string' })
+      .option('days', { type: 'number', default: 30 }).option('page', { type: 'number', default: 1 }).option('page-size', { type: 'number', default: 50 }),
+    async (a) => {
+      const q = qs({ agentId: a['agent-id'], direction: a.direction, origin: a.origin, providerSlug: a['provider-slug'], dateRangeDays: a.days, disposition: a.disposition, page: a.page, pageSize: a['page-size'] });
+      let items = [];
+      let failures = 0;
+      try { const r = await messagingGet(`/Voice/CallRecords/history${q}`); items = items.concat(Array.isArray(r?.items) ? r.items : []); } catch { failures++; }
+      if (!a.origin || a.origin === 'AutoDialerCampaign') {
+        try { const r = await get(`/CallActivity/CampaignCalls${q}`); items = items.concat(Array.isArray(r?.items) ? r.items : []); } catch { failures++; }
+      } else failures += 0;
+      if (failures >= 2) throw new Error('Failed to load call activity from either source.');
+      items.sort((x, y) => new Date(y.startedAt).getTime() - new Date(x.startedAt).getTime());
+      show(items);
+    }],
+]) };
+
+// conversation_* run through the messaging admin-tools gateway (same JSON-RPC the MCP server uses).
+async function adminTool(name, args) {
+  const r = await messagingPost('/mcp/v1/admin-tools/call', { jsonrpc: '2.0', id: 1, method: 'tools/call', params: { name, arguments: args } });
+  if (r?.error) throw new Error(r.error.message || JSON.stringify(r.error));
+  const text = r?.result?.content?.[0]?.text;
+  if (text === undefined) throw new Error('Empty response from admin-tools gateway');
+  return text;
+}
+
+export const conversationCommand = { command: 'conversation', ...group('Conversations (list, get, search)', [
+  ['list', 'List recent conversations',
+    (y) => y.option('limit', { type: 'number' }).option('channel', { type: 'string' }).option('status', { type: 'string', describe: 'open or closed' }).option('agent-id', { type: 'number' }),
+    async (a) => show(await adminTool('conversation_list', { limit: a.limit, channel: a.channel, status: a.status, agentId: a['agent-id'] }))],
+  ['get <id>', 'Get one conversation', (y) => y.positional('id', { type: 'number' }),
+    async (a) => show(await adminTool('conversation_get', { id: a.id }))],
+  ['search <q>', 'Search conversations by phone number or call SID',
+    (y) => y.positional('q', { type: 'string' }).option('limit', { type: 'number' }),
+    async (a) => show(await adminTool('conversation_search', { q: a.q, limit: a.limit }))],
+]) };
+
+export const conversionCommand = { command: 'conversion', ...group('Conversion goals and attribution report', [
+  ['list-goals', 'List conversion goals', null, async () => show(await get('/Conversions/goals'))],
+  ['create-goal', 'Create a conversion goal',
+    (y) => y.option('name', { type: 'string', demandOption: true })
+      .option('trigger-type', { type: 'string', demandOption: true })
+      .option('trigger-url', { type: 'string' }).option('event-name', { type: 'string' })
+      .option('default-amount', { type: 'number', default: 0 })
+      .option('revenue-variable-name', { type: 'string' })
+      .option('allow-once', { type: 'boolean', default: false })
+      .option('attribution-window-hours', { type: 'number', default: 24 }),
+    async (a) => show(await post('/Conversions/goals', {
+      name: a.name, triggerType: a['trigger-type'], triggerUrl: a['trigger-url'] || null, eventName: a['event-name'] || null,
+      defaultAmount: a['default-amount'] ?? 0, revenueVariableName: a['revenue-variable-name'] || null,
+      allowOnce: a['allow-once'] ?? false, attributionWindowHours: a['attribution-window-hours'] ?? 24, isEnabled: true,
+    }))],
+  ['report', 'Conversion attribution report', (y) => y.option('days', { type: 'number', default: 30 }),
+    async (a) => show(await get(`/Conversions/report?days=${a.days ?? 30}`))],
+]) };
+
+export const emailCommand = { command: 'email', ...group('Velaro staff: email delivery queue and stats', [
+  ['queue-status', 'Email delivery queue status', (y) => y.option('site-id', { type: 'number' }),
+    async (a) => show(await messagingGet(`/SuperAdmin/email-delivery/status${qs({ siteId: a['site-id'] })}`))],
+  ['delivery-stats', 'Email delivery stats', (y) => y.option('site-id', { type: 'number' }).option('days', { type: 'number' }).option('hours', { type: 'number' }),
+    async (a) => show(await messagingGet(`/SuperAdmin/email-delivery/stats${qs({ siteId: a['site-id'], days: a.days, hours: a.hours })}`))],
+  ['queue-replay', 'Replay stuck emails (dry run unless --apply --yes)',
+    (y) => y.option('apply', { type: 'boolean', describe: 'Actually replay (default is a dry run)' }).option('yes', { type: 'boolean' }),
+    async (a) => {
+      if (a.apply) needYes(a, 'replay the email queue');
+      show(await messagingPost(`/SuperAdmin/email-delivery/replay?dryRun=${a.apply ? 'false' : 'true'}`));
+    }],
+]) };
+
+export const ivrCommand = { command: 'ivr', ...group('IVR voice configurations, phone lines and business hours', [
+  ['list-voice-configs', 'List IVR voice configurations', null, async () => show(await get('/IVRVoiceConfigurations'))],
+  ['get-voice-config <id>', 'Show one voice configuration', (y) => y.positional('id', { type: 'number' }),
+    async (a) => show(await get(`/IVRVoiceConfigurations/${a.id}`))],
+  ['create-voice-config', 'Create a voice configuration with the standard ElevenLabs/Deepgram defaults',
+    (y) => y.option('name', { type: 'string', demandOption: true })
+      .option('voice-id', { type: 'string' }).option('welcome-greeting', { type: 'string' })
+      .option('bridge-number', { type: 'string' }).option('no-agent-fallback', { type: 'string' })
+      .option('business-hours-json', { type: 'string', describe: 'ivrBusinessHoursJson, e.g. {"tz":"America/Los_Angeles","days":{"mon":{"start":"09:00","end":"17:00"}}}; omit for 24/7' }),
+    async (a) => show(await post('/IVRVoiceConfigurations', {
+      name: a.name, voiceProvider: 'ElevenLabs', voiceId: a['voice-id'] ?? 'XB0fDUnXU5powFXDhCwa', model: 'eleven_turbo_v2_5',
+      speed: 0.85, stability: 1.0, similarity: 0.90, transcriptionProvider: 'Deepgram', transcriptionLanguage: 'en-US',
+      speechModel: 'nova-3-general', interruptible: 'speech', interruptSensitivity: 'medium', transferMode: 'triage',
+      escalationBridgeEnabled: true, escalationCallbackEnabled: true, noAgentFallback: a['no-agent-fallback'] ?? 'take_message',
+      afterHoursFallback: 'take_message', ivrBusinessHoursJson: a['business-hours-json'] ?? null,
+      welcomeGreeting: a['welcome-greeting'] ?? null, alwaysTransferNumber: a['bridge-number'] ?? null,
+    }))],
+  ['update-voice-config <id>', 'Update fields on a voice configuration (only the flags you pass change)',
+    (y) => y.positional('id', { type: 'number' })
+      .option('idle-check-in-seconds', { type: 'number' }).option('idle-check-in-message', { type: 'string' })
+      .option('idle-hangup-seconds', { type: 'number' })
+      .option('escalation-bridge-enabled', { type: 'boolean' }).option('escalation-callback-enabled', { type: 'boolean' })
+      .option('transfer-no-answer-message', { type: 'string' }).option('welcome-greeting', { type: 'string' })
+      .option('always-transfer-number', { type: 'string' }).option('transfer-mode', { type: 'string' })
+      .option('no-agent-fallback', { type: 'string' }).option('after-hours-fallback', { type: 'string' })
+      .option('patch-json', { type: 'string', describe: 'Extra fields to merge, as a JSON object' }),
+    async (a) => {
+      const existing = await get(`/IVRVoiceConfigurations/${a.id}`);
+      if (!existing) throw new Error(`Voice config ${a.id} not found.`);
+      const map = { 'idle-check-in-seconds': 'idleCheckInSeconds', 'idle-check-in-message': 'idleCheckInMessage', 'idle-hangup-seconds': 'idleHangupSeconds',
+        'escalation-bridge-enabled': 'escalationBridgeEnabled', 'escalation-callback-enabled': 'escalationCallbackEnabled',
+        'transfer-no-answer-message': 'transferNoAnswerMessage', 'welcome-greeting': 'welcomeGreeting', 'always-transfer-number': 'alwaysTransferNumber',
+        'transfer-mode': 'transferMode', 'no-agent-fallback': 'noAgentFallback', 'after-hours-fallback': 'afterHoursFallback' };
+      const body = { ...existing, ...(a['patch-json'] ? JSON.parse(a['patch-json']) : {}) };
+      for (const [flag, key] of Object.entries(map)) if (a[flag] !== undefined) body[key] = a[flag];
+      show(await put(`/IVRVoiceConfigurations/${a.id}`, body));
+    }],
+  ['set-business-hours <id>', 'Set (or clear) the business-hours JSON on a voice configuration',
+    (y) => y.positional('id', { type: 'number' })
+      .option('hours-json', { type: 'string', describe: 'ivrBusinessHoursJson string, or 24/7 to clear' }),
+    async (a) => {
+      const existing = await get(`/IVRVoiceConfigurations/${a.id}`);
+      if (!existing) throw new Error(`Voice config ${a.id} not found.`);
+      const h = a['hours-json'];
+      if (h === undefined) throw new Error('--hours-json is required (use 24/7 to clear).');
+      if (!['24/7', 'always', 'none', 'all'].includes(h.trim().toLowerCase())) JSON.parse(h);
+      const clear = ['24/7', 'always', 'none', 'all'].includes(h.trim().toLowerCase());
+      show(await put(`/IVRVoiceConfigurations/${a.id}`, { ...existing, ivrBusinessHoursJson: clear ? null : h }));
+    }],
+  ['agent-availability', 'Agent availability plus each voice config fallback actions', null, async () => {
+    const snap = await get('/LiveDashboard/snapshot');
+    const cfgs = await get('/IVRVoiceConfigurations');
+    show({
+      agentsOnline: snap?.agentsOnline ?? 0, agentsAvailable: snap?.agentsAvailable ?? snap?.agentsOnline ?? 0, agentsTotal: snap?.agentsTotal ?? 0,
+      fallbacks: (Array.isArray(cfgs) ? cfgs : []).map((c) => ({ id: c.id, name: c.name, noAgentFallback: c.noAgentFallback ?? 'take_message', afterHoursFallback: c.afterHoursFallback ?? 'take_message' })),
+    });
+  }],
+  ['list-lines', 'List IVR phone lines', null, async () => show(await get('/IVRVoiceConfigurations/lines'))],
+  ['update-line <id>', 'Set a phone line bridge number and/or voice configuration',
+    (y) => y.positional('id', { type: 'number' })
+      .option('default-transfer-number', { type: 'string' }).option('voice-config-id', { type: 'number' }),
+    async (a) => {
+      const body = {};
+      if (a['default-transfer-number'] !== undefined) body.defaultTransferNumber = a['default-transfer-number'];
+      if (a['voice-config-id'] !== undefined) body.ivrVoiceConfigurationId = a['voice-config-id'];
+      if (!Object.keys(body).length) throw new Error('Provide --default-transfer-number and/or --voice-config-id.');
+      show(await request('PATCH', `/IVRVoiceConfigurations/lines/${a.id}`, body));
+    }],
+]) };

package/lib/commands/parity-staff-tools.js

@@ -0,0 +1,192 @@
+// CLI parity for MCP tool groups that previously had no CLI command group (parity-close 2026-10-23).
+// Every subcommand calls the SAME REST route the matching MCP tool handler calls (mcp/server.js,
+// mcp/staff-server.js). Admin-API routes go through request(); messaging-API routes through
+// messagingRequest(). Staff-only tools are enforced server-side (the CLI only passes your token).
+// Impactful subcommands need --yes. Naming: `velaro <group> <tool-name-without-group-prefix>`.
+import { request, messagingRequest } from '../api.js';
+import { supportCommand } from './support.js';
+import { pricingCommand } from './pricing.js';
+import { scraperCommand } from './scraper.js';
+import { tourPolicyCommand } from './tour-policy.js';
+import fs from 'node:fs';
+import crypto from 'node:crypto';
+
+const out = (r) => console.log(typeof r === 'string' ? r : JSON.stringify(r, null, 2));
+const S = (describe, req) => ({ type: 'string', describe, ...(req ? { demandOption: true } : {}) });
+const N = (describe, req) => ({ type: 'number', describe, ...(req ? { demandOption: true } : {}) });
+const B = (describe) => ({ type: 'boolean', describe });
+const csv = (v) => (v === undefined ? undefined : String(v).split(',').map((x) => x.trim()).filter(Boolean));
+const csvN = (v) => csv(v)?.map(Number);
+const enc = encodeURIComponent;
+// '@file.json' reads a file; otherwise the string is parsed as JSON.
+const json = (v) => (v === undefined ? undefined : JSON.parse(String(v).startsWith('@') ? fs.readFileSync(String(v).slice(1), 'utf8') : v));
+const qs = (o) => {
+  const sp = new URLSearchParams();
+  for (const [k, v] of Object.entries(o)) if (v !== undefined && v !== null && v !== '') sp.set(k, String(v));
+  const s = sp.toString();
+  return s ? `?${s}` : '';
+};
+const pick = (a, map) => Object.fromEntries(Object.entries(map).filter(([f]) => a[f] !== undefined).map(([f, k]) => [k, a[f]]));
+const exclusiveEnd = (d) => (/^\d{4}-\d{2}-\d{2}$/.test(d || '') ? new Date(Date.parse(d) + 86400000).toISOString().slice(0, 10) : d);
+
+// Messaging admin-tools gateway (same endpoint the MCP uses for ms_bookings_*/outlook_calendar_* range/cancel tools).
+async function gatewayTool(name, args) {
+  const r = await messagingRequest('POST', '/mcp/v1/admin-tools/call', { jsonrpc: '2.0', id: 1, method: 'tools/call', params: { name, arguments: args } });
+  if (r?.error) throw new Error(`${name}: ${r.error.message || JSON.stringify(r.error)}`);
+  return r?.result?.content?.[0]?.text ?? r;
+}
+
+async function call(s, a) {
+  const fn = s.api === 'msg' ? messagingRequest : request;
+  return fn(s.method || 'GET', s.path(a), s.body ? s.body(a) : undefined);
+}
+
+export function addRoutes(y, specs) {
+  for (const s of specs) {
+    y.command(s.name, s.desc, (yy) => {
+      for (const [k, v] of Object.entries(s.opts || {})) yy.option(k, v);
+      if (s.yes || s.needsYes) yy.option('yes', B('Confirm this impactful action'));
+      return yy;
+    }, async (a) => {
+      try {
+        if ((s.yes || (s.needsYes && s.needsYes(a))) && !a.yes) { console.error(`Refusing without --yes: ${s.desc}`); process.exit(1); }
+        out(s.run ? await s.run(a) : await call(s, a));
+      } catch (e) { console.error(e.message); process.exit(1); }
+    });
+  }
+  return y;
+}
+
+const site = { site: N('Site id', true) };
+const SP = (a) => `SupportTools/sites/${a.site}`;
+const rpcOpts = { args: S('Extra tool arguments as JSON or @file.json') };
+const rpcArgs = (a, map) => ({ ...pick(a, map), ...(json(a.args) || {}) });
+
+export const SUPPORT_EXTRA = [
+  { name: 'user-lookup', desc: 'Search users by email/name across sites (staff)', opts: { query: S('Search text', true) }, path: (a) => `SupportTools/users/search?q=${enc(a.query)}` },
+  { name: 'site-lookup', desc: 'Search sites by name/URL/admin (staff)', opts: { query: S('Search text', true) }, path: (a) => `SupportTools/sites/search?q=${enc(a.query)}` },
+  { name: 'change-username', desc: 'Change a user login email (staff)', yes: true, method: 'POST', opts: { 'user-id': N('User id', true), 'new-email': S('New email', true) }, path: (a) => `SupportTools/users/${a.userId}/change-username`, body: (a) => ({ newEmail: a.newEmail }) },
+  { name: 'list-admin-users', desc: 'List Velaro staff/admin users', path: () => 'SupportTools/admin-users' },
+  { name: 'list-staff', desc: 'List Velaro staff with roles', path: () => 'SupportTools/admin-users' },
+  { name: 'add-admin-user', desc: 'Grant staff admin access to an email', yes: true, method: 'POST', opts: { email: S('Email', true) }, path: () => 'SupportTools/admin-users', body: (a) => ({ email: a.email }) },
+  { name: 'remove-admin-user', desc: 'Remove staff admin access for a user id', yes: true, method: 'DELETE', opts: { 'user-id': N('User id', true) }, path: (a) => `SupportTools/admin-users/${a.userId}` },
+  { name: 'set-staff-role', desc: 'Set a staff user role', yes: true, method: 'PATCH', opts: { 'user-id': N('User id', true), role: S('Role', true) }, path: (a) => `SupportTools/admin-users/${a.userId}/role`, body: (a) => ({ role: a.role }) },
+  { name: 'integration-logs', desc: 'Integration log entries for a site', opts: { ...site, page: N('Page'), 'page-size': N('Page size (max 100)'), integration: S('Integration'), severity: S('Severity') }, path: (a) => `${SP(a)}/integration-logs${qs({ page: a.page ?? 1, pageSize: Math.min(100, a.pageSize ?? 50), integration: a.integration, severity: a.severity && a.severity !== 'All' ? a.severity : undefined })}` },
+  { name: 'site-health', desc: 'Site health: subscription, agents, last login, 7-day errors', opts: site, path: (a) => `${SP(a)}/health` },
+  { name: 'site-agents', desc: 'Agents on a site', opts: site, path: (a) => `${SP(a)}/agents` },
+  { name: 'site-activity', desc: 'Activity log for a site', opts: { ...site, page: N('Page'), 'page-size': N('Page size (max 200)'), category: S('Category') }, path: (a) => `${SP(a)}/activity${qs({ page: a.page ?? 1, pageSize: Math.min(200, a.pageSize ?? 50), category: a.category })}` },
+  { name: 'extend-subscription', desc: 'Extend a site subscription by N days', yes: true, method: 'POST', opts: { ...site, days: N('Days', true) }, path: (a) => `${SP(a)}/extend-subscription`, body: (a) => ({ days: a.days }) },
+  { name: 'set-user-active', desc: 'Activate/deactivate a user on a site', yes: true, method: 'POST', opts: { ...site, 'user-id': N('User id', true), active: { type: 'boolean', demandOption: true, describe: 'true or false' } }, path: (a) => `SupportTools/users/${a.userId}/sites/${a.site}/set-active`, body: (a) => ({ isActive: a.active }) },
+  { name: 'bulk-set-flags', desc: 'Set several subscription flags at once (JSON object)', yes: true, method: 'POST', opts: { ...site, flags: S('JSON object or @file.json', true) }, path: (a) => `${SP(a)}/subscription/bulk-flags`, body: (a) => ({ flags: json(a.flags) }) },
+  { name: 'create-agent', desc: 'Create an agent on any site (staff)', api: 'msg', method: 'POST', opts: { ...site, email: S('Email', true), 'first-name': S('First name'), 'last-name': S('Last name'), roles: S('Comma list of roles'), 'team-ids': S('Comma list of team ids'), 'max-chats': N('Max chats (0 = default)') }, path: (a) => `/SupportTools/sites/${a.site}/agents`, body: (a) => ({ email: a.email, firstName: a.firstName, lastName: a.lastName, roles: csv(a.roles), teamIds: csvN(a.teamIds), maxChats: a.maxChats ?? 0 }) },
+  { name: 'schedule-adherence', desc: 'Schedule adherence diagnostics for a site', api: 'msg', opts: { ...site, role: S('role'), 'agent-id': N('Agent id (required when role=agent)'), start: S('Start'), end: S('End'), tz: S('Timezone') }, path: (a) => `/Reports/sites/${a.site}/schedule-adherence-diagnostics${qs({ detail: 'true', role: a.role, agentId: a.agentId, start: a.start, end: a.end, tz: a.tz })}` },
+  { name: 'appointments-list-sites', desc: 'Sites with Velaro Appointments enabled', api: 'msg', path: () => '/Appointments/admin/sites-with-appointments' },
+  { name: 'diagnose-after-hours', desc: 'After-hours routing diagnostic data for a site', opts: site, path: (a) => `${SP(a)}/after-hours-routing` },
+  { name: 'diagnose', desc: 'One-shot site diagnosis: health, recent errors, activity, failed Hangfire jobs', opts: site, run: async (a) => {
+    const g = (p) => request('GET', p).catch((e) => ({ error: e.message }));
+    const [health, integrationErrors, aiToolErrors, activity, failedJobs] = await Promise.all([
+      g(`${SP(a)}/health`), g(`${SP(a)}/integration-logs?severity=Error&pageSize=10`), g(`${SP(a)}/integration-logs?severity=Error&category=AiTool&pageSize=10`), g(`${SP(a)}/activity?pageSize=5`), g('DatabaseTool/FailedJobs')]);
+    return { health, integrationErrors, aiToolErrors, activity, failedJobs };
+  } },
+];
+
+const SCRAPER_EXTRA = [
+  { name: 'staff-crawl', desc: 'Trigger a crawl for any site (staff)', method: 'POST', opts: { ...site, urls: S('Comma list of URLs', true), name: S('Job name'), 'crawl-depth': N('Crawl depth (default 1)'), 'max-pages': N('Max pages (default 25)') }, path: (a) => `ScraperJobs/StaffCreate/${a.site}`, body: (a) => ({ name: a.name || `staff-triggered-${a.site}`, urls: csv(a.urls), crawlDepth: a.crawlDepth ?? 1, maxPages: a.maxPages ?? 25 }) },
+];
+
+const LIVEFLUENCE = [
+  { name: 'export', desc: 'Export V10 routing rules for a V10 site', opts: { 'v10-site-id': N('V10 site id', true), 'v20-site-id': N('V20 site id'), 'include-non-routing': B('Include non-routing rules') }, path: (a) => `DatabaseTool/V10Export/${a.v10SiteId}${qs({ v20SiteId: a.v20SiteId, includeNonRouting: a.includeNonRouting ? 'true' : undefined })}` },
+  { name: 'create-teams', desc: 'Create V20 teams from V10 groups (use --dry-run first)', method: 'POST', needsYes: (a) => !a.dryRun, opts: { 'v10-site-id': N('V10 site id', true), 'v20-site-id': N('V20 site id', true), 'dry-run': B('Preview only'), 'group-names': S('Comma list of V10 group names') }, path: () => 'DatabaseTool/V10CreateTeams', body: (a) => ({ v10SiteId: a.v10SiteId, v20SiteId: a.v20SiteId, dryRun: !!a.dryRun, groupNames: csv(a.groupNames) ?? [] }) },
+  { name: 'site-workflows-list', desc: 'List a site workflows', opts: { 'site-id': N('Site id', true) }, path: (a) => `DatabaseTool/SiteWorkflows/${a.siteId}` },
+  { name: 'site-workflows-set-enabled', desc: 'Enable/disable workflows by id or name (use --dry-run first)', method: 'POST', needsYes: (a) => !a.dryRun, opts: { 'site-id': N('Site id', true), 'workflow-ids': S('Comma list of ids'), names: S('Comma list of names'), enabled: B('Enable (omit to disable)'), 'dry-run': B('Preview only'), 'force-partial': B('Allow partial match'), 'v10-site-id': N('V10 site id') }, path: () => 'DatabaseTool/SiteWorkflows/SetEnabled', body: (a) => ({ siteId: a.siteId, workflowIds: csvN(a.workflowIds) ?? [], names: csv(a.names) ?? [], enabled: !!a.enabled, dryRun: !!a.dryRun, forcePartial: !!a.forcePartial, v10SiteId: a.v10SiteId ?? null }) },
+  { name: 'site-workflow-create', desc: 'Create a workflow from a nodes blob', method: 'POST', needsYes: (a) => !a.dryRun, opts: { 'site-id': N('Site id', true), name: S('Name', true), 'trigger-type': S('Trigger (default conversation_opened)'), 'nodes-blob': S('Nodes JSON or @file.json', true), enabled: B('Enable on create'), 'dry-run': B('Preview only') }, path: () => 'DatabaseTool/SiteWorkflows/Create', body: (a) => ({ siteId: a.siteId, name: a.name, triggerType: a.triggerType ?? 'conversation_opened', nodesBlob: String(a.nodesBlob).startsWith('@') ? fs.readFileSync(String(a.nodesBlob).slice(1), 'utf8') : a.nodesBlob, enabled: !!a.enabled, dryRun: !!a.dryRun }) },
+  { name: 'site-workflow-set-action', desc: 'Point a workflow action at a target', method: 'POST', needsYes: (a) => !a.dryRun, opts: { 'site-id': N('Site id', true), 'workflow-id': N('Workflow id', true), 'action-type': S('Action type', true), 'target-id': N('Target id', true), 'dry-run': B('Preview only') }, path: () => 'DatabaseTool/SiteWorkflows/SetAction', body: (a) => ({ siteId: a.siteId, workflowId: a.workflowId, actionType: a.actionType, targetId: a.targetId, dryRun: !!a.dryRun }) },
+  { name: 'site-rules-list', desc: 'List a site routing rules', opts: { 'site-id': N('Site id', true) }, path: (a) => `DatabaseTool/SiteRules/${a.siteId}` },
+  { name: 'site-rules-set-enabled', desc: 'Enable/disable routing rules', method: 'POST', needsYes: (a) => !a.dryRun, opts: { 'site-id': N('Site id', true), 'rule-ids': S('Comma list of ids'), trigger: S('Trigger filter'), enabled: B('Enable (omit to disable)'), 'dry-run': B('Preview only') }, path: () => 'DatabaseTool/SiteRules/SetEnabled', body: (a) => ({ siteId: a.siteId, ruleIds: csvN(a.ruleIds) ?? [], trigger: a.trigger ?? null, enabled: !!a.enabled, dryRun: !!a.dryRun }) },
+  { name: 'seed-url-rules', desc: 'Seed URL rules for an AI config', method: 'POST', needsYes: (a) => !a.dryRun, opts: { 'site-id': N('Site id', true), 'ai-config-id': N('AI config id', true), rules: S('Rules JSON or @file.json', true), 'dry-run': B('Preview only') }, path: () => 'DatabaseTool/V10SeedUrlRules', body: (a) => ({ siteId: a.siteId, aiConfigId: a.aiConfigId, dryRun: !!a.dryRun, rules: json(a.rules) }) },
+  { name: 'conversion-advisor', desc: 'Advise on V10 to V20 conversion (apply with --apply --yes)', method: 'POST', needsYes: (a) => !!a.apply, opts: { 'v10-site-id': N('V10 site id'), 'v20-site-id': N('V20 site id', true), apply: B('Apply recommendations'), 'include-non-routing': B('Include non-routing'), intents: S('Intents JSON array') }, path: () => 'DatabaseTool/ConversionAdvisor', body: (a) => { const intents = json(a.intents); return { v10SiteId: intents?.length ? null : (a.v10SiteId ?? null), v20SiteId: a.v20SiteId, apply: !!a.apply, includeNonRouting: !!a.includeNonRouting, intents: intents ?? null }; } },
+  { name: 'migrate', desc: 'Migrate V10 routing to V20 workflows (use --dry-run first)', method: 'POST', needsYes: (a) => !a.dryRun, opts: { 'v10-site-id': N('V10 site id', true), 'v20-site-id': N('V20 site id'), 'dry-run': B('Preview only'), enable: B('Enable created workflows'), 'include-non-routing': B('Include non-routing'), 'route-bot-groups-to-team': B('Route bot groups to team'), 'team-mappings': S('JSON or @file'), 'ai-config-mappings': S('JSON or @file') }, path: () => 'DatabaseTool/V10Migrate', body: (a) => ({ v10SiteId: a.v10SiteId, v20SiteId: a.v20SiteId ?? null, dryRun: !!a.dryRun, enable: !!a.enable, includeNonRouting: !!a.includeNonRouting, routeBotGroupsToTeam: !!a.routeBotGroupsToTeam, teamMappings: json(a.teamMappings) ?? [], aiConfigMappings: json(a.aiConfigMappings) ?? [] }) },
+];
+
+const TABLES = {
+  missed: [{ name: 'chat-diagnostics', desc: 'Missed chat diagnostics with routing snapshots', opts: { start: S('Start date'), end: S('End date'), reason: S('Reason filter'), 'team-id': N('Team id'), site: N('Site id (staff)') }, path: (a) => `CallCenterAnalytics/MissedChatDiagnostics${qs({ start: a.start, end: a.end, reason: a.reason, teamId: a.teamId, siteId: a.site })}` }],
+  service: [{ name: 'level-report', desc: 'Service level (SLA) report', opts: { 'start-date': S('Start'), 'end-date': S('End (inclusive date)'), granularity: S('day|week|month') }, path: (a) => `ServiceLevel${qs({ startDate: a.startDate, endDate: exclusiveEnd(a.endDate), granularity: a.granularity })}` }],
+  page: [
+    { name: 'widget-list', desc: 'List page widgets', path: () => 'PageWidgets' },
+    { name: 'widget-get', desc: 'Get a page widget', opts: { id: N('Widget id', true) }, path: (a) => `PageWidgets/${a.id}` },
+    { name: 'widget-toggle', desc: 'Enable or disable a page widget', opts: { id: N('Widget id', true), enabled: { type: 'boolean', demandOption: true, describe: 'true or false' } }, run: async (a) => { const w = await request('GET', `PageWidgets/${a.id}`); w.isEnabled = !!a.enabled; await request('PUT', `PageWidgets/${a.id}`, w); return `Widget ${a.id} ${a.enabled ? 'enabled' : 'disabled'}.`; } },
+  ],
+  uploaded: [
+    { name: 'files-list', desc: 'List uploaded AI training files', api: 'msg', path: () => '/uploadedFiles/list/AI' },
+    { name: 'file-reindex', desc: 'Re-index an uploaded file', api: 'msg', method: 'POST', opts: { 'file-id': N('File id'), 'file-name': S('File name'), 'index-name': S('Index name') }, path: () => '/uploadedFiles/reindex', body: (a) => { if (!a.fileId && !a.fileName) throw new Error('--file-id or --file-name is required'); return pick(a, { fileId: 'id', fileName: 'fileName', indexName: 'indexName' }); } },
+  ],
+  ms: [
+    { name: 'bookings-status', desc: 'Microsoft Bookings status for a site (staff)', opts: site, path: (a) => `MicrosoftBookings/superadmin/status?siteId=${a.site}` },
+    { name: 'bookings-configure', desc: 'Configure Microsoft Bookings for a site (staff)', method: 'PUT', opts: { ...site, 'business-id': S('Business id', true), 'business-display-name': S('Display name'), disabled: B('Disable the integration') }, path: (a) => `MicrosoftBookings/superadmin/config?siteId=${a.site}`, body: (a) => ({ businessId: a.businessId, businessDisplayName: a.businessDisplayName ?? '', isEnabled: !a.disabled }) },
+    { name: 'bookings-check-availability-range', desc: 'Bookings availability range for a service', opts: { 'service-id': S('Service id', true), ...rpcOpts }, run: (a) => gatewayTool('ms_bookings_check_availability_range', rpcArgs(a, { serviceId: 'service_id' })) },
+    { name: 'bookings-cancel-appointment', desc: 'Cancel a Bookings appointment', yes: true, opts: { 'appointment-id': S('Appointment id', true), ...rpcOpts }, run: (a) => gatewayTool('ms_bookings_cancel_appointment', rpcArgs(a, { appointmentId: 'appointment_id' })) },
+    { name: 'bookings-reschedule-appointment', desc: 'Reschedule a Bookings appointment', yes: true, opts: { 'appointment-id': S('Appointment id', true), 'new-date': S('YYYY-MM-DD', true), 'new-start-time': S('HH:mm', true), ...rpcOpts }, run: (a) => gatewayTool('ms_bookings_reschedule_appointment', rpcArgs(a, { appointmentId: 'appointment_id', newDate: 'new_date', newStartTime: 'new_start_time' })) },
+  ],
+  outlook: [
+    { name: 'calendar-status', desc: 'Outlook calendar status for a site (staff)', opts: site, path: (a) => `OutlookCalendar/superadmin/status?siteId=${a.site}` },
+    { name: 'calendar-test-connection', desc: 'Test the Outlook calendar connection (staff)', opts: { ...site, 'organizer-email': S('Organizer email') }, path: (a) => `OutlookCalendar/superadmin/test-connection?siteId=${a.site}${a.organizerEmail ? `&organizerEmail=${enc(a.organizerEmail)}` : ''}` },
+    { name: 'calendar-get-available-range', desc: 'Available calendar time range', opts: rpcOpts, run: (a) => gatewayTool('outlook_calendar_get_available_range', rpcArgs(a, {})) },
+    { name: 'calendar-cancel', desc: 'Cancel an Outlook calendar event', yes: true, opts: { 'event-id': S('Event id', true), ...rpcOpts }, run: (a) => gatewayTool('outlook_calendar_cancel', rpcArgs(a, { eventId: 'event_id' })) },
+  ],
+  oauth: [
+    { name: 'list', desc: 'List stored OAuth app configs (staff)', path: () => 'SupportTools/oauth-configs' },
+    { name: 'update', desc: 'Update an integration OAuth client id/secret (staff)', yes: true, method: 'PUT', opts: { integration: S('Integration key', true), 'client-id': S('Client id'), 'client-secret': S('Client secret') }, path: (a) => `SupportTools/oauth-configs/${enc(a.integration)}`, body: (a) => { if (!a.clientId && !a.clientSecret) throw new Error('Pass --client-id and/or --client-secret'); return { clientId: a.clientId, clientSecret: a.clientSecret }; } },
+  ],
+  provision: [{ name: 'health', desc: 'Provisioning health checks (run after every staging deploy)', api: 'msg', path: () => '/SuperAdmin/provision-health' }],
+  sse: [{ name: 'visitor-diagnostic', desc: 'SSE visitor transport diagnostic', api: 'msg', path: () => '/Diagnostics/sse' }],
+  skill: [{ name: 'logs-for-site', desc: 'AI skill call logs for a site (staff)', opts: { ...site, take: N('Entries (max 200)'), 'errors-only': B('Errors only') }, path: (a) => `SuperAdmin/Diagnostics/skill-logs?siteId=${a.site}&take=${Math.min(a.take ?? 50, 200)}&errorsOnly=${!!a.errorsOnly}` }],
+  v10: [{ name: 'bot-turn-limits', desc: 'v10 sites with a MaximumBotTurnsPerMonth limit (staff)', path: () => 'BotAnalytics/V10BotTurnLimits' }],
+  whatsapp: [{ name: 'campaign-diagnostic', desc: 'WhatsApp campaign diagnostic for a site (staff)', api: 'msg', opts: site, path: (a) => `/Diagnostics/whatsapp-campaign/${a.site}` }],
+  mobile: [{ name: 'ota-trigger', desc: 'Trigger the mobile OTA build (GitHub Actions mobile-build.yml; needs GITHUB_TOKEN)', yes: true, run: async () => {
+    const token = process.env.GITHUB_TOKEN;
+    if (!token) throw new Error('GITHUB_TOKEN env var is not set.');
+    const r = await fetch('https://api.github.com/repos/velaro/velaro-messaging/actions/workflows/mobile-build.yml/dispatches', { method: 'POST', headers: { Authorization: `Bearer ${token}`, Accept: 'application/vnd.github+json', 'X-GitHub-Api-Version': '2022-11-28', 'Content-Type': 'application/json' }, body: JSON.stringify({ ref: 'master', inputs: { profile: 'preview' } }) });
+    if (r.status !== 204) throw new Error(`GitHub API returned ${r.status}: ${await r.text()}`);
+    return 'Mobile OTA triggered on GitHub Actions (mobile-build.yml -> master).';
+  } }],
+  signalr: [{ name: 'diagnostics', desc: 'Azure SignalR health (needs SIGNALR_INFRA_CONN / SIGNALR_PROD_CONN env)', opts: { instance: { type: 'string', choices: ['infra', 'legacy', 'both'], default: 'both' }, hub: S('Hub name, e.g. MessengerHub') }, run: async (a) => {
+    const targets = [['infra', 'velaro-eastus-prd-signalr (infra)', process.env.SIGNALR_INFRA_CONN], ['legacy', 'velaro-prod-us (legacy)', process.env.SIGNALR_PROD_CONN]].filter(([k]) => a.instance === 'both' || a.instance === k);
+    const res = {};
+    for (const [, label, conn] of targets) {
+      const ep = (/Endpoint=([^;]+)/i.exec(conn || '') || [])[1]; const key = (/AccessKey=([^;]+)/i.exec(conn || '') || [])[1];
+      if (!ep || !key) { res[label] = 'connection string not set in env'; continue; }
+      const endpoint = ep.replace(/\/+$/, '');
+      const jwt = (url) => { const h = Buffer.from(JSON.stringify({ alg: 'HS256', typ: 'JWT' })).toString('base64url'); const n = Math.floor(Date.now() / 1000); const p = Buffer.from(JSON.stringify({ aud: url, iat: n, exp: n + 300 })).toString('base64url'); return `${h}.${p}.${crypto.createHmac('sha256', Buffer.from(key, 'base64')).update(`${h}.${p}`).digest('base64url')}`; };
+      const get = async (url) => { const r = await fetch(url, { headers: { Authorization: `Bearer ${jwt(url)}` } }); return { status: r.status, body: (await r.text()).slice(0, 2000) }; };
+      res[label] = { health: await get(`${endpoint}/api/v1/health`), ...(a.hub ? { hub: await get(`${endpoint}/api/v1/hubs/${a.hub}`) } : {}) };
+    }
+    return res;
+  } }],
+};
+
+const demand = (y, msg) => y.demandCommand(1, msg);
+
+export const livefluenceCommand = {
+  command: 'livefluence', describe: 'Velaro staff: V10 (LiveFluence) to V20 migration and per-site workflow/rule tools',
+  builder: (y) => demand(addRoutes(y, LIVEFLUENCE), 'Specify a subcommand'), handler: () => {},
+};
+export const missedCommand = { command: 'missed', describe: 'Missed chat diagnostics', builder: (y) => demand(addRoutes(y, TABLES.missed), 'Specify a subcommand'), handler: () => {} };
+export const serviceCommand = { command: 'service', describe: 'Service level (SLA) report', builder: (y) => demand(addRoutes(y, TABLES.service), 'Specify a subcommand'), handler: () => {} };
+export const pageCommand = { command: 'page', describe: 'Page widgets (list, get, toggle)', builder: (y) => demand(addRoutes(y, TABLES.page), 'Specify a subcommand'), handler: () => {} };
+export const uploadedCommand = { command: 'uploaded', describe: 'Uploaded AI training files (list, reindex)', builder: (y) => demand(addRoutes(y, TABLES.uploaded), 'Specify a subcommand'), handler: () => {} };
+export const msCommand = { command: 'ms', describe: 'Microsoft Bookings (status, configure, availability, cancel, reschedule)', builder: (y) => demand(addRoutes(y, TABLES.ms), 'Specify a subcommand'), handler: () => {} };
+export const outlookCommand = { command: 'outlook', describe: 'Outlook calendar (status, test connection, availability, cancel)', builder: (y) => demand(addRoutes(y, TABLES.outlook), 'Specify a subcommand'), handler: () => {} };
+export const oauthCommand = { command: 'oauth', describe: 'Velaro staff: stored OAuth app configs', builder: (y) => demand(addRoutes(y, TABLES.oauth), 'Specify a subcommand'), handler: () => {} };
+export const provisionCommand = { command: 'provision', describe: 'Velaro staff: provisioning health', builder: (y) => demand(addRoutes(y, TABLES.provision), 'Specify a subcommand'), handler: () => {} };
+export const sseCommand = { command: 'sse', describe: 'Velaro staff: SSE visitor transport diagnostic', builder: (y) => demand(addRoutes(y, TABLES.sse), 'Specify a subcommand'), handler: () => {} };
+export const skillCommand = { command: 'skill', describe: 'Velaro staff: AI skill logs for a site', builder: (y) => demand(addRoutes(y, TABLES.skill), 'Specify a subcommand'), handler: () => {} };
+export const v10Command = { command: 'v10', describe: 'Velaro staff: v10 bot turn limits', builder: (y) => demand(addRoutes(y, TABLES.v10), 'Specify a subcommand'), handler: () => {} };
+export const whatsappCommand = { command: 'whatsapp', describe: 'Velaro staff: WhatsApp campaign diagnostic', builder: (y) => demand(addRoutes(y, TABLES.whatsapp), 'Specify a subcommand'), handler: () => {} };
+export const mobileCommand = { command: 'mobile', describe: 'Velaro staff: mobile OTA build trigger', builder: (y) => demand(addRoutes(y, TABLES.mobile), 'Specify a subcommand'), handler: () => {} };
+export const signalrCommand = { command: 'signalr', describe: 'Velaro staff: Azure SignalR diagnostics', builder: (y) => demand(addRoutes(y, TABLES.signalr), 'Specify a subcommand'), handler: () => {} };
+
+// Existing inline-registered groups, re-exposed as detectable command objects with the missing subcommands added.
+export const supportGroupCommand = { command: 'support', describe: 'Staff SupportTools actions on a site (superadmin only)', builder: (y) => addRoutes(supportCommand(y), SUPPORT_EXTRA), handler: () => {} };
+export const pricingGroupCommand = { command: 'pricing', describe: 'View and manage the pricing catalog', builder: pricingCommand, handler: () => {} };
+export const scraperGroupCommand = { command: 'scraper', describe: 'Velaro staff: scraper / upload / chunk usage and crawl for any site', builder: (y) => addRoutes(scraperCommand(y), SCRAPER_EXTRA), handler: () => {} };
+export const tourPolicyGroupCommand = { command: 'tour-policy', describe: 'Velaro staff: guided-tour auto-open policy (versioned, rollback-able)', builder: tourPolicyCommand, handler: () => {} };

package/lib/commands/skill-usage.js

@@ -0,0 +1,39 @@
+import { messagingGet } from '../api.js';
+import { runCommand } from '../run.js';
+
+const usd = (n) => `$${Number(n ?? 0).toFixed(2)}`;
+
+// Pure formatter so the output shape is unit-testable without a network call.
+export function formatSkillUsage(r) {
+  const lines = [];
+  lines.push(`Site ${r.siteId}, ${r.month}${r.isTrial ? ' (trial)' : ''}, overage: ${r.overageBehavior}`);
+  lines.push('');
+  lines.push('Billable usage (same numbers as the customer Billing page):');
+  for (const u of r.usage ?? []) {
+    const limit = u.unlimited ? 'unlimited' : u.limit.toLocaleString();
+    lines.push(`  ${u.name.padEnd(24)} ${String(u.used.toLocaleString()).padStart(9)} / ${limit.padStart(9)}  ${u.unlimited ? '' : `${u.percent}%`.padStart(5)}  gate: ${u.mode ?? 'n/a'}`);
+  }
+  lines.push('');
+  lines.push('Calls by surface (staff, copilot and composite calls are never billed to the customer):');
+  const surfaces = r.callsBySurface ?? [];
+  if (!surfaces.length) lines.push('  (none recorded)');
+  for (const s of surfaces) lines.push(`  ${String(s.surface).padEnd(20)} ${s.calls.toLocaleString()}`);
+  lines.push('');
+  lines.push('LLM cost this month by key source (BYOK removes this cost only; skill usage above still counts):');
+  const llm = r.llmCostThisMonth ?? [];
+  if (!llm.length) lines.push('  (none logged)');
+  for (const l of llm) lines.push(`  ${String(l.keySource ?? 'unknown').padEnd(12)} ${usd(l.costUsd)} / ${l.calls} calls`);
+  return lines.join('\n');
+}
+
+export const skillUsageCommand = {
+  command: 'skill-usage <siteId>',
+  describe: 'Per-customer skill/integration usage vs plan limits, by surface, with LLM cost split (Velaro staff only)',
+  builder: (y) => y
+    .positional('siteId', { type: 'number', describe: 'Target site ID' })
+    .option('json', { type: 'boolean', default: false }),
+  handler: runCommand(async (argv) => {
+    const r = await messagingGet(`/SupportTools/sites/${argv.siteId}/skill-usage`);
+    console.log(argv.json ? JSON.stringify(r, null, 2) : formatSkillUsage(r));
+  }),
+};

package/lib/commands/teams-phone.js

@@ -4,7 +4,7 @@
  *   velaro teams-phone status                    Show current configuration
  *   velaro teams-phone set --tenant-id ...        Create or update the configuration
  *   velaro teams-phone remove                     Delete the configuration
- *   velaro teams-phone test                       Test the Graph subscription connectivity
+ *   velaro teams-phone test                       Run the inbound-calling readiness checks
  *
  * Backend contract: server/Velaro.Messaging/Controllers/Voice/TeamsPhoneConfigController.cs
  * (velaro-messaging). Site is resolved server-side from the auth context — never
@@ -34,6 +34,9 @@ function printConfig(c) {
   console.log(`  Assigned phone number:           ${c.assignedPhoneNumber ?? '(none)'}`);
   console.log(`  Webhook secret configured:       ${c.webhookSecretConfigured ? `${GRN}yes${RST}` : `${DIM}no${RST}`}`);
   const subColor = c.graphSubscriptionActive ? GRN : YEL;
+  if (typeof c.callingReady === 'boolean') {
+    console.log(`  Inbound calling ready:           ${c.callingReady ? GRN : YEL}${c.callingReady}${RST}`);
+  }
   console.log(`  Graph subscription active:       ${subColor}${c.graphSubscriptionActive}${RST}` +
     (c.graphSubscriptionExpiresAt ? `  (expires ${c.graphSubscriptionExpiresAt})` : ''));
   console.log('');
@@ -82,7 +85,16 @@ async function removeHandler() {
 async function testHandler() {
   const result = await messagingPost('/TeamsPhone/Config/Test', {});
   const color = result?.success ? GRN : RED;
-  console.log(`\n${color}${result?.success ? 'Success' : 'Failed'}${RST}: ${result?.message ?? '(no message)'}\n`);
+  console.log(`\n${color}${result?.success ? 'Success' : 'Failed'}${RST}: ${result?.message ?? '(no message)'}`);
+  if (typeof result?.callingReady === 'boolean') {
+    console.log(`  Inbound calling ready: ${result.callingReady ? GRN : RED}${result.callingReady}${RST}`);
+  }
+  if (Array.isArray(result?.checks)) {
+    for (const ck of result.checks) {
+      console.log(`  ${ck?.ok ? GRN + 'PASS' : RED + 'FAIL'}${RST} ${ck?.name ?? ''}${ck?.message ? ': ' + ck.message : ''}`);
+    }
+  }
+  console.log('');
   if (!result?.success) process.exitCode = 1;
 }
 
@@ -121,7 +133,7 @@ export const teamsPhoneCommand = {
     })
     .command({
       command:  'test',
-      describe: 'Test the Teams Phone connection by creating/renewing the Graph /communications/calls subscription',
+      describe: 'Run the Teams Phone readiness checks (consent, resource account, Graph reachability) and print each check',
       builder:  yy => yy,
       handler:  testHandler,
     })

package/lib/commands/visitor-monitor.js

@@ -0,0 +1,61 @@
+import { messagingGet, messagingPut } from '../api.js';
+import { runCommand } from '../run.js';
+
+// ── velaro visitor-monitor ────────────────────────────────────────────────────
+// Visitor Monitor view preferences (per user) and site settings. siteId is applied
+// server-side from the JWT (see cli/lib/api.js messagingRequest), never a CLI arg.
+//
+// Backend contract: velaro-messaging VisitorController (PR 2798)
+//   GET/PUT Visitor/preferences  { columns[], groupBy, sortBy, sortDir, regionGrouping }
+//   GET/PUT Visitor/settings     { storeLocationDetail?, activeWindowMinutes? }  (window 5-240; >30 needs Advanced plan, else 403 feature_not_in_plan)
+//   GET     Visitor/active       live sessions + activeWindowMinutes + locationDetailEnabled
+
+const show = data => console.log(JSON.stringify(data, null, 2));
+
+export const visitorMonitorCommand = {
+  command:  'visitor-monitor <subcommand>',
+  describe: 'Visitor Monitor preferences, settings and live visitors',
+  builder:  yargs => yargs
+    .command({
+      command:  'active',
+      describe: 'List live visitors',
+      handler:  runCommand(async () => show(await messagingGet('/Visitor/active'))),
+    })
+    .command({
+      command:  'preferences <action>',
+      describe: 'get or set your saved Visitor Monitor view',
+      builder:  y => y
+        .positional('action', { choices: ['get', 'set'] })
+        .option('columns',         { type: 'string', describe: 'Comma-separated column keys (set)' })
+        .option('group-by',        { type: 'string', describe: 'Group by key (set)' })
+        .option('sort-by',         { type: 'string', describe: 'Sort key (set)' })
+        .option('sort-dir',        { type: 'string', choices: ['asc', 'desc'], describe: 'Sort direction (set)' })
+        .option('region-grouping', { type: 'string', describe: 'region or city (set)' }),
+      handler:  runCommand(async argv => {
+        if (argv.action === 'get') return show(await messagingGet('/Visitor/preferences'));
+        const body = {};
+        if (argv.columns !== undefined) body.columns = String(argv.columns).split(',').map(s => s.trim()).filter(Boolean);
+        if (argv['group-by'] !== undefined) body.groupBy = argv['group-by'];
+        if (argv['sort-by'] !== undefined) body.sortBy = argv['sort-by'];
+        if (argv['sort-dir'] !== undefined) body.sortDir = argv['sort-dir'];
+        if (argv['region-grouping'] !== undefined) body.regionGrouping = argv['region-grouping'];
+        show(await messagingPut('/Visitor/preferences', body));
+      }),
+    })
+    .command({
+      command:  'settings <action>',
+      describe: 'get or set site Visitor Monitor settings',
+      builder:  y => y
+        .positional('action', { choices: ['get', 'set'] })
+        .option('store-location-detail', { type: 'boolean', describe: 'Store region/city + truncated IP (Advanced plan) (set)' })
+        .option('active-window-minutes', { type: 'number', describe: 'Minutes visitors stay listed, 5-240 (above 30 needs Advanced) (set)' }),
+      handler:  runCommand(async argv => {
+        if (argv.action === 'get') return show(await messagingGet('/Visitor/settings'));
+        const body = {};
+        if (argv['store-location-detail'] !== undefined) body.storeLocationDetail = argv['store-location-detail'];
+        if (argv['active-window-minutes'] !== undefined) body.activeWindowMinutes = argv['active-window-minutes'];
+        show(await messagingPut('/Visitor/settings', body));
+      }),
+    })
+    .demandCommand(1),
+};

package/lib/log-search.js

@@ -207,3 +207,46 @@ export function describeRawMeta(resp) {
   const bestEffort = resp.exact === false ? ' exact=false (answered from the best-effort search index: it can lag and misses text that starts mid-word, so treat counts as a floor, not exact)' : '';
   return `searchPath=${resp.searchPath} scannedRows=${resp.scannedRows} truncated=${t}${t ? ' (NOT proof of absence; continue with nextCursor or narrow the window)' : ''}${bestEffort}${resp.nextCursor ? ' nextCursor=present' : ''}`;
 }
+
+// ── Time window + raw query building (shared by server.js and staff-server.js velaro_logs_search) ──
+// Bug fixed 2026-10-21: the tool only honored `last` and silently ignored from/to, so an explicit
+// historical range returned the newest entries instead. from/to accept an ISO timestamp or a
+// relative duration (30m, 2h, 1d = that long ago). `to` defaults to now, `from` to to - last (2h).
+const DUR_RE = /^(\d+)(m|h|d)$/i;
+const durMs = (s) => {
+  const m = DUR_RE.exec(String(s).trim());
+  const n = parseInt(m[1], 10);
+  const u = m[2].toLowerCase();
+  return u === 'm' ? n * 60000 : u === 'h' ? n * 3600000 : n * 86400000;
+};
+function parseWhen(label, v, nowMs) {
+  const s = String(v).trim();
+  if (DUR_RE.test(s)) return new Date(nowMs - durMs(s));
+  const d = new Date(s);
+  if (Number.isNaN(d.getTime())) throw new Error(`Invalid ${label} "${v}": use an ISO timestamp (2026-10-20T00:00:00Z) or a relative duration like 2h.`);
+  return d;
+}
+export function resolveLogWindow(args = {}, nowMs = Date.now()) {
+  const given = (v) => v !== undefined && v !== null && String(v).trim() !== '';
+  const to = given(args.to) ? parseWhen('to', args.to, nowMs) : new Date(nowMs);
+  const lastMs = DUR_RE.test(String(args.last ?? '').trim()) ? durMs(args.last) : 2 * 3600000;
+  const from = given(args.from) ? parseWhen('from', args.from, nowMs) : new Date(to.getTime() - lastMs);
+  if (from.getTime() >= to.getTime()) throw new Error(`Invalid window: from (${from.toISOString()}) must be before to (${to.toISOString()}).`);
+  return { from, to };
+}
+
+// Query string for GET /superadmin/logs/search (same params as /internal/logs/search).
+export function buildRawLogQuery(args, from, to) {
+  const params = new URLSearchParams({ from: from.toISOString(), to: to.toISOString(), take: String(args.take ?? 50) });
+  if (args.q)             params.set('q',             args.q);
+  if (args.level)         params.set('level',         String(args.level).toUpperCase());
+  if (args.logger)        params.set('logger',        args.logger);
+  if (args.integration)   params.set('integration',   args.integration);
+  if (args.siteId)        params.set('siteId',        String(args.siteId));
+  if (args.source)        params.set('source',        args.source);
+  if (args.platform)      params.set('platform',      args.platform);
+  if (args.environment)   params.set('environment',   args.environment);
+  if (args.correlationId) params.set('correlationId', args.correlationId);
+  if (args.regex)         params.set('regex',         'true');
+  return params.toString();
+}