@velaro/cli 1.4.104 → 1.4.105

package/bin/velaro.js

@@ -98,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';
@@ -115,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';
@@ -125,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';
@@ -244,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: () => {} })
@@ -261,6 +265,7 @@ await yargs(hideBin(process.argv))
   .command(callbackCommand)
   .command(caseCommand)
   .command(pickupCommand)
+  .command(visitorLinkCommand)
   .command(applePayCommand)
   .command(siteBuilderCommand)
   .command(paymentRecoveryCommand)
@@ -269,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/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/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/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/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.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": {