@velaro/cli 1.4.57 → 1.4.59

package/README.md

@@ -104,6 +104,17 @@ client using the old key; the command does not edit client configurations.
 velaro mcp-key rotate 2
 ```
 
+### `velaro routing <subcommand>`
+Auto-routing policy and the agent inactivity chain (v20 only).
+
+```bash
+velaro routing policy get                                   # includes reassignment mode + chain
+velaro routing policy set --reassignment-mode Reassign --chain true --backup-team 5 --backup-after 120 --no-agent-after 300 --terminal-action EndChat
+velaro routing simulate --no-agent-seconds 400 --step 1     # DRY RUN, nothing is sent
+velaro routing precedence                                   # which rule wins + conflict warnings
+velaro routing inactivity-transfers --days 30 --agent-name Sam
+```
+
 ### `velaro kb article <subcommand>`
 Manage your help.velaro.com knowledge base articles. Full reference (including the REST/MCP equivalents and the screenshot pipeline): [`docs/architecture/kb-publishing-system.md`](../docs/architecture/kb-publishing-system.md).
 

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

@@ -1,4 +1,8 @@
-import { messagingGet, messagingPut, messagingDel, get as adminGet } from '../api.js';
+import { messagingGet, messagingPut, messagingPost, messagingDel, get as adminGet } from '../api.js';
+import {
+  TERMINAL_ACTION_NAMES, buildPolicyUpdate, validatePolicyUpdate, describeChain,
+  describeSimulation, describeTransfers,
+} from '../routing-inactivity.js';
 
 // ── helpers ───────────────────────────────────────────────────────────────────
 
@@ -26,8 +30,18 @@ const TERMINAL_LABELS = {
   3: 'Queue',
   4: 'Offline Message',
   5: 'No Action',
+  6: 'End Chat',
+  7: 'Notify Manager',
+  8: 'Run Workflow',
 };
 
+// The API returns the terminal action as a NAME (e.g. "EndChat"); older builds returned an int.
+function terminalText(v) {
+  if (v == null) return 'Default (Survey)';
+  if (typeof v === 'number') return TERMINAL_LABELS[v] ?? String(v);
+  return String(v);
+}
+
 // ── velaro routing engine get ─────────────────────────────────────────────────
 
 const engineGetCommand = {
@@ -129,10 +143,8 @@ const policyGetCommand = {
     console.log(`  ${DIM}Agent follow-up flag:      ${RESET}${p.agentFollowUpFlagEnabled ? `${GRN}yes${RESET}` : 'no'}`);
     console.log(`  ${DIM}Queue unavailable grace:   ${RESET}${p.queueUnavailableGracePeriodSeconds}s`);
 
-    const terminalLabel = p.terminalActionOverride != null
-      ? (TERMINAL_LABELS[p.terminalActionOverride] ?? String(p.terminalActionOverride))
-      : 'Default (Survey)';
-    console.log(`  ${DIM}Terminal action:           ${RESET}${terminalLabel}`);
+    console.log(`  ${DIM}Terminal action:           ${RESET}${terminalText(p.terminalActionOverride)}`);
+    for (const line of describeChain(p)) console.log(`  ${line}`);
     console.log();
   },
 };
@@ -168,26 +180,37 @@ const policySetCommand = {
       describe: 'Prefer previous agent on timeout (true/false)',
     })
     .option('terminal-action', {
-      type:     'number',
-      describe: 'Terminal action: 0=Survey 1=CreateTicket 2=SurveyAndCreateTicket 3=Queue 4=OfflineMessage 5=NoOp',
-    }),
+      type:     'string',
+      describe: `Terminal action, name or 0-8: ${TERMINAL_ACTION_NAMES.map((n, i) => `${i}=${n}`).join(' ')}`,
+    })
+    .option('exhaustion-message', { type: 'string', describe: 'Visitor message when the final action runs' })
+    .option('reassignment-mode', {
+      type: 'string', choices: ['Observe', 'QueueOnly', 'Reassign'],
+      describe: 'Observe = log only (default), QueueOnly = return chat to the queue, Reassign = move to another agent',
+    })
+    .option('chain', { type: 'boolean', describe: 'Turn the agent inactivity chain on/off' })
+    .option('backup-team', { type: 'number', describe: 'Backup group (team) id to offer the chat to' })
+    .option('backup-after', { type: 'number', describe: 'Seconds with no same-group agent before the backup group (0-7200)' })
+    .option('no-agent-after', { type: 'number', describe: 'Seconds with no agent available before the final action (0-14400)' })
+    .option('presence-trigger', { type: 'boolean', describe: 'Reroute when the agent goes Away/Offline' })
+    .option('alert-on-release', { type: 'boolean', describe: 'Alert available agents when a chat is released' })
+    .option('notify-managers', { type: 'boolean', describe: 'Notify managers on inactivity' })
+    .option('cooldown', { type: 'number', describe: 'Seconds between moves of the same chat (0-3600)' })
+    .option('queue-escalation-minutes', { type: 'number', describe: 'Minutes in queue before escalation alert (1-240)' })
+    .option('terminal-workflow', { type: 'number', describe: 'Workflow id to run when the terminal action is RunWorkflow' })
+    .option('visitor-text', { type: 'string', describe: 'Visitor status text (max 500). Tokens: {{releasedFromAgent}} {{reason}} {{teamName}}' })
+    .option('agent-text', { type: 'string', describe: 'Agent status text (max 500)' }),
   handler:  async (argv) => {
     // Load current policy first, then merge
     const current = await messagingGet('/AutoRoutingPolicy');
 
-    const updated = {
-      ...current,
-      initialResponseTimeoutSeconds:  argv['initial-timeout']  ?? current.initialResponseTimeoutSeconds,
-      idleAfterResponseTimeoutSeconds: argv['idle-timeout']     ?? current.idleAfterResponseTimeoutSeconds,
-      idleAlertGraceSeconds:           argv['grace']            ?? current.idleAlertGraceSeconds,
-      maxRerouteAttempts:              argv['max-reroutes']     ?? current.maxRerouteAttempts,
-      allowBounceBack:                 argv['allow-bounceback'] ?? current.allowBounceBack,
-      preferPreviousAgentOnTimeout:    argv['prefer-previous']  ?? current.preferPreviousAgentOnTimeout,
-      terminalActionOverride:
-        argv['terminal-action'] !== undefined
-          ? argv['terminal-action']
-          : current.terminalActionOverride,
-    };
+    const updated = buildPolicyUpdate(current, argv);
+    const problems = validatePolicyUpdate(updated);
+    if (problems.length) {
+      for (const m of problems) console.error(`  ${RED}x${RESET} ${m}`);
+      process.exitCode = 1;
+      return;
+    }
 
     await messagingPut('/AutoRoutingPolicy', updated);
     console.log(`\n  ${GRN}✓${RESET} Routing policy updated.\n`);
@@ -279,7 +302,7 @@ const explainCommand = {
       console.log(`  Initial timeout:    ${p.initialResponseTimeoutSeconds}s`);
       console.log(`  Idle timeout:       ${p.idleAfterResponseTimeoutSeconds}s`);
       console.log(`  Max reroutes:       ${p.maxRerouteAttempts}`);
-      console.log(`  Terminal action:    ${p.terminalActionOverride != null ? TERMINAL_LABELS[p.terminalActionOverride] ?? p.terminalActionOverride : 'default (Survey)'}`);
+      console.log(`  Terminal action:    ${terminalText(p.terminalActionOverride)}`);
       console.log(`  Anti-bounce:        ${!p.allowBounceBack ? `${GRN}ON${RESET}` : `${DIM}off${RESET}`}`);
       console.log(`  Prefer prev agent:  ${p.preferPreviousAgentOnTimeout ? `${GRN}yes${RESET}` : 'no'}`);
     }
@@ -287,6 +310,76 @@ const explainCommand = {
   },
 };
 
+// ── velaro routing simulate ───────────────────────────────────────────────────
+
+const simulateCommand = {
+  command:  'simulate',
+  describe: 'DRY RUN: what would the agent inactivity chain do for a mocked scenario (sends nothing)',
+  builder:  (y) => y
+    .option('team', { type: 'number', describe: 'Group id whose policy to simulate (default: site default)' })
+    .option('no-agent-seconds', { type: 'number', default: 0, describe: 'Seconds nobody has been available' })
+    .option('attempts-used', { type: 'number', default: 0, describe: 'Moves already used on the chat' })
+    .option('step', { type: 'number', default: 0, describe: '0 nothing tried, 1 backup group offered, 2 final action applied' })
+    .option('since-last-transfer', { type: 'number', describe: 'Seconds since the chat was last moved' })
+    .option('already-handled', { type: 'boolean', default: false, describe: 'Simulate the same silence delivered twice' })
+    .option('agent-name', { type: 'string', describe: 'Silent agent name for the alert text' }),
+  handler:  async (argv) => {
+    const r = await messagingPost('/Routing/Inactivity/simulate', {
+      teamId: argv.team ?? null,
+      noAgentSeconds: argv['no-agent-seconds'],
+      attemptsUsed: argv['attempts-used'],
+      inactivityStep: argv.step,
+      secondsSinceLastTransfer: argv['since-last-transfer'] ?? null,
+      sameEpisodeAlreadyHandled: argv['already-handled'],
+      fromAgentName: argv['agent-name'] ?? null,
+    });
+    console.log();
+    for (const l of describeSimulation(r)) console.log(`  ${l}`);
+    console.log();
+  },
+};
+
+// ── velaro routing precedence ─────────────────────────────────────────────────
+
+const precedenceCommand = {
+  command:  'precedence',
+  describe: 'Which routing rule wins when an agent goes silent, plus policy conflict warnings',
+  builder:  (y) => y,
+  handler:  async () => {
+    const [defaults, conflicts] = await Promise.all([
+      messagingGet('/Routing/Inactivity/defaults'),
+      messagingGet('/Routing/Inactivity/conflicts'),
+    ]);
+    console.log(`\n${BOLD}Evaluation order (top to bottom)${RESET}`);
+    for (const p of defaults.precedence ?? []) console.log(`  ${p}`);
+    const list = conflicts.conflicts ?? [];
+    console.log(`\n${BOLD}Warnings${RESET}`);
+    if (!list.length) console.log('  None. No group policy cancels out the site default.');
+    for (const c of list) console.log(`  [${String(c.severity).toUpperCase()}] ${c.teamId != null ? `group ${c.teamId}` : 'site default'}: ${c.message}`);
+    console.log();
+  },
+};
+
+// ── velaro routing inactivity-transfers ───────────────────────────────────────
+
+const inactivityTransfersCommand = {
+  command:  'inactivity-transfers',
+  describe: 'Count agent inactivity transfers (chats taken from a silent agent), total, per agent, per day',
+  builder:  (y) => y
+    .option('days', { type: 'number', default: 30, describe: 'Lookback in days (1-92)' })
+    .option('agent-name', { type: 'string', describe: 'Agent display name (partial match)' })
+    .option('agent-id', { type: 'number', describe: 'Exact agent id' }),
+  handler:  async (argv) => {
+    let path = `RoutingDiagnostics/inactivity-transfers?days=${argv.days}`;
+    if (argv['agent-id'] != null) path += `&agentId=${argv['agent-id']}`;
+    if (argv['agent-name']) path += `&agentName=${encodeURIComponent(argv['agent-name'])}`;
+    const r = await adminGet(path);
+    console.log();
+    for (const l of describeTransfers(r)) console.log(`  ${l}`);
+    console.log();
+  },
+};
+
 // ── top-level routing command ─────────────────────────────────────────────────
 
 export const routingCommand = {
@@ -298,7 +391,10 @@ export const routingCommand = {
     .command(policyCommand)
     .command(decisionLogCommand)
     .command(explainCommand)
-    .demandCommand(1, 'Specify a subcommand: engine, circuit-breaker, policy, decision-log, explain')
+    .command(simulateCommand)
+    .command(precedenceCommand)
+    .command(inactivityTransfersCommand)
+    .demandCommand(1, 'Specify a subcommand: engine, circuit-breaker, policy, decision-log, explain, simulate, precedence, inactivity-transfers')
     .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/lib/routing-inactivity.js

@@ -0,0 +1,160 @@
+// Pure logic for `velaro routing ...` agent inactivity chain commands (velaro-messaging PR #1471).
+// v20 ONLY. No I/O here so it can be unit tested (see routing-inactivity.test.js).
+
+// Persisted as ints by messaging (append-only enum); the API accepts and returns the NAME.
+export const TERMINAL_ACTION_NAMES = [
+  'Survey', 'CreateTicket', 'SurveyAndCreateTicket', 'Queue', 'OfflineMessage', 'NoOp',
+  'EndChat', 'NotifyManager', 'RunWorkflow',
+];
+
+export function terminalLabel(v) {
+  if (v === null || v === undefined || v === '') return 'Default (Survey)';
+  if (typeof v === 'number') return TERMINAL_ACTION_NAMES[v] ?? String(v);
+  return String(v);
+}
+
+/** Accepts an int (0-8) or a name (any case). Returns the enum name, or null for "default". Throws on junk. */
+export function terminalForSave(v) {
+  if (v === null || v === undefined || v === '') return null;
+  if (typeof v === 'number' || /^\d+$/.test(String(v))) {
+    const name = TERMINAL_ACTION_NAMES[Number(v)];
+    if (!name) throw new Error(`Unknown terminal action ${v}. Use 0-8: ${TERMINAL_ACTION_NAMES.map((n, i) => `${i}=${n}`).join(' ')}`);
+    return name;
+  }
+  const hit = TERMINAL_ACTION_NAMES.find(n => n.toLowerCase() === String(v).toLowerCase());
+  if (!hit) throw new Error(`Unknown terminal action "${v}". Use one of: ${TERMINAL_ACTION_NAMES.join(', ')}`);
+  return hit;
+}
+
+// CLI flag -> AutoRoutingPolicy.InactivityChain field
+export const CHAIN_FLAGS = {
+  'chain': 'enabled',
+  'backup-team': 'backupTeamId',
+  'backup-after': 'backupTeamAfterSeconds',
+  'no-agent-after': 'noTargetActionAfterSeconds',
+  'presence-trigger': 'rerouteOnAgentUnavailable',
+  'alert-on-release': 'alertAvailableAgentsOnRelease',
+  'notify-managers': 'notifyManagersOnInactivity',
+  'cooldown': 'rerouteCooldownSeconds',
+  'queue-escalation-minutes': 'queueEscalationAfterMinutes',
+  'terminal-workflow': 'terminalWorkflowId',
+  'visitor-text': 'visitorStatusText',
+  'agent-text': 'agentStatusText',
+};
+
+/**
+ * Merges CLI flags onto the current policy and returns the PUT body.
+ * reassignmentMode is ALWAYS sent (an absent value is treated as Observe by the API and would silently
+ * switch reassignment off). The chain block is only sent when the server reports one or a chain flag is set.
+ */
+export function buildPolicyUpdate(current, argv) {
+  const merged = { ...current };
+  const map = {
+    'initial-timeout': 'initialResponseTimeoutSeconds',
+    'idle-timeout': 'idleAfterResponseTimeoutSeconds',
+    'grace': 'idleAlertGraceSeconds',
+    'max-reroutes': 'maxRerouteAttempts',
+    'allow-bounceback': 'allowBounceBack',
+    'prefer-previous': 'preferPreviousAgentOnTimeout',
+    'exhaustion-message': 'exhaustionMessageTemplate',
+  };
+  for (const [flag, field] of Object.entries(map)) if (argv[flag] !== undefined) merged[field] = argv[flag];
+
+  merged.terminalActionOverride = terminalForSave(
+    argv['terminal-action'] !== undefined ? argv['terminal-action'] : current.terminalActionOverride
+  );
+  // Actions 6-8 exist only on a messaging build with the inactivity chain; an older one would store a different value.
+  if (['EndChat', 'NotifyManager', 'RunWorkflow'].includes(merged.terminalActionOverride) && !('inactivityChain' in current))
+    throw new Error(`Terminal action ${merged.terminalActionOverride} needs a messaging build with the agent inactivity chain; this one does not report it. Use 0-5.`);
+
+  const mode = argv['reassignment-mode'] ?? current.reassignmentMode ?? 'Observe';
+  if (!['Observe', 'QueueOnly', 'Reassign'].includes(mode)) {
+    throw new Error(`Unknown reassignment mode "${mode}". Use Observe, QueueOnly or Reassign.`);
+  }
+  merged.reassignmentMode = mode;
+
+  const patched = Object.keys(CHAIN_FLAGS).filter(f => argv[f] !== undefined);
+  if (current.inactivityChain || patched.length) {
+    const chain = { ...(current.inactivityChain ?? {}) };
+    for (const f of patched) chain[CHAIN_FLAGS[f]] = argv[f];
+    merged.inactivityChain = chain;
+  }
+  return merged;
+}
+
+/** Client-side mirror of the server's cross-field rules, so the CLI fails before the round trip. */
+export function validatePolicyUpdate(p) {
+  const errors = [];
+  const c = p.inactivityChain;
+  // RunWorkflow with no workflow is invalid whatever the chain switch says: the final action also runs
+  // when the chain is off (hop cap reached), so it would have nothing to run.
+  if (p.terminalActionOverride === 'RunWorkflow' && (!c || c.terminalWorkflowId == null))
+    errors.push('Terminal action RunWorkflow needs --terminal-workflow <id>.');
+  if (!c || !c.enabled) return errors;
+  if ((c.backupTeamId != null || c.noTargetActionAfterSeconds != null) && p.reassignmentMode !== 'Reassign')
+    errors.push("The backup group and no-agent-available steps need --reassignment-mode Reassign.");
+  if (c.backupTeamId != null && c.noTargetActionAfterSeconds != null && c.noTargetActionAfterSeconds < (c.backupTeamAfterSeconds ?? 120))
+    errors.push('--no-agent-after must be at least as long as --backup-after (the backup group step runs first).');
+  return errors;
+}
+
+export function describeChain(p) {
+  const c = p.inactivityChain;
+  if (!c) return ['(This messaging build does not report the inactivity chain.)'];
+  const out = [
+    `Reassignment mode:     ${p.reassignmentMode ?? 'Observe'}`,
+    `Inactivity chain:      ${c.enabled ? 'ON' : 'off'}`,
+  ];
+  if (c.enabled) {
+    out.push(
+      `  Backup group:        ${c.backupTeamId ?? 'none'}${c.backupTeamId != null ? ` after ${c.backupTeamAfterSeconds}s` : ''}`,
+      `  Final action after:  ${c.noTargetActionAfterSeconds != null ? `${c.noTargetActionAfterSeconds}s with no agent available` : 'only when the hop cap is used up'}`,
+      `  Cooldown:            ${c.rerouteCooldownSeconds}s`,
+      `  Presence trigger:    ${c.rerouteOnAgentUnavailable}`,
+      `  Alert on release:    ${c.alertAvailableAgentsOnRelease}`,
+      `  Notify managers:     ${c.notifyManagersOnInactivity}`,
+      `  Queue escalation:    ${c.queueEscalationAfterMinutes != null ? `${c.queueEscalationAfterMinutes} min` : 'never'}`,
+      `  Terminal workflow:   ${c.terminalWorkflowId ?? 'none'}`,
+    );
+  }
+  return out;
+}
+
+const GATE = {
+  NotEnabled: "The inactivity chain is off for this rule, so today's behavior applies and nothing new happens.",
+  Proceed: 'Allowed to move the chat.',
+  SkipDedupe: 'Blocked: this exact silence was already handled (double-transfer guard).',
+  SkipCooldown: 'Blocked: the chat was moved too recently (cooldown).',
+  HopCapReached: 'Hop cap reached: no more moves, so the final action applies.',
+};
+const ACTION = {
+  LegacyDefer: 'Nothing new is configured, so the chat stays with its current owner.',
+  Hold: 'Still inside the wait window, nothing happens yet.',
+  WidenToBackupTeam: 'The chat is offered to the backup group.',
+  ApplyTerminal: 'The final action runs.',
+};
+
+export function describeSimulation(r) {
+  const lines = [
+    'DRY RUN (nothing sent, no live chat touched)',
+    `Settings used: ${r.ruleSource}`,
+    `Safety gate:   ${GATE[r.gate] ?? r.gate}`,
+    `Decision:      ${ACTION[r.noTargetAction] ?? r.noTargetAction}`,
+  ];
+  if (r.explanation) lines.push(`Why:           ${r.explanation}`);
+  if (r.nextStepAtSeconds != null) lines.push(`Next step after ${r.nextStepAtSeconds}s with no agent available.`);
+  lines.push(`Visitor would see: "${r.visitorMessage}"`, `Agents would see:  "${r.queueAlert || r.agentStatus}"`);
+  for (const l of r.otherRulesThatMatchedButLost ?? []) lines.push(`Also matched but lost: ${l.rule} (${l.reason})`);
+  return lines;
+}
+
+export function describeTransfers(r) {
+  if (r.note && !r.total && !(r.byAgent ?? []).length) return [r.note];
+  const lines = [`Agent inactivity transfers, site ${r.siteId}, last ${r.days} days: ${r.total}${r.capped ? ' (capped at 5000)' : ''}`];
+  if (r.note) lines.push(r.note);
+  if (r.matchedAgentsCapped) lines.push('The name matched more agents than are counted here. Use a longer name or --agent-id.');
+  for (const a of r.byAgent ?? []) lines.push(`  ${a.name}${a.agentId != null ? ` (id ${a.agentId})` : ''}: ${a.count}`);
+  if ((r.byDay ?? []).length) lines.push('', 'By day (Pacific): ' + r.byDay.map(d => `${d.date}=${d.count}`).join(', '));
+  if (!r.total) lines.push('None. Check that the inactivity chain is on and reassignment mode is not Observe.');
+  return lines;
+}

package/lib/routing-inactivity.test.js

@@ -0,0 +1,101 @@
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import {
+  buildPolicyUpdate, validatePolicyUpdate, terminalForSave, terminalLabel,
+  describeChain, describeSimulation, describeTransfers,
+} from './routing-inactivity.js';
+
+const current = {
+  enabled: true, maxRerouteAttempts: 3, terminalActionOverride: 'Survey', reassignmentMode: 'Reassign',
+  inactivityChain: { enabled: true, backupTeamId: 5, backupTeamAfterSeconds: 120, noTargetActionAfterSeconds: 300, rerouteCooldownSeconds: 60 },
+};
+
+test('terminal action accepts ints and names, rejects junk', () => {
+  assert.equal(terminalForSave(6), 'EndChat');
+  assert.equal(terminalForSave('7'), 'NotifyManager');
+  assert.equal(terminalForSave('runworkflow'), 'RunWorkflow');
+  assert.equal(terminalForSave(undefined), null);
+  assert.throws(() => terminalForSave(9), /Unknown terminal action/);
+  assert.throws(() => terminalForSave('Bogus'), /Unknown terminal action/);
+  assert.equal(terminalLabel(null), 'Default (Survey)');
+  assert.equal(terminalLabel(8), 'RunWorkflow');
+});
+
+test('an update with no chain flags keeps the saved mode and chain (mode is always sent)', () => {
+  const body = buildPolicyUpdate(current, { 'max-reroutes': 4 });
+  assert.equal(body.maxRerouteAttempts, 4);
+  assert.equal(body.reassignmentMode, 'Reassign');
+  assert.deepEqual(body.inactivityChain, current.inactivityChain);
+  assert.equal(body.terminalActionOverride, 'Survey');
+});
+
+test('a server without reassignmentMode still sends Observe explicitly and no chain block', () => {
+  const body = buildPolicyUpdate({ enabled: true }, { 'max-reroutes': 2 });
+  assert.equal(body.reassignmentMode, 'Observe');
+  assert.equal('inactivityChain' in body, false);
+});
+
+test('chain flags patch the chain block', () => {
+  const body = buildPolicyUpdate(current, { 'cooldown': 90, 'chain': false, 'visitor-text': 'Hi' });
+  assert.equal(body.inactivityChain.rerouteCooldownSeconds, 90);
+  assert.equal(body.inactivityChain.enabled, false);
+  assert.equal(body.inactivityChain.visitorStatusText, 'Hi');
+  assert.equal(body.inactivityChain.backupTeamId, 5);
+});
+
+test('chain flags create the block on a server that had none', () => {
+  const body = buildPolicyUpdate({ enabled: true }, { chain: true, 'backup-team': 5, 'reassignment-mode': 'Reassign' });
+  assert.equal(body.inactivityChain.enabled, true);
+  assert.equal(body.reassignmentMode, 'Reassign');
+});
+
+test('rejects an unknown reassignment mode', () => {
+  assert.throws(() => buildPolicyUpdate(current, { 'reassignment-mode': 'Yolo' }), /Unknown reassignment mode/);
+});
+
+test('validation mirrors the server cross-field rules', () => {
+  assert.deepEqual(validatePolicyUpdate(buildPolicyUpdate(current, {})), []);
+  assert.match(validatePolicyUpdate(buildPolicyUpdate(current, { 'reassignment-mode': 'QueueOnly' }))[0], /Reassign/);
+  assert.match(validatePolicyUpdate(buildPolicyUpdate(current, { 'backup-after': 600 }))[0], /at least as long/);
+  assert.match(validatePolicyUpdate(buildPolicyUpdate(current, { 'terminal-action': 'RunWorkflow' }))[0], /--terminal-workflow/);
+  assert.deepEqual(validatePolicyUpdate(buildPolicyUpdate(current, { chain: false, 'reassignment-mode': 'Observe' })), []);
+  // RunWorkflow without a workflow is rejected even with the chain off (the final action still runs at the hop cap).
+  assert.match(
+    validatePolicyUpdate(buildPolicyUpdate(current, { chain: false, 'reassignment-mode': 'Observe', 'terminal-action': 'RunWorkflow' }))[0],
+    /--terminal-workflow/
+  );
+  assert.deepEqual(
+    validatePolicyUpdate(buildPolicyUpdate(current, { 'terminal-action': 'RunWorkflow', 'terminal-workflow': 9 })),
+    []
+  );
+});
+
+test('terminal actions 6-8 are rejected when the current policy has no inactivityChain block', () => {
+  const legacy = { enabled: true, maxRerouteAttempts: 3, terminalActionOverride: 'Survey', reassignmentMode: 'Observe' };
+  assert.throws(() => buildPolicyUpdate(legacy, { 'terminal-action': 'EndChat' }), /inactivity chain/);
+  assert.throws(() => buildPolicyUpdate(legacy, { 'terminal-action': 8 }), /inactivity chain/);
+  assert.equal(buildPolicyUpdate(legacy, { 'terminal-action': 3 }).terminalActionOverride, 'Queue');
+});
+
+test('describeTransfers keeps results when a site override was ignored', () => {
+  const lines = describeTransfers({
+    siteId: 1, days: 30, total: 2, siteOverrideIgnored: true,
+    note: 'siteIdOverride=5 was ignored because only Velaro admins may query another site. These results are for site 1.',
+    byAgent: [{ agentId: 7, name: 'Sam', count: 2 }], byDay: [{ date: '2026-09-24', count: 2 }],
+  }).join('\n');
+  assert.match(lines, /was ignored/);
+  assert.match(lines, /Sam \(id 7\): 2/);
+  assert.match(lines, /By day \(Pacific\): 2026-09-24=2/);
+});
+
+test('describe helpers render the chain, a simulation and a transfer count', () => {
+  assert.match(describeChain(current).join('\n'), /Inactivity chain:\s+ON/);
+  assert.match(describeChain({}).join('\n'), /does not report/);
+  const sim = describeSimulation({ ruleSource: 'SiteDefault', gate: 'SkipCooldown', noTargetAction: 'Hold', explanation: 'x', nextStepAtSeconds: 60, visitorMessage: 'v', agentStatus: 'a', queueAlert: '', otherRulesThatMatchedButLost: [{ rule: 'R', reason: 'why' }] });
+  assert.match(sim.join('\n'), /DRY RUN/);
+  assert.match(sim.join('\n'), /cooldown/);
+  assert.match(sim.join('\n'), /Also matched but lost: R \(why\)/);
+  assert.match(describeTransfers({ siteId: 1, days: 30, total: 0, byAgent: [], byDay: [] }).join('\n'), /None\./);
+  assert.match(describeTransfers({ siteId: 1, days: 30, total: 2, byAgent: [{ agentId: 7, name: 'Sam', count: 2 }], byDay: [] }).join('\n'), /Sam \(id 7\): 2/);
+  assert.deepEqual(describeTransfers({ note: 'No agent found' }), ['No agent found']);
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@velaro/cli",
-  "version": "1.4.57",
+  "version": "1.4.59",
   "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"
+  }
 }