@velaro/cli 1.2.0 → 1.4.9

package/lib/commands/agent.js

@@ -1,50 +1,204 @@
-import { get, post }  from '../api.js';
-import { runCommand }  from '../run.js';
-
-const VALID_STATUSES = ['Available', 'Away', 'Offline'];
-
-export const agentCommand = {
-  command:  'agent <subcommand>',
-  describe: 'View and manage agents',
-  builder:  (yargs) => yargs
-    .command({
-      command:  'list',
-      describe: 'List agents and their current availability',
-      handler:  runCommand(async () => {
-        const [agents, teams] = await Promise.all([
-          get('/Users/List'),
-          get('/Teams/List'),
-        ]);
-
-        const teamMap = Object.fromEntries(teams.map(t => [t.id, t.name]));
-
-        if (!agents.length) { console.log('No agents found.'); return; }
-
-        const rows = agents.map(a => ({
-          id:     `[${a.id}]`,
-          status: (a.status ?? 'Offline').padEnd(9),
-          name:   a.displayName || `${a.firstName} ${a.lastName}`.trim() || a.email,
-          teams:  (a.teamIds ?? []).map(id => teamMap[id] ?? `team ${id}`).join(', ') || '—',
-        }));
-
-        const idW = Math.max(...rows.map(r => r.id.length));
-
-        for (const r of rows) {
-          console.log(`${r.id.padStart(idW)}  ${r.status}  ${r.name.padEnd(30)}  ${r.teams}`);
-        }
-        console.log(`\n${rows.length} agent(s)`);
-      }),
-    })
-    .command({
-      command:  'set-status',
-      describe: 'Set an agent\'s availability status (admin only)',
-      builder:  (y) => y
-        .option('id',     { type: 'number', demandOption: true, describe: 'Agent user ID' })
-        .option('status', { type: 'string', demandOption: true, describe: 'Available | Away | Offline', choices: VALID_STATUSES }),
-      handler: runCommand(async (argv) => {
-        await post('/UserStatus/admin', { userId: argv.id, status: argv.status });
-        console.log(`Agent ${argv.id} set to ${argv.status}.`);
-      }),
-    })
-    .demandCommand(1, 'Specify a subcommand: list | set-status'),
-};
+import { get, post }  from '../api.js';
+import { runCommand }  from '../run.js';
+
+const VALID_STATUSES = ['Available', 'Away', 'Offline'];
+
+const MISSED_REASON_LABELS = {
+  NoAgentsOnline:         'No agents online',
+  AgentsNotAvailable:     'Agents not available',
+  AgentsBusy:             'Agents at capacity',
+  OutOfSchedule:          'Outside business hours',
+  TimedOut:               'Queue timeout',
+  Abandoned:              'Visitor abandoned',
+  Rejected:               'Agent rejected',
+  PreChatSurveyAbandoned: 'Pre-chat abandoned',
+  BotTransferAbandoned:   'Bot transfer abandoned',
+};
+
+function fmtSec(s) {
+  if (s == null) return '—';
+  if (s < 60)   return `${s}s`;
+  if (s < 3600) return `${Math.round(s / 60)}m`;
+  const h = Math.floor(s / 3600), m = Math.round((s % 3600) / 60);
+  return m > 0 ? `${h}h ${m}m` : `${h}h`;
+}
+
+export const agentCommand = {
+  command:  'agent <subcommand>',
+  describe: 'View and manage agents',
+  builder:  (yargs) => yargs
+    .command({
+      command:  'list',
+      describe: 'List agents and their current availability',
+      handler:  runCommand(async () => {
+        const [agents, teams] = await Promise.all([
+          get('/Users/List'),
+          get('/Teams/List'),
+        ]);
+
+        const teamMap = Object.fromEntries(teams.map(t => [t.id, t.name]));
+
+        if (!agents.length) { console.log('No agents found.'); return; }
+
+        const rows = agents.map(a => ({
+          id:     `[${a.id}]`,
+          status: (a.status ?? 'Offline').padEnd(9),
+          name:   a.displayName || `${a.firstName} ${a.lastName}`.trim() || a.email,
+          teams:  (a.teamIds ?? []).map(id => teamMap[id] ?? `team ${id}`).join(', ') || '—',
+        }));
+
+        const idW = Math.max(...rows.map(r => r.id.length));
+
+        for (const r of rows) {
+          console.log(`${r.id.padStart(idW)}  ${r.status}  ${r.name.padEnd(30)}  ${r.teams}`);
+        }
+        console.log(`\n${rows.length} agent(s)`);
+      }),
+    })
+    .command({
+      command:  'set-status',
+      describe: 'Set an agent\'s availability status (admin only)',
+      builder:  (y) => y
+        .option('id',     { type: 'number', demandOption: true, describe: 'Agent user ID' })
+        .option('status', { type: 'string', demandOption: true, describe: 'Available | Away | Offline', choices: VALID_STATUSES }),
+      handler: runCommand(async (argv) => {
+        await post('/UserStatus/admin', { userId: argv.id, status: argv.status });
+        console.log(`Agent ${argv.id} set to ${argv.status}.`);
+      }),
+    })
+    .command({
+      command:  'missed-chats',
+      describe: 'Show recent missed chats with routing snapshots (why each chat was missed)',
+      builder:  (y) => y
+        .option('start',   { type: 'string', describe: 'Start date, e.g. 2026-06-01 (default: 7 days ago)' })
+        .option('end',     { type: 'string', describe: 'End date, e.g. 2026-06-15 (default: now)' })
+        .option('reason',  { type: 'string', describe: 'Filter: NoAgentsOnline | AgentsNotAvailable | AgentsBusy | OutOfSchedule | TimedOut | Abandoned | Rejected' })
+        .option('team-id', { type: 'number', describe: 'Filter by team ID' })
+        .option('site-id', { type: 'number', describe: 'SuperAdmin only — run for a specific customer site' }),
+      handler: runCommand(async (argv) => {
+        const qs = new URLSearchParams();
+        if (argv.start)  qs.set('start',  argv.start);
+        if (argv.end)    qs.set('end',    argv.end);
+        if (argv.reason) qs.set('reason', argv.reason);
+        if (argv['team-id']) qs.set('teamId', String(argv['team-id']));
+        if (argv['site-id']) qs.set('siteId', String(argv['site-id']));
+
+        const r = await get(`/CallCenterAnalytics/MissedChatDiagnostics?${qs}`);
+
+        if (!r?.rows?.length) {
+          console.log('No missed chats in this period.');
+          return;
+        }
+
+        console.log(`Missed chats: ${r.total}  (${r.dateRange?.start?.slice(0,10)} – ${r.dateRange?.end?.slice(0,10)})\n`);
+
+        // Summary by reason
+        const byReason = {};
+        for (const c of r.rows) byReason[c.missedReason] = (byReason[c.missedReason] ?? 0) + 1;
+        for (const [reason, count] of Object.entries(byReason).sort((a, b) => b[1] - a[1])) {
+          console.log(`  ${String(count).padStart(4)}  ${MISSED_REASON_LABELS[reason] ?? reason}`);
+        }
+
+        console.log('\nRecent missed chats (most recent first):');
+        for (const c of r.rows.slice(0, 20)) {
+          const snap = c.routingSnapshot;
+          const ts   = new Date(c.startTimestamp).toISOString().replace('T', ' ').slice(0, 16);
+          const reason = MISSED_REASON_LABELS[c.missedReason] ?? c.missedReason;
+          console.log(`\n  [${c.conversationId}] ${ts} UTC — ${reason}`);
+          if (c.teamName)          console.log(`    Team: ${c.teamName}`);
+          if (c.queueWaitSeconds)  console.log(`    Queue wait: ${fmtSec(c.queueWaitSeconds)}`);
+          if (c.assignedAgentName) console.log(`    Offered to: ${c.assignedAgentName}`);
+          if (snap) {
+            console.log(`    At miss time: ${snap.agentsOnline ?? '?'} online, ${snap.agentsAvailable ?? '?'} available, ${snap.agentsBusy ?? '?'} busy`);
+            if (snap.missDetail)   console.log(`    Detail: ${snap.missDetail}`);
+          }
+        }
+        if (r.total > 20) console.log(`\n  ... and ${r.total - 20} more (use --start/--end to narrow)`);
+      }),
+    })
+    .command({
+      command:  'availability',
+      describe: 'Show per-agent status history and connectivity events',
+      builder:  (y) => y
+        .option('start',    { type: 'string', describe: 'Start date, e.g. 2026-06-01 (default: 7 days ago)' })
+        .option('end',      { type: 'string', describe: 'End date, e.g. 2026-06-15 (default: now). Max 31 days.' })
+        .option('agent-id', { type: 'number', describe: 'Filter to a specific agent (WorkspaceUser ID)' })
+        .option('site-id',  { type: 'number', describe: 'SuperAdmin only — run for a specific customer site' }),
+      handler: runCommand(async (argv) => {
+        const qs = new URLSearchParams();
+        if (argv.start)      qs.set('start',   argv.start);
+        if (argv.end)        qs.set('end',     argv.end);
+        if (argv['agent-id']) qs.set('agentId', String(argv['agent-id']));
+        if (argv['site-id'])  qs.set('siteId',  String(argv['site-id']));
+
+        const r = await get(`/CallCenterAnalytics/AgentAvailability?${qs}`);
+
+        if (!r?.agents?.length) {
+          console.log('No agent activity data in this period.');
+          return;
+        }
+
+        console.log(`Agent availability (${r.dateRange?.start?.slice(0,10)} – ${r.dateRange?.end?.slice(0,10)})\n`);
+
+        for (const a of r.agents) {
+          const s = a.summary;
+          const parts = [];
+          if (s.availableSeconds > 0) parts.push(`Available ${fmtSec(s.availableSeconds)}`);
+          if (s.awaySeconds > 0)      parts.push(`Away ${fmtSec(s.awaySeconds)}`);
+          if (s.offlineSeconds > 0)   parts.push(`Offline ${fmtSec(s.offlineSeconds)}`);
+          if (s.onCallSeconds > 0)    parts.push(`OnCall ${fmtSec(s.onCallSeconds)}`);
+
+          const alerts = [];
+          if (s.disconnectEvents > 0) alerts.push(`${s.disconnectEvents} disconnect(s)`);
+          if (s.tabHiddenEvents > 0)  alerts.push(`${s.tabHiddenEvents} tab hidden`);
+
+          console.log(`  ${a.agentName}${a.email ? ` <${a.email}>` : ''}`);
+          console.log(`    ${parts.join(' | ') || 'no status data'}${alerts.length ? '  ⚠ ' + alerts.join(', ') : ''}`);
+
+          // Show last 5 status transitions
+          if (a.statusLog?.length) {
+            for (const e of a.statusLog.slice(-5)) {
+              const ts = new Date(e.startedAt).toISOString().slice(11, 16);
+              console.log(`    → ${e.status.padEnd(9)} ${ts} UTC  (${e.trigger}${e.durationSeconds != null ? ', ' + fmtSec(e.durationSeconds) : ''})`);
+            }
+          }
+
+          // Show recent disconnect events
+          const disconnects = (a.connectionEvents ?? []).filter(e => e.event?.toLowerCase().includes('disconnect'));
+          if (disconnects.length) {
+            console.log(`    Disconnects: ${disconnects.map(e => new Date(e.occurredAt).toISOString().slice(11,16) + ' UTC').join(', ')}`);
+          }
+          console.log('');
+        }
+      }),
+    })
+    .command({
+      command:  'ai-summary',
+      describe: 'Generate a plain-English AI advisory for agent connectivity (max 7-day window, enterprise feature)',
+      builder:  (y) => y
+        .option('start',   { type: 'string', describe: 'Start date, e.g. 2026-06-10 (max 7 days before end)' })
+        .option('end',     { type: 'string', describe: 'End date, e.g. 2026-06-17 (default: today)' })
+        .option('site-id', { type: 'number', describe: 'SuperAdmin only — run for a specific customer site' }),
+      handler: runCommand(async (argv) => {
+        const qs = new URLSearchParams();
+        if (argv.start)      qs.set('start',  argv.start);
+        if (argv.end)        qs.set('end',    argv.end);
+        if (argv['site-id']) qs.set('siteId', String(argv['site-id']));
+
+        console.log('Generating AI advisory (this may take a few seconds)…\n');
+        const r = await post(`/CallCenterAnalytics/AiSummary${qs.toString() ? '?' + qs : ''}`, {});
+
+        if (!r?.summary) {
+          console.log('No summary returned. Check that the date range contains data.');
+          return;
+        }
+
+        console.log(`Agent Connectivity AI Advisory`);
+        console.log(`Period: ${r.dateRange?.start?.slice(0,10)} – ${r.dateRange?.end?.slice(0,10)}`);
+        console.log(`Data: ${r.dataPoints?.missedCount ?? '?'} missed chats, ${r.dataPoints?.agentCount ?? '?'} agents analyzed`);
+        console.log('─'.repeat(60));
+        console.log(r.summary);
+      }),
+    })
+    .demandCommand(1, 'Specify a subcommand: list | set-status | missed-chats | availability | ai-summary'),
+};

