@velaro/cli 1.4.58 → 1.4.60

package/bin/velaro.js

@@ -9,6 +9,7 @@ import { kbCommand }         from '../lib/commands/kb.js';
 import { botCommand }        from '../lib/commands/bot.js';
 import { indexCommand }      from '../lib/commands/index.js';
 import { ingestCommand }     from '../lib/commands/ingest.js';
+import { indexMoveCommand }  from '../lib/commands/index-move.js';
 import { productCommand }    from '../lib/commands/product.js';
 import { mcpKeyCommand }     from '../lib/commands/mcp-key.js';
 import { opsCommand }        from '../lib/commands/ops.js';
@@ -83,6 +84,8 @@ import { recruitingCommand }        from '../lib/commands/recruiting.js';
 import { surveyCommand }            from '../lib/commands/survey.js';
 import { bundleCommand }            from '../lib/commands/bundle.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 { campaignsCommand }         from '../lib/commands/campaigns.js';
 import { contactsCommand }          from '../lib/commands/contacts.js';
 import { contactListCommand }       from '../lib/commands/contact-list.js';
@@ -104,6 +107,7 @@ await yargs(hideBin(process.argv))
   .command(botCommand)
   .command(indexCommand)
   .command(ingestCommand)
+  .command(indexMoveCommand)
   .command(productCommand)
   .command(mcpKeyCommand)
   .command(opsCommand)
@@ -178,6 +182,8 @@ await yargs(hideBin(process.argv))
   .command(surveyCommand)
   .command(bundleCommand)
   .command({ command: 'feature-discovery', desc: 'View and act on feature-discovery suggestions for this site', builder: featureDiscoveryCommand, handler: () => {} })
+  .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)
   .command(contactsCommand)
   .command(contactListCommand)

package/lib/commands/ai-config.js

@@ -21,7 +21,9 @@ export const aiConfigCommand = {
       .command(aiConfigSetChannelOverrideCommand)
       .command(aiConfigListChannelOverridesCommand)
       .command(aiConfigStaffListCommand)
-      .demandCommand(1, 'Specify a subcommand: list, get, create, set-channel-override, list-channel-overrides, staff-list'),
+      .command(aiConfigResolvedModelCommand)
+      .command(aiConfigModelCallsCommand)
+      .demandCommand(1, 'Specify a subcommand: list, get, create, set-channel-override, list-channel-overrides, staff-list, resolved-model, model-calls'),
   handler: () => {},
 };
 
@@ -44,7 +46,7 @@ const aiConfigListCommand = {
       const id    = `[${c.id}]`.padStart(idW);
       const name  = (c.name ?? '').padEnd(nameW);
       const stat  = (c.status ?? '—').padEnd(7);
-      console.log(`${id}  ${name}  ${stat}  ${c.aiModel ?? '—'}`);
+      console.log(`${id}  ${name}  ${stat}  ${c.aiModel || 'Velaro Default'}`);
     }
     console.log(`\n${rows.length} configuration(s)`);
   }),
@@ -191,3 +193,36 @@ const aiConfigSetChannelOverrideCommand = {
     console.log(`Channel override set: ai-config=${argv.id} channel=${argv.channel} mode=${argv.mode}`);
   }),
 };
+
+// ── resolved-model ────────────────────────────────────────────────────────────
+// Voice preview (GET avatar/voices/{voiceId}/preview) is intentionally UI-only: it streams binary
+// audio for a browser <audio> element and has no useful CLI/MCP shape.
+
+const aiConfigResolvedModelCommand = {
+  command:  'resolved-model <id>',
+  describe: 'Show which model an AI configuration runs on (model name is returned to Velaro staff only)',
+  builder:  (y) => y.positional('id', { type: 'number', describe: 'AI configuration ID' }),
+  handler:  runCommand(async (argv) => {
+    const r = await get(`/AIConfiguration/${argv.id}/resolved-model`);
+    if (!r?.isStaff) { console.log('Velaro Default (model name is visible to Velaro staff only)'); return; }
+    console.log(`resolved: ${r.resolvedModel ?? 'unknown'}  ${r.usingDefault ? '(Velaro Default)' : `(explicit: ${r.explicitModel})`}`);
+  }),
+};
+
+// ── model-calls ───────────────────────────────────────────────────────────────
+
+const aiConfigModelCallsCommand = {
+  command:  'model-calls',
+  describe: 'Velaro staff only: recent AI calls on the current site with the model each call used',
+  builder:  (y) => y
+    .option('role',  { type: 'string', describe: 'AI role filter, e.g. chatbot' })
+    .option('limit', { type: 'number', default: 50 }),
+  handler:  runCommand(async (argv) => {
+    const qs = new URLSearchParams({ limit: String(argv.limit) });
+    if (argv.role) qs.set('role', argv.role);
+    const rows = (await get(`/AIConfiguration/model-calls?${qs}`)) ?? [];
+    if (!rows.length) { console.log('No AI calls found.'); return; }
+    for (const r of rows)
+      console.log(`${new Date(r.calledAt).toISOString()}  ${String(r.role).padEnd(22)} ${String(r.modelId).padEnd(28)} in ${r.inputTokens} out ${r.outputTokens}  $${Number(r.estimatedCostUsd).toFixed(4)}`);
+  }),
+};

