@velaro/cli 1.4.69 → 1.4.71

package/bin/velaro.js

@@ -41,6 +41,7 @@ import { bookingCommand } from '../lib/commands/booking.js';
 import { reportCommand }       from '../lib/commands/report.js';
 import { scheduleAdherenceCommand } from '../lib/commands/schedule-adherence.js';
 import { experienceImpactCommand } from '../lib/commands/experience-impact.js';
+import { reportExplainCommand } from '../lib/commands/report-explain.js';
 import { conversationEfficiencyCommand } from '../lib/commands/conversation-efficiency.js';
 import { dbCommand } from '../lib/commands/db.js';
 import { focusCommand }       from '../lib/commands/focus.js';
@@ -51,6 +52,7 @@ import { notionCommand }        from '../lib/commands/notion.js';
 import { callrailCommand }      from '../lib/commands/callrail.js';
 import { emailCampaignCommand } from '../lib/commands/email-campaign.js';
 import { outboundActivityCommand } from '../lib/commands/outbound-activity.js';
+import { klaviyoMigrationCommand } from '../lib/commands/klaviyo-migration.js';
 import { telephonyCommand }     from '../lib/commands/telephony.js';
 import { teamsPhoneCommand }    from '../lib/commands/teams-phone.js';
 import { teamsCommand }         from '../lib/commands/teams.js';
@@ -143,6 +145,7 @@ await yargs(hideBin(process.argv))
   .command(conversationEfficiencyCommand)
   .command(scheduleAdherenceCommand)
   .command(experienceImpactCommand)
+  .command(reportExplainCommand)
   .command(dbCommand)
   .command(focusCommand)
   .command(automationDraftCommand)
@@ -152,6 +155,7 @@ await yargs(hideBin(process.argv))
   .command(callrailCommand)
   .command(emailCampaignCommand)
   .command(outboundActivityCommand)
+  .command(klaviyoMigrationCommand)
   .command(telephonyCommand)
   .command(teamsPhoneCommand)
   .command(teamsCommand)

package/lib/commands/agent.js

@@ -1,4 +1,4 @@
-import { get, post }  from '../api.js';
+import { get, post, messagingPost, getCredentials }  from '../api.js';
 import { runCommand }  from '../run.js';
 
 const VALID_STATUSES = ['Available', 'Away', 'Offline'];
@@ -55,6 +55,48 @@ export const agentCommand = {
         console.log(`\n${rows.length} agent(s)`);
       }),
     })
