@velaro/cli 1.4.106 → 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';
@@ -130,12 +133,18 @@ import { bundleCommand }            from '../lib/commands/bundle.js';
 import { chatWindowCommand }        from '../lib/commands/chat-window.js';
 import { featureDiscoveryCommand }  from '../lib/commands/feature-discovery.js';
 import { tourPolicyCommand }  from '../lib/commands/tour-policy.js';
+import { livefluenceCommand, missedCommand, serviceCommand, pageCommand, uploadedCommand, msCommand, outlookCommand, oauthCommand, provisionCommand, sseCommand, skillCommand, v10Command, whatsappCommand, mobileCommand, signalrCommand, supportGroupCommand, pricingGroupCommand, scraperGroupCommand, tourPolicyGroupCommand } from '../lib/commands/parity-staff-tools.js';
 import { scraperCommand }      from '../lib/commands/scraper.js';
 import { usageCommand }        from '../lib/commands/usage.js';
 import { campaignsCommand }         from '../lib/commands/campaigns.js';
 import { senderDomainHealthCommand } from '../lib/commands/sender-domain-health.js';
 import { contactsCommand }          from '../lib/commands/contacts.js';
 import { contactListCommand }       from '../lib/commands/contact-list.js';
+import { recycleBinCommand, aiUsageCommand, siteInfoCommand, billingReceiptsCommand } from '../lib/commands/endpoint-parity.js';
+import { adminCommand, appleCommand, forceExpireSiteCommand, backfillCommand, kpiCommand, auditTrailCommand, codeCommand, crmCommand, hangfireCommand } from '../lib/commands/diag-groups.js';
+import { aiFollowupsCommand, businessActionCommand, callCommand, conversationCommand, conversionCommand, emailCommand, ivrCommand } from '../lib/commands/ops-groups.js';
+import { entitlementGroup } from '../lib/commands/entitlement.js';
+import { featureDiscoveryGroup } from '../lib/commands/feature-discovery.js';
 import { startUpdateCheck }  from '../lib/update-check.js';
 import { printBanner, printBannerIfFirstRun } from '../lib/banner.js';
 import { createRequire } from 'module';
@@ -250,16 +259,19 @@ await yargs(hideBin(process.argv))
   .command(billingSubscriptionCommand)
   .command(billingAutomationCommand)
   .command(orderFormCommand)
+  .command(priceIncreaseCommand)
   .command(billingEmailPreferenceCommand)
   .command(billingCommand)
   .command(couponGrantCommand)
   .command(signCommand)
   .command(widgetContainerCommand)
   .command(inlineWidgetConfigCommand)
-  .command({ command: 'pricing', desc: 'View and manage the pricing catalog', builder: pricingCommand, handler: () => {} })
-  .command({ command: 'entitlement', desc: 'Query and manage site feature entitlements (superadmin only)', builder: entitlementCommand, handler: () => {} })
+  .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({ command: 'support', desc: 'Staff SupportTools actions on a site (superadmin only)', builder: supportCommand, handler: () => {} })
+  .command(supportGroupCommand)
   .command(routingCommand)
   .command(diagnosticsCommand)
   .command(aiSpendCommand)
@@ -281,14 +293,49 @@ await yargs(hideBin(process.argv))
   .command(surveyCommand)
   .command(bundleCommand)
   .command(chatWindowCommand)
-  .command({ command: 'feature-discovery', desc: 'View and act on feature-discovery suggestions for this site', builder: featureDiscoveryCommand, handler: () => {} })
+  .command(featureDiscoveryGroup)
+  .command(scraperGroupCommand)
+  .command(tourPolicyGroupCommand)
+  .command(livefluenceCommand)
+  .command(missedCommand)
+  .command(serviceCommand)
+  .command(pageCommand)
+  .command(uploadedCommand)
+  .command(msCommand)
+  .command(outlookCommand)
+  .command(oauthCommand)
+  .command(provisionCommand)
+  .command(sseCommand)
+  .command(skillCommand)
+  .command(v10Command)
+  .command(whatsappCommand)
+  .command(mobileCommand)
+  .command(signalrCommand)
   .command(usageCommand)
-  .command({ command: 'scraper', desc: 'Velaro staff: scraper / upload / chunk usage for any site', builder: scraperCommand, handler: () => {} })
-  .command({ command: 'tour-policy', desc: 'Velaro staff: guided-tour auto-open policy (versioned, rollback-able)', builder: tourPolicyCommand, handler: () => {} })
   .command(campaignsCommand)
   .command(senderDomainHealthCommand)
   .command(contactsCommand)
   .command(contactListCommand)
