@velaro/cli 1.4.102 → 1.4.104

package/lib/commands/avatar.js

@@ -1,6 +1,7 @@
 import { request, messagingGet, messagingPut, messagingDel } from '../api.js';
 import { overrideBody, scopePath } from '../avatar-override.js';
 import { applyMotionArgs } from '../avatar-motion.js';
+import { SWITCH_VALUES, workflowSwitchBody, bulkSwitchBody } from '../avatar-switch.js';
 import { runCommand } from '../run.js';
 
 // ── velaro avatar ─────────────────────────────────────────────────────────────
@@ -28,7 +29,9 @@ export const avatarCommand = {
         console.log(`\nSite ${argv.site}: AI Video Avatar ${data.enabled ? 'ENABLED ✓' : 'configured but DISABLED'}`);
         console.log(`  Provider:      ${data.providerSlug}`);
         console.log(`  Avatar ID:     ${data.avatarId || '(provider default)'}`);
+        console.log(`  Face/provider: ${data.avatarIdByProvider && Object.keys(data.avatarIdByProvider).length ? JSON.stringify(data.avatarIdByProvider) : '(none saved)'} (read-only)`);
         console.log(`  Voice ID:      ${data.voiceId || '(site default)'}`);
+        console.log(`  Keep on agent join: ${data.enabledOnAgentTransfer ? 'yes' : 'no'}`);
         console.log(`  Enabled:       ${data.enabled ? 'yes' : 'no'}`);
         console.log(`  "Call me":     ${data.showCallMeOption ? 'yes' : 'no'}`);
         console.log(`  Callback window: ${data.callbackConfirmWindowMinutes} min`);
@@ -37,7 +40,32 @@ export const avatarCommand = {
         console.log(`  Size:          ${data.sizePx}px`);
         console.log(`  Body motion:   ${data.motionLevel || '(default: natural)'} @ ${data.motionIntensityPercent ?? 100}%`);
         console.log(`  Max minutes/mo:   ${data.maxAvatarMinutesPerMonth ?? '(plan default)'}`);
-        console.log(`  Max TTS chars/mo: ${data.maxAvatarTtsChars ?? '(plan default)'}\n`);
+        console.log(`  Max TTS chars/mo: ${data.maxAvatarTtsChars ?? '(plan default)'}`);
+        try {
+          const ent = await request('GET', `/Entitlements/${argv.site}`);
+          console.log(`  HeyGen entitled:  ${ent?.features?.EnableAvatarHeyGen ? 'yes' : 'no'}\n`);
+        } catch (e) { console.log(`  HeyGen entitled:  unknown (${e.message})\n`); }
+      }),
+    })
+    .command({
+      command:  'heygen',
+      describe: 'Grant or revoke the HeyGen provider entitlement (EnableAvatarHeyGen) for a site',
+      builder:  y => y
+        .option('site',    { type: 'number', demandOption: true, describe: 'Site ID' })
+        .option('enabled', { type: 'boolean', demandOption: true, describe: 'true = grant, false = revoke' }),
+      handler:  runCommand(async argv => {
+        await request('POST', `/Entitlements/${argv.site}/override`, { featureKey: 'EnableAvatarHeyGen', value: argv.enabled, reason: 'velaro avatar heygen' });
+        const ent = await request('GET', `/Entitlements/${argv.site}`);
+        console.log(`\n✓ Site ${argv.site}: EnableAvatarHeyGen=${ent?.features?.EnableAvatarHeyGen ? 'true' : 'false'}\n`);
+      }),
+    })
+    .command({
+      command:  'session-readiness',
+      describe: 'Staff diagnostic: why an avatar session will or will not start for a site (plan, config, key, billing, concurrency). Read-only, no provider call.',
+      builder:  y => y.option('site', { type: 'number', demandOption: true, describe: 'Site ID' }),
+      handler:  runCommand(async argv => {
+        const data = await messagingGet(`/avatar/diagnostics/session-readiness?siteId=${argv.site}`);
+        console.log(JSON.stringify(data, null, 2));
       }),
     })
     .command({
@@ -49,6 +77,7 @@ export const avatarCommand = {
         .option('bot',      { type: 'string', describe: 'Reserved for a future per-bot override (not yet implemented on this endpoint)' })
         .option('avatar-id',{ type: 'string', describe: 'Provider-specific avatar/face ID. Omit for provider default.' })
         .option('voice',    { type: 'string', describe: 'ElevenLabs voice ID override' })
+        .option('keep-on-agent-join', { type: 'boolean', describe: 'Keep the avatar running after a human agent joins. Omit on a re-run to leave it untouched.' })
         .option('call-me',  { type: 'boolean', describe: 'Show the "Call me instead" option. Omit on a re-run to leave it untouched.' })
         .option('display-name', { type: 'string', describe: 'Visitor-facing avatar name on the badge (e.g. Moshky). Empty string resets to "AI".' })
         .option('show-badge',   { type: 'boolean', describe: 'Show the name badge over the avatar video.' })
@@ -66,6 +95,7 @@ export const avatarCommand = {
         body.providerSlug = argv.provider ?? 'velaro';
         if (argv['avatar-id'] !== undefined) body.avatarId = argv['avatar-id'];
         if (argv.voice !== undefined) body.voiceId = argv.voice;
+        if (argv['keep-on-agent-join'] !== undefined) body.enabledOnAgentTransfer = argv['keep-on-agent-join'];
         if (argv['call-me'] !== undefined) body.showCallMeOption = argv['call-me'];
         if (argv['display-name'] !== undefined) body.displayName = argv['display-name'];
         if (argv['show-badge'] !== undefined) body.showBadge = argv['show-badge'];
@@ -163,5 +193,33 @@ export const avatarCommand = {
 `);
       }),
     })
-    .demandCommand(1, 'Specify a subcommand: get | enable | disable | set | override | effective | reset'),
+    .command({
+      command:  'workflow-switch <workflowId> <value>',
+      describe: 'Switch the avatar on, off, or back to the site rules (rules) for ONE workflow of your site',
+      builder:  y => y
+        .positional('workflowId', { type: 'number', describe: 'Workflow id' })
+        .positional('value',      { type: 'string', choices: SWITCH_VALUES, describe: 'on | off | rules (rules = the site rules decide)' }),
+      handler:  runCommand(async argv => {
+        const id = Number(argv.workflowId);
+        if (!Number.isInteger(id) || id <= 0) throw new Error('The workflow id must be a positive whole number');
+        const data = await messagingPut(`/avatar/workflows/${id}/enabled`, workflowSwitchBody(argv.value));
+        if (!data?.success) throw new Error(data?.error || 'Switch failed');
+        console.log(`\n✓ Workflow ${id} avatar switch: ${data.mode} (${data.changed ? 'changed' : 'already set'})\n`);
+      }),
+    })
+    .command({
+      command:  'bulk-switch',
+      describe: 'Set the avatar switch for many workflows and/or teams of your site in one call (max 500)',
+      builder:  y => y
+        .option('ids',    { type: 'string', describe: 'Comma-separated workflow ids, e.g. 12,13,14' })
+        .option('groups', { type: 'string', describe: 'Comma-separated team (group) ids' })
+        .option('value',  { type: 'string', choices: SWITCH_VALUES, demandOption: true, describe: 'on | off | rules' }),
+      handler:  runCommand(async argv => {
+        const body = bulkSwitchBody({ ids: argv.ids, groups: argv.groups, value: argv.value });
+        const data = await messagingPut('/avatar/overrides/enabled', body);
+        if (!data?.success) throw new Error(data?.error || 'Bulk switch failed');
+        console.log(`\n✓ Bulk avatar switch ${data.mode}: ${data.changed} of ${data.requested} rows changed\n`);
+      }),
+    })
+    .demandCommand(1, 'Specify a subcommand: get | enable | disable | set | override | effective | reset | workflow-switch | bulk-switch'),
 };

package/lib/commands/billing-automation.js

@@ -0,0 +1,184 @@
+// velaro billing-automation — review-hold and dry-run switches for invoice emails and charges
+// (BillingAutomationController, /api/BillingAutomation). Staff only.
+import { request } from '../api.js';
+
+const MODES = ['auto', 'review', 'dry_run'];
+const GATES = ['send', 'charge', 'both'];
+
+function money(cents) {
+  if (cents == null) return '';
+  return `$${(cents / 100).toLocaleString('en-US', { minimumFractionDigits: 2, maximumFractionDigits: 2 })}`;
+}
+
+function fail(message) {
+  console.error(message);
+  process.exit(1);
+}
+
+async function listRules() {
+  const rules = await request('GET', '/api/BillingAutomation/rules');
+  if (!rules.length) {
+    console.log('No rules. With no rules, every invoice runs automatically.');
+    return;
+  }
+  for (const r of rules) {
+    const scope = [
+      r.accountType ? `account=${r.accountType}` : null,
+      r.paymentMethod ? `method=${r.paymentMethod}` : null,
+      r.minAmountCents != null ? `from=${money(r.minAmountCents)}` : null,
+      r.maxAmountCents != null ? `to=${money(r.maxAmountCents)}` : null,
+    ].filter(Boolean).join(' ') || 'global default';
+    console.log(`#${r.id}  ${r.enabled ? 'on ' : 'off'}  ${r.appliesTo.padEnd(6)}  ${r.mode.padEnd(8)}  ${scope}  ${r.name}`);
+  }
+}
+
+async function setGlobal(appliesTo, mode) {
+  if (!GATES.includes(appliesTo)) fail(`appliesTo must be one of: ${GATES.join(', ')}`);
+  if (!MODES.includes(mode)) fail(`mode must be one of: ${MODES.join(', ')}`);
+  await request('PUT', `/api/BillingAutomation/global/${appliesTo}`, { mode });
+  console.log(`Global ${appliesTo} set to ${mode}.`);
+}
+
+async function addRule(args) {
+  if (!args.name) fail('Usage: velaro billing-automation rule-add --name "Review big ACH" --applies-to charge --mode review [--account-type enterprise] [--min-cents 100000] [--max-cents 500000] [--payment-method ach]');
+  const body = {
+    name: args.name,
+    appliesTo: args.appliesTo ?? 'both',
+    mode: args.mode,
+    accountType: args.accountType ?? null,
+    minAmountCents: args.minCents ?? null,
+    maxAmountCents: args.maxCents ?? null,
+    paymentMethod: args.paymentMethod ?? null,
+    enabled: true,
+  };
+  const r = await request('POST', '/api/BillingAutomation/rules', body);
+  console.log(`Rule #${r.id} added: ${r.name} (${r.appliesTo} -> ${r.mode}).`);
+}
+
+async function setRuleEnabled(id, enabled) {
+  const rules = await request('GET', '/api/BillingAutomation/rules');
+  const rule = rules.find((r) => r.id === Number(id));
+  if (!rule) fail(`No rule #${id}.`);
+  await request('PUT', `/api/BillingAutomation/rules/${rule.id}`, {
+    name: rule.name,
+    appliesTo: rule.appliesTo,
+    mode: rule.mode,
+    accountType: rule.accountType,
+    minAmountCents: rule.minAmountCents,
+    maxAmountCents: rule.maxAmountCents,
+    paymentMethod: rule.paymentMethod,
+    enabled,
+  });
+  console.log(`Rule #${rule.id} ${enabled ? 'turned on' : 'turned off'}.`);
+}
+
+async function deleteRule(id) {
+  await request('DELETE', `/api/BillingAutomation/rules/${id}`);
+  console.log(`Rule #${id} deleted.`);
+}
+
+function printDecisions(rows, emptyText) {
+  if (!rows.length) {
+    console.log(emptyText);
+    return;
+  }
+  for (const d of rows) {
+    const label = d.outcome === 'dry_run' ? 'WOULD' : 'HELD ';
+    const state = d.resolution ? ` [${d.resolution}]` : '';
+    console.log(`#${d.id}  ${label} ${d.action.padEnd(6)} invoice ${d.invoiceId}  ${money(d.amountCents)}  ${d.paymentMethod ?? '-'}  ${d.createdAt}${state}`);
+    console.log(`      ${d.reason}`);
+  }
+}
+
+async function queue() {
+  printDecisions(await request('GET', '/api/BillingAutomation/decisions?status=open&take=200'), 'Nothing is waiting for review.');
+}
+
+async function dryRuns() {
+  printDecisions(await request('GET', '/api/BillingAutomation/decisions?status=dry_run&take=100'), 'No dry-run entries.');
+}
+
+async function approve(id) {
+  const res = await request('POST', `/api/BillingAutomation/decisions/${id}/approve`, {});
+  console.log(`Approved #${id}. Released: ${res.released}.`);
+}
+
+async function dismiss(id) {
+  await request('POST', `/api/BillingAutomation/decisions/${id}/dismiss`, {});
+  console.log(`Dismissed #${id}. It stays on hold until approved.`);
+}
+
+async function setAccountType(subscriptionId, value) {
+  const res = await request('PUT', `/api/BillingAutomation/subscription/${subscriptionId}/account-type`, { accountType: value ?? null });
+  console.log(`Subscription ${res.id} account type: ${res.accountType ?? '(unset)'}.`);
+}
+
+async function notifySettings() {
+  const all = await request('GET', '/api/BillingNotifications/settings');
+  for (const [key, value] of Object.entries(all)) {
+    console.log(`${key.padEnd(20)} ${value ?? '(not set: code default)'}`);
+  }
+}
+
+async function notifySet(key, value) {
+  await request('PUT', `/api/BillingNotifications/settings/${key}`, { value });
+  console.log(`${key} set to ${value}.`);
+}
+
+// Only the channels you pass change. The others keep their current override (the API replaces all three).
+async function setReceipts(subscriptionId, args) {
+  const sub = await request('GET', `/api/BillingSubscription/${subscriptionId}`);
+  const res = await request('PUT', `/api/BillingNotifications/subscriptions/${subscriptionId}/receipts`, {
+    card: args.card ?? sub.receiptCardOverride ?? null,
+    ach: args.ach ?? sub.receiptAchOverride ?? null,
+    other: args.other ?? sub.receiptOtherOverride ?? null,
+  });
+  console.log(`Subscription ${res.id} receipts: card=${res.card ?? 'inherit'} ach=${res.ach ?? 'inherit'} other=${res.other ?? 'inherit'}.`);
+}
+
+async function digestSendNow() {
+  const res = await request('POST', '/api/BillingNotifications/digest/send-now', {});
+  console.log(`Digest sent to ${res.recipients.join(', ')}: ${res.subject}`);
+}
+
+async function receiptsRunNow() {
+  const res = await request('POST', '/api/BillingNotifications/receipts/run-now', {});
+  console.log(`Receipts run: ${res.summary}`);
+}
+
+export const billingAutomationCommand = {
+  command: 'billing-automation <subcommand>',
+  describe: 'Review-hold and dry-run switches for invoice emails and charges, the review queue, and account types',
+  builder: (yargs) =>
+    yargs
+      .command('rules', 'List every automation rule and global switch', {}, () => listRules())
+      .command('global <appliesTo> <mode>', 'Set the global default: appliesTo = send | charge | both; mode = auto | review | dry_run', {}, (args) => setGlobal(args.appliesTo, args.mode))
+      .command('rule-add', 'Add a scoped rule (--name required; filters are optional)', {
+        name:          { type: 'string' },
+        appliesTo:     { type: 'string', choices: GATES, default: 'both' },
+        mode:          { type: 'string', choices: MODES, demandOption: true },
+        accountType:   { type: 'string' },
+        minCents:      { type: 'number' },
+        maxCents:      { type: 'number' },
+        paymentMethod: { type: 'string', choices: ['cash', 'check', 'ach', 'wire', 'card'] },
+      }, (args) => addRule(args))
+      .command('rule-on <id>', 'Turn a rule on', {}, (args) => setRuleEnabled(args.id, true))
+      .command('rule-off <id>', 'Turn a rule off', {}, (args) => setRuleEnabled(args.id, false))
+      .command('rule-delete <id>', 'Delete a rule (queue entries keep their rule name)', {}, (args) => deleteRule(args.id))
+      .command('queue', 'Show held sends and charges waiting for review', {}, () => queue())
+      .command('dry-runs', 'Show what the dry-run switches would have sent or charged', {}, () => dryRuns())
+      .command('approve <id>', 'Approve a held entry and release its send or charge now', {}, (args) => approve(args.id))
+      .command('dismiss <id>', 'Dismiss a held entry (it stays on hold, alerts stop)', {}, (args) => dismiss(args.id))
+      .command('account-type <subscriptionId> [value]', 'Set a subscription account type that rules match on (omit value to clear)', {}, (args) => setAccountType(args.subscriptionId, args.value))
+      .command('notify-settings', 'Show the global notification settings (receipts, invoice BCC, digest recipients)', {}, () => notifySettings())
+      .command('digest-send-now', 'Send the billing digest now to digest.recipients (same email as the 7am run)', {}, () => digestSendNow())
+      .command('receipts-run-now', 'Decide pending payment receipts now instead of at :05 and print the counts', {}, () => receiptsRunNow())
+      .command('notify-set <key> <value>', 'Set a global notification setting: receipts.card|receipts.ach|receipts.other = never|send; invoices.bcc = emails (blank = none); digest.recipients = emails', {}, (args) => notifySet(args.key, args.value))
+      .command('receipts <subscriptionId>', 'Set receipt overrides on one subscription (--card/--ach/--other = never|send). Channels you omit keep their current override.', {
+        card:  { type: 'string', choices: ['never', 'send'] },
+        ach:   { type: 'string', choices: ['never', 'send'] },
+        other: { type: 'string', choices: ['never', 'send'] },
+      }, (args) => setReceipts(args.subscriptionId, args))
+      .demandCommand(1, 'Specify a subcommand: rules | global | rule-add | rule-on | rule-off | rule-delete | queue | dry-runs | approve | dismiss | account-type'),
+  handler: () => {},
+};

package/lib/commands/copilotstudio.js

@@ -110,5 +110,18 @@ export const copilotStudioCommand = {
         }
       }),
     })
