@velaro/cli 1.4.103 → 1.4.105

package/bin/velaro.js

@@ -42,6 +42,7 @@ import { calendlyCommand }   from '../lib/commands/calendly.js';
 import { copilotStudioCommand } from '../lib/commands/copilotstudio.js';
 import { acuityCommand }     from '../lib/commands/acuity.js';
 import { avatarCommand }     from '../lib/commands/avatar.js';
+import { applePayPresetCommand } from '../lib/commands/apple-pay-preset.js';
 import { imageAnalysisCommand } from '../lib/commands/image-analysis.js';
 import { integrationCommand } from '../lib/commands/integration.js';
 import { appointmentsCommand } from '../lib/commands/appointments.js';
@@ -97,6 +98,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';
@@ -114,6 +116,7 @@ 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 { 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';
@@ -124,6 +127,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';
@@ -185,6 +189,7 @@ await yargs(hideBin(process.argv))
   .command(copilotStudioCommand)
   .command(acuityCommand)
   .command(avatarCommand)
+  .command(applePayPresetCommand)
   .command(imageAnalysisCommand)
   .command(integrationCommand)
   .command(appointmentsCommand)
@@ -242,6 +247,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: () => {} })
@@ -259,6 +265,7 @@ await yargs(hideBin(process.argv))
   .command(callbackCommand)
   .command(caseCommand)
   .command(pickupCommand)
+  .command(visitorLinkCommand)
   .command(applePayCommand)
   .command(siteBuilderCommand)
   .command(paymentRecoveryCommand)
@@ -267,6 +274,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/apple-pay-presets.js

@@ -0,0 +1,66 @@
+// Pure helpers for `velaro apple-pay-preset`: parse line items and build request bodies for the
+// messaging ApplePayPresetOrders API. Totals are always computed server-side; never sent from here.
+
+export const MAX_LINE_ITEMS = 20;
+
+/** Parse one "Label=12.50" spec. The last "=" splits label from amount so labels may contain "=". */
+export function parseItem(spec) {
+  const s = String(spec ?? '');
+  const i = s.lastIndexOf('=');
+  if (i < 1) throw new Error(`Line item "${s}" must look like Label=12.50`);
+  const label = s.slice(0, i).trim();
+  const raw = s.slice(i + 1).trim();
+  if (!label) throw new Error(`Line item "${s}" needs a label`);
+  if (!/^-?\d+(\.\d{1,2})?$/.test(raw)) throw new Error(`Line item "${label}" amount "${raw}" must be a number with at most 2 decimals`);
+  return { label, amount: Number(raw) };
+}
+
+/** Accepts --item specs (string or array) and/or --items-json '[{"label":"x","amount":1}]'. Returns undefined if neither given. */
+export function parseItems({ item, itemsJson } = {}) {
+  let items;
+  if (itemsJson !== undefined) {
+    let parsed;
+    try { parsed = JSON.parse(itemsJson); } catch { throw new Error('--items-json must be valid JSON'); }
+    if (!Array.isArray(parsed)) throw new Error('--items-json must be a JSON array');
+    items = parsed.map(p => {
+      if (!p || typeof p.label !== 'string' || !p.label.trim() || typeof p.amount !== 'number' || !Number.isFinite(p.amount)) {
+        throw new Error('Each --items-json entry needs a string label and a numeric amount');
+      }
+      return { label: p.label.trim(), amount: p.amount };
+    });
+  }
+  if (item !== undefined) {
+    const specs = Array.isArray(item) ? item : [item];
+    items = (items ?? []).concat(specs.map(parseItem));
+  }
+  if (items && items.length > MAX_LINE_ITEMS) throw new Error(`A preset order holds at most ${MAX_LINE_ITEMS} line items`);
+  return items;
+}
+
+/** Body for POST/PUT ApplePayPresetOrders. Only passed fields are included (PUT is a partial update). */
+export function presetBody(args) {
+  const body = {};
+  if (args.name !== undefined) body.name = String(args.name);
+  if (args.description !== undefined) body.description = String(args.description);
+  if (args.currency !== undefined) body.currencyCode = String(args.currency).toUpperCase();
+  const items = parseItems({ item: args.item, itemsJson: args.itemsJson });
+  if (items !== undefined) body.lineItems = items;
+  if (args.active !== undefined) body.isActive = Boolean(args.active);
+  if (args.managersOnly !== undefined) body.overrideRestrictedToManagers = Boolean(args.managersOnly);
+  return body;
+}
+
+export function presetPath(id) {
+  const n = Number(id);
+  if (!Number.isInteger(n) || n <= 0) throw new Error('Preset id must be a positive whole number');
+  return `/ApplePayPresetOrders/${n}`;
+}
+
+export function listPath(activeOnly) {
+  return `/ApplePayPresetOrders${activeOnly ? '?activeOnly=true' : ''}`;
+}
+
+export function formatPreset(p) {
+  const items = (p.lineItems || []).map(li => `    ${li.label}  ${Number(li.amount).toFixed(2)} ${p.currencyCode}`).join('\n');
+  return `#${p.id} ${p.name}${p.isActive ? '' : ' (inactive)'}${p.overrideRestrictedToManagers ? ' [managers-only amount changes]' : ''}\n${items}\n    Total  ${Number(p.totalAmount).toFixed(2)} ${p.currencyCode}`;
+}