package/lib/commands/index-move.js

@@ -0,0 +1,170 @@
+// velaro index-move — move or split knowledge between indexes with no rescan and no OCR, check an
+// index for integrity, and watch/resume/undo a move. Wraps velaro-messaging IndexMoveController
+// (docs/architecture/index-move-and-integrity.md there). The site always comes from your login,
+// never from an argument. Same routes the admin "Knowledge Setup" page uses.
+import { messagingGet, messagingPost } from '../api.js';
+import { runCommand } from '../run.js';
+
+const enc = encodeURIComponent;
+const n = (v) => (v ?? 0).toLocaleString('en-US');
+
+function selectorFrom(argv) {
+  const sel = {};
+  if (argv.all) sel.all = true;
+  if (argv['job-id']) sel.jobId = argv['job-id'];
+  if (argv['url-prefix']) sel.urlPrefix = argv['url-prefix'];
+  if (argv['source-type']) sel.sourceType = argv['source-type'];
+  if (argv['file-name']) sel.fileNames = [].concat(argv['file-name']);
+  if (argv['doc-id']) sel.docIds = [].concat(argv['doc-id']).map(Number);
+  return sel;
+}
+
+function moveBody(argv) {
+  const selector = selectorFrom(argv);
+  if (Object.keys(selector).length === 0) {
+    throw new Error('Give a selector: --all, --job-id, --url-prefix, --file-name, --doc-id or --source-type.');
+  }
+  return {
+    fromIndex: argv.from,
+    toIndex: argv.to,
+    kind: argv.copy ? 'copy' : 'move',
+    skipBlocked: !!argv['skip-blocked'],
+    selector,
+  };
+}
+
+export function printPlan(p) {
+  const q = p.quotaEffect ?? {};
+  console.log(`\n${p.kind}: ${p.fromIndex} -> ${p.toIndex}`);
+  console.log(`  Documents: ${n(p.docs)}   Chunks: ${n(p.chunks)}   Pages: ${n(p.pages)}`);
+  console.log(`  Copied as is: ${n(p.copyVectorsDocs)}   Re-split from saved text: ${n(p.rechunkDocs)}   Already there: ${n(p.alreadyInTargetDocs)}   Blocked: ${n(p.blockedDocs)}`);
+  console.log(`  Storage: ${n(q.indexedChunksCurrent)} -> ${n((q.indexedChunksCurrent ?? 0) + (q.indexedChunksDelta ?? 0))} of ${n(q.indexedChunksMax)} chunks`);
+  console.log('  No rescan, no OCR.');
+  for (const r of p.reasons ?? []) console.log(`  Problem: ${r}`);
+  for (const w of p.warnings ?? []) console.log(`  Note: ${w}`);
+  console.log(`  Can run: ${p.canExecute ? 'yes' : 'no'}`);
+}
+
+export function printStatus(s) {
+  console.log(`\nMove ${s.moveId} (${s.kind}): ${s.fromIndex} -> ${s.toIndex}`);
+  console.log(`  Status: ${s.status}   Documents: ${s.docsDone}/${s.totalDocs} done, ${s.docsSkipped} skipped, ${s.docsFailed} failed`);
+  if (s.errorMessage) console.log(`  Error: ${s.errorMessage}`);
+  const can = [s.canResume && 'resume', s.canAbort && 'abort', s.canUndo && 'undo'].filter(Boolean);
+  if (can.length) console.log(`  You can: ${can.join(', ')}`);
+}
+
+const out = (argv, data, printer) => {
+  if (argv.json) console.log(JSON.stringify(data, null, 2));
+  else printer(data);
+};
+
+export const indexMoveCommand = {
+  command: 'index-move',
+  describe: 'Move/split content between knowledge indexes (no rescan, no OCR), check index integrity',
+  builder: (yargs) => yargs
+    .command('preview', 'Show what a move would do. Writes nothing.', (y) => y
+      .option('from', { type: 'string', demandOption: true })
+      .option('to', { type: 'string', demandOption: true })
+      .option('all', { type: 'boolean' })
+      .option('job-id', { type: 'string' })
+      .option('url-prefix', { type: 'string' })
+      .option('source-type', { type: 'string' })
+      .option('file-name', { type: 'string' })
+      .option('doc-id', { type: 'number' })
+      .option('copy', { type: 'boolean', describe: 'Copy instead of move' })
+      .option('skip-blocked', { type: 'boolean' })
+      .option('json', { type: 'boolean' }),
+    runCommand(async (a) => out(a, await messagingPost('/IndexMove/Preview', moveBody(a)), printPlan)))
+    .command('execute', 'Run a move. Preview it first.', (y) => y
+      .option('from', { type: 'string', demandOption: true })
+      .option('to', { type: 'string', demandOption: true })
+      .option('all', { type: 'boolean' })
+      .option('job-id', { type: 'string' })
+      .option('url-prefix', { type: 'string' })
+      .option('source-type', { type: 'string' })
+      .option('file-name', { type: 'string' })
+      .option('doc-id', { type: 'number' })
+      .option('copy', { type: 'boolean' })
+      .option('skip-blocked', { type: 'boolean' })
+      .option('json', { type: 'boolean' }),
+    runCommand(async (a) => {
+      const r = await messagingPost('/IndexMove/Execute', moveBody(a));
+      out(a, r, (d) => console.log(`Started move ${d.moveId}. Check it with: velaro index-move status --id ${d.moveId}`));
+    }))
+    .command('split', 'Move detected manuals out of a general index into a troubleshooting index', (y) => y
+      .option('from', { type: 'string', demandOption: true })
+      .option('to', { type: 'string', demandOption: true, describe: 'An existing troubleshooting-purpose index' })
+      .option('doc-id', { type: 'number', describe: 'Only these documents (default: every detected manual)' })
+      .option('skip-blocked', { type: 'boolean' })
+      .option('execute', { type: 'boolean', describe: 'Run it. Without this, only previews.' })
+      .option('json', { type: 'boolean' }),
+    runCommand(async (a) => {
+      const body = { fromIndex: a.from, toIndex: a.to, skipBlocked: !!a['skip-blocked'] };
+      if (a['doc-id'] !== undefined) body.docIds = [].concat(a['doc-id']).map(Number);
+      if (a.execute) {
+        const r = await messagingPost('/IndexMove/Split/Execute', body);
+        out(a, r, (d) => console.log(`Started split ${d.moveId}. Check it with: velaro index-move status --id ${d.moveId}`));
+      } else {
+        const r = await messagingPost('/IndexMove/Split/Preview', body);
+        out(a, r, (d) => printPlan(d.plan));
+      }
+    }))
+    .command('status', 'Show one move (--id) or the recent moves', (y) => y
+      .option('id', { type: 'string' })
+      .option('json', { type: 'boolean' }),
+    runCommand(async (a) => {
+      if (a.id) {
+        out(a, await messagingGet(`/IndexMove/Moves/${enc(a.id)}`), printStatus);
+      } else {
+        out(a, await messagingGet('/IndexMove/Moves?take=25'), (list) => list.forEach(printStatus));
+      }
+    }))
+    .command('resume', 'Resume a stopped move', (y) => y.option('id', { type: 'string', demandOption: true }),
+    runCommand(async (a) => {
+      await messagingPost(`/IndexMove/Moves/${enc(a.id)}/Resume`);
+      console.log(`Resumed move ${a.id}.`);
+    }))
+    .command('abort', 'Cancel a queued or failed move that has not started removing content', (y) => y.option('id', { type: 'string', demandOption: true }),
+    runCommand(async (a) => {
+      printStatus(await messagingPost(`/IndexMove/Moves/${enc(a.id)}/Abort`));
+    }))
+    .command('undo', 'Move a completed move back', (y) => y.option('id', { type: 'string', demandOption: true }),
+    runCommand(async (a) => {
+      const r = await messagingPost(`/IndexMove/Moves/${enc(a.id)}/Undo`);
+      console.log(`Started undo as move ${r.moveId}.`);
+    }))
+    .command('mixed', 'Check whether an index holds manual-like documents', (y) => y
+      .option('index', { type: 'string', demandOption: true })
+      .option('json', { type: 'boolean' }),
+    runCommand(async (a) => {
+      const r = await messagingGet(`/IndexMove/MixedContent?index=${enc(a.index)}`);
+      out(a, r, (d) => {
+        console.log(`\n${d.indexName}: ${n(d.manualLikeDocs)} of ${n(d.totalDocs)} documents look like manuals (${n(d.manualLikeChunks)} chunks). ${d.mixed ? 'Recommendation: ' + (d.recommendation ?? 'split') : 'No split needed.'}`);
+        for (const c of d.candidates ?? []) console.log(`  #${c.docId} ${c.title ?? c.sourceId}  ${n(c.chunks)} chunks`);
+      });
+    }))
+    .command('integrity', 'Read-only integrity report for an index', (y) => y
+      .option('index', { type: 'string', demandOption: true })
+      .option('json', { type: 'boolean' }),
+    runCommand(async (a) => {
+      const r = await messagingGet(`/IndexMove/Integrity?index=${enc(a.index)}`);
+      out(a, r, (d) => {
+        const f = d.findings ?? [];
+        console.log(f.length === 0 ? 'No problems found.' : `${f.length} finding(s)${d.truncated ? ' (partial: index is very large)' : ''}:`);
+        for (const x of f) console.log(`  ${x.kind}  ${x.sourceType ?? ''} ${x.sourceId ?? ''}`);
+      });
+    }))
+    .command('repair', 'Repair an index. Additive: fixes counts and records, never deletes content.', (y) => y
+      .option('index', { type: 'string', demandOption: true })
+      .option('remove-duplicate-records', { type: 'boolean', describe: 'Also remove duplicate tracking rows (rows only)' })
+      .option('json', { type: 'boolean' }),
+    runCommand(async (a) => {
+      const r = await messagingPost('/IndexMove/Integrity/Repair', {
+        indexName: a.index,
+        removeDuplicateRecords: !!a['remove-duplicate-records'],
+      });
+      out(a, r, () => console.log('Repair finished. Run "velaro index-move integrity --index ' + a.index + '" to confirm.'));
+    }))
+    .demandCommand(1, 'Specify a subcommand: preview, execute, split, status, resume, abort, undo, mixed, integrity, repair'),
+  handler: () => {},
+};

