@velaro/cli 1.4.102 → 1.4.104

package/lib/commands/ops.js

@@ -1,6 +1,7 @@
 import { describeRawMeta, fetchRetry429 } from '../log-search.js';
 import { get, del, post, getCredentials } from '../api.js';
 import { readConfig, ENVS }   from '../config.js';
+import { parseBuild, formatBuild } from '../build-info.js';
 import { collectAll, render as renderDeployState } from '../deploy-state.js';
 
 // ── helpers ──────────────────────────────────────────────────────────────────
@@ -27,12 +28,6 @@ function extractLogEntries(response) {
   return [];
 }
 
-function utcLabel(dateStr) {
-  if (!dateStr) return '';
-  const d = new Date(dateStr);
-  return d.toISOString().replace('T', ' ').slice(0, 16) + ' UTC';
-}
-
 const OK    = '\x1b[32m✓\x1b[0m';
 const WARN  = '\x1b[33m⚠\x1b[0m';
 const ERR   = '\x1b[31m✗\x1b[0m';
@@ -46,21 +41,15 @@ function severityPrefix(s) {
   return LOW;
 }
 
-async function pingVersion(label, base) {
-  try {
-    const res = await fetch(`${base}/Version`, { signal: AbortSignal.timeout(6000) });
-    if (!res.ok) return { label, ok: false, status: res.status };
-    const data = await res.json();
-    return { label, ok: true, version: data.version, deployedAt: data.deployedAt };
-  } catch (e) {
-    return { label, ok: false, err: e.message };
-  }
-}
-
+// Reads the real running build from /api/health (build.commitId|sha, builtAt). The old /Version
+// endpoint returned a stale CI-stamped version/deployedAt, so workers polling for a new staging
+// build never saw it land (2026-10-12).
 async function pingHealth(label, url) {
   try {
     const res = await fetch(url, { signal: AbortSignal.timeout(6000) });
-    return { label, ok: res.ok, status: res.status };
+    let build = null;
+    try { build = parseBuild(await res.json()); } catch { /* non-JSON health body */ }
+    return { label, ok: res.ok, status: res.status, build };
   } catch (e) {
     return { label, ok: false, err: e.message };
   }
@@ -133,31 +122,32 @@ export const opsCommand = {
 
     const cfg = readConfig();
 
-    // ── 1. Deploy versions (anonymous — both envs in parallel) ───────────────
+    // ── 1+2. Deploy (real running build) + API health, all four services ────
     const prodBase    = cfg.envs?.prod?.adminApiBase    ?? ENVS.prod.adminApiBase;
     const stagingBase = cfg.envs?.staging?.adminApiBase ?? ENVS.staging.adminApiBase;
+    const prodMsgBase    = cfg.envs?.prod?.messagingApiBase    ?? ENVS.prod.messagingApiBase;
+    const stagingMsgBase = cfg.envs?.staging?.messagingApiBase ?? ENVS.staging.messagingApiBase;
 
-    const [prodVer, stagingVer] = await Promise.all([
-      pingVersion('prod',    prodBase),
-      pingVersion('staging', stagingBase),
+    const services = await Promise.all([
+      pingHealth('admin/prod',    `${prodBase}/api/health`),
+      pingHealth('admin/staging', `${stagingBase}/api/health`),
+      pingHealth('msg/prod',      `${prodMsgBase}/api/health`),
+      pingHealth('msg/staging',   `${stagingMsgBase}/api/health`),
     ]);
 
-    console.log('\n\x1b[1m── Deploy ──────────────────────────────────────────────────\x1b[0m');
-    for (const v of [prodVer, stagingVer]) {
-      if (v.ok) {
-        const sym  = OK;
-        const ver  = `\x1b[36m${v.version}\x1b[0m`;
-        const time = `${ago(v.deployedAt).padEnd(12)} (${utcLabel(v.deployedAt)})`;
-        console.log(`  ${sym}  ${v.label.padEnd(8)}  ${ver.padEnd(30)}  deployed ${time}`);
+    console.log('\n\x1b[1m── Deploy / API Health ─────────────────────────────────────\x1b[0m');
+    for (const h of services) {
+      if (h.ok) {
+        console.log(`  ${OK}  ${h.label.padEnd(14)}  ${formatBuild(h.build)}`);
       } else {
-        const detail = v.err ?? `HTTP ${v.status}`;
-        console.log(`  ${ERR}  ${v.label.padEnd(8)}  UNREACHABLE — ${detail}`);
+        const detail = h.err ?? `HTTP ${h.status}`;
+        console.log(`  ${ERR}  ${h.label.padEnd(14)}  ${h.build ? formatBuild(h.build) + '  ' : ''}UNHEALTHY — ${detail}`);
       }
     }
 
     // ── 1b. Where each push landed: staging environment, staging slot 1 of production, production ──
     // Same data as `velaro deploy-state` (needs gh). Never blocks the rest of ops if gh is missing.
-    console.log('\n\x1b[1m── Where each push landed ──────────────────────────────────\x1b[0m');
+    console.log('\n── Where each push landed ──────────────────────────────────');
     try {
       const state = await collectAll();
       console.log(renderDeployState(state, { compact: true }).split('\n').map(l => '  ' + l).join('\n'));
@@ -166,27 +156,6 @@ export const opsCommand = {
       console.log(`  ${WARN}  Deploy state unavailable (${e.message}). Needs gh logged in; run velaro deploy-state.`);
     }
 
-    // ── 2. API health (admin + messaging, both envs) ──────────────────────────
-    const prodMsgBase    = cfg.envs?.prod?.messagingApiBase    ?? ENVS.prod.messagingApiBase;
-    const stagingMsgBase = cfg.envs?.staging?.messagingApiBase ?? ENVS.staging.messagingApiBase;
-
-    const [adminProdHealth, adminStagingHealth, msgProdHealth, msgStagingHealth] = await Promise.all([
-      pingHealth('admin/prod',    `${prodBase}/Status`),
-      pingHealth('admin/staging', `${stagingBase}/Status`),
-      pingHealth('msg/prod',      `${prodMsgBase}/api/health`),
-      pingHealth('msg/staging',   `${stagingMsgBase}/api/health`),
-    ]);
-
-    console.log('\n\x1b[1m── API Health ──────────────────────────────────────────────\x1b[0m');
-    for (const h of [adminProdHealth, adminStagingHealth, msgProdHealth, msgStagingHealth]) {
-      if (h.ok) {
-        console.log(`  ${OK}  ${h.label}`);
-      } else {
-        const detail = h.err ?? `HTTP ${h.status}`;
-        console.log(`  ${ERR}  ${h.label.padEnd(20)}  ${detail}`);
-      }
-    }
-
     // ── 3. Hangfire failed jobs ───────────────────────────────────────────────
     console.log('\n\x1b[1m── Hangfire ────────────────────────────────────────────────\x1b[0m');
     try {
@@ -246,7 +215,7 @@ export const opsCommand = {
     // ── 5. Recent errors + perf + AI routing (last 1h) ───────────────────────
     console.log('\n\x1b[1m── Recent Issues (last 1h) ─────────────────────────────────\x1b[0m');
     try {
-      const stagingMsgBaseLocal = cfg.envs?.staging?.messagingApiBase ?? ENVS.staging.messagingApiBase;
+      const stagingMsgBaseLocal = stagingMsgBase;
       const from1h = new Date(Date.now() - 3600000).toISOString();
 
       // One search at a time: the server runs at most 2 exact scans per instance. 429 (gate full) is retried honouring Retry-After.

package/lib/commands/report-backfill.js

@@ -1,22 +1,40 @@
-import { messagingPost } from '../api.js';
+import { messagingGet, messagingPost } from '../api.js';
 import { runCommand } from '../run.js';
 
 // -- velaro report-backfill <type> --from --to [--apply] ---------------------------
 // Backend: velaro-messaging POST /Reports/backfill/{type}?from&to&apply (site managers; site from auth).
 // Preview by default ("would fill N"); --apply writes. Idempotent. Type "csat" fills survey ratings only.
+// Type "csat-demo" adds tagged demo CSAT assigned to the demo agents (allow-listed demo sites only, e.g. 100050);
+// "csat-demo-undo" with the SAME --from/--to deletes exactly the tagged rows. Example:
+//   velaro report-backfill csat-demo --from 2026-08-01 --to 2026-10-06 [--apply]
+//   velaro report-backfill csat-demo-undo --from 2026-08-01 --to 2026-10-06 [--apply]
+// history-classification(-sample) --apply is QUEUED (HTTP 202 + runId): the run happens in the background on the server;
+// read progress/result with --status (GET /Reports/backfill/{type}/status). csat --apply stays synchronous (200).
 export const reportBackfillCommand = {
   command:  'report-backfill <type>',
-  describe: 'Backfill report data for your site (preview by default; --apply to write). Type: csat',
+  describe: 'Backfill report data for your site (preview by default; --apply to write). Types: csat, csat-demo, csat-demo-undo, history-classification-sample (propose tags from 20 recent chats), history-classification (tag and score past chats, 100 per run)',
   builder:  (y) => y
-    .positional('type', { type: 'string', describe: 'Backfill type, e.g. csat' })
-    .option('from', { type: 'string', demandOption: true, describe: 'yyyy-MM-dd' })
-    .option('to', { type: 'string', demandOption: true, describe: 'yyyy-MM-dd' })
+    .positional('type', { type: 'string', describe: 'Backfill type: csat | csat-demo | csat-demo-undo | history-classification-sample | history-classification' })
+    .option('from', { type: 'string', describe: 'yyyy-MM-dd (required unless --status)' })
+    .option('to', { type: 'string', describe: 'yyyy-MM-dd (required unless --status)' })
+    .option('status', { type: 'boolean', default: false, describe: 'Show the latest queued/running/finished apply run for this type (history-classification types)' })
     .option('apply', { type: 'boolean', default: false, describe: 'Write the changes (default: preview only)' })
     .option('json', { type: 'boolean', default: false, describe: 'Raw JSON output' }),
   handler:  runCommand(async (argv) => {
+    if (argv.status) {
+      const s = await messagingGet(`/Reports/backfill/${encodeURIComponent(argv.type)}/status`);
+      console.log(JSON.stringify(s, null, 2));
+      return;
+    }
+    if (!argv.from || !argv.to) throw new Error('--from and --to are required (yyyy-MM-dd) unless --status');
     const qs = new URLSearchParams({ from: argv.from, to: argv.to, apply: String(!!argv.apply) });
     const r = await messagingPost(`/Reports/backfill/${encodeURIComponent(argv.type)}?${qs}`);
     if (argv.json) { console.log(JSON.stringify(r, null, 2)); return; }
+    if (argv.apply && r && r.runId) {
+      console.log(r.alreadyRunning ? `\nA run is already ${r.status} for this site (run ${r.runId}). Not starting another.` : `\nBackfill QUEUED (run ${r.runId}). It runs in the background; check progress with: velaro report-backfill ${argv.type} --status`);
+      console.log(JSON.stringify(r, null, 2));
+      return;
+    }
     console.log(argv.apply ? '\nBackfill APPLIED' : '\nBackfill PREVIEW (nothing written; add --apply to write)');
     console.log(JSON.stringify(r, null, 2));
   }),

package/lib/commands/report.js

@@ -1,6 +1,7 @@
 import { writeFileSync } from 'fs';
 import { getCredentials, request, messagingRequest } from '../api.js';
 import { runCommand } from '../run.js';
+import { toExclusiveEnd, exclusiveEndParam } from '../report-range.js';
 
 // ── helpers ───────────────────────────────────────────────────────────────────
 
@@ -33,7 +34,7 @@ function section(title) {
 function dateParams(argv) {
   const params = [];
   if (argv.start) params.push(`start=${encodeURIComponent(argv.start)}`);
-  if (argv.end)   params.push(`end=${encodeURIComponent(argv.end)}`);
+  if (argv.end)   params.push(`end=${encodeURIComponent(exclusiveEndParam(argv.end))}`);
   return params.length ? `?${params.join('&')}` : '';
 }
 
@@ -66,12 +67,12 @@ const callcenterTeamsCommand = {
   describe: 'Team breakdown for the call center report',
   builder:  (y) => y
     .option('start',       { type: 'string', describe: 'Start date (YYYY-MM-DD)' })
-    .option('end',         { type: 'string', describe: 'End date (YYYY-MM-DD)' })
+    .option('end',         { type: 'string', describe: 'End date (YYYY-MM-DD; includes that whole day)' })
     .option('sla',         { type: 'number', describe: 'SLA threshold in seconds (overrides server default)' }),
   handler: async (argv) => {
     const params = [];
     if (argv.start) params.push(`start=${encodeURIComponent(argv.start)}`);
-    if (argv.end)   params.push(`end=${encodeURIComponent(argv.end)}`);
+    if (argv.end)   params.push(`end=${encodeURIComponent(exclusiveEndParam(argv.end))}`);
     if (argv.sla)   params.push(`slaSeconds=${argv.sla}`);
     const qs = params.length ? `?${params.join('&')}` : '';
     const data = await fetchReport(`/CallCenterAnalytics/TeamBreakdown${qs}`);
@@ -106,7 +107,7 @@ const callcenterChannelsCommand = {
   describe: 'Channel breakdown for the call center report',
   builder:  (y) => y
     .option('start', { type: 'string', describe: 'Start date (YYYY-MM-DD)' })
-    .option('end',   { type: 'string', describe: 'End date (YYYY-MM-DD)' }),
+    .option('end',   { type: 'string', describe: 'End date (YYYY-MM-DD; includes that whole day)' }),
   handler: async (argv) => {
     const data = await fetchReport(`/CallCenterAnalytics/ChannelBreakdown${dateParams(argv)}`);
     const channels = Array.isArray(data) ? data : (data?.channels ?? []);
@@ -141,7 +142,7 @@ const callcenterCommand = {
     .command(callcenterTeamsCommand)
     .command(callcenterChannelsCommand)
     .option('start', { type: 'string', describe: 'Start date (YYYY-MM-DD)' })
-    .option('end',   { type: 'string', describe: 'End date (YYYY-MM-DD)' }),
+    .option('end',   { type: 'string', describe: 'End date (YYYY-MM-DD; includes that whole day)' }),
   handler: async (argv) => {
     const data = await fetchReport(`/CallCenterAnalytics/Report${dateParams(argv)}`);
 
@@ -197,12 +198,12 @@ const servicelevelCommand = {
   describe: 'Service level compliance report over time',
   builder:  (y) => y
     .option('start',       { type: 'string', describe: 'Start date (YYYY-MM-DD)' })
-    .option('end',         { type: 'string', describe: 'End date (YYYY-MM-DD)' })
+    .option('end',         { type: 'string', describe: 'End date (YYYY-MM-DD; includes that whole day)' })
     .option('granularity', { type: 'string', choices: ['hour', 'day', 'week', 'month'], default: 'day', describe: 'Time bucket size' }),
   handler: async (argv) => {
     const params = [];
-    if (argv.start)       params.push(`start=${encodeURIComponent(argv.start)}`);
-    if (argv.end)         params.push(`end=${encodeURIComponent(argv.end)}`);
+    if (argv.start)       params.push(`startDate=${encodeURIComponent(argv.start)}`);
+    if (argv.end)         params.push(`endDate=${encodeURIComponent(exclusiveEndParam(argv.end))}`);
     if (argv.granularity) params.push(`granularity=${argv.granularity}`);
     const qs = params.length ? `?${params.join('&')}` : '';
     const data = await fetchReport(`/ServiceLevel${qs}`);
@@ -249,17 +250,17 @@ const conversationsCommand = {
   describe: 'Conversation volume report over time',
   builder:  (y) => y
     .option('start',       { type: 'string', describe: 'Start date (YYYY-MM-DD)' })
-    .option('end',         { type: 'string', describe: 'End date (YYYY-MM-DD)' })
+    .option('end',         { type: 'string', describe: 'End date (YYYY-MM-DD; includes that whole day)' })
     .option('granularity', { type: 'string', choices: ['hour', 'day', 'week', 'month'], default: 'day', describe: 'Time bucket size' })
     .option('channel',     { type: 'string', describe: 'Filter by channel (e.g. Web, TwilioSms, WhatsApp)' }),
   handler: async (argv) => {
     const params = [];
-    if (argv.start)       params.push(`start=${encodeURIComponent(argv.start)}`);
-    if (argv.end)         params.push(`end=${encodeURIComponent(argv.end)}`);
+    if (argv.start)       params.push(`startDate=${encodeURIComponent(argv.start)}`);
+    if (argv.end)         params.push(`endDate=${encodeURIComponent(exclusiveEndParam(argv.end))}`);
     if (argv.granularity) params.push(`granularity=${argv.granularity}`);
     if (argv.channel)     params.push(`channel=${encodeURIComponent(argv.channel)}`);
     const qs = params.length ? `?${params.join('&')}` : '';
-    const data = await fetchReport(`/Conversations${qs}`);
+    const data = await fetchReport(`/ConversationsReport${qs}`);
 
     section('Conversations Report');
 
@@ -384,7 +385,7 @@ const workedHoursCommand = {
   describe: `Worked hours breakdown report: site KPIs + per-agent/per-day detail (Time Tracking, max ${MAX_WORKED_HOURS_RANGE_DAYS}-day range per query)`,
   builder:  (y) => y
     .option('start', { type: 'string', demandOption: true, describe: 'Start date (ISO 8601 or YYYY-MM-DD)' })
-    .option('end',   { type: 'string', demandOption: true, describe: `End date (ISO 8601 or YYYY-MM-DD) -- must be at most ${MAX_WORKED_HOURS_RANGE_DAYS} days after --start` }),
+    .option('end',   { type: 'string', demandOption: true, describe: `End date (ISO 8601 or YYYY-MM-DD; a plain date includes that whole day) -- must be at most ${MAX_WORKED_HOURS_RANGE_DAYS} days after --start` }),
   handler: async (argv) => {
     const start = new Date(argv.start);
     const end   = new Date(argv.end);
@@ -400,7 +401,7 @@ const workedHoursCommand = {
 
     let data;
     try {
-      data = await messagingRequest('POST', '/Reports/worked-hours-breakdown', { Start: start.toISOString(), End: end.toISOString() });
+      data = await messagingRequest('POST', '/Reports/worked-hours-breakdown', { Start: start.toISOString(), End: toExclusiveEnd(argv.end, end).toISOString() });
     } catch (err) {
       if (/403/.test(err.message)) {
         console.error('Time Tracking is not enabled for this account.');
@@ -678,6 +679,67 @@ const exportCommand = {
   handler: () => {},
 };
 
+// ── country performance ───────────────────────────────────────────────────────
+
+const countryGetCommand = {
+  command:  'get',
+  describe: 'Performance by Country (US / Canada / Europe / Other)',
+  builder:  (y) => y
+    .option('start',       { type: 'string', describe: 'Start date (YYYY-MM-DD), default 30 days ago' })
+    .option('end',         { type: 'string', describe: 'End date (YYYY-MM-DD), default now' })
+    .option('attribution', { type: 'string', choices: ['visitor', 'agent', 'group'], default: 'visitor', describe: 'visitor country, agent profile country, or assigned group' })
+    .option('channel',     { type: 'string', describe: 'Limit to one channel, e.g. Web or TwilioSms' })
+    .option('json',        { type: 'boolean', describe: 'Print raw JSON' }),
+  handler: runCommand(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 * 86400000);
+    const r = await messagingRequest('POST', '/reports/performance-by-country/query', {
+      start: start.toISOString(), end: end.toISOString(), attribution: argv.attribution,
+      channels: argv.channel ? [argv.channel] : [],
+    });
+    if (argv.json) { console.log(JSON.stringify(r, null, 2)); return; }
+    section(`Performance by Country (${r.attribution})`);
+    for (const b of r.buckets ?? []) {
+      fmtRow(b.bucket, `eng ${b.engagements}  handled ${b.handled}  missed ${b.missed}  abandoned ${b.abandoned}  csat ${fmtNum(b.csatAvg)} (${b.csatCount})`);
+    }
+    section('By agent');
+    for (const a of r.agents ?? []) {
+      fmtRow(a.agentName ?? '', `${a.bucket}  eng ${a.engagements}  handled ${a.handled}  csat ${fmtNum(a.csatAvg)}${a.agentCountryNotSet ? '  [country not set]' : ''}`);
+    }
+  }),
+};
+
+const countryGroupsCommand = {
+  command:  'groups',
+  describe: 'Show the site groups and their Performance by Country bucket; set mappings with --set <teamId>=<label>',
+  builder:  (y) => y.option('set', { type: 'array', describe: 'teamId=label (repeatable). REPLACES the whole mapping.' }),
+  handler: runCommand(async (argv) => {
+    const groups = await messagingRequest('GET', '/reports/performance-by-country/groups');
+    let current;
+    if (argv.set && argv.set.length) {
+      const map = {};
+      for (const pair of argv.set) {
+        const i = String(pair).indexOf('=');
+        if (i < 1) throw new Error(`--set expects teamId=label, got "${pair}"`);
+        map[String(pair).slice(0, i)] = String(pair).slice(i + 1);
+      }
+      current = await messagingRequest('PUT', '/reports/performance-by-country/group-map', { map });
+    } else {
+      current = await messagingRequest('GET', '/reports/performance-by-country/group-map');
+    }
+    const map = current?.map ?? {};
+    section('Groups');
+    for (const g of Array.isArray(groups) ? groups : []) fmtRow(`${g.id} ${g.name}`, map[g.id] ?? '(unmapped: Other)');
+  }),
+};
+
+const countryCommand = {
+  command:  'country',
+  describe: 'Performance by Country report and group-to-bucket mapping',
+  builder:  (y) => y.command(countryGetCommand).command(countryGroupsCommand).demandCommand(1, 'Specify: get | groups'),
+  handler: () => {},
+};
+
 // ── top-level report command ──────────────────────────────────────────────────
 
 export const reportCommand = {
@@ -692,6 +754,7 @@ export const reportCommand = {
     .command(visitorTrafficCommand)
     .command(schedulesCommand)
     .command(exportCommand)
+    .command(countryCommand)
     .demandCommand(1, 'Specify a report type. Run "velaro report --help" for options.'),
   handler: () => {},
 };

package/lib/commands/salesforce.js

@@ -0,0 +1,101 @@
+/**
+ * velaro salesforce — Salesforce integration diagnostics (OAuth, per-object read probes)
+ *
+ *   velaro salesforce diagnose --site-id <id> [--quick]   Live read-only diagnostic: config, auth, per-capability probes
+ *   velaro salesforce matrix --site-id <id>             Capability matrix vs live probes (same data as diagnose)
+ *
+ * Calls messaging DiagController GET /diagnostics/test-salesforce?siteId=<id>&deep=<bool> (Velaro staff only). Read-only:
+ * nothing is created or changed in Salesforce, and a write capability is never reported as verified.
+ */
+
+import { messagingRequest } from '../api.js';
+
+const GRN  = '\x1b[32m';
+const RED  = '\x1b[31m';
+const YEL  = '\x1b[33m';
+const DIM  = '\x1b[2m';
+const BOLD = '\x1b[1m';
+const RST  = '\x1b[0m';
+
+const ICON = { pass: `${GRN}✓${RST}`, warn: `${YEL}!${RST}`, fail: `${RED}✗${RST}`, skip: `${DIM}-${RST}` };
+
+async function fetchReport(argv, deep) {
+  const siteId = argv['site-id'];
+  if (!siteId) {
+    console.error(`${RED}✗ --site-id is required${RST}`);
+    process.exitCode = 1;
+    return null;
+  }
+  try {
+    const r = await messagingRequest('GET', `/diagnostics/test-salesforce?siteId=${encodeURIComponent(siteId)}&deep=${deep ? 'true' : 'false'}`);
+    return r?.report ?? r;
+  } catch (e) {
+    console.error(`\n${RED}✗ Diagnostic failed: ${e.message}${RST}\n`);
+    process.exitCode = 1;
+    return null;
+  }
+}
+
+function printSteps(report) {
+  console.log(`\n${BOLD}Salesforce diagnostic — site ${report.siteId ?? report.SiteId}${RST}  ${DIM}${report.product} / ${report.target}${RST}`);
+  console.log(`  overall: ${String(report.overall).toUpperCase()}\n`);
+  for (const s of report.steps ?? []) {
+    const ms = s.latencyMs != null ? `${DIM} (${s.latencyMs}ms)${RST}` : '';
+    console.log(`  ${ICON[s.status] ?? '?'} ${s.name}${ms}${s.detail ? `  ${DIM}${s.detail}${RST}` : ''}`);
+    if (s.hint) console.log(`      ${DIM}→ ${s.hint}${RST}`);
+  }
+}
+
+function printCapabilities(report) {
+  const caps = report.capabilities ?? [];
+  if (!caps.length) return;
+  console.log(`\n${BOLD}Capabilities${RST} ${DIM}(package = skill tier; live = read-only SOQL probe now; writes are never probed)${RST}\n`);
+  for (const c of caps) {
+    const live = c.liveOk === true ? `${GRN}live ok${RST}` : c.liveOk === false ? `${RED}live FAIL${RST}` : `${DIM}not probed${RST}`;
+    const proven = c.liveVerified ? `${GRN}verified${RST}` : `${DIM}unverified${RST}`;
+    console.log(`  ${c.capability.padEnd(38)} ${String(c.package).padEnd(9)} ${String(c.documented).padEnd(6)} ${live}  ${proven}`);
+    if (c.liveOk === false && c.hint) console.log(`      ${DIM}→ ${c.hint}${RST}`);
+  }
+  console.log('');
+}
+
+async function diagnoseHandler(argv) {
+  const report = await fetchReport(argv, !argv.quick);
+  if (!report) return;
+  if (argv.json) { console.log(JSON.stringify(report, null, 2)); return; }
+  printSteps(report);
+  printCapabilities(report);
+  if (report.overall === 'failed' || report.overall === 'not_configured') process.exitCode = 1;
+}
+
+async function matrixHandler(argv) {
+  const report = await fetchReport(argv, true);
+  if (!report) return;
+  if (argv.json) { console.log(JSON.stringify(report.capabilities ?? [], null, 2)); return; }
+  printCapabilities(report);
+}
+
+export const salesforceCommand = {
+  command:  'salesforce <subcommand>',
+  describe: 'Salesforce integration diagnostics (token, per-object read probes)',
+  builder: y => y
+    .command({
+      command:  'diagnose',
+      describe: 'Live read-only diagnostic: configuration, token, per-object probes',
+      builder: yy => yy
+        .option('site-id', { describe: 'Customer site id', type: 'number' })
+        .option('quick',   { describe: 'Skip per-capability probes', type: 'boolean', default: false })
+        .option('json',    { describe: 'Raw JSON output', type: 'boolean', default: false }),
+      handler: diagnoseHandler,
+    })
+    .command({
+      command:  'matrix',
+      describe: 'Capability matrix: package tier and what a live read probe proves',
+      builder: yy => yy
+        .option('site-id', { describe: 'Customer site id', type: 'number' })
+        .option('json',    { describe: 'Raw JSON output', type: 'boolean', default: false }),
+      handler: matrixHandler,
+    })
+    .demandCommand(1),
+  handler: () => {},
+};

package/lib/commands/shopify.js

@@ -0,0 +1,84 @@
+/**
+ * velaro shopify - Shopify write-tier policy (velaro-messaging ShopifyIntegrationsController)
+ *
+ *   velaro shopify write-policy get
+ *   velaro shopify write-policy set [--enable-shopify-write|--no-enable-shopify-write]
+ *        [--require-confirmation|--no-require-confirmation]
+ *        [--max-refund-amount N|default] [--max-discount-percent N|default]
+ *        [--max-discount-fixed-amount N|default]
+ *
+ * Backend contract: GET/PUT /api/Shopify/WritePolicy (velaro-messaging). Site is resolved
+ * server-side from the auth context, never caller-supplied. Partial update: omitted flags keep
+ * their stored value; the word "default" sends null, returning that cap to its default.
+ */
+
+import { messagingGet, messagingPut } from '../api.js';
+
+const GRN = '\x1b[32m';
+const BOLD = '\x1b[1m';
+const RST = '\x1b[0m';
+
+export function parseCap(v, name) {
+  if (v === undefined) return undefined;
+  if (v === null || String(v).toLowerCase() === 'default' || String(v).toLowerCase() === 'null') return null;
+  const n = Number(v);
+  if (!Number.isFinite(n) || n < 0) throw new Error(`--${name} must be a non-negative number or "default".`);
+  return n;
+}
+
+export function buildWritePolicyBody(argv) {
+  const body = {};
+  if (argv.enableShopifyWrite !== undefined) body.enableShopifyWrite = !!argv.enableShopifyWrite;
+  if (argv.requireConfirmation !== undefined) body.requireConfirmation = !!argv.requireConfirmation;
+  const caps = [
+    ['maxRefundAmount', 'max-refund-amount'],
+    ['maxDiscountPercent', 'max-discount-percent'],
+    ['maxDiscountFixedAmount', 'max-discount-fixed-amount'],
+  ];
+  for (const [key, flag] of caps) {
+    const v = parseCap(argv[key], flag);
+    if (v !== undefined) body[key] = v;
+  }
+  if (!Object.keys(body).length) throw new Error('Provide at least one option to change (see --help).');
+  return body;
+}
+
+function printPolicy(p) {
+  console.log(`\n${BOLD}Shopify write policy${RST}`);
+  console.log(`  Shopify write skills enabled:  ${p.enableShopifyWrite}`);
+  console.log(`  Require confirmation:          ${p.requireConfirmation}`);
+  console.log(`  Max refund amount:             ${p.maxRefundAmount}`);
+  console.log(`  Max discount percent:          ${p.maxDiscountPercent}`);
+  console.log(`  Max discount fixed amount:     ${p.maxDiscountFixedAmount}\n`);
+}
+
+async function getHandler() {
+  printPolicy(await messagingGet('/Shopify/WritePolicy'));
+}
+
+async function setHandler(argv) {
+  const updated = await messagingPut('/Shopify/WritePolicy', buildWritePolicyBody(argv));
+  console.log(`\n${GRN}✓${RST} Shopify write policy updated.`);
+  printPolicy(updated);
+}
+
+export const shopifyCommand = {
+  command: 'shopify <subcommand>',
+  describe: 'Shopify integration settings (write-tier policy: enable toggle, confirmation, refund/discount caps)',
+  builder: y => y
+    .command({
+      command: 'write-policy <action>',
+      describe: 'Get or set the Shopify write policy for this site',
+      builder: yy => yy
+        .positional('action', { choices: ['get', 'set'], type: 'string' })
+        .option('enable-shopify-write', { type: 'boolean', describe: 'Master toggle for the 11 Shopify write skills (reads unaffected)' })
+        .option('require-confirmation', { type: 'boolean', describe: 'Require customer confirmation before a write skill runs' })
+        .option('max-refund-amount', { type: 'string', describe: 'Max refund amount, or "default"' })
+        .option('max-discount-percent', { type: 'string', describe: 'Max percentage discount, or "default"' })
+        .option('max-discount-fixed-amount', { type: 'string', describe: 'Max fixed discount, or "default"' }),
+      handler: argv => (argv.action === 'get' ? getHandler() : setHandler(argv)),
+    })
+    .demandCommand(1, 'Specify a shopify subcommand.')
+    .strict(),
+  handler: () => {},
+};

package/lib/commands/signature.js

@@ -0,0 +1,79 @@
+import { messagingGet, messagingPut } from '../api.js';
+import { buildPolicyBody, findPolicy, describeMode, parseTeamId } from '../signature-policy.js';
+
+// velaro signature policy get|set
+//
+// Company email signature policy for the calling admin's site. Goes through GET/PUT Signatures/policy in
+// velaro-messaging (admin only there). The site comes from the caller's token, never from an argument.
+
+const GRN = '\x1b[32m';
+const DIM = '\x1b[2m';
+const BOLD = '\x1b[1m';
+const RESET = '\x1b[0m';
+
+function printRow(label, row) {
+  console.log(`${BOLD}${label}${RESET}`);
+  if (!row) { console.log(`  ${DIM}no override, follows the company-wide setting${RESET}`); return; }
+  console.log(`  mode        ${describeMode(row.mode)}`);
+  console.log(`  signature   ${row.corporateSignature ? `${row.corporateSignature.length} characters of HTML` : '(none)'}`);
+  const dis = row.disclaimerEnabled === null || row.disclaimerEnabled === undefined ? 'follows company-wide (off if none set)' : row.disclaimerEnabled ? 'on' : 'off';
+  console.log(`  disclaimer  ${dis}`);
+  if (row.disclaimerText) console.log(`  text        ${row.disclaimerText}`);
+}
+
+const getCommand = {
+  command: 'get',
+  describe: 'Show the company signature policy and any per-team overrides',
+  builder: (y) => y.option('team-id', { type: 'number', describe: 'Show only this team override (0 = company-wide)' }),
+  handler: async (argv) => {
+    const data = await messagingGet('/Signatures/policy');
+    const rows = Array.isArray(data.policies) ? data.policies : [];
+    if (argv['team-id'] !== undefined) {
+      printRow(`Team ${argv['team-id']}`, findPolicy(rows, argv['team-id']));
+    } else {
+      printRow('Company-wide', findPolicy(rows, 0));
+      for (const r of rows.filter((p) => p.teamId !== 0)) printRow(`Team ${r.teamId}`, r);
+    }
+    console.log(`\n${DIM}Suggested disclaimer:${RESET} ${data.suggestedDisclaimer ?? ''}`);
+  },
+};
+
+const setCommand = {
+  command: 'set',
+  describe: 'Update the signature policy (only the options you pass change; default clears back to company-wide)',
+  builder: (y) => y
+    .option('team-id', { type: 'number', default: 0, describe: '0 = company-wide, otherwise a per-team override' })
+    .option('mode', { type: 'string', describe: 'locked | company-default | personal-only | default' })
+    .option('signature', { type: 'string', describe: 'Company signature HTML (empty string clears it)' })
+    .option('disclaimer', { type: 'boolean', describe: 'Turn the legal disclaimer on or off' })
+    .option('disclaimer-default', { type: 'boolean', describe: 'Clear the disclaimer on/off choice back to company-wide' })
+    .option('disclaimer-text', { type: 'string', describe: 'Legal disclaimer text (empty string clears it)' }),
+  handler: async (argv) => {
+    const teamId = parseTeamId(argv['team-id']);
+    const data = await messagingGet('/Signatures/policy');
+    const current = findPolicy(data.policies, teamId);
+    const body = buildPolicyBody(current, {
+      teamId,
+      mode: argv.mode,
+      corporateSignature: argv.signature,
+      disclaimerEnabled: argv['disclaimer-default'] ? null : argv.disclaimer,
+      disclaimerText: argv['disclaimer-text'],
+    });
+    await messagingPut('/Signatures/policy', body);
+    console.log(`${GRN}Signature policy updated.${RESET} Run \`velaro signature policy get\` to review.`);
+  },
+};
+
+const policyCommand = {
+  command: 'policy <subcommand>',
+  describe: 'View and update the company email signature policy',
+  builder: (y) => y.command(getCommand).command(setCommand).demandCommand(1, 'Specify a subcommand: get | set'),
+  handler: () => {},
+};
+
+export const signatureCommand = {
+  command: 'signature <subcommand>',
+  describe: 'Email signature controls',
+  builder: (y) => y.command(policyCommand).demandCommand(1, 'Specify: policy get | policy set'),
+  handler: () => {},
+};