@velaro/cli 1.4.107 → 1.4.108

package/bin/velaro.js

@@ -97,6 +97,7 @@ import { billingContactsCommand } from '../lib/commands/billing-contacts.js';
 import { billingSubscriptionCommand } from '../lib/commands/billing-subscription.js';
 import { billingAutomationCommand } from '../lib/commands/billing-automation.js';
 import { orderFormCommand } from '../lib/commands/order-form.js';
+import { priceIncreaseCommand } from '../lib/commands/price-increase.js';
 import { billingEmailPreferenceCommand } from '../lib/commands/billing-email-preference.js';
 import { billingCommand }         from '../lib/commands/billing.js';
 import { couponGrantCommand }     from '../lib/commands/coupon-grant.js';
@@ -104,6 +105,8 @@ import { signCommand } from '../lib/commands/sign.js';
 import { widgetContainerCommand }  from '../lib/commands/widget-container.js';
 import { inlineWidgetConfigCommand } from '../lib/commands/inline-widget-config.js';
 import { pricingCommand }          from '../lib/commands/pricing.js';
+import { billingAgentsCommand }    from '../lib/commands/billing-agents.js';
+import { packageBuilderCommand }   from '../lib/commands/package-builder.js';
 import { entitlementCommand }       from '../lib/commands/entitlement.js';
 import { subscriptionCommand }      from '../lib/commands/subscription.js';
 import { supportCommand }           from '../lib/commands/support.js';
@@ -256,6 +259,7 @@ await yargs(hideBin(process.argv))
   .command(billingSubscriptionCommand)
   .command(billingAutomationCommand)
   .command(orderFormCommand)
+  .command(priceIncreaseCommand)
   .command(billingEmailPreferenceCommand)
   .command(billingCommand)
   .command(couponGrantCommand)
@@ -264,6 +268,8 @@ await yargs(hideBin(process.argv))
   .command(inlineWidgetConfigCommand)
   .command(pricingGroupCommand)
   .command(entitlementGroup)
+  .command({ command: 'billing-agents', desc: 'Run and review the billing agents (staff)', builder: billingAgentsCommand, handler: () => {} })
+  .command({ command: 'package-builder', desc: 'Package graph, drafts, simulation, audit (staff)', builder: packageBuilderCommand, handler: () => {} })
   .command({ command: 'subscription', desc: 'Apply/diff SubscriptionPackage packages on a site (superadmin only)', builder: subscriptionCommand, handler: () => {} })
   .command(supportGroupCommand)
   .command(routingCommand)

package/lib/commands/agent.js

@@ -1,7 +1,7 @@
 import { get, post, messagingGet, messagingPost, messagingPut, getCredentials }  from '../api.js';
 import { runCommand }  from '../run.js';
 
-const VALID_STATUSES = ['Available', 'Away', 'Offline'];
+const VALID_STATUSES = ['Available', 'Busy', 'Away', 'Offline'];
 
 const MISSED_REASON_LABELS = {
   NoAgentsOnline:         'No agents online',
@@ -120,6 +120,16 @@ export const agentCommand = {
         console.log(`Agent ${argv.id} set to ${argv.status}.`);
       }),
     })