package/lib/commands/ai-config.js

@@ -0,0 +1,193 @@
+import fs                 from 'node:fs';
+import { messagingGet, messagingPost, messagingPut } from '../api.js';
+import { runCommand }     from '../run.js';
+
+// messagingGet() authenticates with the caller's own user JWT, scoped to the caller's site — fine
+// for the subcommands above. staff-list below hits SupportTools/sites/{siteId}/ai-configs instead,
+// which is gated by staff auth (Velaro staff JWT or the internal vel_live_* service key), never the
+// caller's site JWT, so it can read ANY site's AI config without needing that site's own login.
+
+const get  = messagingGet;
+const post = messagingPost;
+
+export const aiConfigCommand = {
+  command:  'ai-config <subcommand>',
+  describe: 'Manage AI configurations (bot prompts, channel overrides)',
+  builder:  (yargs) =>
+    yargs
+      .command(aiConfigListCommand)
+      .command(aiConfigGetCommand)
+      .command(aiConfigCreateCommand)
+      .command(aiConfigSetChannelOverrideCommand)
+      .command(aiConfigListChannelOverridesCommand)
+      .command(aiConfigStaffListCommand)
+      .demandCommand(1, 'Specify a subcommand: list, get, create, set-channel-override, list-channel-overrides, staff-list'),
+  handler: () => {},
+};
+
+// ── list ──────────────────────────────────────────────────────────────────────
+
+const aiConfigListCommand = {
+  command:  'list',
+  describe: 'List all AI configurations on the current site',
+  handler:  runCommand(async () => {
+    const configs = await get('/AIConfiguration/list');
+    const rows = configs ?? [];
+    if (!rows.length) { console.log('No AI configurations found.'); return; }
+
+    const idW   = Math.max(...rows.map(c => String(c.id).length + 2));
+    const nameW = Math.max('name'.length, ...rows.map(c => (c.name ?? '').length));
+
+    console.log(`\n${'id'.padStart(idW)}  ${'name'.padEnd(nameW)}  status   model`);
+    console.log(`${'-'.repeat(idW)}  ${'-'.repeat(nameW)}  -------  -----`);
+    for (const c of rows) {
+      const id    = `[${c.id}]`.padStart(idW);
+      const name  = (c.name ?? '').padEnd(nameW);
+      const stat  = (c.status ?? '—').padEnd(7);
+      console.log(`${id}  ${name}  ${stat}  ${c.aiModel ?? '—'}`);
+    }
+    console.log(`\n${rows.length} configuration(s)`);
+  }),
+};
+
+// ── get ───────────────────────────────────────────────────────────────────────
+
+const aiConfigGetCommand = {
+  command:  'get <id>',
+  describe: 'Show one AI configuration',
+  builder:  (y) => y.positional('id', { type: 'number', describe: 'AI configuration ID' }),
+  handler:  runCommand(async (argv) => {
+    const all = (await get('/AIConfiguration/list')) ?? [];
+    const c   = all.find(x => x.id === argv.id);
+    if (!c) { console.error(`AI configuration ${argv.id} not found.`); process.exit(1); }
+    console.log(`\n[${c.id}] ${c.name}`);
+    console.log(`  Status:      ${c.status ?? '—'}`);
+    console.log(`  Model:       ${c.aiModel ?? '—'}`);
+    console.log(`  Language:    ${c.language ?? '—'}`);
+    console.log(`  Tone:        ${c.tone ?? '—'}`);
+    console.log(`  Index:       ${c.indexName ?? '—'}`);
+    if (c.prompt) {
+      console.log(`\n  Prompt:`);
+      console.log(c.prompt.split('\n').map(l => '    ' + l).join('\n'));
+    }
+  }),
+};
+
+// ── create ────────────────────────────────────────────────────────────────────
+
+const aiConfigCreateCommand = {
+  command:  'create',
+  describe: 'Create an AI configuration. Provide --name + --prompt, or --file path/to/config.json',
+  builder:  (y) =>
+    y
+      .option('name',        { type: 'string',  describe: 'Configuration name' })
+      .option('prompt',      { type: 'string',  describe: 'System prompt text' })
+      .option('model',       { type: 'string',  describe: 'Model (e.g. gpt-4o-mini, claude-haiku-4-5)' })
+      .option('tone',        { type: 'string',  describe: 'Tone (e.g. friendly, professional)' })
+      .option('language',    { type: 'string',  default: 'en', describe: 'Language code' })
+      .option('reply-length',{ type: 'string',  describe: 'Reply length (e.g. short, medium, long)' })
+      .option('index',       { type: 'string',  describe: 'KB index name to use for retrieval' })
+      .option('temperature', { type: 'number',  describe: 'Sampling temperature (0–2)' })
+      .option('file',        { type: 'string',  describe: 'JSON file with AIConfigurationViewModel body (overrides flags)' }),
+  handler:  runCommand(async (argv) => {
+    let body;
+    if (argv.file) {
+      body = JSON.parse(fs.readFileSync(argv.file, 'utf8'));
+      if (body.id == null) body.id = 0;
+    } else {
+      if (!argv.name) { console.error('--name is required (or use --file).'); process.exit(1); }
+      if (!argv.prompt) { console.error('--prompt is required (or use --file).'); process.exit(1); }
+      body = {
+        id:           0,
+        name:         argv.name,
+        prompt:       argv.prompt,
+        aiModel:      argv.model ?? null,
+        tone:         argv.tone ?? null,
+        language:     argv.language,
+        replyLength:  argv['reply-length'] ?? null,
+        indexName:    argv.index ?? null,
+        temperature:  argv.temperature ?? null,
+        dataUrls:     [],
+      };
+    }
+
+    const result = await post('/AIConfiguration', body);
+    const id = result?.id ?? result;
+    console.log(`AI configuration created: ${id}`);
+    console.log(`View: velaro ai-config get ${id}`);
+  }),
+};
+
+// ── channel overrides ─────────────────────────────────────────────────────────
+
+const CHANNELS = ['Web', 'TwilioSms', 'TwilioIvr', 'WhatsApp', 'Facebook', 'Twitter', 'Email', 'Apple'];
+const MODES    = ['additive', 'replace', 'suppress'];
+
+const aiConfigListChannelOverridesCommand = {
+  command:  'list-channel-overrides <id>',
+  describe: 'List channel prompt overrides on an AI configuration',
+  builder:  (y) => y.positional('id', { type: 'number', describe: 'AI configuration ID' }),
+  handler:  runCommand(async (argv) => {
+    const list = await get(`/AIConfiguration/${argv.id}/channel-overrides`);
+    if (!list?.length) { console.log('No channel overrides set.'); return; }
+    console.log(`\nchannel        mode       text`);
+    console.log(`-------------  ---------  ----`);
+    for (const o of list) {
+      const ch   = (o.conversationSource ?? '').padEnd(13);
+      const mode = (o.mode ?? '').padEnd(9);
+      const txt  = (o.overrideText ?? '').slice(0, 60);
+      console.log(`${ch}  ${mode}  ${txt}`);
+    }
+    console.log(`\n${list.length} override(s)`);
+  }),
+};
+
+// ── staff-list (SupportTools, service-authed, any site) ───────────────────────
+
+const aiConfigStaffListCommand = {
+  command:  'staff-list <siteId>',
+  describe: 'Velaro staff only — read AI configurations for ANY site by ID (including IndexDocumentCount), without needing that site\'s own user JWT.',
+  builder:  (y) => y.positional('siteId', { type: 'number', describe: 'Site ID to inspect' }),
+  handler:  runCommand(async (argv) => {
+    const data = await get(`/SupportTools/sites/${argv.siteId}/ai-configs`);
+    const rows = data?.configs ?? [];
+    if (!rows.length) { console.log(`No AI configurations found for site ${argv.siteId}.`); return; }
+
+    const idW   = Math.max(...rows.map(c => String(c.id).length + 2));
+    const nameW = Math.max('name'.length, ...rows.map(c => (c.name ?? '').length));
+
+    console.log(`\nSite ${argv.siteId} — ${rows.length} AI configuration(s)\n`);
+    console.log(`${'id'.padStart(idW)}  ${'name'.padEnd(nameW)}  status   model         index                docs`);
+    console.log(`${'-'.repeat(idW)}  ${'-'.repeat(nameW)}  -------  ------------  -------------------  ----`);
+    for (const c of rows) {
+      const id    = `[${c.id}]`.padStart(idW);
+      const name  = (c.name ?? '').padEnd(nameW);
+      const stat  = (c.status ?? '—').padEnd(7);
+      const model = (c.aiModel ?? '—').padEnd(12);
+      const index = (c.indexName ?? '—').padEnd(19);
+      console.log(`${id}  ${name}  ${stat}  ${model}  ${index}  ${c.indexDocumentCount ?? 0}`);
+    }
+  }),
+};
+
+const aiConfigSetChannelOverrideCommand = {
+  command:  'set-channel-override <id>',
+  describe: 'Add or replace a channel override on an AI configuration',
+  builder:  (y) =>
+    y
+      .positional('id',   { type: 'number', describe: 'AI configuration ID' })
+      .option('channel',  { type: 'string', choices: CHANNELS, demandOption: true, describe: 'Conversation source (PascalCase)' })
+      .option('mode',     { type: 'string', choices: MODES,    demandOption: true, describe: 'Override mode' })
+      .option('text',     { type: 'string', describe: 'Override prompt text (omit for suppress mode)' }),
+  handler:  runCommand(async (argv) => {
+    if (argv.mode !== 'suppress' && !argv.text) {
+      console.error('--text is required for additive/replace modes.');
+      process.exit(1);
+    }
+    const existing = (await get(`/AIConfiguration/${argv.id}/channel-overrides`)) ?? [];
+    const others   = existing.filter(o => o.conversationSource !== argv.channel);
+    const next     = [...others, { conversationSource: argv.channel, mode: argv.mode, overrideText: argv.text ?? '' }];
+    await messagingPut(`/AIConfiguration/${argv.id}/channel-overrides`, next);
+    console.log(`Channel override set: ai-config=${argv.id} channel=${argv.channel} mode=${argv.mode}`);
+  }),
+};