package/lib/apple-pay-presets.test.js

@@ -0,0 +1,61 @@
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import fs from 'node:fs';
+import { parseItem, parseItems, presetBody, presetPath, listPath, formatPreset } from './apple-pay-presets.js';
+
+test('parseItem splits on the last "=" and validates the amount', () => {
+  assert.deepEqual(parseItem('Haircut=30'), { label: 'Haircut', amount: 30 });
+  assert.deepEqual(parseItem('A=B=1.50'), { label: 'A=B', amount: 1.5 });
+  assert.throws(() => parseItem('Haircut'), /Label=12.50/);
+  assert.throws(() => parseItem('=5'), /Label=12.50/);
+  assert.throws(() => parseItem('x=abc'), /number/);
+  assert.throws(() => parseItem('x=1.234'), /2 decimals/);
+});
+
+test('parseItems merges --item and --items-json, caps at 20, rejects bad json', () => {
+  assert.equal(parseItems({}), undefined);
+  assert.deepEqual(parseItems({ item: 'a=1' }), [{ label: 'a', amount: 1 }]);
+  assert.deepEqual(parseItems({ itemsJson: '[{"label":"b","amount":2}]', item: ['c=3'] }), [{ label: 'b', amount: 2 }, { label: 'c', amount: 3 }]);
+  assert.throws(() => parseItems({ itemsJson: '{' }), /valid JSON/);
+  assert.throws(() => parseItems({ itemsJson: '{}' }), /array/);
+  assert.throws(() => parseItems({ itemsJson: '[{"label":"","amount":1}]' }), /label/);
+  assert.throws(() => parseItems({ item: Array.from({ length: 21 }, (_, i) => `i${i}=1`) }), /at most 20/);
+});
+
+test('presetBody includes only passed fields and never a total', () => {
+  assert.deepEqual(presetBody({}), {});
+  assert.deepEqual(presetBody({ active: false }), { isActive: false });
+  const b = presetBody({ name: 'Cut', currency: 'usd', item: ['Haircut=30'], managersOnly: true, active: true, description: 'd' });
+  assert.deepEqual(b, { name: 'Cut', description: 'd', currencyCode: 'USD', lineItems: [{ label: 'Haircut', amount: 30 }], isActive: true, overrideRestrictedToManagers: true });
+  assert.equal('totalAmount' in b, false);
+});
+
+test('paths validate ids', () => {
+  assert.equal(presetPath('7'), '/ApplePayPresetOrders/7');
+  assert.throws(() => presetPath('0'), /positive/);
+  assert.throws(() => presetPath('x'), /positive/);
+  assert.equal(listPath(true), '/ApplePayPresetOrders?activeOnly=true');
+  assert.equal(listPath(false), '/ApplePayPresetOrders');
+});
+
+test('formatPreset shows items and total', () => {
+  const out = formatPreset({ id: 3, name: 'Cut', isActive: false, overrideRestrictedToManagers: true, currencyCode: 'USD', totalAmount: 35, lineItems: [{ label: 'Haircut', amount: 30 }, { label: 'Tip', amount: 5 }] });
+  assert.match(out, /#3 Cut \(inactive\) \[managers-only/);
+  assert.match(out, /Total {2}35.00 USD/);
+});
+
+test('MCP server exposes the four preset tools wired to ApplePayPresetOrders on the messaging api', () => {
+  const src = fs.readFileSync(new URL('../../mcp/server.js', import.meta.url), 'utf8');
+  for (const t of ['apple_pay_preset_list', 'apple_pay_preset_create', 'apple_pay_preset_update', 'apple_pay_preset_delete']) {
+    assert.ok(src.includes(`name: '${t}'`), `tool def ${t}`);
+    assert.ok(src.includes(`case '${t}':`), `handler ${t}`);
+  }
+  assert.match(src, /messagingRequest\('POST', '\/ApplePayPresetOrders'/);
+  assert.match(src, /messagingRequest\('DELETE', `\/ApplePayPresetOrders\//);
+});
+
+test('command file uses messaging helpers only', () => {
+  const src = fs.readFileSync(new URL('./commands/apple-pay-preset.js', import.meta.url), 'utf8');
+  assert.match(src, /messagingGet, messagingPost, messagingPut, messagingDel/);
+  assert.doesNotMatch(src, /import\s*\{[^}]*\b(get|post|del|request)\b[^}]*\}\s*from '\.\.\/api\.js'/);
+});

package/lib/commands/apple-pay-preset.js

@@ -0,0 +1,65 @@
+import { messagingGet, messagingPost, messagingPut, messagingDel } from '../api.js';
+import { presetBody, presetPath, listPath, formatPreset } from '../apple-pay-presets.js';
+import { runCommand } from '../run.js';
+
+// ── velaro apple-pay-preset ──────────────────────────────────────────────────
+// Pre-canned Apple Pay orders (messaging ApplePayPresetOrders API). Messaging routes, so
+// every call goes through the messaging helpers. Totals are computed by the server.
+// Registered as `apple-pay-preset` until the `apple-pay` command (PR #1774) lands, then it can nest as `apple-pay preset`.
+
+const fieldOptions = y => y
+  .option('name',          { type: 'string', describe: 'Preset name' })
+  .option('description',   { type: 'string', describe: 'Preset description' })
+  .option('currency',      { type: 'string', describe: 'ISO currency code, e.g. USD' })
+  .option('item',          { type: 'string', array: true, describe: 'Line item as "Label=12.50" (repeatable, max 20)' })
+  .option('items-json',    { type: 'string', describe: 'Line items as JSON: [{"label":"Haircut","amount":30}]' })
+  .option('active',        { type: 'boolean', describe: 'Preset is available to agents and the AI' })
+  .option('managers-only', { type: 'boolean', describe: 'Only managers can change amounts at send time' });
+
+export const applePayPresetCommand = {
+  command:  'apple-pay-preset <subcommand>',
+  describe: 'Manage pre-canned Apple Pay orders',
+  builder:  yargs => yargs
+    .command({
+      command: 'list',
+      describe: 'List preset orders',
+      builder: y => y.option('active-only', { type: 'boolean', default: false }),
+      handler: runCommand(async argv => {
+        const rows = await messagingGet(listPath(argv.activeOnly));
+        const list = Array.isArray(rows) ? rows : [];
+        console.log(list.length ? `\n${list.map(formatPreset).join('\n\n')}\n` : '\nNo preset orders.\n');
+      }),
+    })
+    .command({
+      command: 'get <id>',
+      describe: 'Show one preset order',
+      handler: runCommand(async argv => { console.log(`\n${formatPreset(await messagingGet(presetPath(argv.id)))}\n`); }),
+    })
+    .command({
+      command: 'create',
+      describe: 'Create a preset order',
+      builder: y => fieldOptions(y).demandOption('name'),
+      handler: runCommand(async argv => {
+        const body = presetBody(argv);
+        if (!body.lineItems || !body.lineItems.length) throw new Error('Provide at least one --item "Label=12.50" (or --items-json)');
+        console.log(`\nCreated:\n${formatPreset(await messagingPost('/ApplePayPresetOrders', body))}\n`);
+      }),
+    })
+    .command({
+      command: 'update <id>',
+      describe: 'Update a preset order (only passed fields change)',
+      builder: fieldOptions,
+      handler: runCommand(async argv => {
+        const body = presetBody(argv);
+        if (!Object.keys(body).length) throw new Error('Pass at least one field to change');
+        console.log(`\nUpdated:\n${formatPreset(await messagingPut(presetPath(argv.id), body))}\n`);
+      }),
+    })
+    .command({
+      command: 'delete <id>',
+      describe: 'Delete a preset order',
+      handler: runCommand(async argv => { await messagingDel(presetPath(argv.id)); console.log(`\nDeleted preset ${Number(argv.id)}.\n`); }),
+    })
+    .demandCommand(1),
+  handler: () => {},
+};

package/lib/commands/billing-automation.js

@@ -136,6 +136,16 @@ async function setReceipts(subscriptionId, args) {
   console.log(`Subscription ${res.id} receipts: card=${res.card ?? 'inherit'} ach=${res.ach ?? 'inherit'} other=${res.other ?? 'inherit'}.`);
 }
 
+async function digestSendNow() {
+  const res = await request('POST', '/api/BillingNotifications/digest/send-now', {});
+  console.log(`Digest sent to ${res.recipients.join(', ')}: ${res.subject}`);
+}
+
+async function receiptsRunNow() {
+  const res = await request('POST', '/api/BillingNotifications/receipts/run-now', {});
+  console.log(`Receipts run: ${res.summary}`);
+}
+
 export const billingAutomationCommand = {
   command: 'billing-automation <subcommand>',
   describe: 'Review-hold and dry-run switches for invoice emails and charges, the review queue, and account types',
@@ -161,6 +171,8 @@ export const billingAutomationCommand = {
       .command('dismiss <id>', 'Dismiss a held entry (it stays on hold, alerts stop)', {}, (args) => dismiss(args.id))
       .command('account-type <subscriptionId> [value]', 'Set a subscription account type that rules match on (omit value to clear)', {}, (args) => setAccountType(args.subscriptionId, args.value))
       .command('notify-settings', 'Show the global notification settings (receipts, invoice BCC, digest recipients)', {}, () => notifySettings())
+      .command('digest-send-now', 'Send the billing digest now to digest.recipients (same email as the 7am run)', {}, () => digestSendNow())
+      .command('receipts-run-now', 'Decide pending payment receipts now instead of at :05 and print the counts', {}, () => receiptsRunNow())
       .command('notify-set <key> <value>', 'Set a global notification setting: receipts.card|receipts.ach|receipts.other = never|send; invoices.bcc = emails (blank = none); digest.recipients = emails', {}, (args) => notifySet(args.key, args.value))
       .command('receipts <subscriptionId>', 'Set receipt overrides on one subscription (--card/--ach/--other = never|send). Channels you omit keep their current override.', {
         card:  { type: 'string', choices: ['never', 'send'] },

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/entitlement.js

@@ -166,6 +166,45 @@ async function reconcile(args) {
   }
 }
 
+async function trial(args) {
+  const sub = args.action;
+  const need = (v, n) => { if (v === undefined || v === null || v === '') { console.error(`--${n} is required for trial ${sub}`); process.exit(1); } };
+  if (sub === 'get' || sub === 'recommend') {
+    need(args.site, 'site');
+    const r = await request('GET', `Entitlements/${args.site}/trial${sub === 'recommend' ? '/recommendation' : ''}`);
+    console.log(JSON.stringify(r, null, 2));
+  } else if (sub === 'not-paying') {
+    console.log(JSON.stringify(await request('GET', 'Entitlements/admin/trial/not-paying'), null, 2));
+  } else if (sub === 'grant') {
+    need(args.site, 'site'); need(args.feature, 'feature'); need(args.reason, 'reason');
+    const r = await request('POST', `Entitlements/${args.site}/trial/grant`, { featureKey: args.feature, reason: args.reason });
+    console.log(`Site ${args.site}: ${r.featureKey} granted for the trial (${r.state}).`);
+  } else if (sub === 'hold' || sub === 'reactivate') {
+    need(args.site, 'site');
+    const body = { featureKey: args.feature, dryRun: !!args['dry-run'] };
+    console.log(JSON.stringify(await request('POST', `Entitlements/${args.site}/trial/${sub}`, body)));
+  } else if (sub === 'set-limit') {
+    need(args.site, 'site'); need(args.key, 'key'); need(args.value, 'value'); need(args.reason, 'reason');
+    const r = await request('POST', `Entitlements/${args.site}/trial/limit`, { key: args.key, value: Number(args.value), reason: args.reason });
+    console.log(`Site ${args.site}: ${r.key} ${r.old} -> ${r.value}.`);
+  } else if (sub === 'set-text') {
+    need(args.feature, 'feature');
+    console.log(JSON.stringify(await request('POST', 'Entitlements/admin/trial/feature-text', { featureKey: args.feature, text: args.text })));
+  } else if (sub === 'approve-limit' || sub === 'deny-limit') {
+    need(args.request, 'request');
+    if (sub === 'approve-limit') {
+      need(args.key, 'key'); need(args.value, 'value');
+      console.log(JSON.stringify(await request('POST', `Entitlements/admin/trial/limit-request/${args.request}/approve`, { key: args.key, value: Number(args.value), message: args.message })));
+    } else {
+      need(args.reason, 'reason');
+      console.log(JSON.stringify(await request('POST', `Entitlements/admin/trial/limit-request/${args.request}/deny`, { reason: args.reason })));
+    }
+  } else {
+    console.error('Unknown trial action. Use: get | recommend | not-paying | grant | hold | reactivate | set-limit | approve-limit | deny-limit | set-text');
+    process.exit(1);
+  }
+}
+
 async function setLock(args) {
   if (!args.site) {
     console.error('Usage: velaro entitlement set-lock --site 1032 --at 2026-01-01T00:00:00Z\n       velaro entitlement set-lock --site 1032 --unlock');
@@ -250,10 +289,21 @@ export function entitlementCommand(yargs) {
       .option('at',     { type: 'string',  desc: 'ISO 8601 timestamp to lock entitlement resolution to' })
       .option('unlock', { type: 'boolean', desc: 'Clear an existing lock (resolves against current plan version again)' })
     , a => setLock(a))
+    .command('trial <action>', 'Trial governance (superadmin): get | recommend | not-paying | grant | hold | reactivate | set-limit | approve-limit | deny-limit | set-text', y => y
+      .option('site',    { type: 'number', desc: 'Site ID' })
+      .option('feature', { type: 'string', desc: 'Feature key, e.g. EnableIvr' })
+      .option('key',     { type: 'string', desc: 'Cap name, e.g. MaxKbArticles' })
+      .option('value',   { type: 'string', desc: 'Whole number cap' })
+      .option('reason',  { type: 'string', desc: 'Reason (audited)' })
+      .option('request', { type: 'number', desc: 'Limit-increase request id' })
+      .option('message', { type: 'string', desc: 'approve-limit: note added to the customer reply' })
+      .option('text', { type: 'string', desc: 'set-text: customer-safe, number-free limit text' })
+      .option('dry-run', { type: 'boolean', desc: 'hold: report only, write nothing' })
+    , a => trial(a))
     .command('list-cutover', 'List all feature keys and whether they are live (messaging reads admin) or not (Subscription.cs)', () => {}, () => listCutover())
     .command('set-cutover', 'Flip a feature key live (or roll it back). Live = messaging reads admin value within 45s. --rollback reverts to Subscription.cs.', y => y
       .option('key',      { type: 'string',  demandOption: true, desc: 'Feature key, e.g. EnableIvr' })
       .option('rollback', { type: 'boolean', desc: 'Pass to roll back this flag to Subscription.cs (default: go live)' })
     , a => setCutover(a))
-    .demandCommand(1, 'Specify a subcommand: get | list-features | enterprise-reports | report-packages | set-override | remove-override | seed | seed-plans | backfill | backfill-sap-tiers | backfill-legacy-write-tiers | reconcile | comp | set-lock | list-cutover | set-cutover');
+    .demandCommand(1, 'Specify a subcommand: get | list-features | enterprise-reports | report-packages | set-override | remove-override | seed | seed-plans | backfill | backfill-sap-tiers | backfill-legacy-write-tiers | reconcile | comp | set-lock | trial | list-cutover | set-cutover');
 }

package/lib/commands/env.js

@@ -32,7 +32,7 @@ export const envCommand = {
         ? `logged in as ${creds.userName ?? 'unknown'} (site ${creds.siteId})`
         : 'not logged in';
       const expiry  = creds?.velaroExpires
-        ? new Date(creds.velaroExpires) > new Date() ? '' : '  ⚠ token expired'
+        ? new Date(creds.velaroExpires) > new Date() ? '' : creds.entraRefreshToken ? '  (session token idle; auto-refreshes on next command)' : '  ⚠ token expired, run velaro login'
         : '';
       console.log(`${marker}${name.padEnd(10)} ${status}${expiry}`);
       console.log(`          ${urls.adminApiBase}`);

package/lib/commands/logs.js

@@ -362,8 +362,6 @@ function parsePositiveIntFlag(flagName, rawValue, { max } = {}) {
 // emails/sms isn't wrongly flagged as "fires into the void" when defaults
 // actually cover it.
 function hasAnyRecipient({ emails, sms, webhook, teams, mobileUserIds, hasGlobalDefaultContacts }) {
-// also cover webhook, which that component's check omits).
-function hasAnyRecipient({ emails, sms, webhook, mobileUserIds, teams }) {
   return Boolean(
     (emails && String(emails).trim()) ||
     (sms && String(sms).trim()) ||
@@ -374,8 +372,6 @@ function hasAnyRecipient({ emails, sms, webhook, mobileUserIds, teams }) {
     // ResolveRecipients) -- if there's at least one global-default contact with a phone or
     // email, a rule with both blank is NOT actually silent, even though neither field is set.
     ((!emails || !String(emails).trim()) && (!sms || !String(sms).trim()) && hasGlobalDefaultContacts)
-    (mobileUserIds && String(mobileUserIds).trim()) ||
-    teams
   );
 }
 
@@ -532,10 +528,6 @@ async function createAlertRule(argv) {
   if (!hasAnyRecipient({ emails: argv.emails, sms: argv.sms, webhook: argv.webhook, teams: argv.teams, mobileUserIds: argv.mobileUserIds, hasGlobalDefaultContacts: hasDefaults })
       && !argv.noRecipientsOk) {
     console.error('No notification channel given (--emails, --sms, --webhook, --teams, or --mobile-user-ids), and no global-default contact exists to fall back to — this rule would fire but notify no one.');
-  // HIGH: a rule with zero notification channels fires into the void.
-  if (!hasAnyRecipient({ emails: argv.emails, sms: argv.sms, webhook: argv.webhook, mobileUserIds: argv.mobileUserIds, teams: argv.teams })
-      && !argv.noRecipientsOk) {
-    console.error('No notification channel given (--emails, --sms, --webhook, --teams, or --mobile-user-ids) — this rule would fire but notify no one.');
     console.error('If that\'s intentional (e.g. you only want it visible in Alert History), pass --no-recipients-ok to proceed anyway.');
     console.error('To set up global defaults so a blank --emails/--sms is covered automatically: velaro logs contacts add --name alex --phone +1... --email alex@velaro.com --global');
     process.exit(1);
@@ -658,9 +650,6 @@ async function updateAlertRule(argv) {
   if (!hasAnyRecipient({ emails: body.notifyEmails, sms: body.notifyPhoneNumbers, webhook: body.notifyWebhookUrl, teams: body.notifyTeams, mobileUserIds: body.notifyMobileUserIds, hasGlobalDefaultContacts: hasDefaults })
       && !argv.noRecipientsOk) {
     console.error('This update would leave the rule with no notification channel (--emails, --sms, --webhook, --teams, or --mobile-user-ids), and no global-default contact exists to fall back to — it would fire but notify no one.');
-  if (!hasAnyRecipient({ emails: body.notifyEmails, sms: body.notifyPhoneNumbers, webhook: body.notifyWebhookUrl, mobileUserIds: body.notifyMobileUserIds, teams: body.notifyTeams })
-      && !argv.noRecipientsOk) {
-    console.error('This update would leave the rule with no notification channel (--emails, --sms, --webhook, --teams, or --mobile-user-ids) — it would fire but notify no one.');
     console.error('If that\'s intentional, pass --no-recipients-ok to proceed anyway.');
     process.exit(1);
   }

package/lib/commands/mcp-key.js

@@ -106,21 +106,6 @@ const mcpKeyInstallCommand = {
     const result  = await request('POST', '/McpApiKeys', payload, env);
     const rawKey  = result.rawKey;
 
-    // Claude Code reads user-scope MCP server definitions from the
-    // top-level "mcpServers" key in ~/.claude.json — NOT from
-    // ~/.claude/settings.json (that file is for permissions/hooks/env,
-    // and any mcpServers entry written there is silently ignored).
-    // prod  → entry named "velaro"
-    // staging → entry named "velaro-staging"
-    const serverName    = env === 'prod' ? 'velaro' : `velaro-${env}`;
-    const claudeJsonPath = path.join(os.homedir(), '.claude.json');
-    let claudeJson = {};
-    if (fs.existsSync(claudeJsonPath)) {
-      try { claudeJson = JSON.parse(fs.readFileSync(claudeJsonPath, 'utf8')); } catch {}
-    }
-
-    claudeJson.mcpServers = claudeJson.mcpServers || {};
-    claudeJson.mcpServers[serverName] = {
     // Claude Code reads MCP server definitions from the top-level "mcpServers" key
     // in ~/.claude.json (NOT ~/.claude/settings.json — that file has no effect here).
     // This is the same shape `claude mcp add` itself writes.
@@ -152,8 +137,7 @@ const mcpKeyInstallCommand = {
       },
     };
 
-    fs.mkdirSync(path.dirname(claudeJsonPath), { recursive: true });
-    fs.writeFileSync(claudeJsonPath, JSON.stringify(claudeJson, null, 2));
+    fs.mkdirSync(path.dirname(configPath), { recursive: true });
     // Claude Code itself writes ~/.claude.json continuously (history, project state),
     // so this must never be a plain in-place write: write to a temp file and rename,
     // which is atomic on the same filesystem — a crash or concurrent write mid-save

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/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/workflow.js

@@ -1,5 +1,5 @@
 import fs                          from 'node:fs';
-import { getCredentials, messagingGet, messagingPost, messagingPut } from '../api.js';
+import { getCredentials, messagingGet, messagingPost, messagingPut, messagingDel } from '../api.js';
 import { requireFeature }          from '../subscription.js';
 import { runCommand }              from '../run.js';
 import { applyFollowUpOptions }    from '../ai-followups.js';
@@ -18,8 +18,9 @@ export const workflowCommand = {
       .command(workflowNodeOptionsCommand)
       .command(workflowIntegrityScanCommand)
       .command(workflowAiFollowupsCommand)
+      .command(workflowScheduleCommand)
       .command(siteAiFollowupsCommand)
-      .demandCommand(1, 'Specify a subcommand: list, get, create, enable, disable, node-options, integrity-scan, ai-followups, ai-followups-site'),
+      .demandCommand(1, 'Specify a subcommand: list, get, create, enable, disable, node-options, integrity-scan, ai-followups, ai-followups-site, schedule'),
   handler: () => {},
 };
 
@@ -358,3 +359,124 @@ const workflowIntegrityScanCommand = {
     }
   }),
 };
+
+// ── schedule (workflow schedule priority; messaging owns /Workflows/schedule/*) ──────────────
+// Mirrors the velaro MCP tools workflow_schedule_resolve / _timeline / _validate / _banner / _override_save / _override_list / _override_delete.
+// An older messaging answers 404/501: print "not available" instead of failing.
+
+const NOT_AVAILABLE = "Workflow scheduling is not available on this site's version.";
+
+async function scheduleTolerant(fn) {
+  try {
+    return await fn();
+  } catch (err) {
+    if (/->\s*(404|501)\b|\b(404|501)\b/.test(String(err?.message))) { console.log(NOT_AVAILABLE); return undefined; }
+    throw err;
+  }
+}
+
+const qs = (o) => new URLSearchParams(Object.entries(o).filter(([, v]) => v !== undefined && v !== '')).toString();
+
+const workflowScheduleCommand = {
+  command:  'schedule <subcommand>',
+  describe: 'Workflow schedule priority: set, get, delete, validate, resolve, timeline, gaps',
+  builder:  (yargs) =>
+    yargs
+      .command({
+        command:  'set',
+        describe: 'Create/update a SwitchWorkflow schedule override (run another workflow on given dates)',
+        builder:  (y) => y
+          .option('id',       { type: 'number', describe: 'Existing override id to update (omit to create)' })
+          .option('schedule', { type: 'number', demandOption: true, describe: 'Shared schedule id' })
+          .option('workflow', { type: 'number', demandOption: true, describe: 'Target workflow id to run' })
+          .option('name',     { type: 'string' })
+          .option('start',    { type: 'string', demandOption: true, describe: 'YYYY-MM-DD' })
+          .option('end',      { type: 'string', describe: 'YYYY-MM-DD' }),
+        handler:  runCommand(async (argv) => {
+          await requireFeature('enableAutomation', 'Workflows');
+          const body = { sharedScheduleId: argv.schedule, name: argv.name, startDate: argv.start, endDate: argv.end, action: 3, targetWorkflowId: argv.workflow };
+          const r = await scheduleTolerant(() => argv.id
+            ? messagingPut(`/ScheduleOverride/${argv.id}`, body)
+            : messagingPost('/ScheduleOverride', body));
+          if (r !== undefined) console.log(JSON.stringify(r, null, 2));
+        }),
+      })
+      .command({
+        command:  'get',
+        describe: 'List this site\'s SwitchWorkflow schedule overrides',
+        handler:  runCommand(async () => {
+          await requireFeature('enableAutomation', 'Workflows');
+          const r = await scheduleTolerant(() => messagingGet('/ScheduleOverride?action=3'));
+          if (r !== undefined) console.log(JSON.stringify(r, null, 2));
+        }),
+      })
+      .command({
+        command:  'delete',
+        describe: 'Delete a schedule override by id (site admins only)',
+        builder:  (y) => y.option('id', { type: 'number', demandOption: true }),
+        handler:  runCommand(async (argv) => {
+          await requireFeature('enableAutomation', 'Workflows');
+          const r = await scheduleTolerant(async () => { await messagingDel(`/ScheduleOverride/${argv.id}`); return { success: true, deleted: argv.id }; });
+          if (r !== undefined) console.log(JSON.stringify(r, null, 2));
+        }),
+      })
+      .command({
+        command:  'validate',
+        describe: 'Dry-run a draft override (or no override: list current gaps) without saving',
+        builder:  (y) => y
+          .option('trigger',  { type: 'string', default: 'conversation_opened' })
+          .option('channel',  { type: 'string' })
+          .option('schedule', { type: 'number', describe: 'Shared schedule id of the draft override' })
+          .option('workflow', { type: 'number', describe: 'Target workflow id of the draft override' })
+          .option('name',     { type: 'string' })
+          .option('start',    { type: 'string', describe: 'YYYY-MM-DD' })
+          .option('end',      { type: 'string', describe: 'YYYY-MM-DD' }),
+        handler:  runCommand(async (argv) => {
+          await requireFeature('enableAutomation', 'Workflows');
+          const override = argv.schedule && argv.workflow && argv.start
+            ? { sharedScheduleId: argv.schedule, name: argv.name, startDate: argv.start, endDate: argv.end, action: 3, targetWorkflowId: argv.workflow }
+            : undefined;
+          const r = await scheduleTolerant(() => messagingPost('/Workflows/schedule/validate', { trigger: argv.trigger, channel: argv.channel, override }));
+          if (r !== undefined) console.log(JSON.stringify(r, null, 2));
+        }),
+      })
+      .command({
+        command:  'resolve',
+        describe: 'Which workflow runs at a date/time?',
+        builder:  (y) => y
+          .option('trigger', { type: 'string', demandOption: true })
+          .option('channel', { type: 'string' })
+          .option('at',      { type: 'string', describe: 'ISO date-time (default now)' })
+          .option('tz',      { type: 'string', describe: 'IANA time zone' }),
+        handler:  runCommand(async (argv) => {
+          await requireFeature('enableAutomation', 'Workflows');
+          const r = await scheduleTolerant(() => messagingGet('/Workflows/schedule/resolve?' + qs({ trigger: argv.trigger, channel: argv.channel, at: argv.at, tz: argv.tz })));
+          if (r !== undefined) console.log(JSON.stringify(r, null, 2));
+        }),
+      })
+      .command({
+        command:  'timeline',
+        describe: 'Winner timeline, gaps and conflicts over a date range',
+        builder:  (y) => y
+          .option('trigger', { type: 'string', demandOption: true })
+          .option('channel', { type: 'string' })
+          .option('from',    { type: 'string' })
+          .option('to',      { type: 'string' }),
+        handler:  runCommand(async (argv) => {
+          await requireFeature('enableAutomation', 'Workflows');
+          const r = await scheduleTolerant(() => messagingGet('/Workflows/schedule/timeline?' + qs({ trigger: argv.trigger, channel: argv.channel, from: argv.from, to: argv.to })));
+          if (r !== undefined) console.log(JSON.stringify(r, null, 2));
+        }),
+      })
+      .command({
+        command:  'gaps',
+        describe: 'Upcoming gaps where no workflow will run',
+        handler:  runCommand(async () => {
+          await requireFeature('enableAutomation', 'Workflows');
+          const r = await scheduleTolerant(() => messagingGet('/Workflows/schedule/banner'));
+          if (r !== undefined) console.log(JSON.stringify(r, null, 2));
+        }),
+      })
+      .demandCommand(1, 'Specify: set, get, delete, validate, resolve, timeline, gaps'),
+  handler: () => {},
+};

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/messaging-routes.test.js

@@ -9,7 +9,7 @@ import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 
 const dir = path.join(path.dirname(fileURLToPath(import.meta.url)), 'commands');
-const MESSAGING_ONLY = ['/Teams/List', '/Deployment', '/Users/List', '/Workflows/List', '/Rules', '/Ticket/knowledge-overrides', '/UserStatus/admin', '/api/ivr/config', '/WooCommerce/billing', '/WooCommerce/auth', '/diagnostics/test-magento', '/voice/admin', '/api/enterprise-reports', '/avatar/groups', '/avatar/workflows', '/avatar/group-overrides', '/Recruiting', '/superadmin/logs/insights', '/ApplePayConfig'];
+const MESSAGING_ONLY = ['/Teams/List', '/Deployment', '/Users/List', '/Workflows/List', '/Rules', '/Ticket/knowledge-overrides', '/UserStatus/admin', '/api/ivr/config', '/WooCommerce/billing', '/WooCommerce/auth', '/diagnostics/test-magento', '/voice/admin', '/api/enterprise-reports', '/avatar/groups', '/avatar/workflows', '/avatar/group-overrides', '/Recruiting', '/superadmin/logs/insights', '/ApplePayPresetOrders', '/ApplePayConfig'];
 
 test('messaging-only routes are never called through the admin api helpers', () => {
   const offenders = [];

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/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.103",
+  "version": "1.4.105",
   "description": "Velaro Workspace v20 — command-line interface for managing bots, knowledge base ingestion, MCP API keys, search indexes, and ops health.",
   "type": "module",
   "bin": {