-    .demandCommand(1, 'Specify a subcommand: list | add | update | remove | test'),
+    .command({
+      command:  'ask <id> <question>',
+      describe: 'Live diagnostic: ask the agent a real question and classify the reply (answered | vendor_limit | no_answer). Exit 1 unless answered.',
+      builder:  y => y.positional('id', { type: 'number' }).positional('question', { type: 'string' }),
+      handler:  runCommand(async argv => {
+        const r = await request('POST', '/CopilotStudio/message', { configId: argv.id, message: argv.question });
+        console.log(`
+kind: ${r?.kind}
+reply: ${r?.reply}
+`);
+        if (r?.kind !== 'answered') process.exitCode = 1;
+      }),
+    })
+    .demandCommand(1, 'Specify a subcommand: list | add | update | remove | test | ask'),
 };

package/lib/commands/enterprise-reports.js

@@ -19,6 +19,7 @@ const REPORTS = {
   'bot-containment': 'Claimed vs true bot containment and handoff regret',
   'effort-index': 'Inferred 0-100 customer effort by topic, program and team (not a survey CES)',
   'promise-ledger': 'Agent commitments made in chat and whether a follow-up appeared; overdue list',
+  'new-agent-ramp': 'Agents whose first chat is in --from/--to: week-by-week ramp (chats, first response, QA, rating) against tenured agents',
   'promise-dismiss': 'Dismiss one promise by --id (managers only)',
   'weekly-brief-send-test': 'Email this week\'s brief to the signed-in user',
   'year-in-review': 'Build the 12-month Year in review document: --from/--to (default last 12 whole Pacific months) starts a build and prints its id; --id <id> checks status and the download link',

package/lib/commands/entitlement.js

@@ -39,6 +39,31 @@ ${pkg.displayName} (${pkg.packageKey}) - plan ${pkg.plan}, default OFF${pkg.site
   console.log('');
 }
 
+// Formats the GET Entitlements/report-packages payload (five category packages nested under Enterprise Reports). Exported for the unit test.
+export function formatReportPackages(pkg) {
+  const lines = [];
+  const site = pkg.siteId ? `, site ${pkg.siteId}` : '';
+  lines.push(`${pkg.top.name} (${pkg.top.slug}) - plan ${pkg.plan}, default OFF${site}${pkg.siteId ? (pkg.top.enabled ? ' [ALL ON]' : '') : ''}`);
+  lines.push(`  ${pkg.top.tagline}`);
+  for (const c of pkg.categories) {
+    const state = pkg.siteId ? ` [${c.enabled ? 'ON ' : 'off'}] ${c.enabledCount}/${c.reportCount} reports` : ` ${c.reportCount} reports`;
+    lines.push('');
+    lines.push(`${c.name} (${c.slug})${state}`);
+    lines.push(`  ${c.tagline}`);
+    for (const r of c.reports) {
+      const mark = pkg.siteId ? (r.enabled ? '[ON ] ' : '[off] ') : '';
+      lines.push(`  ${mark}${r.name} (${r.id}) - package ${r.packageSlug}, key ${r.packageKey}`);
+    }
+  }
+  return lines.join('\n');
+}
+
+async function reportPackages(args) {
+  const q = args.site ? `?siteId=${encodeURIComponent(args.site)}` : '';
+  const pkg = await request('GET', `Entitlements/report-packages${q}`);
+  console.log(`\n${formatReportPackages(pkg)}\n`);
+}
+
 async function listFeatures() {
   const features = await request('GET', 'Entitlements/features');
 
@@ -141,6 +166,45 @@ async function reconcile(args) {
   }
 }
 
+async function trial(args) {
+  const sub = args.action;
+  const need = (v, n) => { if (v === undefined || v === null || v === '') { console.error(`--${n} is required for trial ${sub}`); process.exit(1); } };
+  if (sub === 'get' || sub === 'recommend') {
+    need(args.site, 'site');
+    const r = await request('GET', `Entitlements/${args.site}/trial${sub === 'recommend' ? '/recommendation' : ''}`);
+    console.log(JSON.stringify(r, null, 2));
+  } else if (sub === 'not-paying') {
+    console.log(JSON.stringify(await request('GET', 'Entitlements/admin/trial/not-paying'), null, 2));
+  } else if (sub === 'grant') {
+    need(args.site, 'site'); need(args.feature, 'feature'); need(args.reason, 'reason');
+    const r = await request('POST', `Entitlements/${args.site}/trial/grant`, { featureKey: args.feature, reason: args.reason });
+    console.log(`Site ${args.site}: ${r.featureKey} granted for the trial (${r.state}).`);
+  } else if (sub === 'hold' || sub === 'reactivate') {
+    need(args.site, 'site');
+    const body = { featureKey: args.feature, dryRun: !!args['dry-run'] };
+    console.log(JSON.stringify(await request('POST', `Entitlements/${args.site}/trial/${sub}`, body)));
+  } else if (sub === 'set-limit') {
+    need(args.site, 'site'); need(args.key, 'key'); need(args.value, 'value'); need(args.reason, 'reason');
+    const r = await request('POST', `Entitlements/${args.site}/trial/limit`, { key: args.key, value: Number(args.value), reason: args.reason });
+    console.log(`Site ${args.site}: ${r.key} ${r.old} -> ${r.value}.`);
+  } else if (sub === 'set-text') {
+    need(args.feature, 'feature');
+    console.log(JSON.stringify(await request('POST', 'Entitlements/admin/trial/feature-text', { featureKey: args.feature, text: args.text })));
+  } else if (sub === 'approve-limit' || sub === 'deny-limit') {
+    need(args.request, 'request');
+    if (sub === 'approve-limit') {
+      need(args.key, 'key'); need(args.value, 'value');
+      console.log(JSON.stringify(await request('POST', `Entitlements/admin/trial/limit-request/${args.request}/approve`, { key: args.key, value: Number(args.value), message: args.message })));
+    } else {
+      need(args.reason, 'reason');
+      console.log(JSON.stringify(await request('POST', `Entitlements/admin/trial/limit-request/${args.request}/deny`, { reason: args.reason })));
+    }
+  } else {
+    console.error('Unknown trial action. Use: get | recommend | not-paying | grant | hold | reactivate | set-limit | approve-limit | deny-limit | set-text');
+    process.exit(1);
+  }
+}
+
 async function setLock(args) {
   if (!args.site) {
     console.error('Usage: velaro entitlement set-lock --site 1032 --at 2026-01-01T00:00:00Z\n       velaro entitlement set-lock --site 1032 --unlock');
@@ -193,6 +257,9 @@ export function entitlementCommand(yargs) {
     .command('enterprise-reports', 'Show the Enterprise Reports package items (with --site, which are ON for that site)', y => y
       .option('site', { type: 'number', desc: 'Site ID' })
     , a => enterpriseReportsPackage(a))
+    .command('report-packages', 'Show the five report category packages and every report in them (with --site, which are ON for that site)', y => y
+      .option('site', { type: 'number', desc: 'Site ID' })
+    , a => reportPackages(a))
     .command('set-override', 'Enable or disable a feature for a specific site (overrides plan)', y => y
       .option('site',   { type: 'number',  demandOption: true, desc: 'Site ID' })
       .option('key',    { type: 'string',  demandOption: true, desc: 'Feature key, e.g. EnableIvr' })
@@ -222,10 +289,21 @@ export function entitlementCommand(yargs) {
       .option('at',     { type: 'string',  desc: 'ISO 8601 timestamp to lock entitlement resolution to' })
       .option('unlock', { type: 'boolean', desc: 'Clear an existing lock (resolves against current plan version again)' })
     , a => setLock(a))
+    .command('trial <action>', 'Trial governance (superadmin): get | recommend | not-paying | grant | hold | reactivate | set-limit | approve-limit | deny-limit | set-text', y => y
+      .option('site',    { type: 'number', desc: 'Site ID' })
+      .option('feature', { type: 'string', desc: 'Feature key, e.g. EnableIvr' })
+      .option('key',     { type: 'string', desc: 'Cap name, e.g. MaxKbArticles' })
+      .option('value',   { type: 'string', desc: 'Whole number cap' })
+      .option('reason',  { type: 'string', desc: 'Reason (audited)' })
+      .option('request', { type: 'number', desc: 'Limit-increase request id' })
+      .option('message', { type: 'string', desc: 'approve-limit: note added to the customer reply' })
+      .option('text', { type: 'string', desc: 'set-text: customer-safe, number-free limit text' })
+      .option('dry-run', { type: 'boolean', desc: 'hold: report only, write nothing' })
+    , a => trial(a))
     .command('list-cutover', 'List all feature keys and whether they are live (messaging reads admin) or not (Subscription.cs)', () => {}, () => listCutover())
     .command('set-cutover', 'Flip a feature key live (or roll it back). Live = messaging reads admin value within 45s. --rollback reverts to Subscription.cs.', y => y
       .option('key',      { type: 'string',  demandOption: true, desc: 'Feature key, e.g. EnableIvr' })
       .option('rollback', { type: 'boolean', desc: 'Pass to roll back this flag to Subscription.cs (default: go live)' })
     , a => setCutover(a))
-    .demandCommand(1, 'Specify a subcommand: get | list-features | enterprise-reports | set-override | remove-override | seed | seed-plans | backfill | backfill-sap-tiers | backfill-legacy-write-tiers | reconcile | comp | set-lock | list-cutover | set-cutover');
+    .demandCommand(1, 'Specify a subcommand: get | list-features | enterprise-reports | report-packages | set-override | remove-override | seed | seed-plans | backfill | backfill-sap-tiers | backfill-legacy-write-tiers | reconcile | comp | set-lock | trial | list-cutover | set-cutover');
 }

package/lib/commands/env.js

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

package/lib/commands/focus.js

@@ -225,7 +225,7 @@ const setTriageRuleCommand = {
   builder:  (y) => y
     .positional('label',   { type: 'string', describe: `Label: ${VALID_LABELS.join(', ')}` })
     .positional('enabled', { type: 'string', describe: 'true or false', choices: ['true', 'false'] })
-    .option('triage-mode', { type: 'string', choices: ['off', 'economy'], describe: 'off (default) or economy (skip AI call for obvious messages)' }),
+    .option('triage-mode', { type: 'string', choices: ['off', 'economy'], describe: 'off (this site always uses the AI call) or economy (skip the AI call for obvious messages). Unset = platform default (economy)' }),
   handler:  async (argv) => {
     const { label, enabled } = argv;
     const mode = argv['triage-mode'];

package/lib/commands/index.js

@@ -1,4 +1,4 @@
-import { get, post, getCredentials, messagingGet, messagingPost } from '../api.js';
+import { get, post, getCredentials, messagingGet, messagingPost, messagingPut } from '../api.js';
 
 // ── helpers ──────────────────────────────────────────────────────────────────
 
@@ -266,6 +266,41 @@ Index ready on site ${argv.site}: ${idx.name} (id: ${idx.id}, purpose: ${idx.pur
   },
 };
 
+// -- profile (Velaro staff only) --------------------------------------------------
+// PUT KnowledgeSetup/Staff/{siteId}/index-profile on velaro-messaging. Apply-if-present: only the
+// flags you pass are changed. The index is addressed by name (the endpoint looks up siteId+name).
+
+const profileCommand = {
+  command:  'profile',
+  describe: 'Set the ingestion profile of one index on any site (Velaro staff only; only passed flags change)',
+  builder:  (y) =>
+    y
+      .option('site', { type: 'number', demandOption: true, describe: 'Target site ID' })
+      .option('index', { type: 'string', demandOption: true, describe: 'Index name, e.g. 100140-troubleshooting' })
+      .option('strategy', { type: 'string', choices: ['procedure', 'section'], describe: 'Chunk strategy' })
+      .option('chunk-size', { type: 'number', describe: 'Chunk size' })
+      .option('chunk-overlap', { type: 'number', describe: 'Chunk overlap' })
+      .option('purpose', { type: 'string', choices: ['general', 'troubleshooting', 'catalog'], describe: 'Index purpose' })
+      .option('search-size', { type: 'number', describe: 'Results per search' })
+      .option('exclude-from-all-sources', { type: 'boolean', describe: 'Keep this index out of the ["*"] all-sources search' })
+      .option('json', { type: 'boolean', describe: 'Print raw JSON' }),
+  handler: async (argv) => {
+    const body = { indexName: argv.index };
+    if (argv.strategy !== undefined) body.chunkStrategy = argv.strategy;
+    if (argv['chunk-size'] !== undefined) body.chunkSize = argv['chunk-size'];
+    if (argv['chunk-overlap'] !== undefined) body.chunkOverlap = argv['chunk-overlap'];
+    if (argv.purpose !== undefined) body.purpose = argv.purpose;
+    if (argv['search-size'] !== undefined) body.searchSize = argv['search-size'];
+    if (argv['exclude-from-all-sources'] !== undefined) body.excludeFromAllSources = argv['exclude-from-all-sources'];
+    const idx = await messagingPut(`/KnowledgeSetup/Staff/${encodeURIComponent(argv.site)}/index-profile`, body);
+    if (argv.json) { console.log(JSON.stringify(idx, null, 2)); return; }
+    console.log(`
+Profile updated on site ${argv.site}: ${idx.name} (purpose: ${idx.purpose}, strategy: ${idx.chunkStrategy}, size: ${idx.chunkSize}, overlap: ${idx.chunkOverlap}, searchSize: ${idx.searchSize}, excludeFromAllSources: ${!!idx.excludeFromAllSources})
+Re-ingest to apply the new chunking to existing content.
+`);
+  },
+};
+
 export const indexCommand = {
   command:  'index <subcommand>',
   describe: 'Manage search indexes — view quota, physical index health, and reingest content',
@@ -277,6 +312,7 @@ export const indexCommand = {
       .command(reingestCommand)
       .command(testCommand)
       .command(createCommand)
-      .demandCommand(1, 'Specify a subcommand: list, site, provision, reingest, test, create'),
+      .command(profileCommand)
+      .demandCommand(1, 'Specify a subcommand: list, site, provision, reingest, test, create, profile'),
   handler: () => {},
 };