+  .command(recycleBinCommand)
+  .command(aiUsageCommand)
+  .command(siteInfoCommand)
+  .command(billingReceiptsCommand)
+  .command(adminCommand)
+  .command(appleCommand)
+  .command(forceExpireSiteCommand)
+  .command(backfillCommand)
+  .command(kpiCommand)
+  .command(auditTrailCommand)
+  .command(codeCommand)
+  .command(crmCommand)
+  .command(hangfireCommand)
+  .command(aiFollowupsCommand)
+  .command(businessActionCommand)
+  .command(callCommand)
+  .command(conversationCommand)
+  .command(conversionCommand)
+  .command(emailCommand)
+  .command(ivrCommand)
   .demandCommand(1, 'Specify a command. Run "velaro --help" for options.')
   .strict()
   .help()

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/billing-automation.js

@@ -35,7 +35,7 @@ async function listRules() {
 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 });
+  await request('PUT', `/api/BillingAutomation/global/${appliesTo}`, { mode }); // controller action: SaveGlobal
   console.log(`Global ${appliesTo} set to ${mode}.`);
 }
 

package/lib/commands/diag-groups.js

@@ -0,0 +1,108 @@
+// MCP parity command groups: admin, apple, force-expire-site, backfill, kpi, audit-trail, code, crm, hangfire.
+// Each subcommand calls the same REST route as the MCP tool of the same name (mcp/server.js, mcp/staff-server.js).
+// Staff-only routes are enforced by the backend.
+import { get, post, del, messagingGet, messagingPost } from '../api.js';
+import { show, qs, needYes, group } from '../parity-util.js';
+
+export const adminCommand = { command: 'admin', ...group('Velaro staff: admin API diagnostics', [
+  ['startup-diagnostics', 'Recent AdminStartupDiagnostics rows (migrations, startup exceptions)',
+    (y) => y.option('context-label', { type: 'string' }).option('count', { type: 'number' }),
+    async (a) => show(await get(`/SuperAdmin/StartupDiagnostics${qs({ contextLabel: a['context-label'], count: a.count })}`))],
+]) };
+
+export const appleCommand = { command: 'apple', ...group('Velaro staff: Apple Messages for Business diagnostics', [
+  ['health <siteId>', 'Apple Messages health for a site',
+    (y) => y.positional('siteId', { type: 'number' }),
+    async (a) => show(await messagingGet(`/SupportTools/sites/${a.siteId}/apple/health`))],
+  ['test-control <siteId>', 'Send an Apple test-control action to a conversation',
+    (y) => y.positional('siteId', { type: 'number' })
+      .option('control', { type: 'string', demandOption: true, describe: 'Control name' })
+      .option('conversation-id', { type: 'number' }),
+    async (a) => show(await messagingPost(`/SupportTools/sites/${a.siteId}/apple/test-control`, { control: a.control, conversationId: a['conversation-id'] }))],
+]) };
+
+export const forceExpireSiteCommand = {
+  command: 'force-expire-site <siteId>',
+  describe: 'Velaro staff: force-expire a site subscription (destructive, needs --yes)',
+  builder: (y) => y.positional('siteId', { type: 'number' }).option('yes', { type: 'boolean', describe: 'Confirm' }),
+  handler: async (a) => {
+    needYes(a, `force-expire site ${a.siteId}`);
+    show(await messagingPost(`/SuperAdmin/subscription/${a.siteId}/force-expire`));
+  },
+};
+
+export const backfillCommand = { command: 'backfill', ...group('Velaro staff: per-site data backfills (preview unless --apply --yes)', [
+  ['types', 'List backfill types', null, async () => show(await messagingGet('/SuperAdmin/backfill-types'))],
+  ['run <siteId>', 'Preview or apply a backfill for a site',
+    (y) => y.positional('siteId', { type: 'number' })
+      .option('type', { type: 'string', demandOption: true })
+      .option('from', { type: 'string', demandOption: true, describe: 'yyyy-MM-dd' })
+      .option('to', { type: 'string', demandOption: true, describe: 'yyyy-MM-dd' })
+      .option('apply', { type: 'boolean', describe: 'Write the backfill (default is a preview)' })
+      .option('yes', { type: 'boolean', describe: 'Confirm --apply' }),
+    async (a) => {
+      if (a.apply) needYes(a, 'apply a backfill');
+      show(await messagingPost(`/SuperAdmin/sites/${encodeURIComponent(a.siteId)}/backfill`, { type: a.type, from: a.from, to: a.to, apply: a.apply === true }));
+    }],
+]) };
+
+export const kpiCommand = { command: 'kpi', ...group('Live operations KPIs', [
+  ['snapshot', 'Real-time ops snapshot: agents, queues, waits, channels, teams', null, async () => show(await get('/LiveDashboard/snapshot'))],
+]) };
+
+export const auditTrailCommand = { command: 'audit-trail', ...group('Audit trail of configuration changes', [
+  ['list', 'List audit entries',
+    (y) => y.option('entity-type', { type: 'string' }).option('entity-id', { type: 'string' }).option('take', { type: 'number', default: 200 }),
+    async (a) => show(await get(`/AuditTrail${qs({ entityType: a['entity-type'], entityId: a['entity-id'], take: Math.min(500, a.take ?? 200) })}`))],
+]) };
+
+export const codeCommand = { command: 'code', ...group('Push files to a Velaro repo branch (needs GITHUB_TOKEN)', [
+  ['push-files', 'Create one commit with files on dev/main/master (destructive, needs --yes)',
+    (y) => y.option('message', { type: 'string', demandOption: true })
+      .option('file', { type: 'array', demandOption: true, describe: 'repoPath=localPath, repeatable' })
+      .option('repo', { type: 'string', default: 'velaro-admin' })
+      .option('branch', { type: 'string', default: 'dev' })
+      .option('yes', { type: 'boolean' }),
+    async (a) => {
+      needYes(a, 'push a commit');
+      const token = process.env.GITHUB_TOKEN;
+      if (!token) throw new Error('GITHUB_TOKEN env var is not set.');
+      const { readFileSync } = await import('node:fs');
+      const files = a.file.map((f) => { const [p, l] = String(f).split('='); return { path: p, content: readFileSync(l || p, 'utf8') }; });
+      const REPOS = ['velaro-admin', 'velaro-messaging', 'velaro-shared', 'velaro-shared-frontend'];
+      if (!REPOS.includes(a.repo)) throw new Error(`Repo not allowed. Allowed: ${REPOS.join(', ')}`);
+      if (!['dev', 'master', 'main'].includes(a.branch)) throw new Error('Branch must be dev, master or main.');
+      const norm = (p) => p.replace(/\\/g, '/').replace(/^\.\//, '').replace(/^\//, '');
+      if (files.some((f) => norm(f.path) === '.github' || norm(f.path).startsWith('.github/'))) throw new Error('Cannot push to .github/ paths.');
+      const base = `https://api.github.com/repos/velaro/${a.repo}`;
+      const headers = { Authorization: `Bearer ${token}`, Accept: 'application/vnd.github+json', 'X-GitHub-Api-Version': '2022-11-28', 'Content-Type': 'application/json' };
+      const gh = async (path, opts = {}) => {
+        const r = await fetch(base + path, { headers, ...opts });
+        if (!r.ok) throw new Error(`GitHub API ${path} -> ${r.status}: ${await r.text()}`);
+        return r.json();
+      };
+      const head = (await gh(`/git/refs/heads/${a.branch}`)).object.sha;
+      const baseTree = (await gh(`/git/commits/${head}`)).tree.sha;
+      const tree = await Promise.all(files.map(async (f) => {
+        const b = await gh('/git/blobs', { method: 'POST', body: JSON.stringify({ content: f.content, encoding: 'utf-8' }) });
+        return { path: f.path, mode: '100644', type: 'blob', sha: b.sha };
+      }));
+      const nt = await gh('/git/trees', { method: 'POST', body: JSON.stringify({ base_tree: baseTree, tree }) });
+      const c = await gh('/git/commits', { method: 'POST', body: JSON.stringify({ message: a.message, tree: nt.sha, parents: [head] }) });
+      await gh(`/git/refs/heads/${a.branch}`, { method: 'PATCH', body: JSON.stringify({ sha: c.sha }) });
+      console.log(`Pushed to velaro/${a.repo}@${a.branch} commit ${c.sha.slice(0, 8)}\n${files.map((f) => '  ' + f.path).join('\n')}`);
+    }],
+]) };
+
+export const crmCommand = { command: 'crm', ...group('Velaro staff: CRM email-campaign engine audit', [
+  ['email-campaign-audit', 'Row counts for the legacy CRM email-campaign tables (safe-to-retire check)', null,
+    async () => show(await messagingGet('/SuperAdmin/crm-email-campaign-audit'))],
+]) };
+
+export const hangfireCommand = { command: 'hangfire', ...group('Velaro staff: failed Hangfire jobs', [
+  ['list-failed', 'List failed jobs', null, async () => show(await get('/DatabaseTool/FailedJobs'))],
+  ['retry <id>', 'Requeue one failed job', (y) => y.positional('id', { type: 'string' }),
+    async (a) => show(await post(`/DatabaseTool/FailedJobs/${a.id}/retry`))],
+  ['delete-failed <id>', 'Delete one failed job (needs --yes)', (y) => y.positional('id', { type: 'string' }).option('yes', { type: 'boolean' }),
+    async (a) => { needYes(a, `delete failed job ${a.id}`); show(await del(`/DatabaseTool/FailedJobs/${a.id}`)); }],
+]) };

package/lib/commands/endpoint-parity.js

@@ -0,0 +1,58 @@
+// CLI halves of the MCP parity tools in mcp/parity/endpoints.customer.js and endpoints.staff.js.
+// Each handler names the controller action it calls.
+import { request } from '../api.js';
+
+const show = (r) => console.log(JSON.stringify(r, null, 2));
+const int = (y, k, d) => y.option(k, { type: 'number', demandOption: true, describe: d });
+
+export const recycleBinCommand = {
+  command: 'recycle-bin',
+  describe: 'List and restore soft-deleted contact lists, members, segments and KB articles/topics (one id at a time)',
+  builder: (y) => y
+    .command({ command: 'contact-lists', describe: 'List deleted contact lists', handler: async () => show(await request('GET', '/ContactLists/deleted')) }) // controller action: GetDeletedLists
+    .command({ command: 'restore-contact-list', describe: 'Restore one contact list', builder: (z) => int(z, 'id', 'List id'), handler: async (a) => show(await request('POST', `/ContactLists/${a.id}/restore`)) }) // controller action: RestoreList
+    .command({ command: 'members', describe: 'List deleted members of a list', builder: (z) => int(z, 'list', 'List id'), handler: async (a) => show(await request('GET', `/ContactLists/${a.list}/Members/deleted`)) }) // controller action: GetDeletedMembers
+    .command({ command: 'restore-member', describe: 'Restore one list member', builder: (z) => int(int(z, 'list', 'List id'), 'member', 'Member id'), handler: async (a) => show(await request('POST', `/ContactLists/${a.list}/Members/${a.member}/restore`)) }) // controller action: RestoreMember
+    .command({ command: 'segments', describe: 'List deleted segments', handler: async () => show(await request('GET', '/ContactSegments/deleted')) }) // controller action: ListDeleted (ContactSegments)
+    .command({ command: 'kb-articles', describe: 'List deleted KB articles', handler: async () => show(await request('GET', '/api/kb/articles/deleted')) }) // controller action: ListDeleted (KBArticles)
+    .command({ command: 'restore-kb-article', describe: 'Restore one KB article', builder: (z) => int(z, 'id', 'Article id'), handler: async (a) => show(await request('POST', `/api/kb/articles/${a.id}/restore`)) }) // controller action: RestoreDeleted (KBArticles)
+    .command({ command: 'kb-topics', describe: 'List deleted KB topics', handler: async () => show(await request('GET', '/api/kb/topics/deleted')) }) // controller action: ListDeleted (KBTopics)
+    .command({ command: 'restore-kb-topic', describe: 'Restore one KB topic', builder: (z) => int(z, 'id', 'Topic id'), handler: async (a) => show(await request('POST', `/api/kb/topics/${a.id}/restore`)) }) // controller action: RestoreDeleted (KBTopics)
+    .demandCommand(1),
+  handler: () => {},
+};
+
+export const aiUsageCommand = {
+  command: 'ai-usage',
+  describe: 'Your site AI usage summary and budget alert',
+  builder: (y) => y
+    .command({ command: 'summary', describe: 'AI usage summary', handler: async () => show(await request('GET', '/AiUsageReport/summary')) }) // controller action: GetSummary
+    .command({
+      command: 'budget-alert-set', describe: 'Update the budget alert',
+      builder: (z) => z.option('enabled', { type: 'boolean' }).option('threshold-percent', { type: 'number' }).option('recipients', { type: 'string', describe: 'Comma-separated emails' }),
+      handler: async (a) => show(await request('PUT', '/AiUsageReport/budget-alert', { enabled: a.enabled, thresholdPercent: a.thresholdPercent, recipientEmails: a.recipients })), // controller action: UpdateBudgetAlert
+    })
+    .command({ command: 'budget-alert-delete', describe: 'Delete the budget alert', handler: async () => show(await request('DELETE', '/AiUsageReport/budget-alert')) }) // controller action: DeleteBudgetAlert
+    .demandCommand(1),
+  handler: () => {},
+};
+
+export const siteInfoCommand = {
+  command: 'site-info',
+  describe: 'Read-only site settings, entitlements and platform uptime for your site',
+  builder: (y) => y
+    .command({ command: 'settings', describe: 'Site settings', handler: async () => show(await request('GET', '/api/SiteSettings')) }) // controller action: GetSiteSettings
+    .command({ command: 'entitlements', describe: 'Your resolved entitlements', handler: async () => show(await request('GET', '/Entitlements/my')) }) // controller action: GetMyEntitlements
+    .command({ command: 'uptime', describe: 'Platform uptime', handler: async () => show(await request('GET', '/PlatformUptime')) }) // controller action: GetAsync (PlatformUptime)
+    .command({ command: 'last-copilot-session', describe: 'Your last Copilot session summary', handler: async () => show(await request('GET', '/Copilot/LastSession')) }) // controller action: LastSession
+    .command({ command: 'sender-domain-health', describe: 'Sender domain health', handler: async () => show(await request('GET', '/SenderDomains/Health')) }) // controller action: GetHealth
+    .command({ command: 'netsuite-interaction-summary', describe: 'NetSuite AI interaction summary for a conversation', builder: (z) => int(z, 'conversation', 'Conversation id'), handler: async (a) => show(await request('POST', `/NetSuite/interaction-summary?conversationId=${a.conversation}`)) }) // controller action: GetInteractionSummary
+    .demandCommand(1),
+  handler: () => {},
+};
+
+export const billingReceiptsCommand = {
+  command: 'billing-receipts-run',
+  describe: 'Staff only: run the payment receipt job now',
+  handler: async () => show(await request('POST', '/api/BillingNotifications/receipts/run-now')), // controller action: RunReceiptsNow
+};

package/lib/commands/entitlement.js

@@ -1,6 +1,19 @@
 // velaro entitlement — query and manage site feature entitlements (superadmin only)
 import { request } from '../api.js';
 
+async function syncStripe(a) {
+  const r = await request('PUT', `Entitlements/admin/sync-stripe/${a.site}`, {
+    planKey: a.plan,
+    status: a.status,
+    cancelAtPeriodEnd: a['cancel-at-period-end'] ?? false,
+    currentPeriodEnd: a['current-period-end'] ?? null,
+    trialEndAt: a['trial-end-at'] ?? null,
+    stripeCustomerId: a['stripe-customer-id'],
+    stripeSubscriptionId: a['stripe-subscription-id'],
+  });
+  console.log(`Site ${a.site} synced: status=${r.status} plan=${r.planKey || 'unchanged'}`);
+}
+
 async function getSite(args) {
   if (!args.site) { console.error('Usage: velaro entitlement get --site 1032'); process.exit(1); }
   const result = await request('GET', `Entitlements/${args.site}`);
@@ -289,6 +302,16 @@ 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('sync-stripe', 'Sync the Stripe subscription state into its entitlement record (superadmin only)', y => y
+      .option('site',   { type: 'number', demandOption: true, desc: 'Site ID' })
+      .option('status', { type: 'string', demandOption: true, desc: 'Stripe subscription status, e.g. active, trialing, canceled' })
+      .option('plan',   { type: 'string', desc: 'Plan key, e.g. plan.professional' })
+      .option('cancel-at-period-end', { type: 'boolean', desc: 'Subscription cancels at period end' })
+      .option('current-period-end',   { type: 'string', desc: 'ISO 8601 current period end' })
+      .option('trial-end-at',         { type: 'string', desc: 'ISO 8601 trial end' })
+      .option('stripe-customer-id',      { type: 'string', desc: 'Stripe customer id' })
+      .option('stripe-subscription-id',  { type: 'string', desc: 'Stripe subscription id' })
+    , a => syncStripe(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' })
@@ -305,5 +328,8 @@ export function entitlementCommand(yargs) {
       .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 | 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');
+    .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 | sync-stripe | trial | list-cutover | set-cutover');
 }
+
+// Registered group object (the CLI/MCP parity validator reads `command:` from a named const).
+export const entitlementGroup = { command: 'entitlement', desc: 'Query and manage site feature entitlements (superadmin only)', builder: entitlementCommand, handler: () => {} };

package/lib/commands/feature-discovery.js

@@ -38,3 +38,6 @@ export function featureDiscoveryCommand(yargs) {
     , a => requestFeature(a))
     .demandCommand(1, 'Specify a subcommand: list | request');
 }
+
+// Registered group object (the CLI/MCP parity validator reads `command:` from a named const).
+export const featureDiscoveryGroup = { command: 'feature-discovery', desc: 'View and act on feature-discovery suggestions for this site', builder: featureDiscoveryCommand, handler: () => {} };

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: () => {},
 };