package/lib/commands/magento.js

@@ -7,6 +7,7 @@
  *   velaro magento orders           Search orders by email or order ID
  *   velaro magento products         Search the product catalog
  *   velaro magento logs             View integration activity logs
+ *   velaro magento diagnose         Live connection diagnostic (token, /rest/V1, scopes)
  */
 
 import { request } from '../api.js';
@@ -152,6 +153,27 @@ async function logsHandler(argv) {
   console.log('');
 }
 
+// ── diagnose ──────────────────────────────────────────────────────────────────
+
+async function diagnoseHandler(argv) {
+  const siteId = argv['site-id'];
+  if (!siteId) {
+    console.error(`${RED}✗ --site-id is required${RST}`);
+    process.exitCode = 1;
+    return;
+  }
+  try {
+    // Messaging DiagController: GET diagnostics/test-magento?siteId=<id>
+    const r = await request('GET', `/diagnostics/test-magento?siteId=${encodeURIComponent(siteId)}`);
+    console.log(`\n${BOLD}Magento diagnostic (site ${siteId})${RST}\n`);
+    console.log(JSON.stringify(r, null, 2));
+    console.log('');
+  } catch (e) {
+    console.error(`\n${RED}✗ Diagnostic failed: ${e.message}${RST}\n`);
+    process.exitCode = 1;
+  }
+}
+
 // ── command export ────────────────────────────────────────────────────────────
 
 export const magentoCommand = {
@@ -205,6 +227,13 @@ export const magentoCommand = {
         .option('page-size', { describe: 'Results per page (default: 25)', type: 'number', default: 25 }),
       handler: logsHandler,
     })