+    .command({
+      command:  'force-sign-out',
+      describe: 'Force an agent to sign in again: revokes all their sessions now and sets them Offline (administrator only, same site, audited)',
+      builder:  (y) => y
+        .option('id', { type: 'number', demandOption: true, describe: 'Agent user ID' }),
+      handler: runCommand(async (argv) => {
+        await messagingPost(`/Users/${argv.id}/ForceSignOut`, {});
+        console.log(`Agent ${argv.id} was signed out of every session and set to Offline.`);
+      }),
+    })
     .command({
       command:  'missed-chats',
       describe: 'Show recent missed chats with routing snapshots (why each chat was missed)',

package/lib/commands/avatar.js

@@ -35,6 +35,7 @@ export const avatarCommand = {
         console.log(`  Enabled:       ${data.enabled ? 'yes' : 'no'}`);
         console.log(`  "Call me":     ${data.showCallMeOption ? 'yes' : 'no'}`);
         console.log(`  Callback window: ${data.callbackConfirmWindowMinutes} min`);
+        console.log(`  Show transcript: ${data.showTranscript ? 'yes' : 'no'}`);
         console.log(`  Display name:  ${data.displayName || '(AI)'}`);
         console.log(`  Badge shown:   ${data.showBadge ? 'yes' : 'no'}`);
         console.log(`  Size:          ${data.sizePx}px`);
@@ -78,6 +79,7 @@ export const avatarCommand = {
         .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('show-transcript', { type: 'boolean', describe: 'Show an on-screen avatar transcript (default off). 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.' })
@@ -97,6 +99,7 @@ export const avatarCommand = {
         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['show-transcript'] !== undefined) body.showTranscript = argv['show-transcript'];
         if (argv['display-name'] !== undefined) body.displayName = argv['display-name'];
         if (argv['show-badge'] !== undefined) body.showBadge = argv['show-badge'];
         if (argv.size !== undefined) body.sizePx = argv.size;

package/lib/commands/billing-agents.js

@@ -0,0 +1,51 @@
+// velaro billing-agents: run and review the billing agents (staff only). Contract: docs/architecture/billing-agents-and-package-builder.md
+import { request } from '../api.js';
+
+const show = (o) => console.log(JSON.stringify(o, null, 2));
+
+async function list() {
+  const agents = await request('GET', '/BillingAgents');
+  for (const a of agents) console.log(`${a.key.padEnd(12)} ${a.name.padEnd(18)} open findings: ${a.openFindings}  last run: ${a.lastRun ? `${a.lastRun.mode}/${a.lastRun.status} ${a.lastRun.startedAt}` : 'never'}`);
+}
+
+async function run(args) {
+  const mode = args.live ? 'live' : 'test';
+  const body = { mode };
+  if (args.site) body.siteId = args.site;
+  if (args.days) body.params = { days: args.days };
+  const r = await request('POST', `/BillingAgents/${args.agent}/run`, body);
+  console.log(`Run ${r.run.id} [${r.run.mode}] ${r.run.status}: ${r.findings.length} findings${mode === 'test' ? ' (dry run, no side effects)' : ''}`);
+  for (const f of r.findings) console.log(`  #${f.id} ${f.severity.padEnd(5)} ${f.ruleKey.padEnd(26)} ${f.title}`);
+}
+
+async function runs(args) {
+  const q = new URLSearchParams();
+  if (args.agent) q.set('agentKey', args.agent);
+  if (args.mode) q.set('mode', args.mode);
+  show(await request('GET', `/BillingAgents/runs?${q}`));
+}
+
+async function findings(args) {
+  const q = new URLSearchParams();
+  for (const k of ['status', 'severity']) if (args[k]) q.set(k, args[k]);
+  if (args.agent) q.set('agentKey', args.agent);
+  show(await request('GET', `/BillingAgents/findings?${q}`));
+}
+
+const step = (verb) => async (args) => show(await request('POST', `/BillingAgents/findings/${args.id}/${verb}`, {}));
+
+export function billingAgentsCommand(yargs) {
+  return yargs
+    .command('list', 'List agents with last run and open findings', () => {}, () => list())
+    .command('run <agent>', 'Run an agent (default TEST mode = dry run)', y => y
+      .positional('agent', { type: 'string', desc: 'close|collections|analyst|pricing|orders|utilization|syncfailure' })
+      .option('live', { type: 'boolean', desc: 'Live mode (findings + approval queue; still no side effects until apply)' })
+      .option('site', { type: 'number' }).option('days', { type: 'number' }), a => run(a))
+    .command('runs', 'List runs', y => y.option('agent', { type: 'string' }).option('mode', { type: 'string' }), a => runs(a))
+    .command('findings', 'List findings', y => y.option('status', { type: 'string' }).option('severity', { type: 'string' }).option('agent', { type: 'string' }), a => findings(a))
+    .command('approve <id>', 'Approve a finding (two-person rule for financial actions)', y => y.positional('id', { type: 'number' }), step('approve'))
+    .command('reject <id>', 'Reject a finding', y => y.positional('id', { type: 'number' }), step('reject'))
+    .command('apply <id>', 'Apply an approved finding (draft-safe actions only)', y => y.positional('id', { type: 'number' }), step('apply'))
+    .command('monitor', 'Agent health: last runs, 7d failure rate, stale agents', () => {}, async () => show(await request('GET', '/BillingAgents/monitor')))
+    .demandCommand(1, 'Specify a subcommand: list | run | runs | findings | approve | reject | apply | monitor');
+}

package/lib/commands/magento.js

@@ -8,6 +8,7 @@
  *   velaro magento products         Search the product catalog
  *   velaro magento logs             View integration activity logs
  *   velaro magento diagnose         Live connection diagnostic (token, /rest/V1, scopes)
+ *   velaro magento sidebar-fields get|set   Agent sidebar fields (site from your login)
  */
 
 import { request, messagingRequest } from '../api.js';
@@ -189,6 +190,48 @@ async function diagnoseHandler(argv) {
   }
 }
 
+// ── sidebar-fields ────────────────────────────────────────────────────────────
+
+async function sidebarFieldsHandler(argv) {
+  const action = argv.action;
+  try {
+    if (action === 'get') {
+      const r = await messagingRequest('GET', '/Magento/data/sidebar-fields');
+      console.log(JSON.stringify(r, null, 2));
+      return;
+    }
+    if (action !== 'set') {
+      console.error(`${RED}✗ action must be get or set${RST}`);
+      process.exitCode = 1;
+      return;
+    }
+    let fields;
+    if (argv.clear) {
+      fields = [];
+    } else if (argv.fields !== undefined) {
+      try { fields = JSON.parse(argv.fields); } catch (e) {
+        console.error(`${RED}✗ --fields must be valid JSON: ${e.message}${RST}`);
+        process.exitCode = 1;
+        return;
+      }
+      if (!Array.isArray(fields)) {
+        console.error(`${RED}✗ --fields must be a JSON array of {fieldName, entity, label}${RST}`);
+        process.exitCode = 1;
+        return;
+      }
+    }
+    // Partial body: omitting --fields leaves the saved list untouched.
+    const body = fields === undefined ? {} : { fields };
+    const r = await messagingRequest('PUT', '/Magento/data/sidebar-fields', body);
+    console.log(JSON.stringify(r, null, 2));
+  } catch (e) {
+    console.error(`
+${RED}✗ sidebar-fields ${action} failed: ${e.message}${RST}
+`);
+    process.exitCode = 1;
+  }
+}
+
 // ── command export ────────────────────────────────────────────────────────────
 
 export const magentoCommand = {
@@ -250,6 +293,15 @@ export const magentoCommand = {
         .option('site-id', { describe: 'Site ID to diagnose', type: 'number' }),
       handler: diagnoseHandler,
     })
+    .command({
+      command:  'sidebar-fields <action>',
+      describe: 'Get or set the Magento agent sidebar fields (action: get|set)',
+      builder: yy => yy
+        .positional('action', { choices: ['get', 'set'], type: 'string' })
+        .option('fields', { describe: 'JSON array of {fieldName, entity, label} (set only)', type: 'string' })
+        .option('clear',  { describe: 'Clear the saved list (set only)', type: 'boolean', default: false }),
+      handler: sidebarFieldsHandler,
+    })
     .demandCommand(1, 'Specify a subcommand. Try: velaro magento --help'),
   handler: () => {},
 };

package/lib/commands/order-form.js

@@ -21,6 +21,7 @@ function parseLine(spec) {
 
 function printForm(f) {
   console.log(`Order form ${f.id}: ${f.customerName} [${f.status}]`);
+  if (f.annualIncreasePercent != null) console.log(`  annual increase ${f.annualIncreasePercent}% on ${f.increaseBasis ?? 'site default'} price`);
   console.log(`  payment=${f.paymentMode} invoiceDetail=${f.invoiceDetailMode} applyOnSign=${f.applyOnSign} contractId=${f.contractId ?? '-'}`);
   for (const l of f.lines ?? []) {
     console.log(`  - ${l.catalogSlug} x${l.quantity} @ ${money(l.unitPriceCents)} (list ${money(l.listPriceCents)}) setup ${money(l.setupFeeCents)} ${l.termMonths}mo ${l.cadence}`);
@@ -30,7 +31,7 @@ function printForm(f) {
 async function createForm(args) {
   const lines = [].concat(args.line ?? []).map(parseLine);
   if (!args.customer || lines.length === 0) {
-    console.error('Usage: velaro order-form create --customer "Acme" --line slug:qty[:unitCents[:setupCents[:termMonths[:cadence]]]] [--line ...] [--site-id N] [--target v20] [--target-account-id X] [--payment-mode manual|card_checkout|invoice_net_terms] [--invoice-detail LineItemized|TermsReference] [--apply-on-sign]');
+    console.error('Usage: velaro order-form create --customer "Acme" --line slug:qty[:unitCents[:setupCents[:termMonths[:cadence]]]] [--line ...] [--site-id N] [--target v20] [--target-account-id X] [--payment-mode manual|card_checkout|invoice_net_terms] [--invoice-detail LineItemized|TermsReference] [--apply-on-sign] [--increase-percent 8] [--increase-basis list|net]');
     process.exit(1);
   }
   const body = {
@@ -41,6 +42,8 @@ async function createForm(args) {
     paymentMode: args.paymentMode,
     invoiceDetailMode: args.invoiceDetail,
     applyOnSign: !!args.applyOnSign,
+    annualIncreasePercent: args.increasePercent,
+    increaseBasis: args.increaseBasis,
     lines,
   };
   const f = await request('POST', '/api/OrderForm', body);
@@ -91,6 +94,8 @@ export const orderFormCommand = {
         'payment-mode': { type: 'string', choices: ['manual', 'card_checkout', 'invoice_net_terms'] },
         'invoice-detail': { type: 'string', choices: ['LineItemized', 'TermsReference'] },
         'apply-on-sign': { type: 'boolean', default: false },
+        'increase-percent': { type: 'number', describe: 'annual price increase percent stated in the contract' },
+        'increase-basis': { type: 'string', choices: ['list', 'net'], describe: 'calculate the increase on the undiscounted (list) or discounted (net) price; omit for the site default' },
       }, (args) => createForm(args))
       .command('get <id>', 'Show an order form', {}, (args) => getForm(args.id))
       .command('list', 'List order forms', { status: { type: 'string' } }, (args) => listForms(args))

package/lib/commands/package-builder.js

@@ -0,0 +1,35 @@
+// velaro package-builder: package graph, drafts, simulation, audit (staff only; `my` is customer-safe).
+import { request } from '../api.js';
+
+const show = (o) => console.log(JSON.stringify(o, null, 2));
+const get = (path) => async () => show(await request('GET', path));
+const enc = encodeURIComponent;
+
+export function packageBuilderCommand(yargs) {
+  return yargs
+    .command('graph', 'Features, packages, add-ons and standalone flags', () => {}, get('/PackageBuilder/graph'))
+    .command('site <siteId>', 'Per-flag provenance for a site', y => y.positional('siteId', { type: 'number' }), async a => show(await request('GET', `/PackageBuilder/site/${a.siteId}`)))
+    .command('versions <planKey>', 'Version history of a plan', y => y.positional('planKey', { type: 'string' }), async a => show(await request('GET', `/PackageBuilder/versions/${enc(a.planKey)}`)))
+    .command('diff', 'Diff two plan versions', y => y.option('plan', { type: 'string', demandOption: true }).option('from', { type: 'number', demandOption: true }).option('to', { type: 'number', demandOption: true }),
+      async a => show(await request('GET', `/PackageBuilder/diff?planKey=${enc(a.plan)}&from=${a.from}&to=${a.to}`)))
+    .command('drafts', 'List drafts', y => y.option('status', { type: 'string' }), async a => show(await request('GET', `/PackageBuilder/drafts${a.status ? `?status=${enc(a.status)}` : ''}`)))
+    .command('draft-create', 'Create a draft (from scratch or --clone-of plan.key)', y => y
+      .option('name', { type: 'string' }).option('clone-of', { type: 'string' }).option('features', { type: 'string', desc: 'comma-separated feature keys' }),
+      async a => show(await request('POST', '/PackageBuilder/drafts', { name: a.name, cloneOf: a['clone-of'], definition: a.features ? { features: a.features.split(',') } : undefined })))
+    .command('draft-update <id>', 'Replace a draft definition', y => y.positional('id', { type: 'number' }).option('features', { type: 'string', demandOption: true }).option('price-cents', { type: 'number' }).option('name', { type: 'string' }),
+      async a => show(await request('PUT', `/PackageBuilder/drafts/${a.id}`, { name: a.name, definition: { features: a.features.split(','), priceCents: a['price-cents'] } })))
+    .command('submit <id>', 'Submit draft for approval', y => y.positional('id', { type: 'number' }), async a => show(await request('POST', `/PackageBuilder/drafts/${a.id}/submit`, {})))
+    .command('approve <id>', 'Approve draft (approver must differ from creator)', y => y.positional('id', { type: 'number' }), async a => show(await request('POST', `/PackageBuilder/drafts/${a.id}/approve`, {})))
+    .command('publish <id>', 'Publish approved draft as new PlanEntitlement version rows', y => y.positional('id', { type: 'number' }), async a => show(await request('POST', `/PackageBuilder/drafts/${a.id}/publish`, {})))
+    .command('simulate', 'What-if across a cohort (pure read)', y => y.option('draft', { type: 'number' }).option('plan', { type: 'string' }).option('cohort', { type: 'string' }),
+      async a => show(await request('POST', '/PackageBuilder/simulate', { draftId: a.draft, basePlanKey: a.plan, cohort: a.cohort })))
+    .command('audit', 'Entitlement/package change timeline', y => y.option('site', { type: 'number' }).option('plan', { type: 'string' }),
+      async a => show(await request('GET', `/PackageBuilder/audit?${new URLSearchParams({ ...(a.site ? { siteId: a.site } : {}), ...(a.plan ? { planKey: a.plan } : {}) })}`)))
+    .command('health', 'Orphan flags, overlap, drift, cart parity', () => {}, get('/PackageBuilder/health'))
+    .command('fit', 'Cheapest package covering the given features', y => y.option('features', { type: 'string', demandOption: true }),
+      async a => show(await request('POST', '/PackageBuilder/fit', { featureKeys: a.features.split(',') })))
+    .command('proration', 'Upgrade/downgrade proration preview', y => y.option('from', { type: 'string', demandOption: true }).option('to', { type: 'string', demandOption: true }).option('days-remaining', { type: 'number', demandOption: true }).option('days-in-period', { type: 'number', default: 30 }),
+      async a => show(await request('GET', `/PackageBuilder/proration?fromPlan=${enc(a.from)}&toPlan=${enc(a.to)}&daysRemaining=${a['days-remaining']}&daysInPeriod=${a['days-in-period']}`)))
+    .command('my', 'Your own package and what it includes (customer-safe)', () => {}, get('/PackageBuilder/my'))
+    .demandCommand(1, 'Specify a subcommand');
+}

package/lib/commands/price-increase.js

@@ -0,0 +1,93 @@
+// velaro price-increase -- staff-only annual price increase basis (PriceIncreaseController).
+// See docs/architecture/price-increase-basis.md.
+//   basis "list": increase = % of the undiscounted price, added to what the customer pays (discount stays the same dollars)
+//   basis "net":  increase = % of what the customer pays (discount stays the same percent)
+// Nothing here appears on an invoice; every applied increase is written to an internal audit log.
+import { request } from '../api.js';
+
+const BASE = '/api/PriceIncrease';
+
+function money(cents) {
+  if (cents === null || cents === undefined) return '-';
+  return `$${(Number(cents) / 100).toLocaleString('en-US', { minimumFractionDigits: 2, maximumFractionDigits: 2 })}`;
+}
+
+async function getSettings() {
+  const s = await request('GET', `${BASE}/settings`);
+  console.log(`Default increase basis: ${s.defaultBasis}${s.isExplicitlySet ? '' : ' (never set, using the built-in default)'}`);
+}
+
+async function setDefault(args) {
+  if (!['list', 'net', 'clear'].includes(args.basis)) {
+    console.error('Usage: velaro price-increase set-default <list|net|clear>');
+    process.exit(1);
+  }
+  const r = await request('PUT', `${BASE}/settings`, { defaultBasis: args.basis === 'clear' ? null : args.basis });
+  console.log(`Default increase basis is now: ${r.defaultBasis}`);
+}
+
+async function showSubscription(id) {
+  const t = await request('GET', `${BASE}/subscriptions/${id}`);
+  console.log(`Subscription ${t.subscriptionId}`);
+  console.log(`  net per period:  ${money(t.recurringAmountCents)}   list per period: ${money(t.recurringListAmountCents)}`);
+  console.log(`  basis: ${t.effectiveBasis} (from ${t.effectiveBasisSource}${t.basis ? '' : ', inherited'})   annual increase: ${t.annualIncreasePercent ?? '-'}%`);
+  console.log(`  next increase: ${t.nextPriceIncreaseDate?.slice(0, 10) ?? '-'}   applied so far: ${t.priceIncreasesApplied}${t.needsReview ? '   NEEDS REVIEW (list price missing)' : ''}`);
+  for (const l of t.log ?? []) {
+    console.log(`  year ${l.contractYearIndex} ${l.anniversaryDate?.slice(0, 10)} ${l.applied ? 'APPLIED' : 'SKIPPED'}: ${l.formula}${l.invoiceId ? ` (invoice ${l.invoiceId})` : ''}`);
+  }
+}
+
+async function setSubscription(id, args) {
+  const body = {};
+  if (args.basis !== undefined) body.basis = args.basis === 'inherit' ? null : args.basis;
+  if (args.percent !== undefined) body.annualIncreasePercent = args.percent === 'none' ? null : Number(args.percent);
+  if (args.listCents !== undefined) body.recurringListAmountCents = Number(args.listCents);
+  if (args.next !== undefined) body.nextPriceIncreaseDate = args.next === 'none' ? null : args.next;
+  if (Object.keys(body).length === 0) {
+    console.error('Usage: velaro price-increase set <subscriptionId> [--basis list|net|inherit] [--percent 8|none] [--list-cents 1000000] [--next 2027-01-01|none]');
+    process.exit(1);
+  }
+  const r = await request('PUT', `${BASE}/subscriptions/${id}`, body);
+  console.log(r.changes?.length ? `Updated: ${r.changes.join('; ')}` : 'No change.');
+}
+
+async function linkOrderForm(id, formId) {
+  const r = await request('POST', `${BASE}/subscriptions/${id}/link-order-form/${formId}`, {});
+  console.log(r.summary ?? 'Linked.');
+}
+
+async function preview(args) {
+  const r = await request('POST', `${BASE}/preview`, {
+    listCents: Number(args.listCents), netCents: Number(args.netCents), percent: Number(args.percent), years: args.years,
+  });
+  console.log('Year  LIST basis (net / discount)        NET basis (net / discount)');
+  r.list.forEach((row, i) => {
+    const n = r.net[i];
+    console.log(`${String(row.year).padEnd(5)} ${(money(row.netCents) + ' / ' + money(row.discountCents)).padEnd(34)} ${money(n.netCents)} / ${money(n.discountCents)}`);
+  });
+}
+
+export const priceIncreaseCommand = {
+  command: 'price-increase <subcommand>',
+  describe: 'Annual price increase basis: list vs discounted price (staff only)',
+  builder: (yargs) =>
+    yargs
+      .command('settings', 'Show the site-wide default basis', {}, () => getSettings())
+      .command('set-default <basis>', 'Set the site-wide default basis: list | net | clear', {}, (args) => setDefault(args))
+      .command('show <id>', 'Show a subscription\'s increase terms and its audit log', {}, (args) => showSubscription(args.id))
+      .command('set <id>', 'Update a subscription\'s increase terms (only the flags you pass change)', {
+        basis: { type: 'string', choices: ['list', 'net', 'inherit'] },
+        percent: { type: 'string', describe: 'annual percent, or "none" to clear' },
+        'list-cents': { type: 'number', describe: 'undiscounted price per billing period, in cents' },
+        next: { type: 'string', describe: 'next anniversary date (YYYY-MM-DD) or "none"' },
+      }, (args) => setSubscription(args.id, args))
+      .command('link-order-form <id> <formId>', 'Copy the increase terms of a SIGNED order form (basis, percent, per-line exceptions) onto a subscription so billing follows the contract', {}, (args) => linkOrderForm(args.id, args.formId))
+      .command('preview', 'Compare both bases side by side (no changes made)', {
+        'list-cents': { type: 'number', demandOption: true },
+        'net-cents': { type: 'number', demandOption: true },
+        percent: { type: 'number', demandOption: true },
+        years: { type: 'number' },
+      }, (args) => preview(args))
+      .demandCommand(1),
+  handler: () => {},
+};

package/lib/commands/safety.js

@@ -40,9 +40,56 @@ function printSettings(s) {
   console.log(`Count alert:       ${s.threshold?.count ?? 0} events in ${s.threshold?.windowMinutes ?? 60} minutes`);
 }
 
+
+// ── Safety policy (Compliance > Safety Controls) ─────────────────────────────────────────────
+// Wraps SafetyPolicyController. Customer routes take the site from login; Velaro staff pass --site to use the staff routes.
+// Turning a control OFF needs the recorded liability acknowledgement: the CLI prints the exact text and only sends it when you pass --accept.
+const policyPath = (a) => (a.site ? `/SafetyPolicy/staff/${Number(a.site)}` : '/SafetyPolicy');
+const AUDIENCES = ['ai_bot', 'human_agent'];
+
+function printPolicy(v) {
+  console.log('Safety controls (on by default):');
+  for (const c of v.controls ?? []) {
+    console.log(`  ${c.control}: AI bot ${c.aiBot ? 'on' : 'OFF'}, human agent ${c.humanAgent ? 'on' : 'OFF'}`);
+  }
+  console.log(`Always on (floor): ${(v.floor ?? []).join(', ')}`);
+  if (v.anyOff) console.log(`\nWARNING: ${v.warning}`);
+  const feats = Object.keys(v.overrides?.features ?? {});
+  if (feats.length) console.log(`Per-feature overrides: ${feats.join(', ')}`);
+  console.log(`Acknowledgement version: ${v.acknowledgement?.version}`);
+}
+
+async function applyChange(a, enabled) {
+  const audiences = a.audience === 'both' ? AUDIENCES : [a.audience];
+  let last;
+  if (enabled === false) {
+    if (!a.accept) {
+      const cur = await messagingGet(policyPath(a));
+      console.error(`Turning off a safety control needs the acknowledgement. Read it, then re-run with --accept:\n\n${cur.acknowledgement?.text}\n`);
+      throw new Error('Acknowledgement not accepted (pass --accept after reading the text above).');
+    }
+  }
+  const ack = enabled === false ? (await messagingGet(policyPath(a))).acknowledgement : null;
+  for (const audience of audiences) {
+    last = await messagingPut(policyPath(a), {
+      control: a.control,
+      audience,
+      featureKey: a.feature ?? null,
+      enabled,
+      ...(enabled === false ? { acknowledged: true, ackTextVersion: ack.version } : {}),
+    });
+  }
+  return last;
+}
+
+const siteOpt = { type: 'number', describe: 'Velaro staff only: target site ID (uses the staff route)' };
+const controlOpt = { type: 'string', demandOption: true, describe: 'emergency_self_harm | abuse_ladder | threat_detection | input_jailbreak | output_filter' };
+const audienceOpt = { type: 'string', choices: [...AUDIENCES, 'both'], default: 'both' };
+const featureOpt = { type: 'string', describe: 'Per-feature/channel scope (chat, voice, sms, whatsapp, email). Omit for the whole account.' };
+
 export const safetyCommand = {
   command: 'safety',
-  describe: 'Safety events and alerts: list events, acknowledge, alert settings, test alert, ask Velaro for help',
+  describe: 'Safety events, alerts and safety controls: list events, acknowledge, alert settings, policy (on/off controls), test alert, ask Velaro for help',
   builder: (yargs) => yargs
     .command('events', 'List safety events', (y) => y
       .option('from', { type: 'string', describe: 'ISO start' })
@@ -106,6 +153,35 @@ export const safetyCommand = {
       await messagingPost('/SafetyEvents/need-help', { message: a.message });
       console.log('Sent. The Velaro team has been alerted.');
     }))
-    .demandCommand(1, 'Specify a subcommand: events, summary, ack, settings, test, need-help'),
+    .command('policy <action>', 'Safety controls on/off policy (get | set)', (y) => y
+      .positional('action', { choices: ['get', 'set'] })
+      .option('site', siteOpt)
+      .option('control', { ...controlOpt, demandOption: false })
+      .option('audience', audienceOpt)
+      .option('feature', featureOpt)
+      .option('enabled', { type: 'boolean', describe: 'true = on, false = off (off needs --accept)' })
+      .option('reset', { type: 'boolean', describe: 'Clear the override and use the default (on)' })
+      .option('accept', { type: 'boolean', describe: 'Accept the liability acknowledgement (required to turn a control off)' })
+      .option('json', { type: 'boolean' }),
+    runCommand(async (a) => {
+      if (a.action === 'get') return out(a, await messagingGet(policyPath(a)), printPolicy);
+      if (!a.control) throw new Error('--control is required for set.');
+      if (a.reset && a.enabled !== undefined) throw new Error('Use either --enabled or --reset, not both.');
+      if (!a.reset && a.enabled === undefined) throw new Error('Pass --enabled true|false or --reset.');
+      const v = await applyChange(a, a.reset ? null : a.enabled);
+      out(a, v, (x) => { console.log('Saved.\n'); printPolicy(x); });
+    }))
+    .command('acknowledge-off', 'Turn a safety control OFF after accepting the liability acknowledgement', (y) => y
+      .option('site', siteOpt)
+      .option('control', controlOpt)
+      .option('audience', audienceOpt)
+      .option('feature', featureOpt)
+      .option('accept', { type: 'boolean', describe: 'I have read the acknowledgement text and accept it' })
+      .option('json', { type: 'boolean' }),
+    runCommand(async (a) => {
+      const v = await applyChange(a, false);
+      out(a, v, (x) => { console.log(`${a.control} turned off. The acceptance was recorded.\n`); printPolicy(x); });
+    }))
+    .demandCommand(1, 'Specify a subcommand: events, summary, ack, settings, policy, acknowledge-off, test, need-help'),
   handler: () => {},
 };

package/lib/commands/teams-phone.js

@@ -5,6 +5,9 @@
  *   velaro teams-phone set --tenant-id ...        Create or update the configuration
  *   velaro teams-phone remove                     Delete the configuration
  *   velaro teams-phone test                       Run the inbound-calling readiness checks
+ *   velaro teams-phone agents list                List agents and their Teams user object IDs
+ *   velaro teams-phone agents set <agentId> <teamsUserId>   Map an agent to an Entra user Object ID
+ *   velaro teams-phone agents delete <agentId>    Clear an agent's mapping
  *
  * Backend contract: server/Velaro.Messaging/Controllers/Voice/TeamsPhoneConfigController.cs
  * (velaro-messaging). Site is resolved server-side from the auth context — never
@@ -98,6 +101,39 @@ async function testHandler() {
   if (!result?.success) process.exitCode = 1;
 }
 
+// -- agents (agent -> Entra user object id) ---------------------------------------
+
+async function agentsListHandler() {
+  const agents = await messagingGet('/TeamsPhone/Agents');
+  if (!Array.isArray(agents) || agents.length === 0) {
+    console.log(`
+${DIM}No agents found.${RST}
+`);
+    return;
+  }
+  console.log(`
+${BOLD}Teams Phone agent mapping${RST}`);
+  for (const a of agents) {
+    const name = `${a.firstName ?? ''} ${a.lastName ?? ''}`.trim();
+    console.log(`  ${String(a.id).padEnd(8)} ${name.padEnd(28)} ${String(a.email ?? '').padEnd(34)} ${a.teamsUserId ? GRN + a.teamsUserId + RST : DIM + '(unmapped)' + RST}`);
+  }
+  console.log('');
+}
+
+async function agentsSetHandler(argv) {
+  const r = await messagingPut(`/TeamsPhone/Agents/${encodeURIComponent(argv.agentId)}`, { teamsUserId: argv.teamsUserId });
+  console.log(`
+${GRN}✓${RST} Agent ${argv.agentId} mapped to Teams user ${r?.teamsUserId ?? argv.teamsUserId}.
+`);
+}
+
+async function agentsDeleteHandler(argv) {
+  await messagingDel(`/TeamsPhone/Agents/${encodeURIComponent(argv.agentId)}`);
+  console.log(`
+${GRN}✓${RST} Agent ${argv.agentId} mapping cleared.
+`);
+}
+
 // -- command export ------------------------------------------------------------------
 
 export const teamsPhoneCommand = {
@@ -137,6 +173,33 @@ export const teamsPhoneCommand = {
       builder:  yy => yy,
       handler:  testHandler,
     })
+    .command({
+      command:  'agents <action>',
+      describe: 'Agent mapping: which Entra user Object ID is which Velaro agent (list | set | delete)',
+      builder: yy => yy
+        .command({
+          command: 'list',
+          describe: 'List agents with their Teams user Object ID',
+          builder: z => z,
+          handler: agentsListHandler,
+        })
+        .command({
+          command: 'set <agentId> <teamsUserId>',
+          describe: 'Map a Velaro agent (workspace user id) to a Microsoft Entra user Object ID (GUID)',
+          builder: z => z
+            .positional('agentId', { type: 'number', describe: 'Velaro agent (workspace user) id' })
+            .positional('teamsUserId', { type: 'string', describe: 'Entra user Object ID (GUID); "" clears' }),
+          handler: agentsSetHandler,
+        })
+        .command({
+          command: 'delete <agentId>',
+          describe: 'Clear the Teams user mapping for a Velaro agent',
+          builder: z => z.positional('agentId', { type: 'number', describe: 'Velaro agent (workspace user) id' }),
+          handler: agentsDeleteHandler,
+        })
+        .demandCommand(1, 'Specify list, set or delete.'),
+      handler: () => {},
+    })
     .demandCommand(1, 'Specify a teams-phone subcommand.')
     .strict(),
   handler: () => {},

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@velaro/cli",
-  "version": "1.4.107",
+  "version": "1.4.108",
   "description": "Velaro Workspace v20 — command-line interface for managing bots, knowledge base ingestion, MCP API keys, search indexes, and ops health.",
   "type": "module",
   "bin": {