@velaro/cli 1.4.70 → 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';
@@ -144,6 +145,7 @@ await yargs(hideBin(process.argv))
   .command(conversationEfficiencyCommand)
   .command(scheduleAdherenceCommand)
   .command(experienceImpactCommand)
+  .command(reportExplainCommand)
   .command(dbCommand)
   .command(focusCommand)
   .command(automationDraftCommand)

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/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/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.70",
+  "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": {