+    .command({
+      command:  'create',
+      describe: 'Provision a new licensed agent/admin on an EXISTING site (Velaro staff only) -- ' +
+                'closes the gap where site-provision only creates brand-new sites and Users/List ' +
+                'requires an existing site admin, which a zero-agent site can never have',
+      builder:  (y) => y
+        .option('site-id', { type: 'number', demandOption: true, describe: 'Target site ID (must already exist)' })
+        .option('email',   { type: 'string', demandOption: true, describe: 'New agent email' })
+        .option('first-name', { type: 'string', describe: 'First name' })
+        .option('last-name',  { type: 'string', describe: 'Last name' })
+        .option('roles',     { type: 'array',  describe: 'Roles to grant, e.g. --roles Administrator (default: Administrator). "Velaro Admin"/"Velaro Support" are always stripped server-side.' })
+        .option('team-ids',  { type: 'array',  describe: 'Team IDs on the target site (default: the site\'s first team)' })
+        .option('max-chats', { type: 'number', describe: 'Concurrent chat capacity (default: site ceiling, usually 4)' }),
+      handler: runCommand(async (argv) => {
+        const creds = await getCredentials();
+        if (creds.siteId !== 1032) {
+          console.error('This command is only available to Velaro staff.');
+          process.exit(1);
+        }
+
+        const body = {
+          email:     argv.email,
+          firstName: argv['first-name'],
+          lastName:  argv['last-name'],
+          roles:     argv.roles,
+          teamIds:   argv['team-ids']?.map(Number),
+          maxChats:  argv['max-chats'] ?? 0,
+        };
+
+        console.log(`\nCreating agent ${argv.email} on site ${argv['site-id']}...`);
+        // Non-2xx (existing email, seat limit reached, site not found) throws via
+        // messagingRequest and is reported by runCommand's own catch -- no separate
+        // success/error branch needed here, unlike site-provision's payload-level flag.
+        const result = await messagingPost(`/SupportTools/sites/${argv['site-id']}/agents`, body);
+
+        console.log(`\x1b[32mOK: agent created on site ${argv['site-id']}\x1b[0m`);
+        console.log(`  Email: ${result.user?.email ?? argv.email}`);
+        console.log(`  Roles: ${(result.user?.roles ?? []).join(', ')}`);
+        if (result.temporaryPassword) console.log(`  Temp password: ${result.temporaryPassword}`);
+        console.log(`  ${result.message ?? ''}`);
+      }),
+    })
     .command({
       command:  'set-status',
       describe: 'Set an agent\'s availability status (admin only)',

package/lib/commands/ai-models.js

@@ -114,6 +114,29 @@ async function clearTierDefault(argv) {
   console.log(`\n${GREEN}OK${RESET} Cleared tier '${argv.tier}' role '${argv.role}'. Reverts to global default.\n`);
 }
 
+// -- per-site thinking + version pin -------------------------------------------
+
+async function setSiteThinking(argv) {
+  const data = await callResolver(argv, `site/${argv.site}/thinking`, {
+    method: 'POST',
+    body: { effort: argv.effort, ...(argv.role ? { role: argv.role } : {}) },
+  });
+  console.log(`
+${GREEN}OK${RESET} Site ${data.siteId}: ${data.key} = ${data.effort}`);
+  console.log(`${DIM}Thinking bills as output tokens; only active if the site holds EnableAiThinking.${RESET}
+`);
+}
+
+async function setSitePin(argv) {
+  const data = await callResolver(argv, `site/${argv.site}`, {
+    method: 'POST',
+    body: { role: argv.role, model: argv.model, pinVersion: argv.pin === true, updatedBy: 'velaro-cli' },
+  });
+  console.log(`
+${GREEN}OK${RESET} Site ${data.siteId} role '${data.role}' -> ${data.model} (pinVersion=${data.pinVersion})
+`);
+}
+
 // -- command export -------------------------------------------------------------
 
 export const aiModelsCommand = {
@@ -155,5 +178,26 @@ export const aiModelsCommand = {
         .option('env', { describe: 'staging or prod', type: 'string' }),
       handler: clearTierDefault,
     })
-    .demandCommand(1, 'Specify a subcommand: resolver, effective, set-tier, or clear-tier'),
+    .command({
+      command:  'set-thinking',
+      describe: 'Set the extended-thinking level for a site (off default; needs EnableAiThinking entitlement)',
+      builder:  y => y
+        .option('site',   { describe: 'Site ID', type: 'number', demandOption: true })
+        .option('effort', { describe: 'off, low, medium, or high', type: 'string', choices: ['off', 'low', 'medium', 'high'], demandOption: true })
+        .option('role',   { describe: 'Scope to one role (omit for site-wide)', type: 'string' })
+        .option('env',    { describe: 'staging or prod', type: 'string' }),
+      handler: setSiteThinking,
+    })
+    .command({
+      command:  'set-site-model',
+      describe: 'Set a site role override, optionally pinned to its exact version (--pin), e.g. velaro ai-models set-site-model --site 1032 --role chatbot --model claude-opus-5 --pin',
+      builder:  y => y
+        .option('site',  { describe: 'Site ID', type: 'number', demandOption: true })
+        .option('role',  { describe: 'e.g. chatbot, ivr, skill_synthesis', type: 'string', demandOption: true })
+        .option('model', { describe: 'Model alias/ID', type: 'string', demandOption: true })
+        .option('pin',   { describe: 'Keep this exact model, do not auto-upgrade', type: 'boolean', default: false })
+        .option('env',   { describe: 'staging or prod', type: 'string' }),
+      handler: setSitePin,
+    })
+    .demandCommand(1, 'Specify a subcommand: resolver, effective, set-tier, clear-tier, set-thinking, or set-site-model'),
 };

package/lib/commands/article.js

@@ -198,7 +198,7 @@ const pushCommand = {
 
 const deleteCommand = {
   command:  'delete <id>',
-  describe: 'Delete a KB article',
+  describe: 'Delete a KB article (restorable for 30 days)',
   builder:  (y) => y.positional('id', { type: 'number', describe: 'Article ID' }),
   handler: runCommand(async (argv) => {
     await adminRequest('DELETE', `/api/kb/articles?id=${argv.id}`);
@@ -206,6 +206,48 @@ const deleteCommand = {
   }),
 };
 
+// ── recycle bin (soft delete) ────────────────────────────────────────────────
+
+const deletedCommand = {
+  command:  'deleted',
+  describe: 'List recently deleted KB articles (restorable for 30 days)',
+  handler: runCommand(async () => {
+    const rows = await adminRequest('GET', '/api/kb/articles/deleted');
+    (rows || []).forEach(r => console.log(`#${r.id} ${r.name} (purges in ${r.daysUntilPurge} day(s))`));
+    if (!rows || !rows.length) console.log('Nothing in Recently deleted.');
+  }),
+};
+
+const restoreCommand = {
+  command:  'restore <id>',
+  describe: 'Restore a deleted KB article (re-indexes it)',
+  builder:  (y) => y.positional('id', { type: 'number', describe: 'Article ID' }),
+  handler: runCommand(async (argv) => {
+    await adminRequest('POST', `/api/kb/articles/${argv.id}/restore`);
+    console.log(`Article ${argv.id} restored.`);
+  }),
+};
+
+const deletedTopicsCommand = {
+  command:  'deleted-topics',
+  describe: 'List recently deleted KB topics',
+  handler: runCommand(async () => {
+    const rows = await adminRequest('GET', '/api/kb/topics/deleted');
+    (rows || []).forEach(r => console.log(`#${r.id} ${r.name} (purges in ${r.daysUntilPurge} day(s))`));
+    if (!rows || !rows.length) console.log('Nothing in Recently deleted.');
+  }),
+};
+
+const restoreTopicCommand = {
+  command:  'restore-topic <id>',
+  describe: 'Restore a deleted KB topic',
+  builder:  (y) => y.positional('id', { type: 'number', describe: 'Topic ID' }),
+  handler: runCommand(async (argv) => {
+    await adminRequest('POST', `/api/kb/topics/${argv.id}/restore`);
+    console.log(`Topic ${argv.id} restored.`);
+  }),
+};
+
 // ── seed-views ────────────────────────────────────────────────────────────────
 
 const seedViewsCommand = {
@@ -461,6 +503,10 @@ export const articleCommand = {
       .command(pushCommand)
       .command(previewCommand)
       .command(deleteCommand)
+      .command(deletedCommand)
+      .command(restoreCommand)
+      .command(deletedTopicsCommand)
+      .command(restoreTopicCommand)
       .command(seedViewsCommand)
       .command(improveCommand)
       .command(screenshotCommand)

package/lib/commands/booking.js

@@ -1,12 +1,15 @@
 import { messagingGet, messagingPost, messagingPut, messagingDel } from '../api.js';
 import { runCommand } from '../run.js';
 
-// ── velaro booking ────────────────────────────────────────────────────────────
-// CLI surface for the generic booking engine (Phase 1b) -- see velaro-admin
-// memory project_2026_09_06_generic_booking_engine_schema_plan.md. Backend:
+// -- velaro booking --------------------------------------------------------------
+// CLI surface for the generic booking engine (Phase 1b config CRUD + Phase 1c
+// booking write path) -- see velaro-admin memory
+// project_2026_09_06_generic_booking_engine_schema_plan.md. Backend:
 // server/Velaro.Messaging/Controllers/{BookableResourcesController,
 // BookableServicesController,ResourceAvailabilityRulesController}.cs, routed
-// at /BookableResources, /BookableServices, /ResourceAvailabilityRules.
+// at /BookableResources, /BookableServices, /ResourceAvailabilityRules
+// (Phase 1b, config); server/Velaro.Messaging/Controllers/Bookings/BookingsController.cs,
+// routed at /Bookings (Phase 1c, staff-facing list/get/cancel of actual bookings).
 // Mirrors the booking_* MCP tools. SiteId always derives from the caller's
 // JWT server-side -- never accepted as a CLI argument.
 
@@ -17,9 +20,9 @@ function fmtTime(t) { return t == null ? '-' : String(t); }
 
 export const bookingCommand = {
   command:  'booking <subcommand>',
-  describe: 'Generic booking engine -- bookable resources, services, and availability rules',
+  describe: 'Generic booking engine -- bookable resources, services, availability rules, and bookings',
   builder:  yargs => yargs
-    // ── resource ────────────────────────────────────────────────────────────
+    // -- resource --------------------------------------------------------------
     .command({
       command:  'resource <action>',
       describe: 'Manage bookable resources (staff / room / equipment / virtual)',
@@ -93,7 +96,7 @@ export const bookingCommand = {
         })
         .demandCommand(1, 'Specify a resource action: list | get | create | update | delete'),
     })
-    // ── service ─────────────────────────────────────────────────────────────
+    // -- service -----------------------------------------------------------------
     .command({
       command:  'service <action>',
       describe: 'Manage bookable services (the "thing" a customer books)',
@@ -179,7 +182,7 @@ export const bookingCommand = {
         })
         .demandCommand(1, 'Specify a service action: list | get | create | update | delete'),
     })
-    // ── availability ────────────────────────────────────────────────────────
+    // -- availability --------------------------------------------------------------
     .command({
       command:  'availability <action>',
       describe: 'Manage weekly-recurring resource availability rules',
@@ -275,5 +278,55 @@ export const bookingCommand = {
         })
         .demandCommand(1, 'Specify an availability action: list | get | create | update | delete'),
     })
-    .demandCommand(1, 'Specify a subcommand: resource | service | availability'),
-};
+    // -- appointment (Phase 1c: real bookings, staff-facing) ------------------------
+    .command({
+      command:  'appointment <action>',
+      describe: 'View and cancel actual bookings made against the booking engine (staff-facing)',
+      builder:  y => y
+        .command({
+          command:  'list',
+          describe: 'List bookings for this site, optionally filtered by date range or service',
+          builder:  y2 => y2
+            .option('from',       { type: 'string', describe: 'Only bookings starting at or after this ISO 8601 timestamp' })
+            .option('to',         { type: 'string', describe: 'Only bookings starting at or before this ISO 8601 timestamp' })
+            .option('service-id', { type: 'number', describe: 'Only bookings for this bookable service id' }),
+          handler:  runCommand(async argv => {
+            const params = new URLSearchParams();
+            if (argv.from != null) params.set('fromUtc', argv.from);
+            if (argv.to != null) params.set('toUtc', argv.to);
+            if (argv.serviceId != null) params.set('bookableServiceId', String(argv.serviceId));
+            const qs = params.toString();
+            const bookings = await messagingGet(`/Bookings${qs ? `?${qs}` : ''}`);
+            if (!Array.isArray(bookings) || !bookings.length) {
+              console.log('\n  No bookings found.\n');
+              return;
+            }
+            console.log('\nBookings\n');
+            for (const b of bookings) {
+              console.log(`  id:${b.id}  service:${b.bookableServiceId}  resource:${b.resourceId ?? '-'}  ${fmtDate(b.startUtc)}-${fmtDate(b.endUtc)}  party:${b.partySize}  status:${b.status}  customer:${b.customerName} (${b.customerPhone})`);
+            }
+            console.log('');
+          }),
+        })
+        .command({
+          command:  'get <id>',
+          describe: 'Get a single booking by id',
+          builder:  y2 => y2.positional('id', { type: 'number', describe: 'Booking id' }),
+          handler:  runCommand(async argv => {
+            const booking = await messagingGet(`/Bookings/${argv.id}`);
+            console.log(JSON.stringify(booking, null, 2));
+          }),
+        })
+        .command({
+          command:  'cancel <id>',
+          describe: 'Cancel a booking (staff-initiated)',
+          builder:  y2 => y2.positional('id', { type: 'number', describe: 'Booking id' }),
+          handler:  runCommand(async argv => {
+            const result = await messagingPost(`/Bookings/${argv.id}/cancel`, {});
+            console.log(`\n✓ Cancelled booking id:${result.bookingId} (status: ${result.status})\n`);
+          }),
+        })
+        .demandCommand(1, 'Specify an appointment action: list | get | cancel'),
+    })
+    .demandCommand(1, 'Specify a subcommand: resource | service | availability | appointment'),
+};

package/lib/commands/contact-list.js

@@ -277,6 +277,52 @@ export const contactListCommand = {
   describe: 'Marketing contact lists: CRUD, members, export, resync, quota, segments, CRM import',
   builder:  (y) => y
     .command({ command: 'list', describe: 'List all contact lists for this site', handler: runCommand(listsHandler) })
+    .command({
+      command:  'deleted',
+      describe: 'List recently deleted contact lists (restorable for 30 days)',
+      handler: runCommand(async () => {
+        const rows = await request('GET', 'ContactLists/deleted');
+        (rows || []).forEach(r => console.log(`#${r.id} ${r.name} (purges in ${r.daysUntilPurge} day(s))`));
+        if (!rows || !rows.length) console.log('Nothing in Recently deleted.');
+      }),
+    })
+    .command({
+      command:  'restore <id>',
+      describe: 'Restore a deleted contact list',
+      builder:  (y2) => y2.positional('id', { type: 'number' }),
+      handler: runCommand(async (argv) => { await request('POST', `ContactLists/${argv.id}/restore`); console.log(`List #${argv.id} restored.`); }),
+    })
+    .command({
+      command:  'deleted-members <listId>',
+      describe: 'List members recently removed from a list',
+      builder:  (y2) => y2.positional('listId', { type: 'number' }),
+      handler: runCommand(async (argv) => {
+        const rows = await request('GET', `ContactLists/${argv.listId}/Members/deleted`);
+        (rows || []).forEach(r => console.log(`#${r.id} ${r.name} (purges in ${r.daysUntilPurge} day(s))`));
+        if (!rows || !rows.length) console.log('Nothing in Recently deleted.');
+      }),
+    })
+    .command({
+      command:  'restore-member <listId> <memberId>',
+      describe: 'Restore a member removed from a list',
+      builder:  (y2) => y2.positional('listId', { type: 'number' }).positional('memberId', { type: 'number' }),
+      handler: runCommand(async (argv) => { await request('POST', `ContactLists/${argv.listId}/Members/${argv.memberId}/restore`); console.log(`Member #${argv.memberId} restored.`); }),
+    })
+    .command({
+      command:  'deleted-segments',
+      describe: 'List recently deleted contact segments',
+      handler: runCommand(async () => {
+        const rows = await request('GET', 'ContactSegments/deleted');
+        (rows || []).forEach(r => console.log(`#${r.id} ${r.name} (purges in ${r.daysUntilPurge} day(s))`));
+        if (!rows || !rows.length) console.log('Nothing in Recently deleted.');
+      }),
+    })
+    .command({
+      command:  'restore-segment <id>',
+      describe: 'Restore a deleted contact segment',
+      builder:  (y2) => y2.positional('id', { type: 'number' }),
+      handler: runCommand(async (argv) => { await request('POST', `ContactSegments/${argv.id}/restore`); console.log(`Segment #${argv.id} restored.`); }),
+    })
     .command({
       command:  'create',
       describe: 'Create a new contact list',

package/lib/commands/experience-impact.js

@@ -36,6 +36,12 @@ export const experienceImpactCommand = {
         console.log(`    ${label}: ${x.chats} chats | avg wait ${x.avgWaitSec}s | missed ${x.missed} | CSAT ${x.csatResponses ? x.csatAvg : '-'} (${x.csatResponses ?? 0})`);
       }
     }
+    // Additive fields from the rebuilt report (absent on older backends).
+    if (d.coverage) {
+      const c = d.coverage;
+      console.log(`  CSAT coverage: ${(c.sources ?? []).map(x => `${x.label} ${x.responses} (avg ${x.avg ?? '-'})`).join(' | ')} | survey submissions ${c.surveySubmissions ?? 0}, rated ${c.surveyRated ?? 0}, response rate ${c.responseRatePct ?? 0}% | CSAT survey configured: ${c.csatSurveyConfigured ? 'yes' : 'no'}`);
+    }
+    for (const x of d.reasons ?? []) console.log(`  Why ${x.kpi} is low/empty [${x.code}]: ${x.message}${x.action ? ' Action: ' + x.action : ''}`);
     for (const i of d.insights ?? []) console.log(`  [${i.severity}] ${i.text}`);
     for (const a of d.agents ?? []) {
       console.log(`  [${a.agentId}] ${a.name}: index ${a.experienceIndex} adherence ${a.adherencePct}% CSAT ${a.csatAvg ?? '-'} handled ${a.handled}`);

package/lib/commands/klaviyo-migration.js

@@ -0,0 +1,84 @@
+/**
+ * velaro klaviyo-migration - Klaviyo -> Velaro importer + savings calculator
+ *
+ *   velaro klaviyo-migration preview                 Dry run: what would be imported (writes nothing)
+ *   velaro klaviyo-migration apply                   Import lists, segments, flows (idempotent)
+ *   velaro klaviyo-migration savings --profiles N --bill USD [--plan plan.professional]
+ *
+ * Uses the API key stored by the Klaviyo integration. Site scoping is server-side.
+ */
+
+import { request } from '../api.js';
+
+const BOLD = '\x1b[1m';
+const YEL = '\x1b[33m';
+const RED = '\x1b[31m';
+const DIM = '\x1b[2m';
+const RST = '\x1b[0m';
+
+function body(argv) {
+  const split = v => (v ? String(v).split(',').map(s => s.trim()).filter(Boolean) : undefined);
+  return {
+    listIds: split(argv.lists),
+    segmentIds: split(argv.segments),
+    flowIds: split(argv.flows),
+    includeFlows: argv['no-flows'] ? false : true,
+    maxProfilesPerGroup: argv.max,
+  };
+}
+
+function render(r) {
+  console.log(`\n${BOLD}${r.dryRun ? 'Klaviyo import preview (nothing written)' : 'Klaviyo import applied'}${RST}\n`);
+  for (const e of r.errors ?? []) console.log(`${RED}  ! ${e}${RST}`);
+  for (const i of r.items ?? []) {
+    const n = i.kind === 'flow' ? `${i.stepCount} steps` : `${i.profileCount ?? 0} contacts`;
+    console.log(`  ${i.kind.padEnd(8)} ${i.name}  ${DIM}${i.action}, ${n}, skipped not-subscribed ${i.skippedNotSubscribed}${i.truncated ? ', capped' : ''}${RST}`);
+    for (const w of i.warnings ?? []) console.log(`${YEL}           ${w}${RST}`);
+  }
+  if (!r.dryRun) {
+    console.log(`\n  Created: ${r.listsCreated} lists, ${r.segmentsCreated} segments, ${r.flowsCreated} flows; ${r.contactsUpserted} contacts upserted.`);
+  }
+  console.log('');
+}
+
+const sharedOptions = yy => yy
+  .option('lists', { describe: 'Comma-separated Klaviyo list ids (default all)', type: 'string' })
+  .option('segments', { describe: 'Comma-separated Klaviyo segment ids (default all)', type: 'string' })
+  .option('flows', { describe: 'Comma-separated Klaviyo flow ids (default all)', type: 'string' })
+  .option('no-flows', { describe: 'Skip flows', type: 'boolean' })
+  .option('max', { describe: 'Max profiles per list/segment', type: 'number', default: 5000 });
+
+export const klaviyoMigrationCommand = {
+  command: 'klaviyo-migration <subcommand>',
+  describe: 'Import lists, segments and flows from Klaviyo; compare cost',
+  builder: y => y
+    .command({
+      command: 'preview',
+      describe: 'Dry run, writes nothing',
+      builder: sharedOptions,
+      handler: async argv => render(await request('POST', '/KlaviyoMigration/Preview', body(argv))),
+    })
+    .command({
+      command: 'apply',
+      describe: 'Run the import (idempotent)',
+      builder: sharedOptions,
+      handler: async argv => render(await request('POST', '/KlaviyoMigration/Apply', body(argv))),
+    })
+    .command({
+      command: 'savings',
+      describe: 'Compare your Klaviyo bill to a Velaro plan catalog price',
+      builder: yy => yy
+        .option('profiles', { describe: 'Klaviyo profile count', type: 'number', demandOption: true })
+        .option('bill', { describe: 'Klaviyo monthly bill in USD', type: 'number', demandOption: true })
+        .option('plan', { describe: 'Velaro plan key (default plan.professional)', type: 'string' }),
+      handler: async argv => {
+        const qs = new URLSearchParams({ profiles: String(argv.profiles), klaviyoMonthlyBill: String(argv.bill) });
+        if (argv.plan) qs.set('planKey', argv.plan);
+        const r = (await request('GET', `/KlaviyoMigration/SavingsCalculator?${qs}`)).result;
+        console.log(`\nVelaro ${r.planName}: $${r.velaroMonthly}/mo vs Klaviyo $${r.klaviyoMonthly}/mo`);
+        console.log(`Difference: $${r.monthlySavings}/mo, $${r.annualSavings}/yr\n${DIM}${r.note}${RST}\n`);
+      },
+    })
+    .demandCommand(1, 'Specify a subcommand. Try: velaro klaviyo-migration --help'),
+  handler: () => {},
+};

package/lib/commands/report-explain.js

@@ -0,0 +1,29 @@
+import { readFileSync } from 'node:fs';
+import { join, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { runCommand } from '../run.js';
+
+// -- velaro report-explain [report] ---------------------------------------------
+// Static how-to-interpret guidance per report (same data as the report_explain MCP tool
+// and copilot-kb/report-interpretation-guide.md). No network call.
+
+export const reportExplainCommand = {
+  command:  'report-explain [report]',
+  describe: 'Explain how to read a report, its data sources, setup prerequisites and why values can be zero',
+  builder:  (y) => y
+    .positional('report', { type: 'string', describe: 'Report key, e.g. experience-impact (omit to list all)' })
+    .option('json', { type: 'boolean', default: false, describe: 'Raw JSON output' }),
+  handler:  runCommand(async (argv) => {
+    const all = JSON.parse(readFileSync(join(dirname(fileURLToPath(import.meta.url)), '..', 'report-explain.json'), 'utf8'));
+    const key = (argv.report ?? '').toString().trim().toLowerCase();
+    if (!key) {
+      if (argv.json) { console.log(JSON.stringify(Object.keys(all))); return; }
+      for (const [k, r] of Object.entries(all)) console.log(`${k}: ${r.name}`);
+      return;
+    }
+    const r = all[key];
+    if (!r) throw new Error(`Unknown report "${key}". Valid keys: ${Object.keys(all).join(', ')}`);
+    if (argv.json) { console.log(JSON.stringify(r, null, 2)); return; }
+    console.log(`\n${r.name}\n  Answers: ${r.answers}\n  Sources: ${r.sources}\n  Setup: ${r.prerequisites}\n  How to read: ${r.interpret}\n  Why zero/empty: ${r.whyZero}\n  What to do: ${r.fix}\n  Related: ${r.related}`);
+  }),
+};

package/lib/commands/report.js

@@ -448,6 +448,57 @@ const workedHoursCommand = {
   },
 };
 
+// -- visitor-traffic command ------------------------------------------------
+// Visitor Traffic report (velaro-messaging): daily visit trend, top countries,
+// chat-channel breakdown. Backend: server/Velaro.Messaging/Controllers/ReportsController.cs
+// POST reports/visitor-traffic-overview { start, end } -> { kpis, dailySeries, countryBreakdown, channelBreakdown }
+const visitorTrafficCommand = {
+  command:  'visitor-traffic',
+  describe: 'Visitor Traffic report: daily visit trend, top countries and chat-channel breakdown for a date range',
+  builder:  (y) => y
+    .option('start', { type: 'string', describe: 'Start date (ISO 8601 or YYYY-MM-DD). Default: 30 days ago' })
+    .option('end',   { type: 'string', describe: 'End date (ISO 8601 or YYYY-MM-DD). Default: now' }),
+  handler: async (argv) => {
+    const end   = argv.end   ? new Date(argv.end)   : new Date();
+    const start = argv.start ? new Date(argv.start) : new Date(end.getTime() - 30 * 24 * 60 * 60 * 1000);
+    if (Number.isNaN(start.getTime()) || Number.isNaN(end.getTime())) {
+      console.error('--start and --end must be valid dates (ISO 8601 or YYYY-MM-DD).');
+      process.exit(1);
+    }
+
+    const data = await messagingRequest('POST', '/reports/visitor-traffic-overview', {
+      start: start.toISOString(),
+      end:   end.toISOString(),
+    });
+
+    section('Visitor Traffic');
+    console.log(`  Period: ${data?.start ?? start.toISOString().slice(0, 10)} -> ${data?.end ?? end.toISOString().slice(0, 10)}`);
+
+    const k = data?.kpis ?? {};
+    fmtRow('Total visits',       fmtNum(k.totalVisits));
+    fmtRow('Avg daily visits',   fmtNum(k.avgDailyVisits));
+    fmtRow('Countries reached',  fmtNum(k.countriesReached));
+    fmtRow('Chats started',      fmtNum(k.chatsStarted));
+
+    const countries = Array.isArray(data?.countryBreakdown) ? data.countryBreakdown : [];
+    section('Top Countries');
+    if (!countries.length) {
+      console.log('  (no data)');
+    } else {
+      for (const c of countries) console.log(`  ${(c.country ?? '?').padEnd(6)} ${fmtNum(c.count)}`);
+    }
+
+    const channels = Array.isArray(data?.channelBreakdown) ? data.channelBreakdown : [];
+    section('By Channel');
+    if (!channels.length) {
+      console.log('  (no data)');
+    } else {
+      for (const c of channels) console.log(`  ${(c.name ?? '?').padEnd(16)} ${fmtNum(c.count)}  (${fmtNum(c.pct)}%)`);
+    }
+    console.log('');
+  },
+};
+
 // ── scheduled reports (Reports/Schedules) ──────────────────────────────────────
 // Backend: server/Velaro.Admin/Controllers/ReportsController.cs
 //   GET  Reports/Schedules -> scheduledReport[]
@@ -638,6 +689,7 @@ export const reportCommand = {
     .command(conversationsCommand)
     .command(callactivityCommand)
     .command(workedHoursCommand)
+    .command(visitorTrafficCommand)
     .command(schedulesCommand)
     .command(exportCommand)
     .demandCommand(1, 'Specify a report type. Run "velaro report --help" for options.'),

package/lib/commands/support.js

@@ -1,5 +1,6 @@
 // velaro support — staff SupportTools / staff-scoped actions (superadmin only)
 import { request, messagingPost, messagingGet } from '../api.js';
+import { ensureSiteUser } from '../siteUser.js';
 
 async function toggleFlag(args) {
   if (!args.site || !args.flag || args.enabled === undefined) {
@@ -91,6 +92,18 @@ async function agentLookup(args) {
   console.log(JSON.stringify(result, null, 2));
 }
 
+async function addSiteUser(args) {
+  // Password via --password or VELARO_NEW_USER_PASSWORD env (preferred; keeps it out of shell history). Never printed.
+  const password = args.password || process.env.VELARO_NEW_USER_PASSWORD;
+  try {
+    const r = await ensureSiteUser({ get: messagingGet, post: messagingPost }, { ...args, siteId: args.site, password });
+    console.log(`${r.created ? 'Created' : 'Updated existing'} ${r.email} on site ${r.siteId} (userId ${r.userId}, roles ${r.roles.join(',')}); password set, usable immediately.`);
+  } catch (e) {
+    console.error(`add-site-user failed: ${e.message}`);
+    process.exit(1);
+  }
+}
+
 async function listDeployments(args) {
   const result = await request('GET', `SupportTools/sites/${args.site}/deployments`);
   if (args.json) {
@@ -114,8 +127,43 @@ async function tourInsights(args) {
   console.log(JSON.stringify(result, null, 2));
 }
 
+function windowQuery(args, extra = {}) {
+  const q = new URLSearchParams();
+  if (args.from) q.set('from', args.from);
+  if (args.to) q.set('to', args.to);
+  for (const [k, v] of Object.entries(extra)) if (v !== undefined) q.set(k, String(v));
+  const s = q.toString();
+  return s ? `?${s}` : '';
+}
+
+async function connectionTimeline(args) {
+  // velaro-messaging SupportToolsController.AgentConnectionTimelineAsync (staff-only, read-only).
+  const result = await messagingGet(
+    `SupportTools/sites/${args.site}/agents/${args.agent}/connection-timeline${windowQuery(args, { limit: args.limit })}`);
+  console.log(JSON.stringify(result, null, 2));
+}
+
+async function connectionEvidence(args) {
+  // velaro-messaging SupportToolsController.ConnectionEvidenceAsync (staff-only, read-only).
+  const result = await messagingGet(
+    `SupportTools/sites/${args.site}/connection-evidence${windowQuery(args)}`);
+  console.log(JSON.stringify(result, null, 2));
+}
+
 export function supportCommand(yargs) {
   return yargs
+    .command('connection-timeline', 'Raw ordered agent connection events (connect/disconnect/reconnect) for one agent in a time window (Velaro staff, read-only)', y => y
+      .option('site',  { type: 'number', demandOption: true, desc: 'Site ID' })
+      .option('agent', { type: 'number', demandOption: true, desc: 'WorkspaceUser.Id of the agent' })
+      .option('from',  { type: 'string', desc: 'ISO start (default: 24h before --to)' })
+      .option('to',    { type: 'string', desc: 'ISO end (default: now)' })
+      .option('limit', { type: 'number', default: 2000, desc: 'Max events (1-5000)' })
+    , a => connectionTimeline(a))
+    .command('connection-evidence', 'Dispute-grade connection evidence for a site: Velaro probe uptime, incidents (incl. excluded, with reason), per-agent disconnects and client-vs-server reconciliation (Velaro staff, read-only)', y => y
+      .option('site', { type: 'number', demandOption: true, desc: 'Site ID' })
+      .option('from', { type: 'string', desc: 'ISO start (default: 30 days before --to)' })
+      .option('to',   { type: 'string', desc: 'ISO end (default: now)' })
+    , a => connectionEvidence(a))
     .command('tour-insights', 'Moshky setup-tour funnel + scrubbed feedback across all sites, or one site\'s tour timeline with --site (Velaro staff, read-only)', y => y
       .option('site', { type: 'number', desc: 'Optional site ID: show that site\'s tour events and feedback instead of the funnel' })
       .option('days', { type: 'number', default: 30, desc: 'Look-back window in days (max 365)' })
@@ -136,6 +184,14 @@ export function supportCommand(yargs) {
     .command('agent-lookup', 'Resolve a bare WorkspaceUser.Id (AgentId) to its Email/DisplayName/SiteId across all sites (superadmin only, read-only)', y => y
       .option('id', { type: 'number', demandOption: true, desc: 'WorkspaceUser.Id / AgentId to look up' })
     , a => agentLookup(a))
+    .command('add-site-user', 'Create or ensure a NORMAL user (agent|administrator, never staff) on ANY site with an explicit non-forcing password (staff only, idempotent)', y => y
+      .option('site',      { type: 'number', demandOption: true, desc: 'Target site ID' })
+      .option('email',     { type: 'string', demandOption: true, desc: 'User email' })
+      .option('password',  { type: 'string', desc: 'Password (or set VELARO_NEW_USER_PASSWORD; never logged)' })
+      .option('role',      { type: 'string', default: 'agent', choices: ['agent', 'administrator'], desc: 'agent or administrator' })
+      .option('firstName', { type: 'string' })
+      .option('lastName',  { type: 'string' })
+    , a => addSiteUser(a))
     .command('toggle-flag', 'Toggle a single legacy Subscription.cs feature flag on a site (superadmin only, allowlisted flags)', y => y
       .option('site',    { type: 'number',  demandOption: true, desc: 'Site ID' })
       .option('flag',    { type: 'string',  demandOption: true, desc: 'Flag name, e.g. EnableScraperBotIndexing (must be on SupportToolsController.AllowedFeatureFlags)' })
@@ -155,5 +211,5 @@ export function supportCommand(yargs) {
       .option('channel',         { type: 'string', desc: 'Conversation source, e.g. Web, TwilioSms (default Web)' })
       .option('overrideIndexes', { type: 'string', desc: 'Comma-separated index names to override the config\'s own IndexName for this query' })
     , a => chatQuery(a))
-    .demandCommand(1, 'Specify a subcommand: deployments | impersonate | agent-lookup | toggle-flag | scraper-create-job | chat-query | send-email | tour-insights');
+    .demandCommand(1, 'Specify a subcommand: deployments | impersonate | agent-lookup | add-site-user | toggle-flag | scraper-create-job | chat-query | send-email | tour-insights | connection-timeline | connection-evidence');
 }

package/lib/report-explain.json

@@ -0,0 +1,232 @@
+{
+  "experience-impact": {
+    "name": "Experience Impact",
+    "answers": "How staffing and adherence affect what customers feel, as a 0 to 100 Experience Index.",
+    "sources": "Work Schedules and presence, chat queue timing, missed chats, and CSAT from ticket replies and 1-5 survey ratings (questions tagged csat or star_rating).",
+    "prerequisites": "Work Schedules for agents; a survey with a 1-5 CSAT or star question attached to post-chat or a workflow, or ticket CSAT requests turned on; chat traffic in range.",
+    "interpret": "Weights: service level 30, adherence 25, CSAT 25, missed chats 20; a signal with no data drops out. CSAT needs 5+ responses to count. Response rate = rated survey submissions / all survey submissions. Actual agents below scheduled while missed chats rise = staffing gap.",
+    "whyZero": "CSAT empty: no CSAT survey configured; survey exists but nobody answered; answers came in with no 1-5 rating question; fewer than 5 responses; or the range predates the survey. If older chats were surveyed but never counted, ask Velaro support to run a CSAT backfill. Adherence empty: no Work Schedules. Sample data never mixes with real data.",
+    "fix": "Add a 1-5 star or CSAT question to the post-chat survey, enable ticket CSAT requests, widen the range, then fix the weakest component.",
+    "related": "Schedule Adherence, Service Level, Missed Chats, Surveys & NPS, Sentiment, Agent Performance"
+  },
+  "conversations": {
+    "name": "Conversations",
+    "answers": "How many conversations came in, on which channels and when.",
+    "sources": "Every conversation record on your account, grouped by channel, team, bot or agent, and time.",
+    "prerequisites": "At least one deployed channel (chat widget, SMS, email, voice, social).",
+    "interpret": "Overview shows totals and trend; Breakdown splits by channel, team and handler. Look at peaks by hour and day to plan staffing. Rising volume with flat staffing predicts longer waits.",
+    "whyZero": "No channel deployed or no traffic; the date range or team filter is too narrow; or you lack access to that team's data.",
+    "fix": "Widen the range, clear filters, confirm the deployment is live and the widget loads on your site.",
+    "related": "Service Level, Missed Chats, Visitor Traffic"
+  },
+  "missed": {
+    "name": "Missed Chats",
+    "answers": "Visitors who asked for help and got no live answer, and why.",
+    "sources": "Chat requests that ended without an agent or bot response, plus offline or unanswered conversations.",
+    "prerequisites": "Live chat deployed with agents or routing configured.",
+    "interpret": "Overview gives the missed count and rate. Breakdown shows time of day and team. Analysis groups likely causes such as nobody online, queue timeout, or visitor left. A missed spike at one hour points to a coverage gap.",
+    "whyZero": "Genuinely none, no chat traffic, or a bot answers everything so nothing reaches an agent queue.",
+    "fix": "Add agents or schedules for peak hours, review routing and after-hours behavior, enable offline message capture.",
+    "related": "Service Level, Experience Impact, Agent Availability"
+  },
+  "agent-performance": {
+    "name": "Agent Performance",
+    "answers": "How each agent handles conversations: volume, handle time, response speed and quality.",
+    "sources": "Conversations assigned to and handled by each agent, message timestamps, and survey scores where collected.",
+    "prerequisites": "Agents added to the account and handling chats.",
+    "interpret": "Compare an agent against the team over several weeks, not one day. Pair handle time with CSAT: fast and unhappy is a quality problem, slow and happy may be complex work.",
+    "whyZero": "Agent has no assigned chats in range, was not online, or the filter excludes their team. Quality scores need survey data.",
+    "fix": "Check routing assigns chats to that agent and that they set themselves available.",
+    "related": "Response Time, Agent Utilization, Surveys & NPS"
+  },
+  "response-time": {
+    "name": "Response Time",
+    "answers": "How quickly customers get a first reply and how long replies take afterwards.",
+    "sources": "Message timestamps between the customer's message and the first agent or bot reply.",
+    "prerequisites": "Chats with at least one reply.",
+    "interpret": "Look at the median and the slow tail together. A fine average with a long tail means some customers wait far too long.",
+    "whyZero": "No replies in range, or chats were only bot-handled and excluded from agent timing.",
+    "fix": "Add coverage at slow hours, turn on auto-greeting, review the routing capacity limit.",
+    "related": "Service Level, Agent Performance"
+  },
+  "service-level": {
+    "name": "Service Level",
+    "answers": "The share of chats answered within your target time.",
+    "sources": "Queue entry and first-answer timestamps compared with your configured service level threshold.",
+    "prerequisites": "A service level threshold in report settings and chats that enter an agent queue.",
+    "interpret": "A common target is 80 percent answered in 30 seconds. Check the trend by hour to find breaches.",
+    "whyZero": "No chats were queued for agents in the range, or no threshold is set.",
+    "fix": "Set the threshold, then staff to the hours that breach it.",
+    "related": "Response Time, Missed Chats, Experience Impact"
+  },
+  "sentiment": {
+    "name": "Sentiment",
+    "answers": "The overall tone of customer messages, by contact and by agent.",
+    "sources": "AI sentiment scoring of conversation messages.",
+    "prerequisites": "Sentiment reporting enabled on your plan and enough conversations to score.",
+    "interpret": "Watch the trend and the share of negative conversations. Use By Agent for coaching, By Contact to spot at-risk customers. Sentiment is inferred from text, so treat single scores as hints.",
+    "whyZero": "Feature not enabled, conversations too short to score, or scoring has not run yet for recent chats.",
+    "fix": "Confirm the plan includes it, widen the range, check again after the next processing cycle.",
+    "related": "Customer Health, Surveys & NPS, Experience Impact"
+  },
+  "health": {
+    "name": "Customer Health",
+    "answers": "Which contacts look healthy or at risk based on recent interactions.",
+    "sources": "Conversation frequency, sentiment, unresolved issues and survey results per contact.",
+    "prerequisites": "Contacts with conversation history.",
+    "interpret": "Low scores with rising contact frequency are the first to act on. Scores are relative to your own customers.",
+    "whyZero": "New account with little history, or sentiment data is not yet available.",
+    "fix": "Allow history to accumulate and enable surveys to add a direct signal.",
+    "related": "Sentiment, Surveys & NPS, Intelligence Suite"
+  },
+  "surveys": {
+    "name": "Surveys & NPS",
+    "answers": "What customers say in surveys: CSAT, NPS and custom questions, and how many respond.",
+    "sources": "Survey answers collected after chats, through workflows, standalone links or email.",
+    "prerequisites": "At least one active survey (post-chat CSAT, NPS or custom) delivered on a channel.",
+    "interpret": "Read the average with the response count and response rate. NPS is promoters minus detractors. Under about 30 responses, trends are noisy.",
+    "whyZero": "No survey enabled, survey not attached to the channel or workflow, nobody responded, or the range predates the survey. The visitor may close the chat before the survey shows.",
+    "fix": "Enable a short post-chat survey on every staffed channel, test it yourself, and keep questions to one or two.",
+    "related": "Experience Impact, Sentiment, Missed Chats"
+  },
+  "tickets": {
+    "name": "Tickets",
+    "answers": "Ticket volume, status, age and resolution speed.",
+    "sources": "Tickets created from email, forms, chats and manual entry.",
+    "prerequisites": "Ticketing or an email inbox connected.",
+    "interpret": "Watch open backlog and time to resolve. A growing backlog with steady intake means capacity is short.",
+    "whyZero": "Ticketing not enabled, no inbox connected, or no tickets in range.",
+    "fix": "Connect an inbox or enable ticket creation from forms and chat.",
+    "related": "Conversations, Agent Performance"
+  },
+  "calls": {
+    "name": "Calls",
+    "answers": "Phone call volume, duration, answered and missed calls.",
+    "sources": "Call records from your connected phone line or voice integration.",
+    "prerequisites": "A provisioned phone line or connected voice integration.",
+    "interpret": "Compare answered against missed by hour. Long durations may signal complexity or unresolved issues.",
+    "whyZero": "No phone line connected or no calls in range.",
+    "fix": "Connect a number and confirm it routes into Velaro.",
+    "related": "IVR, Voice"
+  },
+  "ivr": {
+    "name": "IVR",
+    "answers": "How callers move through your phone menus and where they drop off.",
+    "sources": "IVR call events for each menu step and outcome.",
+    "prerequisites": "An IVR configured on a phone line.",
+    "interpret": "A high drop-off at one step suggests a confusing prompt. Many transfers to an agent from one option shows demand to automate.",
+    "whyZero": "No IVR configured or no calls reached it.",
+    "fix": "Complete IVR setup, place a test call, then re-check.",
+    "related": "Calls, Voice"
+  },
+  "account-utilization": {
+    "name": "Account Utilization",
+    "answers": "How much of your plan (agents, bots, AI usage, channels) you are using.",
+    "sources": "Plan limits compared with measured usage on your account.",
+    "prerequisites": "Administrator or manager access.",
+    "interpret": "Near 100 percent means you may need a higher limit; very low usage means features you pay for are idle.",
+    "whyZero": "Feature not enabled yet or no usage in range.",
+    "fix": "Turn on unused features or request a limit increase.",
+    "related": "Agent Utilization"
+  },
+  "agent-availability": {
+    "name": "Agent Availability",
+    "answers": "When agents were online, away or offline.",
+    "sources": "Agent presence and status changes.",
+    "prerequisites": "Agents logging in to the workspace.",
+    "interpret": "Compare online time with scheduled time and chat demand to find coverage gaps.",
+    "whyZero": "Agents did not log in or the selected agents are not in range.",
+    "fix": "Confirm agents sign in and set their status to available.",
+    "related": "Schedule Adherence, Agent Utilization, Missed Chats"
+  },
+  "agent-utilization": {
+    "name": "Agent Utilization",
+    "answers": "How busy agents are compared with their capacity.",
+    "sources": "Concurrent chat load and online time per agent.",
+    "prerequisites": "Administrator or manager access; agents handling chats.",
+    "interpret": "Around 60 to 80 percent is healthy. Above that risks long waits and burnout, well below means spare capacity.",
+    "whyZero": "Agents were not online or not given chats.",
+    "fix": "Rebalance routing and capacity limits.",
+    "related": "Agent Availability, Agent Performance"
+  },
+  "visitor-traffic": {
+    "name": "Visitor Traffic",
+    "answers": "Who is visiting pages that have the Velaro widget and how many start chats.",
+    "sources": "Visitor tracking from the widget script on your site.",
+    "prerequisites": "Visitor tracking enabled and the widget installed on your pages.",
+    "interpret": "Compare visits with chats started to find pages where engagement is low.",
+    "whyZero": "Widget not installed on those pages, tracking not enabled, or an ad blocker or consent setting blocks it.",
+    "fix": "Verify the embed code on the live page and the tracking setting.",
+    "related": "Conversations"
+  },
+  "schedule-adherence": {
+    "name": "Schedule Adherence",
+    "answers": "Whether agents were online when scheduled.",
+    "sources": "Work Schedules compared with agent presence, plus approved exceptions.",
+    "prerequisites": "Work Schedules assigned to agents; the site time zone set correctly.",
+    "interpret": "Adherence is minutes available during scheduled time divided by scheduled minutes. Approved exceptions are excluded. Use Intraday for now and Timeline for the day's detail.",
+    "whyZero": "No schedules assigned, agents not scheduled in range, or time zone mismatch.",
+    "fix": "Create and assign schedules and check the time zone.",
+    "related": "Experience Impact, Agent Availability, Service Level"
+  },
+  "chat-intelligence": {
+    "name": "Chat Intelligence",
+    "answers": "What topics customers ask about, trends, and where the bot or KB falls short.",
+    "sources": "AI topic grouping of conversations and missed topics.",
+    "prerequisites": "Enough conversations (typically dozens) and the feature enabled.",
+    "interpret": "Rising themes show new demand. Missed topics are KB gaps: write or ingest content for them. Recommendations can be applied or dismissed.",
+    "whyZero": "Too little traffic, feature not enabled, or analysis has not run.",
+    "fix": "Widen the range and allow the next analysis run.",
+    "related": "Intelligence Suite, Conversation Efficiency"
+  },
+  "conversation-efficiency": {
+    "name": "Conversation Efficiency",
+    "answers": "How efficiently conversations are resolved and where time is lost.",
+    "sources": "Message counts, handle time, transfers and outcomes.",
+    "prerequisites": "Conversations with agent involvement.",
+    "interpret": "Agents shows who is above or below the norm, Correlation shows what drives long chats, Recommendations suggests actions.",
+    "whyZero": "No handled conversations in range.",
+    "fix": "Widen the range or pick a team with traffic.",
+    "related": "Agent Performance, Chat Intelligence"
+  },
+  "intelligence": {
+    "name": "Intelligence Suite",
+    "answers": "AI analysis across agents, customers, knowledge gaps, volume forecasts, revenue impact, competitors and channels.",
+    "sources": "Conversation history, surveys, and connected commerce or CRM data where present.",
+    "prerequisites": "Feature enabled on the plan and a few weeks of data. Revenue Impact needs a commerce or CRM integration.",
+    "interpret": "Treat each tab as guidance. Predictive Volume is a forecast, not a guarantee. Revenue Impact is an estimate from connected data.",
+    "whyZero": "Not enough history, missing integration, or feature not enabled.",
+    "fix": "Connect the relevant integration and allow data to accumulate.",
+    "related": "Customer Health, Chat Intelligence"
+  },
+  "operations": {
+    "name": "Operations Center",
+    "answers": "Live view of queues, agents and conversations right now.",
+    "sources": "Real-time presence and queue state.",
+    "prerequisites": "Workforce management enabled.",
+    "interpret": "Use it for moment-to-moment staffing. A rising queue with idle agents suggests a routing problem.",
+    "whyZero": "No active conversations or agents online.",
+    "fix": "Confirm agents are online and routing is active.",
+    "related": "Agent Availability, Service Level"
+  },
+  "voice": {
+    "name": "Voice",
+    "answers": "Individual call history and voice usage and billing.",
+    "sources": "Call log and voice minute usage.",
+    "prerequisites": "Voice enabled with a phone number.",
+    "interpret": "Call Log for detail, Usage for minutes against your plan.",
+    "whyZero": "No voice line or no calls.",
+    "fix": "Set up a voice number.",
+    "related": "Calls, IVR"
+  },
+  "email-subscriptions": {
+    "name": "Email Reports",
+    "answers": "Scheduled report summaries emailed to you.",
+    "sources": "The same data as the reports, summarized on your schedule.",
+    "prerequisites": "Access to the underlying report; some are manager or admin only.",
+    "interpret": "Each email links back to the full report.",
+    "whyZero": "Subscription not saved, the report is not on your plan, or it had no data for the period.",
+    "fix": "Re-save the subscription and check spam filtering for noreply@velaro.com.",
+    "related": "All reports"
+  }
+}

package/lib/siteUser.js

@@ -0,0 +1,35 @@
+// Ensure a NORMAL (agent|administrator) user with an explicit, non-forcing password on any customer site.
+// Composes velaro-messaging's existing staff SuperAdmin endpoints (no new backend):
+//   GET  SuperAdmin/users/{siteId}                       (find by email)
+//   POST SuperAdmin/users/{siteId}                       (create WorkspaceUser + Entra, SendEmail=false)
+//   POST SuperAdmin/users/{siteId}/{userId}/set-password (non-forcing, audit-logged server side)
+// The password is only ever sent in the HTTPS body of set-password; never logged or returned.
+const ROLE_MAP = { agent: 'Agent', administrator: 'Administrator' };
+
+export async function ensureSiteUser({ get, post }, args) {
+  const role = String(args.role || 'agent').toLowerCase();
+  if (!ROLE_MAP[role]) throw new Error('role must be agent or administrator (staff/superadmin roles are never granted here).');
+  const siteId = Number(args.siteId);
+  if (!Number.isInteger(siteId) || siteId <= 0) throw new Error('siteId must be a positive integer.');
+  const email = String(args.email || '').trim().toLowerCase();
+  if (!/^[^@\s]+@[^@\s]+\.[^@\s]+$/.test(email)) throw new Error('A valid email is required.');
+  if (typeof args.password !== 'string' || args.password.length < 8) throw new Error('password is required (min 8 characters).');
+
+  const listed = await get(`SuperAdmin/users/${siteId}`);
+  const users = Array.isArray(listed) ? listed : (listed?.users || []);
+  let user = users.find(u => String(u.email || u.Email || '').toLowerCase() === email);
+  let created = false;
+  if (!user) {
+    const res = await post(`SuperAdmin/users/${siteId}`, {
+      email, firstName: args.firstName || '', lastName: args.lastName || '',
+      roles: [ROLE_MAP[role]], sendEmail: false,
+    });
+    if (!res?.success) throw new Error(`Create failed: ${res?.error || res?.message || 'unknown error'}`);
+    user = { id: res.user.id ?? res.user.Id, roles: res.user.roles };
+    created = true;
+  }
+  const userId = user.id ?? user.Id;
+  const sp = await post(`SuperAdmin/users/${siteId}/${userId}/set-password`, { newPassword: args.password });
+  if (sp && sp.success === false) throw new Error(`set-password failed: ${sp.error || 'unknown error'}`);
+  return { success: true, siteId, userId, email, created, roles: user.roles || [ROLE_MAP[role]], passwordSet: true };
+}

package/lib/siteUser.test.js

@@ -0,0 +1,45 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { ensureSiteUser } from './siteUser.js';
+
+const base = { siteId: 100160, email: 'R@Velaro.com', password: 'S3cretPassw0rd!', role: 'agent' };
+function fakes(existing) {
+  const calls = [];
+  return {
+    calls,
+    get: async (p) => { calls.push(['GET', p]); return existing ? [{ id: 7, email: 'r@velaro.com', roles: ['Agent'] }] : []; },
+    post: async (p, b) => { calls.push(['POST', p, b]); return p.endsWith('set-password') ? { success: true } : { success: true, user: { id: 9, roles: ['Agent'] } }; },
+  };
+}
+
+test('creates user then sets password, never returns the password', async () => {
+  const f = fakes(false);
+  const r = await ensureSiteUser(f, base);
+  assert.equal(r.created, true);
+  assert.equal(r.userId, 9);
+  assert.ok(!JSON.stringify(r).includes(base.password));
+  assert.equal(f.calls[1][2].sendEmail, false);
+  assert.deepEqual(f.calls[1][2].roles, ['Agent']);
+});
+
+test('idempotent: existing user only gets password reset', async () => {
+  const f = fakes(true);
+  const r = await ensureSiteUser(f, base);
+  assert.equal(r.created, false);
+  assert.equal(f.calls.filter(c => c[0] === 'POST').length, 1);
+  assert.ok(f.calls[1][1].endsWith('/7/set-password'));
+});
+
+test('rejects superadmin/staff roles and weak input', async () => {
+  const f = fakes(false);
+  for (const role of ['superadmin', 'Velaro Admin', 'support']) await assert.rejects(ensureSiteUser(f, { ...base, role }));
+  await assert.rejects(ensureSiteUser(f, { ...base, password: 'short' }));
+  await assert.rejects(ensureSiteUser(f, { ...base, email: 'nope' }));
+  assert.equal(f.calls.length, 0);
+});
+
+test('errors never contain the password', async () => {
+  const f = fakes(true);
+  f.post = async () => ({ success: false, error: 'boom' });
+  await assert.rejects(ensureSiteUser(f, base), e => !e.message.includes(base.password));
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@velaro/cli",
-  "version": "1.4.69",
+  "version": "1.4.71",
   "description": "Velaro Workspace v20 — command-line interface for managing bots, knowledge base ingestion, MCP API keys, search indexes, and ops health.",
   "type": "module",
   "bin": {