@velaro/cli 1.4.104 → 1.4.106

package/bin/velaro.js

@@ -12,6 +12,7 @@ import { ingestCommand }     from '../lib/commands/ingest.js';
 import { indexMoveCommand }  from '../lib/commands/index-move.js';
 import { safetyCommand }     from '../lib/commands/safety.js';
 import { knowledgeAdvisorCommand } from '../lib/commands/knowledge-advisor.js';
+import { knowledgeCommand } from '../lib/commands/knowledge.js';
 import { productCommand }    from '../lib/commands/product.js';
 import { mcpKeyCommand }     from '../lib/commands/mcp-key.js';
 import { opsCommand }        from '../lib/commands/ops.js';
@@ -63,6 +64,7 @@ import { keywordIntelligenceCommand } from '../lib/commands/keyword-intelligence
 import { aiFieldExtractionCommand } from '../lib/commands/ai-field-extraction.js';
 import { sentimentCommand, qualityCommand, chatIntelligenceThemesCommand } from '../lib/commands/quality-reports.js';
 import { cannedLearningCommand } from '../lib/commands/canned-learning.js';
+import { csatOverrideUnapproveCommand } from '../lib/commands/csat-override.js';
 import { chatIntelligenceTopicsCommand } from '../lib/commands/chat-intelligence-topics.js';
 import { focusCommand }       from '../lib/commands/focus.js';
 import { triageCommand }      from '../lib/commands/triage.js';
@@ -98,6 +100,7 @@ import { orderFormCommand } from '../lib/commands/order-form.js';
 import { billingEmailPreferenceCommand } from '../lib/commands/billing-email-preference.js';
 import { billingCommand }         from '../lib/commands/billing.js';
 import { couponGrantCommand }     from '../lib/commands/coupon-grant.js';
+import { signCommand } from '../lib/commands/sign.js';
 import { widgetContainerCommand }  from '../lib/commands/widget-container.js';
 import { inlineWidgetConfigCommand } from '../lib/commands/inline-widget-config.js';
 import { pricingCommand }          from '../lib/commands/pricing.js';
@@ -107,6 +110,7 @@ import { supportCommand }           from '../lib/commands/support.js';
 import { routingCommand }           from '../lib/commands/routing.js';
 import { diagnosticsCommand }       from '../lib/commands/diagnostics.js';
 import { aiSpendCommand }           from '../lib/commands/ai-spend.js';
+import { skillUsageCommand }        from '../lib/commands/skill-usage.js';
 import { aiFederationCommand }       from '../lib/commands/ai-federation.js';
 import { statusPageCommand }        from '../lib/commands/status-page.js';
 import { statusNotifyCommand }      from '../lib/commands/status-notify.js';
@@ -115,6 +119,8 @@ import { emailInboxCommand }        from '../lib/commands/email-inbox.js';
 import { callbackCommand }          from '../lib/commands/callback.js';
 import { caseCommand }              from '../lib/commands/case.js';
 import { pickupCommand }            from '../lib/commands/pickup.js';
+import { visitorMonitorCommand }    from '../lib/commands/visitor-monitor.js';
+import { visitorLinkCommand }      from '../lib/commands/visitor-link.js';
 import { applePayCommand }         from '../lib/commands/apple-pay.js';
 import { siteBuilderCommand }        from '../lib/commands/site-builder.js';
 import { paymentRecoveryCommand }   from '../lib/commands/payment-recovery.js';
@@ -125,6 +131,7 @@ import { chatWindowCommand }        from '../lib/commands/chat-window.js';
 import { featureDiscoveryCommand }  from '../lib/commands/feature-discovery.js';
 import { tourPolicyCommand }  from '../lib/commands/tour-policy.js';
 import { scraperCommand }      from '../lib/commands/scraper.js';
+import { usageCommand }        from '../lib/commands/usage.js';
 import { campaignsCommand }         from '../lib/commands/campaigns.js';
 import { senderDomainHealthCommand } from '../lib/commands/sender-domain-health.js';
 import { contactsCommand }          from '../lib/commands/contacts.js';
@@ -156,6 +163,7 @@ await yargs(hideBin(process.argv))
   .command(indexMoveCommand)
   .command(safetyCommand)
   .command(knowledgeAdvisorCommand)
+  .command(knowledgeCommand)
   .command(productCommand)
   .command(mcpKeyCommand)
   .command(opsCommand)
@@ -210,6 +218,7 @@ await yargs(hideBin(process.argv))
   .command(chatIntelligenceThemesCommand)
   .command(cannedLearningCommand)
   .command(chatIntelligenceTopicsCommand)
+  .command(csatOverrideUnapproveCommand)
   .command(focusCommand)
   .command(triageCommand)
   .command(automationDraftCommand)
@@ -244,6 +253,7 @@ await yargs(hideBin(process.argv))
   .command(billingEmailPreferenceCommand)
   .command(billingCommand)
   .command(couponGrantCommand)
+  .command(signCommand)
   .command(widgetContainerCommand)
   .command(inlineWidgetConfigCommand)
   .command({ command: 'pricing', desc: 'View and manage the pricing catalog', builder: pricingCommand, handler: () => {} })
@@ -253,6 +263,7 @@ await yargs(hideBin(process.argv))
   .command(routingCommand)
   .command(diagnosticsCommand)
   .command(aiSpendCommand)
+  .command(skillUsageCommand)
   .command(aiFederationCommand)
   .command(statusPageCommand)
   .command(statusNotifyCommand)
@@ -261,6 +272,8 @@ await yargs(hideBin(process.argv))
   .command(callbackCommand)
   .command(caseCommand)
   .command(pickupCommand)
+  .command(visitorMonitorCommand)
+  .command(visitorLinkCommand)
   .command(applePayCommand)
   .command(siteBuilderCommand)
   .command(paymentRecoveryCommand)
@@ -269,6 +282,7 @@ await yargs(hideBin(process.argv))
   .command(bundleCommand)
   .command(chatWindowCommand)
   .command({ command: 'feature-discovery', desc: 'View and act on feature-discovery suggestions for this site', builder: featureDiscoveryCommand, handler: () => {} })
+  .command(usageCommand)
   .command({ command: 'scraper', desc: 'Velaro staff: scraper / upload / chunk usage for any site', builder: scraperCommand, handler: () => {} })
   .command({ command: 'tour-policy', desc: 'Velaro staff: guided-tour auto-open policy (versioned, rollback-able)', builder: tourPolicyCommand, handler: () => {} })
   .command(campaignsCommand)