+    .command({
+      command:  'diagnose',
+      describe: 'Live Magento connection diagnostic for a site',
+      builder: yy => yy
+        .option('site-id', { describe: 'Site ID to diagnose', type: 'number' }),
+      handler: diagnoseHandler,
+    })
     .demandCommand(1, 'Specify a subcommand. Try: velaro magento --help'),
   handler: () => {},
 };

package/lib/commands/netsuite.js

@@ -54,6 +54,36 @@ async function generateHandler(argv) {
   printUrls(urls);
 }
 
+// velaro netsuite m2m init|save|verify - OAuth 2.0 Client Credentials (machine-to-machine).
+// Backend: NetSuiteAuthController POST NetSuite/M2M/Init | Save | Verify (velaro-messaging).
+function printChecks(res) {
+  const checks = Array.isArray(res?.checks) ? res.checks : [];
+  console.log(`\n${BOLD}NetSuite M2M verification${RST}`);
+  for (const c of checks) {
+    console.log(`  ${c.ok ? 'PASS' : 'FAIL'} ${c.name}${c.ok ? '' : ` - ${c.reason || c.reasonCode || 'failed'}`}`);
+    if (!c.ok && c.howToFix) console.log(`      ${DIM}How to fix: ${c.howToFix}${RST}`);
+  }
+  console.log('');
+}
+
+async function m2mInitHandler(argv) {
+  const res = await messagingPost('/NetSuite/M2M/Init', { id: argv.config ?? null, company: argv.company, displayName: argv.name });
+  console.log(`\n${BOLD}Velaro public certificate${RST} (config ${res.id ?? argv.config ?? 'new'})`);
+  console.log('Upload in NetSuite: Setup > Integration > Manage Authentication > OAuth 2.0 Client Credentials (M2M) Setup');
+  console.log(res.certificatePem ?? '(no certificate returned)');
+  if (Array.isArray(res.steps)) res.steps.forEach((st, i) => console.log(`  ${i + 1}. ${st}`));
+  console.log('');
+}
+
+async function m2mSaveHandler(argv) {
+  await messagingPost('/NetSuite/M2M/Save', { id: Number(argv.configId), clientId: argv.clientId, certificateId: argv.certificateId });
+  console.log(`\n  ${GRN}Saved.${RST} Run "velaro netsuite m2m verify ${argv.configId}".\n`);
+}
+
+async function m2mVerifyHandler(argv) {
+  printChecks(await messagingPost('/NetSuite/M2M/Verify', { id: Number(argv.configId) }));
+}
+
 export const netsuiteCommand = {
   command:  'netsuite <subcommand>',
   describe: 'NetSuite integration setup (click-to-dial / CTI)',
@@ -81,6 +111,31 @@ export const netsuiteCommand = {
         .strict(),
       handler: () => {},
     })