package/lib/commands/ai-models.js

@@ -0,0 +1,159 @@
+import { getCredentials }   from '../api.js';
+import { readConfig, ENVS } from '../config.js';
+
+// -- helpers -------------------------------------------------------------------
+
+const RESET  = '\x1b[0m';
+const DIM    = '\x1b[2m';
+const BOLD   = '\x1b[1m';
+const GREEN  = '\x1b[32m';
+const YEL    = '\x1b[33m';
+const CYN    = '\x1b[36m';
+
+async function getMsgBase(argv) {
+  const cfg = readConfig();
+  const env = argv.env || cfg.env || 'staging';
+  return cfg.envs?.[env]?.messagingApiBase ?? ENVS[env]?.messagingApiBase
+    ?? 'https://velaro-messaging-api-staging.azurewebsites.net';
+}
+
+async function requireAdmin(creds) {
+  if (creds.siteId !== 1032) {
+    console.error('velaro ai-models is only available to Velaro staff (site 1032).');
+    process.exit(1);
+  }
+}
+
+async function callResolver(argv, path, opts = {}) {
+  const creds   = await getCredentials();
+  await requireAdmin(creds);
+  const msgBase = await getMsgBase(argv);
+
+  const res = await fetch(`${msgBase}/superadmin/ai-models/${path}`, {
+    method: opts.method ?? 'GET',
+    headers: {
+      Authorization:       `Bearer ${creds.velaroToken}`,
+      'X-Internal-SiteId': String(creds.siteId),
+      ...(opts.body ? { 'Content-Type': 'application/json' } : {}),
+    },
+    body: opts.body ? JSON.stringify(opts.body) : undefined,
+    signal: AbortSignal.timeout(20000),
+  });
+
+  if (!res.ok) {
+    const body = await res.text().catch(() => '');
+    console.error(`HTTP ${res.status}: ${body}`);
+    process.exit(1);
+  }
+  return res.json();
+}
+
+// -- resolver-map (the full "what is everything actually using" dashboard) ----
+
+async function showResolverMap(argv) {
+  const data = await callResolver(argv, 'resolver-map');
+  const roles = argv.role
+    ? data.roles.filter(r => r.role === argv.role)
+    : data.roles;
+
+  if (argv.role && !roles.length) {
+    console.error(`Unknown role '${argv.role}'. Known roles: ${data.roles.map(r => r.role).join(', ')}`);
+    process.exit(1);
+  }
+
+  console.log(`\n${BOLD}AI Model Resolver, ${argv.role ? `role: ${argv.role}` : 'all roles'}${RESET}\n`);
+  for (const r of roles) {
+    console.log(`${CYN}${r.role}${RESET}  ${DIM}(code default: ${r.codeDefault})${RESET}`);
+    console.log(`  global:  ${r.globalDefault ?? `${DIM}(none, falls back to code default)${RESET}`}`);
+    const activeTiers = r.tierDefaults.filter(t => t.model);
+    if (activeTiers.length) {
+      for (const t of activeTiers) console.log(`  tier:    ${t.tier.padEnd(12)} -> ${t.model}`);
+    }
+    if (r.siteOverrideCount > 0) {
+      console.log(`  ${YEL}site overrides (${r.siteOverrideCount}):${RESET}`);
+      for (const o of r.siteOverrides) console.log(`    site ${o.siteId}: ${o.model}  ${DIM}(${o.updatedBy}, ${o.updatedAt})${RESET}`);
+    }
+    console.log('');
+  }
+
+  if (data.unrecognizedTierRows?.length) {
+    console.log(`${YEL}WARNING: unrecognized tier rows (legacy format, should self-migrate on next deploy):${RESET}`);
+    for (const row of data.unrecognizedTierRows) console.log(`  ${row.key} = ${row.value}`);
+    console.log('');
+  }
+}
+
+// -- effective (what a specific site actually resolves to, per role) ----------
+
+async function showEffective(argv) {
+  if (!argv.site) {
+    console.error('--site is required, e.g. velaro ai-models effective --site 1032');
+    process.exit(1);
+  }
+  const data = await callResolver(argv, `site/${argv.site}/effective`);
+  console.log(`\n${BOLD}Effective models, site ${argv.site}${RESET}\n`);
+  for (const r of data) {
+    const marker = r.isOverridden ? `${GREEN}[override]${RESET}` : `${DIM}[default]  ${RESET}`;
+    console.log(`${marker} ${r.role.padEnd(28)} ${r.model}${r.isOverridden ? `${DIM}  (code default: ${r.codeDefault})${RESET}` : ''}`);
+  }
+  console.log(`\n${DIM}[override] = overridden from code default   [default] = using code default${RESET}\n`);
+}
+
+// -- set / clear a role-scoped tier default ------------------------------------
+
+async function setTierDefault(argv) {
+  const data = await callResolver(argv, `tier/${argv.tier}/${argv.role}`, {
+    method: 'POST',
+    body: { model: argv.model, updatedBy: 'velaro-cli' },
+  });
+  console.log(`\n${GREEN}OK${RESET} Tier '${data.tier}' role '${data.role}' set to ${data.model}\n`);
+}
+
+async function clearTierDefault(argv) {
+  await callResolver(argv, `tier/${argv.tier}/${argv.role}`, { method: 'DELETE' });
+  console.log(`\n${GREEN}OK${RESET} Cleared tier '${argv.tier}' role '${argv.role}'. Reverts to global default.\n`);
+}
+
+// -- command export -------------------------------------------------------------
+
+export const aiModelsCommand = {
+  command:  'ai-models <subcommand>',
+  describe: 'AI model resolver diagnostics (Velaro staff only)',
+  builder: yargs => yargs
+    .command({
+      command:  'resolver [role]',
+      describe: 'Show the full resolver map: code default, global default, tier defaults, and every site override, per role',
+      builder:  y => y
+        .positional('role', { describe: 'Show only this role (e.g. ivr, chatbot, skill_synthesis)', type: 'string' })
+        .option('env', { describe: 'staging or prod', type: 'string' }),
+      handler: showResolverMap,
+    })
+    .command({
+      command:  'effective',
+      describe: 'Show what a specific site actually resolves to for every role',
+      builder:  y => y
+        .option('site', { describe: 'Site ID', type: 'number', demandOption: true })
+        .option('env',  { describe: 'staging or prod', type: 'string' }),
+      handler: showEffective,
+    })
+    .command({
+      command:  'set-tier <tier> <role> <model>',
+      describe: 'Set a role-scoped tier default, e.g. velaro ai-models set-tier enterprise ivr claude-sonnet-4-6',
+      builder:  y => y
+        .positional('tier',  { describe: 'starter, professional, or enterprise', type: 'string' })
+        .positional('role',  { describe: 'e.g. ivr, chatbot, skill_synthesis', type: 'string' })
+        .positional('model', { describe: 'Model alias/ID', type: 'string' })
+        .option('env', { describe: 'staging or prod', type: 'string' }),
+      handler: setTierDefault,
+    })
+    .command({
+      command:  'clear-tier <tier> <role>',
+      describe: 'Clear a role-scoped tier default, reverting to the global default',
+      builder:  y => y
+        .positional('tier', { describe: 'starter, professional, or enterprise', type: 'string' })
+        .positional('role', { describe: 'e.g. ivr, chatbot, skill_synthesis', type: 'string' })
+        .option('env', { describe: 'staging or prod', type: 'string' }),
+      handler: clearTierDefault,
+    })
+    .demandCommand(1, 'Specify a subcommand: resolver, effective, set-tier, or clear-tier'),
+};