package/lib/commands/ai-config.js

@@ -84,7 +84,7 @@ const aiConfigCreateCommand = {
     y
       .option('name',        { type: 'string',  describe: 'Configuration name' })
       .option('prompt',      { type: 'string',  describe: 'System prompt text' })
-      .option('model',       { type: 'string',  describe: 'Model (e.g. gpt-4o-mini, claude-haiku-4-5)' })
+      .option('model',       { type: 'string',  describe: 'Model (e.g. gpt-4o-mini, claude-haiku-5-5)' })
       .option('tone',        { type: 'string',  describe: 'Tone (e.g. friendly, professional)' })
       .option('language',    { type: 'string',  default: 'en', describe: 'Language code' })
       .option('reply-length',{ type: 'string',  describe: 'Reply length (e.g. short, medium, long)' })

package/lib/commands/csat-override.js

@@ -0,0 +1,14 @@
+import { messagingPost } from '../api.js';
+import { runCommand } from '../run.js';
+
+// velaro csat-override-unapprove <id>
+// REST: messaging POST /api/intelligence/csat-override-candidates/{id}/unapprove (site comes from the CLI session)
+export const csatOverrideUnapproveCommand = {
+  command: 'csat-override-unapprove <id>',
+  describe: 'Return an approved Chat Intelligence improvement candidate to Pending (deactivates the override, removes any vectorized copy)',
+  builder: (y) => y.positional('id', { type: 'number', describe: 'Approved override candidate id' }),
+  handler: runCommand(async (a) => {
+    if (!Number.isInteger(a.id) || a.id <= 0) throw new Error('id must be a positive integer');
+    console.log(JSON.stringify(await messagingPost(`/api/intelligence/csat-override-candidates/${a.id}/unapprove`, {}), null, 2));
+  }),
+};

package/lib/commands/enterprise-reports.js

@@ -21,6 +21,9 @@ const REPORTS = {
   'promise-ledger': 'Agent commitments made in chat and whether a follow-up appeared; overdue list',
   'new-agent-ramp': 'Agents whose first chat is in --from/--to: week-by-week ramp (chats, first response, QA, rating) against tenured agents',
   'promise-dismiss': 'Dismiss one promise by --id (managers only)',
+  'bonus': 'Bonus insights, pick one with --name: ' + 'coverage_gap | next_best_fix | escalation_risk | skill_gap_matrix | handle_quality_outliers | abandon_causes' + ' (deterministic, no AI cost; assumptions are echoed in the result)',
+  'operations-briefing': 'One run of every package report from a single data load, plus one cached token-capped AI narrative (--no-narrative skips it); reports its own AI cost',
+  'entitled': 'Which Enterprise Reports items this site holds (includes Entry-point routing and Automatic tagging, which have no report of their own)',
   'weekly-brief-send-test': 'Email this week\'s brief to the signed-in user',
   'year-in-review': 'Build the 12-month Year in review document: --from/--to (default last 12 whole Pacific months) starts a build and prints its id; --id <id> checks status and the download link',
 };
@@ -46,6 +49,13 @@ export const enterpriseReportsCommand = {
     .option('time-zone', { type: 'string', describe: 'demand-coverage: IANA time zone (default America/Los_Angeles)' })
     .option('low-score', { type: 'number', describe: 'bot-containment: QA score below which a handed-off chat counts as regret (1-100, default 60)' })
     .option('include-demo', { type: 'boolean', describe: 'Show only the seeded sample (demo) data' })
+    .option('name', { type: 'string', describe: 'bonus: which analysis (coverage_gap|next_best_fix|escalation_risk|skill_gap_matrix|handle_quality_outliers|abandon_causes)' })
+    .option('narrative', { type: 'boolean', describe: 'operations-briefing: include the AI narrative (default true; --no-narrative to skip)' })
+    .option('minutes-per-review', { type: 'number', describe: 'bonus: assumed minutes per manual review (0-240)' })
+    .option('hourly-cost', { type: 'number', describe: 'bonus: assumed reviewer hourly cost (0-1000)' })
+    .option('deflection-pct', { type: 'number', describe: 'bonus: assumed deflection percent (0-100)' })
+    .option('cost-per-chat', { type: 'number', describe: 'bonus: assumed cost per chat (0-1000)' })
+    .option('wait-minutes', { type: 'number', describe: 'bonus: wait minutes that counts as abandoned (1-1440)' })
     .option('id', { type: 'string', describe: 'promise-dismiss: the promise id; year-in-review: the build id to check' }),
   handler:  runCommand(async (argv) => {
     if (argv.report === 'weekly-brief-send-test') {
@@ -66,10 +76,15 @@ export const enterpriseReportsCommand = {
       console.log(JSON.stringify(await messagingPost(`/api/enterprise-reports/promise-ledger/${encodeURIComponent(String(argv.id))}/dismiss`, {}), null, 2));
       return;
     }
+    let seg = argv.report;
+    if (argv.report === 'bonus') {
+      if (!argv.name) throw new Error('--name is required for bonus (coverage_gap|next_best_fix|escalation_risk|skill_gap_matrix|handle_quality_outliers|abandon_causes)');
+      seg = `bonus/${encodeURIComponent(String(argv.name).replace(/-/g, '_'))}`;
+    }
     const qs = new URLSearchParams();
-    const map = { from: 'from', to: 'to', groupBy: 'groupBy', deploymentId: 'deploymentId', teamId: 'teamId', threshold: 'threshold', perAgent: 'perAgent', limit: 'limit', days: 'days', windowDays: 'windowDays', weeks: 'weeks', handleMinutes: 'handleMinutes', maxConcurrent: 'maxConcurrent', timeZone: 'timeZone', lowScore: 'lowScore', includeDemo: 'includeDemo' };
+    const map = { minutesPerReview: 'minutesPerReview', hourlyCost: 'hourlyCost', deflectionPct: 'deflectionPct', costPerChat: 'costPerChat', waitMinutes: 'waitMinutes', narrative: 'narrative', from: 'from', to: 'to', groupBy: 'groupBy', deploymentId: 'deploymentId', teamId: 'teamId', threshold: 'threshold', perAgent: 'perAgent', limit: 'limit', days: 'days', windowDays: 'windowDays', weeks: 'weeks', handleMinutes: 'handleMinutes', maxConcurrent: 'maxConcurrent', timeZone: 'timeZone', lowScore: 'lowScore', includeDemo: 'includeDemo' };
     for (const [arg, key] of Object.entries(map)) if (argv[arg] != null && argv[arg] !== '') qs.set(key, String(argv[arg]));
     const q = qs.toString();
-    console.log(JSON.stringify(await messagingGet(`/api/enterprise-reports/${argv.report}${q ? `?${q}` : ''}`), null, 2));
+    console.log(JSON.stringify(await messagingGet(`/api/enterprise-reports/${seg}${q ? `?${q}` : ''}`), null, 2));
   }),
 };

package/lib/commands/knowledge.js

@@ -0,0 +1,114 @@
+// velaro knowledge clinical-text get|set -- emergency and safety wording per channel and language.
+// Backend: velaro-messaging KnowledgeSetupController. Customer routes take the site from auth
+// (GET KnowledgeSetup/state, PUT KnowledgeSetup/clinical-text); --site switches to the staff twins
+// (GET/PUT KnowledgeSetup/Staff/{siteId}/...), Velaro super admin only.
+import fs from 'node:fs';
+import { messagingGet, messagingPut } from '../api.js';
+import { runCommand } from '../run.js';
+
+const CHANNELS = ['chat', 'voice', 'sms', 'whatsapp', 'email'];
+
+export function basePath(site) {
+  return site ? `/KnowledgeSetup/Staff/${encodeURIComponent(site)}` : '/KnowledgeSetup';
+}
+
+/** Key is default | channel | lang | lang.channel (es.voice). Value is the wording. */
+export function parseEntries(list) {
+  const out = {};
+  for (const raw of [].concat(list ?? [])) {
+    const i = String(raw).indexOf('=');
+    if (i < 1) throw new Error(`Expected key=text (for example es.voice="..."), got: ${raw}`);
+    out[String(raw).slice(0, i).trim().toLowerCase()] = String(raw).slice(i + 1);
+  }
+  return out;
+}
+
+export function buildBody(argv) {
+  if (argv.reset) return { resetToDefault: true };
+  let body = {};
+  if (argv.file) body = JSON.parse(fs.readFileSync(argv.file, 'utf8'));
+  const em = parseEntries(argv.emergency);
+  const rf = parseEntries(argv.referral);
+  if (Object.keys(em).length) body.emergency = { ...(body.emergency ?? {}), ...em };
+  if (Object.keys(rf).length) body.referral = { ...(body.referral ?? {}), ...rf };
+  if (argv['emergency-number'] !== undefined) body.emergencyNumber = argv['emergency-number'];
+  if (argv['service-mode'] !== undefined || argv['service-mode-text'] !== undefined) {
+    body.emergencyServiceMode = {};
+    if (argv['service-mode'] !== undefined) body.emergencyServiceMode.enabled = argv['service-mode'];
+    if (argv['service-mode-text'] !== undefined) body.emergencyServiceMode.text = argv['service-mode-text'];
+    if (argv.confirm) body.emergencyServiceMode.confirm = true;
+  }
+  return body;
+}
+
+export function printState(ct) {
+  console.log(`\nEmergency number: ${ct.overrides?.emergencyNumber || `(default) ${ct.defaultEmergencyNumber}`}`);
+  console.log(`Limits: ${ct.limits?.minLength}-${ct.limits?.maxLength} characters. Emergency text must keep ${ct.placeholder}.`);
+  console.log(`Supported languages: ${(ct.supportedLanguages ?? []).join(', ') || '-'}`);
+  const m = ct.emergencyServiceMode;
+  console.log(`Emergency-service mode: ${m?.enabled ? 'ON' : 'off'}${m?.text ? ` | text: ${m.text}` : ''} (staff only)`);
+  console.log('Custom wording (key = text):');
+  for (const kind of ['emergency', 'referral']) {
+    const e = Object.entries(ct.overrides?.[kind] ?? {});
+    if (!e.length) console.log(`  ${kind}: none, built-in wording`);
+    for (const [k, v] of e) console.log(`  ${kind}.${k} = ${v}`);
+  }
+  console.log('Effective English wording per channel:');
+  for (const c of CHANNELS) {
+    const x = ct.effective?.[c];
+    if (x) console.log(`  ${c}: emergency "${x.emergency}" | referral "${x.referral}"`);
+  }
+}
+
+const clinicalGet = {
+  command: 'get',
+  describe: 'Show emergency/safety wording, supported languages and emergency-service mode',
+  builder: (y) => y
+    .option('site', { type: 'number', describe: 'Target site ID (Velaro staff only; omit for your own site)' })
+    .option('json', { type: 'boolean', default: false }),
+  handler: runCommand(async (argv) => {
+    const state = await messagingGet(`${basePath(argv.site)}/state`);
+    const ct = state?.clinicalText;
+    if (!ct) throw new Error('The setup state did not include clinicalText (backend too old?).');
+    if (argv.json) { console.log(JSON.stringify(ct, null, 2)); return; }
+    printState(ct);
+  }),
+};
+
+const clinicalSet = {
+  command: 'set',
+  describe: 'Set emergency/safety wording. Entries replace the stored set: pass every override you want to keep (use get --json).',
+  builder: (y) => y
+    .option('site', { type: 'number', describe: 'Target site ID (Velaro staff only)' })
+    .option('emergency', { type: 'array', string: true, describe: 'key=text, key is default|chat|voice|sms|whatsapp|email|<lang>|<lang>.<channel>; must contain {emergencyNumber}' })
+    .option('referral', { type: 'array', string: true, describe: 'key=text, same keys as --emergency' })
+    .option('emergency-number', { type: 'string', describe: 'Replaces {emergencyNumber}' })
+    .option('file', { type: 'string', describe: 'JSON body { emergency, referral, emergencyNumber }' })
+    .option('reset', { type: 'boolean', default: false, describe: 'Clear all custom wording' })
+    .option('service-mode', { type: 'boolean', describe: 'Staff only (--site): turn emergency-service mode on/off' })
+    .option('service-mode-text', { type: 'string', describe: 'Staff only: required emergency text for service mode (20-600 chars)' })
+    .option('confirm', { type: 'boolean', default: false, describe: 'Required to turn service mode on' })
+    .option('json', { type: 'boolean', default: false }),
+  handler: runCommand(async (argv) => {
+    const body = buildBody(argv);
+    if (body.emergencyServiceMode && !argv.site) throw new Error('Emergency-service mode is staff only: pass --site <id>.');
+    const r = await messagingPut(`${basePath(argv.site)}/clinical-text`, body);
+    if (argv.json) { console.log(JSON.stringify(r, null, 2)); return; }
+    console.log(r.changed ? 'Saved.' : 'No change.');
+    if (r.clinicalText) printState(r.clinicalText);
+  }),
+};
+
+export const knowledgeCommand = {
+  command: 'knowledge <subcommand>',
+  describe: 'Knowledge setup safety settings',
+  builder: (y) => y
+    .command({
+      command: 'clinical-text <action>',
+      describe: 'Emergency and safety messages per channel and language',
+      builder: (yy) => yy.command(clinicalGet).command(clinicalSet).demandCommand(1, 'Specify get or set'),
+      handler: () => {},
+    })
+    .demandCommand(1, 'Specify a subcommand: clinical-text'),
+  handler: () => {},
+};

package/lib/commands/netsuite.js

@@ -43,6 +43,13 @@ async function listHandler() {
   printConfigs(configs);
 }
 
+async function rollbackAuthHandler(argv) {
+  const r = await messagingPost('/NetSuite/Auth/RollbackAuthType', { id: argv.configId });
+  console.log(`
+  ${GRN}✓${RST} Config ${r?.id ?? argv.configId} switched back to ${r?.authType ?? 'oauth1'}.
+`);
+}
+
 async function urlsHandler(argv) {
   const urls = await messagingGet(`/NetSuite/Integrations/${argv.configId}/CtiUrls`);
   printUrls(urls);
@@ -147,6 +154,17 @@ export const netsuiteCommand = {
         .strict(),
       handler: () => {},
     })
+    .command({
+      command:  'embed-status',
+      describe: 'Alias of: embed status',
+      handler:  embedStatusHandler,
+    })
+    .command({
+      command:  'rollback-auth <configId>',
+      describe: 'Undo a switch to OAuth 2.0/M2M: restore OAuth 1.0a (only while old credentials still exist)',
+      builder: a => a.positional('configId', { type: 'number' }),
+      handler:  rollbackAuthHandler,
+    })
     .command({
       command:  'suiteapp',
       describe: 'Download the screen-pop SuiteApp zip (key included by default: no API Secret to create)',

package/lib/commands/quality-reports.js

@@ -71,18 +71,26 @@ const calibration = {
 
 const rubric = {
   command: 'rubric <action>',
-  describe: 'QA rubrics: list | get | default | create | update | delete (--json for the rubric body)',
-  builder: (y) => y.positional('action', { choices: ['list', 'get', 'default', 'create', 'update', 'delete'] })
-    .option('id', { type: 'number' }).option('json', { type: 'string', describe: 'Rubric JSON body' }),
+  describe: 'QA rubrics: list | get | default | starter | create | update | clone | activate | deactivate | rescore | delete (--json for the rubric body)',
+  builder: (y) => y.positional('action', { choices: ['list', 'get', 'default', 'starter', 'create', 'update', 'clone', 'activate', 'deactivate', 'rescore', 'delete'] })
+    .option('id', { type: 'number' }).option('json', { type: 'string', describe: 'Rubric JSON body' })
+    .option('name', { type: 'string', describe: 'clone: name of the copy' })
+    .option('days', { type: 'number', default: 30, describe: 'rescore: look back this many days (1-90)' })
+    .option('limit', { type: 'number', default: 200, describe: 'rescore: max chats (1-500)' }),
   handler: runCommand(async (a) => {
     const base = '/api/admin/QualityQa/rubrics';
     const body = a.json ? JSON.parse(a.json) : {};
     if (a.action === 'list') return print(await messagingGet(base));
     if (a.action === 'default') return print(await messagingGet(`${base}/default`));
+    if (a.action === 'starter') return print(await messagingPost(`${base}/starter`, {}));
+    if (a.action === 'rescore') return print(await messagingPost(`/api/admin/QualityQa/rescore?days=${a.days}&limit=${a.limit}`, {}));
     if (a.action === 'create') return print(await messagingPost(base, body));
     if (a.id == null) throw new Error('--id is required');
     if (a.action === 'get') return print(await messagingGet(`${base}/${a.id}`));
     if (a.action === 'update') return print(await messagingPut(`${base}/${a.id}`, body));
+    if (a.action === 'clone') return print(await messagingPost(`${base}/${a.id}/clone`, a.name ? { name: a.name } : {}));
+    if (a.action === 'activate') return print(await messagingPut(`${base}/${a.id}`, { isActive: true }));
+    if (a.action === 'deactivate') return print(await messagingPut(`${base}/${a.id}`, { isActive: false }));
     print(await messagingDel(`${base}/${a.id}`));
   }),
 };

package/lib/commands/sign.js

@@ -0,0 +1,49 @@
+// velaro sign - Velaro Sign document versions (owner-only). REST: GET /api/Contract/{id}/versions,
+// GET /api/Contract/{id}/diff, POST /api/Contract/{id}/document (multipart, draft only).
+import { getCredentials, get } from '../api.js';
+import {
+  versionsPath, diffPath, uploadPath, describeVersions, describeDiff, buildUploadForm, OWNER_ONLY_RULE,
+} from '../sign-versions.js';
+
+async function versions(id, json) {
+  const res = await get(versionsPath(id));
+  console.log(json ? JSON.stringify(res, null, 2) : describeVersions(res));
+}
+
+async function diff(id, from, to, json) {
+  const res = await get(diffPath(id, from, to));
+  console.log(json ? JSON.stringify(res, null, 2) : describeDiff(res));
+}
+
+async function uploadVersion(id, file, note) {
+  const creds = await getCredentials();
+  const form = buildUploadForm(file, note);
+  const base = String(creds.adminApiBase).replace(/\/+$/, '');
+  const res = await fetch(`${base}${uploadPath(id)}`, {
+    method: 'POST',
+    headers: { Authorization: `Bearer ${creds.velaroToken}` },
+    body: form,
+  });
+  const text = await res.text();
+  if (!res.ok) throw new Error(`POST ${uploadPath(id)} -> ${res.status}: ${text.slice(0, 300)}\n${OWNER_ONLY_RULE}`);
+  console.log(`Uploaded new version for contract ${id}.`);
+  console.log(describeVersions(await get(versionsPath(id))));
+}
+
+export const signCommand = {
+  command: 'sign <subcommand>',
+  describe: 'Velaro Sign document versions (owner-only; signers never see old versions)',
+  builder: (yargs) =>
+    yargs
+      .command('versions <contractId>', 'List every uploaded document version of a contract', {
+        json: { type: 'boolean', default: false },
+      }, (a) => versions(a.contractId, a.json))
+      .command('diff <contractId> <from> <to>', 'Text diff between two document versions', {
+        json: { type: 'boolean', default: false },
+      }, (a) => diff(a.contractId, a.from, a.to, a.json))
+      .command('upload-version <contractId> <file>', 'Upload a new PDF version (draft contracts only; after send/sign void and re-send)', {
+        note: { type: 'string', describe: 'Change note stored with the version' },
+      }, (a) => uploadVersion(a.contractId, a.file, a.note))
+      .demandCommand(1, 'Specify: versions | diff | upload-version'),
+  handler: () => {},
+};

package/lib/commands/skill-usage.js

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

package/lib/commands/teams-phone.js

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

package/lib/commands/usage.js

@@ -0,0 +1,28 @@
+// velaro usage alerts — plan-limit alerts for the authenticated site (GET Usage/alerts on the messaging API).
+// Same rules as the usage-limit emails and the dashboard banner; site comes from auth, never an argument.
+import { messagingGet } from '../api.js';
+
+async function alerts(argv) {
+  const r = await messagingGet('/Usage/alerts');
+  if (argv.json) { console.log(JSON.stringify(r, null, 2)); return; }
+  if (!r.alerts?.length) { console.log('\nNo plan-limit alerts. Every metered resource is under its warning threshold.'); return; }
+  console.log(`\nPlan-limit alerts (${r.alerts.length})\n${'─'.repeat(50)}`);
+  for (const a of r.alerts) {
+    const tag = a.level === 'limit' ? 'LIMIT REACHED' : a.level === 'critical' ? 'CRITICAL' : 'WARNING';
+    console.log(`  [${tag}] ${a.displayName}: ${a.current.toLocaleString('en-US')} of ${a.limit.toLocaleString('en-US')} (${a.percent}%)${a.softLimit ? '  overage is billed' : ''}`);
+  }
+  console.log('\nRequest more capacity: Billing > Contact Account Manager, or email sales@velaro.com.');
+}
+
+// Object form (not a bare builder) so cli/bin/velaro.js registers it like every other group and the
+// CLI/MCP group-parity check (scripts/validate-cli-mcp-group-parity.js) can see the "usage" group.
+export const usageCommand = {
+  command:  'usage <subcommand>',
+  describe: 'Plan-limit usage and alerts for this site',
+  builder:  (y) => y
+    .command('alerts', 'Show plan-limit alerts (resources at or above the warning threshold)', (y2) => y2
+      .option('json', { type: 'boolean', describe: 'Print raw JSON' }), (a) => alerts(a))
+    .demandCommand(1, 'Specify a subcommand: alerts')
+    .strict(),
+  handler: () => {},
+};

package/lib/commands/visitor-link.js

@@ -0,0 +1,90 @@
+import { messagingGet, messagingPost, messagingPut } from '../api.js';
+import { runCommand } from '../run.js';
+import { diagnoseLink, validateSettingsArgs } from '../visitor-link.js';
+
+// ── velaro visitor-link ────────────────────────────────────────────────────────
+// Signed visitor link: lets a chat visitor be tied to a later form or survey submission.
+// Off by default per site; a link is only minted for a visitor who has chatted and (when the site uses a
+// consent banner) granted functional storage. siteId comes from the session, never a CLI arg.
+//
+// Backend contract: server/Velaro.Messaging/Controllers/VisitorLinkControllers.cs (messaging)
+//   GET  SiteSettings/visitor-linking              -> { enabled, ttlMinutes, keyConfigured }
+//   PUT  SiteSettings/visitor-linking              { enabled?, ttlMinutes? (1..1440) } -> same shape
+//   POST api/v1/visitor-links/resolve              { token } -> { data: { visitorId, conversationBaseId, contactId }, error }
+
+const BOLD = '\x1b[1m';
+const GRN = '\x1b[32m';
+const YEL = '\x1b[33m';
+const RST = '\x1b[0m';
+
+function printSettings(s) {
+  console.log(`\n${BOLD}Visitor linking${RST}`);
+  console.log(`  Enabled:       ${s.enabled ? GRN + 'on' + RST : 'off'}`);
+  console.log(`  Link lifetime: ${s.ttlMinutes} minutes`);
+  console.log(`  Signing key:   ${s.keyConfigured ? 'configured' : YEL + 'NOT configured (links fail closed)' + RST}\n`);
+}
+
+async function getHandler() {
+  printSettings(await messagingGet('/SiteSettings/visitor-linking'));
+}
+
+async function setHandler(argv) {
+  const body = validateSettingsArgs({ enabled: argv.enabled, ttlMinutes: argv.ttlMinutes });
+  printSettings(await messagingPut('/SiteSettings/visitor-linking', body));
+}
+
+async function resolveHandler(argv) {
+  const r = await messagingPost('/api/v1/visitor-links/resolve', { token: argv.token });
+  const d = r?.data ?? r;
+  console.log(`\n${GRN}✓${RST} Token resolved`);
+  console.log(`  Visitor:      ${d.visitorId}`);
+  console.log(`  Conversation: ${d.conversationBaseId ?? '(none)'}`);
+  console.log(`  Contact:      ${d.contactId ?? '(none)'}\n`);
+}
+
+async function diagnoseHandler(argv) {
+  const settings = await messagingGet('/SiteSettings/visitor-linking');
+  const d = diagnoseLink({ token: argv.token, settings });
+  printSettings(settings);
+  if (argv.token) console.log(`  Token claims: ${JSON.stringify(d.claims)}`);
+  console.log(d.healthy ? `\n${GRN}✓${RST} No problems found.\n` : `\n${YEL}Findings${RST}\n${d.findings.map((f) => '  - ' + f).join('\n')}\n`);
+}
+
+const getCommand = { command: 'get', describe: 'Show visitor-linking settings for this site', builder: (y) => y, handler: runCommand(getHandler) };
+const setCommand = {
+  command: 'set',
+  describe: 'Turn visitor linking on/off and set the link lifetime',
+  builder: (y) => y
+    .option('enabled', { describe: 'Enable (true) or disable (false) visitor linking', type: 'boolean' })
+    .option('ttl-minutes', { describe: 'Link lifetime in minutes, 1-1440', type: 'number' }),
+  handler: runCommand(setHandler),
+};
+const settingsCommand = {
+  command: 'settings <action>',
+  describe: 'Get or set visitor-linking settings',
+  builder: (y) => y.command(getCommand).command(setCommand).demandCommand(1, 'Specify: get | set'),
+  handler: () => {},
+};
+const resolveCommand = {
+  command: 'resolve <token>',
+  describe: 'Exchange a link token for the visitor and conversation ids (what your server does)',
+  builder: (y) => y.positional('token', { type: 'string', describe: 'vlk1 token from the form hidden field' }),
+  handler: runCommand(resolveHandler),
+};
+const diagnoseCommand = {
+  command: 'diagnose [token]',
+  describe: 'Check settings and, optionally, why a specific link token would fail',
+  builder: (y) => y.positional('token', { type: 'string', describe: 'Optional vlk1 token to inspect' }),
+  handler: runCommand(diagnoseHandler),
+};
+
+export const visitorLinkCommand = {
+  command: 'visitor-link <subcommand>',
+  describe: 'Link chat visitors to later form and survey submissions (settings, resolve, diagnose)',
+  builder: (y) => y
+    .command(settingsCommand)
+    .command(resolveCommand)
+    .command(diagnoseCommand)
+    .demandCommand(1, 'Specify a visitor-link subcommand: settings | resolve | diagnose'),
+  handler: () => {},
+};

package/lib/commands/visitor-monitor.js

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

package/lib/enterprise-reports.test.js

@@ -10,6 +10,23 @@ test('describe lists the five novel reports and the promise dismiss action', ()
   }
 });
 
+// Parity burn-down (2026-10-14): Bonus insights, Operations Briefing and the shared `entitled` view (which also covers
+// Entry-point routing and Automatic tagging, items without a report route) are on the CLI and the MCP tool.
+test('describe lists bonus, operations-briefing and entitled', () => {
+  for (const r of ['bonus', 'operations-briefing', 'entitled']) {
+    assert.ok(enterpriseReportsCommand.describe.includes(r), `${r} missing from describe`);
+  }
+});
+
+test('bonus requires --name and the MCP tool maps the same segments', async () => {
+  const { readFileSync } = await import('node:fs');
+  const { fileURLToPath } = await import('node:url');
+  const mcp = readFileSync(fileURLToPath(new URL('../../mcp/server.js', import.meta.url)), 'utf8');
+  for (const m of ["bonus_insights: 'bonus'", "operations_briefing: 'operations-briefing'", "entitled: 'entitled'"]) assert.ok(mcp.includes(m), m);
+  const cli = readFileSync(fileURLToPath(new URL('./commands/enterprise-reports.js', import.meta.url)), 'utf8');
+  assert.ok(cli.includes('--name is required for bonus') && cli.includes('`bonus/${encodeURIComponent'), 'bonus must require --name and hit bonus/{report}');
+});
+
 // Year in review (item 16): the CLI sends Pacific-midnight instants, defaulting to the last 12 whole Pacific months.
 test('describe lists year-in-review', () => {
   assert.ok(enterpriseReportsCommand.describe.includes('year-in-review'));

package/lib/sign-versions.js

@@ -0,0 +1,58 @@
+// Shared helpers for Velaro Sign document versions (owner-only; REST: ContractVersionsController +
+// ContractController.UploadSourceDocument). Used by `velaro sign ...`; pure functions so they unit-test cleanly.
+import { readFileSync, existsSync } from 'node:fs';
+import { basename } from 'node:path';
+
+export function versionsPath(contractId) {
+  return `/api/Contract/${Number(contractId)}/versions`;
+}
+
+export function diffPath(contractId, from, to) {
+  return `/api/Contract/${Number(contractId)}/diff?from=${Number(from)}&to=${Number(to)}`;
+}
+
+export function uploadPath(contractId) {
+  return `/api/Contract/${Number(contractId)}/document`;
+}
+
+export function describeVersions(res) {
+  const rows = res?.versions ?? [];
+  if (!rows.length) return `Contract ${res?.contractId}: no document versions yet.`;
+  const lines = [`Contract ${res.contractId}: ${rows.length} version(s), newest first`];
+  for (const v of rows) {
+    const kb = Math.max(1, Math.round((v.byteLength || 0) / 1024));
+    lines.push(`  v${v.versionNumber}  ${String(v.uploadedAt || '').slice(0, 19)}  ${v.uploadedBy || '-'}  ${v.fileName || '-'}  ${v.pageCount ?? '?'}p ${kb}KB  sha256:${String(v.sha256 || '').slice(0, 12)}${v.note ? `  note: ${v.note}` : ''}`);
+  }
+  return lines.join('\n');
+}
+
+export function describeDiff(res) {
+  if (res?.identical) return `v${res.from} and v${res.to} are byte-identical (same SHA-256).`;
+  const blocks = res?.blocks ?? [];
+  const changed = blocks.filter(b => b.kind !== 'same' && b.kind !== 'equal');
+  const lines = [`Diff v${res.from} -> v${res.to}: ${changed.length} changed block(s)`];
+  for (const b of changed) {
+    for (const r of b.removed ?? []) lines.push(`- ${r}`);
+    for (const a of b.added ?? []) lines.push(`+ ${a}`);
+    lines.push('');
+  }
+  return lines.join('\n').trimEnd();
+}
+
+export function readPdf(filePath) {
+  if (!filePath || !existsSync(filePath)) throw new Error(`File not found: ${filePath}`);
+  const buf = readFileSync(filePath);
+  if (buf.length < 5 || buf.subarray(0, 5).toString('latin1') !== '%PDF-') throw new Error('Only PDF files can be uploaded as a contract version.');
+  return { buf, name: basename(filePath) };
+}
+
+export function buildUploadForm(filePath, note) {
+  const { buf, name } = readPdf(filePath);
+  const form = new FormData();
+  form.append('file', new Blob([buf], { type: 'application/pdf' }), name);
+  if (note) form.append('note', note);
+  return form;
+}
+
+export const OWNER_ONLY_RULE =
+  'Versions are owner-only: signers never see older versions. A new version can be uploaded only while the contract is a draft; after send/sign, void it and re-send.';

package/lib/sign-versions.test.js

@@ -0,0 +1,50 @@
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { writeFileSync, mkdtempSync } from 'node:fs';
+import { join } from 'node:path';
+import { tmpdir } from 'node:os';
+import { versionsPath, diffPath, uploadPath, describeVersions, describeDiff, buildUploadForm } from './sign-versions.js';
+
+test('paths', () => {
+  assert.equal(versionsPath('12'), '/api/Contract/12/versions');
+  assert.equal(diffPath(12, 1, 3), '/api/Contract/12/diff?from=1&to=3');
+  assert.equal(uploadPath(12), '/api/Contract/12/document');
+});
+
+test('describeVersions lists newest first with note', () => {
+  const out = describeVersions({ contractId: 5, versions: [
+    { versionNumber: 2, fileName: 'b.pdf', sha256: 'abcdef1234567890', byteLength: 2048, pageCount: 3, uploadedBy: 'a@v.com', uploadedAt: '2026-10-11T10:00:00Z', note: 'fix term' },
+    { versionNumber: 1, fileName: 'a.pdf', sha256: '1111111111111111', byteLength: 100, pageCount: 3, uploadedBy: 'a@v.com', uploadedAt: '2026-10-10T10:00:00Z' }] });
+  assert.match(out, /2 version\(s\)/);
+  assert.match(out, /v2 .*note: fix term/);
+  assert.equal(describeVersions({ contractId: 5, versions: [] }), 'Contract 5: no document versions yet.');
+});
+
+test('describeDiff shows removed/added and identical case', () => {
+  assert.match(describeDiff({ from: 1, to: 2, identical: true }), /byte-identical/);
+  const out = describeDiff({ from: 1, to: 2, identical: false, blocks: [{ kind: 'changed', removed: ['Term 12 months'], added: ['Term 24 months'] }] });
+  assert.match(out, /- Term 12 months/);
+  assert.match(out, /\+ Term 24 months/);
+});
+
+test('buildUploadForm rejects non-PDF and accepts PDF', () => {
+  const d = mkdtempSync(join(tmpdir(), 'sv-'));
+  const bad = join(d, 'x.pdf'); writeFileSync(bad, 'hello');
+  assert.throws(() => buildUploadForm(bad), /Only PDF/);
+  assert.throws(() => buildUploadForm(join(d, 'missing.pdf')), /not found/);
+  const ok = join(d, 'ok.pdf'); writeFileSync(ok, '%PDF-1.4\n%%EOF');
+  const f = buildUploadForm(ok, 'n');
+  assert.equal(f.get('note'), 'n');
+  assert.equal(f.get('file').name, 'ok.pdf');
+});
+
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { dirname, join as pjoin } from 'node:path';
+const root = pjoin(dirname(fileURLToPath(import.meta.url)), '..', '..');
+for (const f of ['mcp/server.js', 'mcp/staff-server.js', 'server/Velaro.Admin/Controllers/StaffMcpController.cs']) {
+  test(`${f} registers sign_versions tools`, () => {
+    const s = readFileSync(pjoin(root, f), 'utf8');
+    for (const t of ['sign_versions_list', 'sign_versions_diff', 'sign_versions_upload']) assert.ok(s.includes(t), `${t} missing in ${f}`);
+  });
+}

package/lib/skill-usage.test.js

@@ -0,0 +1,36 @@
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { formatSkillUsage } from './commands/skill-usage.js';
+
+const sample = {
+  siteId: 1032,
+  month: '2026-10',
+  isTrial: true,
+  overageBehavior: 'block',
+  usage: [
+    { metric: 'ai_tool_calls', name: 'AI Tool Calls', used: 120, limit: 500, unlimited: false, percent: 24, mode: 'Enforce' },
+    { metric: 'api_calls', name: 'REST API Calls', used: 9, limit: 0, unlimited: true, percent: 0, mode: 'Observe' },
+  ],
+  callsBySurface: [{ surface: 'McpStaff', calls: 4 }],
+  llmCostThisMonth: [{ keySource: 'byok', costUsd: 1.5, calls: 3 }],
+};
+
+test('shows usage against the limit with the gate mode, and marks unlimited metrics', () => {
+  const out = formatSkillUsage(sample);
+  assert.match(out, /Site 1032, 2026-10 \(trial\), overage: block/);
+  assert.match(out, /AI Tool Calls\s+120 \/\s+500\s+24%\s+gate: Enforce/);
+  assert.match(out, /REST API Calls\s+9 \/\s+unlimited/);
+});
+
+test('lists calls by surface and the LLM cost split, saying BYOK removes LLM cost only', () => {
+  const out = formatSkillUsage(sample);
+  assert.match(out, /McpStaff\s+4/);
+  assert.match(out, /byok\s+\$1\.50 \/ 3 calls/);
+  assert.match(out, /BYOK removes this cost only/);
+});
+
+test('handles a site with no recorded usage without throwing', () => {
+  const out = formatSkillUsage({ siteId: 5, month: '2026-10', overageBehavior: 'warn' });
+  assert.match(out, /\(none recorded\)/);
+  assert.match(out, /\(none logged\)/);
+});

package/lib/visitor-link.js

@@ -0,0 +1,61 @@
+// Shared helpers for `velaro visitor-link` (settings + token diagnose).
+// Token format (velaro-messaging VisitorLinkTokenService): "vlk1." + b64url(payload) + "." + b64url(hmac)
+// payload = siteId|visitorId|conversationBaseId|scope|iat|exp. The signature needs the server key, so this
+// only reads the claims; it never proves a token valid. Resolve (server side) is the real validity check.
+
+export const MAX_TTL_MINUTES = 1440;
+
+export function decodeLinkToken(token) {
+  const out = { ok: false, problems: [] };
+  if (typeof token !== 'string' || !token.trim()) { out.problems.push('empty token'); return out; }
+  const parts = token.trim().split('.');
+  if (parts.length !== 3 || parts[0] !== 'vlk1') { out.problems.push('not a vlk1 link token (expected vlk1.<payload>.<signature>)'); return out; }
+  const payload = Buffer.from(parts[1].replace(/-/g, '+').replace(/_/g, '/'), 'base64').toString('utf8');
+  const f = payload.split('|');
+  if (f.length < 6) { out.problems.push('payload has fewer than 6 fields'); return out; }
+  const [siteId, visitorId, conversationBaseId, scope, iat, exp] = f;
+  const toMs = (v) => { const n = Number(v); return Number.isFinite(n) && n > 0 ? (n > 1e12 ? n : n * 1000) : null; };
+  const issuedMs = toMs(iat);
+  const expMs = toMs(exp);
+  Object.assign(out, {
+    ok: true,
+    siteId: Number(siteId) || null,
+    visitorId,
+    conversationBaseId: Number(conversationBaseId) || null,
+    scope,
+    issuedAt: issuedMs ? new Date(issuedMs).toISOString() : null,
+    expiresAt: expMs ? new Date(expMs).toISOString() : null,
+    signaturePresent: parts[2].length > 0,
+  });
+  if (scope !== 'link') out.problems.push(`unexpected scope "${scope}" (v1 only issues "link")`);
+  if (!out.signaturePresent) out.problems.push('signature missing');
+  if (!expMs) out.problems.push('expiry not parseable');
+  return out;
+}
+
+// Full diagnosis: claims plus comparison with the site's current settings.
+export function diagnoseLink({ token, siteId, settings, now = Date.now() }) {
+  const claims = token ? decodeLinkToken(token) : { ok: false, problems: [] };
+  const findings = [...claims.problems];
+  if (claims.ok) {
+    if (siteId && claims.siteId && Number(siteId) !== claims.siteId) findings.push(`token was minted for site ${claims.siteId}, not site ${siteId}: cross-site tokens always fail`);
+    if (claims.expiresAt && Date.parse(claims.expiresAt) <= now) findings.push(`token expired at ${claims.expiresAt}`);
+    if (!claims.conversationBaseId) findings.push('token carries no conversation id (visitor had not started a chat when it was minted)');
+  }
+  if (settings) {
+    if (!settings.enabled) findings.push('visitor linking is OFF for this site: mint returns linking_disabled');
+    if (settings.keyConfigured === false) findings.push('link signing key is not configured on the server: mint and resolve fail closed (503 key_not_configured)');
+  }
+  return { claims, settings: settings ?? null, findings, healthy: findings.length === 0 };
+}
+
+export function validateSettingsArgs({ enabled, ttlMinutes }) {
+  if (enabled === undefined && ttlMinutes === undefined) throw new Error('Pass enabled and/or ttlMinutes.');
+  if (ttlMinutes !== undefined && (!Number.isInteger(ttlMinutes) || ttlMinutes < 1 || ttlMinutes > MAX_TTL_MINUTES)) {
+    throw new Error(`ttlMinutes must be a whole number from 1 to ${MAX_TTL_MINUTES}.`);
+  }
+  const body = {};
+  if (enabled !== undefined) body.enabled = !!enabled;
+  if (ttlMinutes !== undefined) body.ttlMinutes = ttlMinutes;
+  return body;
+}

package/lib/visitor-link.test.js

@@ -0,0 +1,67 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { decodeLinkToken, diagnoseLink, validateSettingsArgs } from './visitor-link.js';
+
+const b64 = (s) => Buffer.from(s, 'utf8').toString('base64url');
+const mk = (fields, sig = 'sig') => `vlk1.${b64(fields.join('|'))}.${sig}`;
+const NOW = Date.UTC(2026, 9, 13, 12, 0, 0);
+const sec = (ms) => Math.floor(ms / 1000);
+
+test('decodes a well-formed token', () => {
+  const c = decodeLinkToken(mk([1032, 'v-9', 555, 'link', sec(NOW), sec(NOW + 1800000)]));
+  assert.equal(c.ok, true);
+  assert.equal(c.siteId, 1032);
+  assert.equal(c.visitorId, 'v-9');
+  assert.equal(c.conversationBaseId, 555);
+  assert.deepEqual(c.problems, []);
+});
+
+test('rejects wrong prefix, empty and short payload', () => {
+  assert.equal(decodeLinkToken('').ok, false);
+  assert.equal(decodeLinkToken('abc.def.ghi').ok, false);
+  assert.equal(decodeLinkToken(`vlk1.${b64('1|2')}.s`).ok, false);
+});
+
+test('flags cross-site, expired, no conversation, missing signature', () => {
+  const t = mk([1032, 'v', 0, 'link', sec(NOW - 7200000), sec(NOW - 3600000)], '');
+  const d = diagnoseLink({ token: t, siteId: 20365, now: NOW });
+  const text = d.findings.join('\n');
+  assert.match(text, /not site 20365/);
+  assert.match(text, /expired/);
+  assert.match(text, /no conversation id/);
+  assert.match(text, /signature missing/);
+  assert.equal(d.healthy, false);
+});
+
+test('settings findings: off and missing key fail closed', () => {
+  const d = diagnoseLink({ settings: { enabled: false, ttlMinutes: 30, keyConfigured: false } });
+  assert.match(d.findings.join('\n'), /OFF/);
+  assert.match(d.findings.join('\n'), /key is not configured/);
+});
+
+test('healthy when token valid and settings on', () => {
+  const t = mk([1032, 'v', 5, 'link', sec(NOW), sec(NOW + 600000)]);
+  const d = diagnoseLink({ token: t, siteId: 1032, settings: { enabled: true, keyConfigured: true }, now: NOW });
+  assert.equal(d.healthy, true);
+});
+
+test('validateSettingsArgs enforces 1..1440 and requires a field', () => {
+  assert.throws(() => validateSettingsArgs({}), /enabled and\/or ttlMinutes/);
+  assert.throws(() => validateSettingsArgs({ ttlMinutes: 0 }), /1 to 1440/);
+  assert.throws(() => validateSettingsArgs({ ttlMinutes: 1441 }), /1 to 1440/);
+  assert.throws(() => validateSettingsArgs({ ttlMinutes: 1.5 }), /1 to 1440/);
+  assert.deepEqual(validateSettingsArgs({ enabled: true, ttlMinutes: 30 }), { enabled: true, ttlMinutes: 30 });
+  assert.deepEqual(validateSettingsArgs({ enabled: false }), { enabled: false });
+});
+
+test('MCP and staff-MCP inlined helpers stay in sync with the CLI helper', async () => {
+  const fs = await import('node:fs');
+  const path = await import('node:path');
+  const here = path.dirname(new URL(import.meta.url).pathname.replace(/^\/(\w:)/, '$1'));
+  const norm = (src) => src.replace(/\/\/.*$/gm, '').replace(/\bexport\s+/g, '').replace(/\s+/g, ' ');
+  const cli = norm(fs.readFileSync(path.join(here, 'visitor-link.js'), 'utf8')).trim();
+  for (const f of ['server.js', 'staff-server.js']) {
+    const src = norm(fs.readFileSync(path.join(here, '..', '..', 'mcp', f), 'utf8'));
+    assert.ok(src.includes(cli), `mcp/${f} inlined visitor-link helpers drifted from cli/lib/visitor-link.js`);
+  }
+});

package/package.json

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