+    .command({
+      command:  'm2m <action>',
+      describe: 'NetSuite machine-to-machine (OAuth 2.0 Client Credentials) setup',
+      builder: yy => yy
+        .command({
+          command: 'init',
+          describe: 'Generate the Velaro public certificate to upload into NetSuite',
+          builder: a => a.option('config', { type: 'number' }).option('company', { type: 'string' }).option('name', { type: 'string' }),
+          handler: m2mInitHandler,
+        })
+        .command({
+          command: 'save <configId>',
+          describe: 'Store the Client ID and Certificate ID from NetSuite',
+          builder: a => a.option('client-id', { type: 'string', demandOption: true }).option('certificate-id', { type: 'string', demandOption: true }),
+          handler: argv => m2mSaveHandler({ configId: argv.configId, clientId: argv['client-id'], certificateId: argv['certificate-id'] }),
+        })
+        .command({
+          command: 'verify <configId>',
+          describe: 'Run the per-check verification (token, REST, customer read)',
+          handler: m2mVerifyHandler,
+        })
+        .demandCommand(1, 'Specify an m2m action: init, save, or verify.')
+        .strict(),
+      handler: () => {},
+    })
     .demandCommand(1, 'Specify a netsuite subcommand.')
     .strict(),
   handler: () => {},

package/lib/commands/scraper.js

@@ -0,0 +1,27 @@
+// velaro scraper usage --site <id> — Velaro staff only. Scraper / upload / chunk consumption for
+// any site (GET ScraperJobs/StaffUsage/{siteId}; IsVelaroAdminAsync + super-admin enforced
+// server-side). The site is always explicit in the route, never derived from the caller's auth.
+import { request } from '../api.js';
+
+const n = (v) => (v ?? 0).toLocaleString('en-US');
+
+async function usage(argv) {
+  const u = await request('GET', `ScraperJobs/StaffUsage/${encodeURIComponent(argv.site)}`);
+  if (argv.json) { console.log(JSON.stringify(u, null, 2)); return; }
+  console.log(`\nScraper usage, site ${u.siteId}${u.isTrial ? ' (trial)' : ''}`);
+  console.log(`  Crawl pages this month:  ${n(u.pagesThisMonthEffective)} / ${n(u.pagesBudgetPerMonth)}  (admin ledger ${n(u.pagesThisMonthAdminLedger)}, messaging ledger ${u.pagesThisMonthMessagingLedger ?? 'n/a'})`);
+  console.log(`  Upload pages this month: ${n(u.uploadPagesThisMonth)} / ${n(u.uploadPagesBudgetPerMonth)}`);
+  console.log(`  OCR pages this month:    ${n(u.ocrPagesThisMonth)}`);
+  console.log(`  Jobs today:              ${n(u.jobsToday)} / ${n(u.maxJobsPerDay)}`);
+  console.log(`  Chunks indexed:          ${n(u.chunksIndexed)} / ${n(u.maxIndexedChunkTotal)}`);
+  for (const i of u.chunksByIndex ?? []) console.log(`    ${i.indexName}: ${n(i.chunks)} chunks, ${n(i.documents)} docs`);
+  for (const note of u.notes ?? []) console.log(`  Note: ${note}`);
+}
+
+export function scraperCommand(yargs) {
+  return yargs
+    .command('usage', 'Show scraper/upload/chunk usage for a site (staff only)', (y) => y
+      .option('site', { type: 'number', demandOption: true, describe: 'Target site id' })
+      .option('json', { type: 'boolean', describe: 'Print raw JSON' }), (a) => usage(a))
+    .demandCommand(1, 'Specify a subcommand: usage');
+}

package/lib/commands/support.js

@@ -105,8 +105,21 @@ async function listDeployments(args) {
   console.log('Use the embed key as test-frame.html?siteId=<site>&deploymentId=<embed-key>.');
 }
 
+async function tourInsights(args) {
+  const days = Math.min(365, Math.max(1, args.days ?? 30));
+  const path = args.site
+    ? `SupportTools/sites/${args.site}/tour-events?days=${days}`
+    : `SupportTools/tour-insights?days=${days}`;
+  const result = await request('GET', path);
+  console.log(JSON.stringify(result, null, 2));
+}
+
 export function supportCommand(yargs) {
   return yargs
+    .command('tour-insights', 'Moshky setup-tour funnel + scrubbed feedback across all sites, or one site\'s tour timeline with --site (Velaro staff, read-only)', y => y
+      .option('site', { type: 'number', desc: 'Optional site ID: show that site\'s tour events and feedback instead of the funnel' })
+      .option('days', { type: 'number', default: 30, desc: 'Look-back window in days (max 365)' })
+    , a => tourInsights(a))
     .command('deployments', 'List a site’s widget embed keys and survey assignments (Velaro staff, read-only)', y => y
       .option('site', { type: 'number', demandOption: true, desc: 'Target site ID' })
       .option('json', { type: 'boolean', default: false, desc: 'Print the complete JSON response' })
@@ -142,5 +155,5 @@ export function supportCommand(yargs) {
       .option('channel',         { type: 'string', desc: 'Conversation source, e.g. Web, TwilioSms (default Web)' })
       .option('overrideIndexes', { type: 'string', desc: 'Comma-separated index names to override the config\'s own IndexName for this query' })
     , a => chatQuery(a))
-    .demandCommand(1, 'Specify a subcommand: deployments | impersonate | agent-lookup | toggle-flag | scraper-create-job | chat-query | send-email');
+    .demandCommand(1, 'Specify a subcommand: deployments | impersonate | agent-lookup | toggle-flag | scraper-create-job | chat-query | send-email | tour-insights');
 }

package/lib/commands/tour-policy.js

@@ -0,0 +1,61 @@
+// velaro tour-policy — Velaro staff only. Guided-tour auto-open policy, resolved
+// site override, then global default, then built-in default. Every write is versioned
+// (last 20) and reversible. Site is always explicit in the route (TourPolicy/sites/{siteId}/...),
+// never derived from the caller's auth context; omit --site for the global default (Velaro Admin).
+import { request } from '../api.js';
+
+const enc = encodeURIComponent;
+const base = (argv) =>
+  argv.site ? `TourPolicy/sites/${argv.site}/${enc(argv.tour)}` : `TourPolicy/global/${enc(argv.tour)}`;
+
+const fmt = (p) =>
+  p ? `${p.enabled ? 'ON' : 'OFF'}, ${p.maxAutoOpens} opens, ${p.minHoursBetweenAutoOpens}h apart, ${p.windowDays}d window${p.source ? ` (source: ${p.source})` : ''}` : '(none)';
+
+async function get(argv) {
+  const r = await request('GET', base(argv));
+  console.log(`\nTour ${r.tourKey}, ${argv.site ? `site ${argv.site}` : 'global default'}`);
+  console.log(`  Stored:    ${fmt(r.stored)}`);
+  if (argv.site) console.log(`  Effective: ${fmt(r.effective)}`);
+}
+
+async function set(argv) {
+  const body = {};
+  if (argv.enabled !== undefined) body.enabled = argv.enabled;
+  if (argv.maxAutoOpens !== undefined) body.maxAutoOpens = argv.maxAutoOpens;
+  if (argv.minHours !== undefined) body.minHoursBetweenAutoOpens = argv.minHours;
+  if (argv.windowDays !== undefined) body.windowDays = argv.windowDays;
+  const r = await request('PUT', base(argv), body);
+  console.log(`Saved as version ${r.version.version}. Undo with: velaro tour-policy rollback --tour ${argv.tour}${argv.site ? ` --site ${argv.site}` : ''} --version <n>`);
+}
+
+async function history(argv) {
+  const r = await request('GET', `${base(argv)}/history`);
+  if (!r.versions?.length) { console.log('No history yet.'); return; }
+  for (const v of r.versions) {
+    const restored = v.restoredFromVersion ? ` (from v${v.restoredFromVersion})` : '';
+    console.log(`v${v.version} ${v.action}${restored} by ${v.by} at ${v.at}: ${fmt(v.oldPolicy)} -> ${fmt(v.newPolicy)}`);
+  }
+}
+
+async function rollback(argv) {
+  const r = await request('POST', `${base(argv)}/rollback`, { version: argv.version });
+  console.log(`Restored v${argv.version} as new version ${r.version.version}.`);
+}
+
+const common = (y) => y
+  .option('tour', { type: 'string', default: 'CommerceWelcome', describe: 'CommerceWelcome or ShopifyWelcome' })
+  .option('site', { type: 'number', describe: 'Site id. Omit for the global default (Velaro Admin).' });
+
+export function tourPolicyCommand(yargs) {
+  return yargs
+    .command('get', 'Show stored and effective tour policy', common, (a) => get(a))
+    .command('set', 'Set tour policy (partial: omitted fields keep their value)', (y) => common(y)
+      .option('enabled', { type: 'boolean' })
+      .option('max-auto-opens', { type: 'number', alias: 'maxAutoOpens', describe: '0-20' })
+      .option('min-hours', { type: 'number', describe: 'Hours between auto-opens, 0-720' })
+      .option('window-days', { type: 'number', alias: 'windowDays', describe: '1-365' }), (a) => set(a))
+    .command('history', 'List the last 20 versions, newest first', common, (a) => history(a))
+    .command('rollback', 'Restore the state after a version (recorded as a new version)', (y) => common(y)
+      .option('version', { type: 'number', demandOption: true }), (a) => rollback(a))
+    .demandCommand(1, 'Specify a subcommand: get | set | history | rollback');
+}

package/lib/commands/workflow.js

@@ -1,5 +1,5 @@
 import fs                          from 'node:fs';
-import { get, post, getCredentials, messagingGet } from '../api.js';
+import { getCredentials, messagingGet, messagingPost, messagingPut } from '../api.js';
 import { requireFeature }          from '../subscription.js';
 import { runCommand }              from '../run.js';
 
@@ -20,6 +20,9 @@ export const workflowCommand = {
 };
 
 // ── list ───────────────────────────────────────────────────────────────────────
+// NOTE: every /Workflows/* route lives on the messaging API (WorkflowsController in
+// velaro-messaging), never the admin API — these commands were 404ing in every environment
+// until fixed 2026-09-27 because they called the admin-API-only get()/post() helpers.
 
 const workflowListCommand = {
   command:  'list',
@@ -27,7 +30,7 @@ const workflowListCommand = {
   handler:  runCommand(async () => {
     await requireFeature('enableAutomation', 'Workflows');
 
-    const workflows = await get('/Workflows/List');
+    const workflows = await messagingGet('/Workflows/List');
     const rows = (workflows ?? []).filter(w => !w.isTemplate);
 
     if (!rows.length) { console.log('No workflows found.'); return; }
@@ -56,14 +59,17 @@ const workflowGetCommand = {
   handler:  runCommand(async (argv) => {
     await requireFeature('enableAutomation', 'Workflows');
 
-    const w = await get(`/Workflows/${argv.id}`);
+    const w = await messagingGet(`/Workflows/${argv.id}`);
     if (!w) { console.error(`Workflow ${argv.id} not found.`); process.exit(1); }
 
     console.log(`\n[${w.id}] ${w.name}`);
     console.log(`  Status:  ${w.enabled ? 'enabled' : 'disabled'}`);
     console.log(`  Trigger: ${w.triggerType ?? '—'}`);
-    if (w.nodes?.length) {
-      console.log(`  Nodes:   ${w.nodes.length}`);
+    // WorkflowViewModel.Nodes serializes as a JSON object keyed by node id
+    // (Dictionary<int, WorkflowNode>), not an array.
+    const nodeCount = w.nodes ? Object.keys(w.nodes).length : 0;
+    if (nodeCount) {
+      console.log(`  Nodes:   ${nodeCount}`);
     }
   }),
 };
@@ -100,7 +106,7 @@ const workflowCreateCommand = {
       };
     }
 
-    const id = await post('/Workflows', body);
+    const id = await messagingPost('/Workflows', body);
     console.log(`Workflow created: ${id}`);
     console.log(`View: velaro workflow get ${id}`);
   }),
@@ -114,7 +120,16 @@ const workflowEnableCommand = {
   builder:  (y) => y.positional('id', { type: 'number', describe: 'Workflow ID' }),
   handler:  runCommand(async (argv) => {
     await requireFeature('enableAutomation', 'Workflows');
-    await post(`/Workflows/toggle/${argv.id}`, null);
+
+    const w = await messagingGet(`/Workflows/${argv.id}`);
+    if (!w) { console.error(`Workflow ${argv.id} not found.`); process.exit(1); }
+
+    if (w.enabled) {
+      console.log(`Workflow ${argv.id} is already enabled.`);
+      return;
+    }
+
+    await messagingPost(`/Workflows/toggle/${argv.id}`, null);
     console.log(`Workflow ${argv.id} enabled.`);
   }),
 };
@@ -126,7 +141,7 @@ const workflowDisableCommand = {
   handler:  runCommand(async (argv) => {
     await requireFeature('enableAutomation', 'Workflows');
 
-    const w = await get(`/Workflows/${argv.id}`);
+    const w = await messagingGet(`/Workflows/${argv.id}`);
     if (!w) { console.error(`Workflow ${argv.id} not found.`); process.exit(1); }
 
     if (!w.enabled) {
@@ -134,12 +149,17 @@ const workflowDisableCommand = {
       return;
     }
 
-    await post(`/Workflows/toggle/${argv.id}`, null);
+    await messagingPost(`/Workflows/toggle/${argv.id}`, null);
     console.log(`Workflow ${argv.id} disabled.`);
   }),
 };
 
 // ── node-options ───────────────────────────────────────────────────────────────
+// The backend has no per-node route — WorkflowsController only exposes [HttpPut] on the
+// whole workflow (PutAsync(WorkflowViewModel)). This command previously POSTed to a
+// nonexistent `/Workflows/{workflowId}/node/{nodeId}` route; it now reads the full workflow,
+// mutates the one node in its Nodes dictionary, and PUTs the whole WorkflowViewModel back —
+// the same read-modify-write the admin canvas UI performs on every node edit.
 
 const workflowNodeOptionsCommand = {
   command:  'node-options <workflowId> <nodeId>',
@@ -156,10 +176,14 @@ const workflowNodeOptionsCommand = {
   handler:  runCommand(async (argv) => {
     await requireFeature('enableAutomation', 'Workflows');
 
-    const w = await get(`/Workflows/${argv.workflowId}`);
+    const w = await messagingGet(`/Workflows/${argv.workflowId}`);
     if (!w) { console.error(`Workflow ${argv.workflowId} not found.`); process.exit(1); }
 
-    const node = (w.nodes ?? []).find(n => n.id === argv.nodeId) ?? Object.values(w.nodes ?? {})[argv.nodeId];
+    // Nodes is a Dictionary<int, WorkflowNode> — serializes as a JSON object keyed by
+    // node id string, not an array.
+    const nodes = w.nodes ?? {};
+    const nodeKey = String(argv.nodeId);
+    const node = nodes[nodeKey];
     if (!node) { console.error(`Node ${argv.nodeId} not found in workflow ${argv.workflowId}.`); process.exit(1); }
     if (node.actionType !== 'askQuestion' || node.questionType !== 'multiSelect') {
       console.error(`Node ${argv.nodeId} is not a multiSelect ask-question node (found: ${node.actionType}/${node.questionType}).`);
@@ -168,6 +192,16 @@ const workflowNodeOptionsCommand = {
 
     const hasChanges = argv.options || argv.min != null || argv.max != null || argv['dynamic-var'] || argv.strategy;
 
+    // WorkflowNode (velaro-messaging) has no MinSelections/MaxSelections/OptionsSource/
+    // DynamicOptionsVariable properties and no [JsonExtensionData] catch-all, so these fields
+    // are silently dropped on save — confirmed by reading WorkflowNode's source. Refuse rather
+    // than print a false "Node updated." The admin canvas (MultiSelectEditor.tsx) has the same
+    // gap; the real fix is adding those properties server-side.
+    if (argv.min != null || argv.max != null || argv['dynamic-var']) {
+      console.error('--min, --max, and --dynamic-var are not supported yet: WorkflowNode has no backing fields for them, so the server silently drops them on save. Only --options and --strategy actually persist.');
+      process.exit(1);
+    }
+
     if (!hasChanges) {
       // Read mode — print current config
       console.log(`\nNode ${argv.nodeId} — multiSelect options:`);
@@ -184,21 +218,16 @@ const workflowNodeOptionsCommand = {
       return;
     }
 
-    // Update mode
+    // Update mode — only --options and --strategy have backing fields on WorkflowNode today.
     const updated = { ...node };
     if (argv.options) {
       updated.options = JSON.parse(argv.options);
       updated.optionsSource = 'static';
     }
-    if (argv['dynamic-var']) {
-      updated.dynamicOptionsVariable = argv['dynamic-var'];
-      updated.optionsSource = 'dynamic';
-    }
-    if (argv.min != null)  updated.minSelections = argv.min;
-    if (argv.max != null)  updated.maxSelections = argv.max;
-    if (argv.strategy)     updated.largeListStrategy = argv.strategy;
+    if (argv.strategy) updated.largeListStrategy = argv.strategy;
 
-    await post(`/Workflows/${argv.workflowId}/node/${argv.nodeId}`, updated);
+    const updatedWorkflow = { ...w, nodes: { ...nodes, [nodeKey]: updated } };
+    await messagingPut('/Workflows', updatedWorkflow);
     console.log(`Node ${argv.nodeId} updated.`);
   }),
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@velaro/cli",
-  "version": "1.4.58",
+  "version": "1.4.60",
   "description": "Velaro Workspace v20 — command-line interface for managing bots, knowledge base ingestion, MCP API keys, search indexes, and ops health.",
   "type": "module",
   "bin": {
@@ -17,7 +17,7 @@
     "@azure/identity": "^4.4.1",
     "@azure/keyvault-secrets": "^4.9.0",
     "mssql": "^12.7.0",
-    "pdfkit": "^0.15.2",
+    "pdfkit": "^0.20.2",
     "yargs": "^17.7.2"
   },
   "optionalDependencies": {
@@ -33,5 +33,8 @@
     "lib/",
     "scripts/",
     "assets/"
-  ]
+  ],
+  "devDependencies": {
+    "license-checker-rseidelsohn": "^4.4.2"
+  }
 }