@velaro/cli 1.4.103 → 1.4.104

package/bin/velaro.js

@@ -42,6 +42,7 @@ import { calendlyCommand }   from '../lib/commands/calendly.js';
 import { copilotStudioCommand } from '../lib/commands/copilotstudio.js';
 import { acuityCommand }     from '../lib/commands/acuity.js';
 import { avatarCommand }     from '../lib/commands/avatar.js';
+import { applePayPresetCommand } from '../lib/commands/apple-pay-preset.js';
 import { imageAnalysisCommand } from '../lib/commands/image-analysis.js';
 import { integrationCommand } from '../lib/commands/integration.js';
 import { appointmentsCommand } from '../lib/commands/appointments.js';
@@ -185,6 +186,7 @@ await yargs(hideBin(process.argv))
   .command(copilotStudioCommand)
   .command(acuityCommand)
   .command(avatarCommand)
+  .command(applePayPresetCommand)
   .command(imageAnalysisCommand)
   .command(integrationCommand)
   .command(appointmentsCommand)

package/lib/apple-pay-presets.js

@@ -0,0 +1,66 @@
+// Pure helpers for `velaro apple-pay-preset`: parse line items and build request bodies for the
+// messaging ApplePayPresetOrders API. Totals are always computed server-side; never sent from here.
+
+export const MAX_LINE_ITEMS = 20;
+
+/** Parse one "Label=12.50" spec. The last "=" splits label from amount so labels may contain "=". */
+export function parseItem(spec) {
+  const s = String(spec ?? '');
+  const i = s.lastIndexOf('=');
+  if (i < 1) throw new Error(`Line item "${s}" must look like Label=12.50`);
+  const label = s.slice(0, i).trim();
+  const raw = s.slice(i + 1).trim();
+  if (!label) throw new Error(`Line item "${s}" needs a label`);
+  if (!/^-?\d+(\.\d{1,2})?$/.test(raw)) throw new Error(`Line item "${label}" amount "${raw}" must be a number with at most 2 decimals`);
+  return { label, amount: Number(raw) };
+}
+
+/** Accepts --item specs (string or array) and/or --items-json '[{"label":"x","amount":1}]'. Returns undefined if neither given. */
+export function parseItems({ item, itemsJson } = {}) {
+  let items;
+  if (itemsJson !== undefined) {
+    let parsed;
+    try { parsed = JSON.parse(itemsJson); } catch { throw new Error('--items-json must be valid JSON'); }
+    if (!Array.isArray(parsed)) throw new Error('--items-json must be a JSON array');
+    items = parsed.map(p => {
+      if (!p || typeof p.label !== 'string' || !p.label.trim() || typeof p.amount !== 'number' || !Number.isFinite(p.amount)) {
+        throw new Error('Each --items-json entry needs a string label and a numeric amount');
+      }
+      return { label: p.label.trim(), amount: p.amount };
+    });
+  }
+  if (item !== undefined) {
+    const specs = Array.isArray(item) ? item : [item];
+    items = (items ?? []).concat(specs.map(parseItem));
+  }
+  if (items && items.length > MAX_LINE_ITEMS) throw new Error(`A preset order holds at most ${MAX_LINE_ITEMS} line items`);
+  return items;
+}
+
+/** Body for POST/PUT ApplePayPresetOrders. Only passed fields are included (PUT is a partial update). */
+export function presetBody(args) {
+  const body = {};
+  if (args.name !== undefined) body.name = String(args.name);
+  if (args.description !== undefined) body.description = String(args.description);
+  if (args.currency !== undefined) body.currencyCode = String(args.currency).toUpperCase();
+  const items = parseItems({ item: args.item, itemsJson: args.itemsJson });
+  if (items !== undefined) body.lineItems = items;
+  if (args.active !== undefined) body.isActive = Boolean(args.active);
+  if (args.managersOnly !== undefined) body.overrideRestrictedToManagers = Boolean(args.managersOnly);
+  return body;
+}
+
+export function presetPath(id) {
+  const n = Number(id);
+  if (!Number.isInteger(n) || n <= 0) throw new Error('Preset id must be a positive whole number');
+  return `/ApplePayPresetOrders/${n}`;
+}
+
+export function listPath(activeOnly) {
+  return `/ApplePayPresetOrders${activeOnly ? '?activeOnly=true' : ''}`;
+}
+
+export function formatPreset(p) {
+  const items = (p.lineItems || []).map(li => `    ${li.label}  ${Number(li.amount).toFixed(2)} ${p.currencyCode}`).join('\n');
+  return `#${p.id} ${p.name}${p.isActive ? '' : ' (inactive)'}${p.overrideRestrictedToManagers ? ' [managers-only amount changes]' : ''}\n${items}\n    Total  ${Number(p.totalAmount).toFixed(2)} ${p.currencyCode}`;
+}

package/lib/apple-pay-presets.test.js

@@ -0,0 +1,61 @@
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import fs from 'node:fs';
+import { parseItem, parseItems, presetBody, presetPath, listPath, formatPreset } from './apple-pay-presets.js';
+
+test('parseItem splits on the last "=" and validates the amount', () => {
+  assert.deepEqual(parseItem('Haircut=30'), { label: 'Haircut', amount: 30 });
+  assert.deepEqual(parseItem('A=B=1.50'), { label: 'A=B', amount: 1.5 });
+  assert.throws(() => parseItem('Haircut'), /Label=12.50/);
+  assert.throws(() => parseItem('=5'), /Label=12.50/);
+  assert.throws(() => parseItem('x=abc'), /number/);
+  assert.throws(() => parseItem('x=1.234'), /2 decimals/);
+});
+
+test('parseItems merges --item and --items-json, caps at 20, rejects bad json', () => {
+  assert.equal(parseItems({}), undefined);
+  assert.deepEqual(parseItems({ item: 'a=1' }), [{ label: 'a', amount: 1 }]);
+  assert.deepEqual(parseItems({ itemsJson: '[{"label":"b","amount":2}]', item: ['c=3'] }), [{ label: 'b', amount: 2 }, { label: 'c', amount: 3 }]);
+  assert.throws(() => parseItems({ itemsJson: '{' }), /valid JSON/);
+  assert.throws(() => parseItems({ itemsJson: '{}' }), /array/);
+  assert.throws(() => parseItems({ itemsJson: '[{"label":"","amount":1}]' }), /label/);
+  assert.throws(() => parseItems({ item: Array.from({ length: 21 }, (_, i) => `i${i}=1`) }), /at most 20/);
+});
+
+test('presetBody includes only passed fields and never a total', () => {
+  assert.deepEqual(presetBody({}), {});
+  assert.deepEqual(presetBody({ active: false }), { isActive: false });
+  const b = presetBody({ name: 'Cut', currency: 'usd', item: ['Haircut=30'], managersOnly: true, active: true, description: 'd' });
+  assert.deepEqual(b, { name: 'Cut', description: 'd', currencyCode: 'USD', lineItems: [{ label: 'Haircut', amount: 30 }], isActive: true, overrideRestrictedToManagers: true });
+  assert.equal('totalAmount' in b, false);
+});
+
+test('paths validate ids', () => {
+  assert.equal(presetPath('7'), '/ApplePayPresetOrders/7');
+  assert.throws(() => presetPath('0'), /positive/);
+  assert.throws(() => presetPath('x'), /positive/);
+  assert.equal(listPath(true), '/ApplePayPresetOrders?activeOnly=true');
+  assert.equal(listPath(false), '/ApplePayPresetOrders');
+});
+
+test('formatPreset shows items and total', () => {
+  const out = formatPreset({ id: 3, name: 'Cut', isActive: false, overrideRestrictedToManagers: true, currencyCode: 'USD', totalAmount: 35, lineItems: [{ label: 'Haircut', amount: 30 }, { label: 'Tip', amount: 5 }] });
+  assert.match(out, /#3 Cut \(inactive\) \[managers-only/);
+  assert.match(out, /Total {2}35.00 USD/);
+});
+
+test('MCP server exposes the four preset tools wired to ApplePayPresetOrders on the messaging api', () => {
+  const src = fs.readFileSync(new URL('../../mcp/server.js', import.meta.url), 'utf8');
+  for (const t of ['apple_pay_preset_list', 'apple_pay_preset_create', 'apple_pay_preset_update', 'apple_pay_preset_delete']) {
+    assert.ok(src.includes(`name: '${t}'`), `tool def ${t}`);
+    assert.ok(src.includes(`case '${t}':`), `handler ${t}`);
+  }
+  assert.match(src, /messagingRequest\('POST', '\/ApplePayPresetOrders'/);
+  assert.match(src, /messagingRequest\('DELETE', `\/ApplePayPresetOrders\//);
+});
+
+test('command file uses messaging helpers only', () => {
+  const src = fs.readFileSync(new URL('./commands/apple-pay-preset.js', import.meta.url), 'utf8');
+  assert.match(src, /messagingGet, messagingPost, messagingPut, messagingDel/);
+  assert.doesNotMatch(src, /import\s*\{[^}]*\b(get|post|del|request)\b[^}]*\}\s*from '\.\.\/api\.js'/);
+});

package/lib/commands/apple-pay-preset.js

@@ -0,0 +1,65 @@
+import { messagingGet, messagingPost, messagingPut, messagingDel } from '../api.js';
+import { presetBody, presetPath, listPath, formatPreset } from '../apple-pay-presets.js';
+import { runCommand } from '../run.js';
+
+// ── velaro apple-pay-preset ──────────────────────────────────────────────────
+// Pre-canned Apple Pay orders (messaging ApplePayPresetOrders API). Messaging routes, so
+// every call goes through the messaging helpers. Totals are computed by the server.
+// Registered as `apple-pay-preset` until the `apple-pay` command (PR #1774) lands, then it can nest as `apple-pay preset`.
+
+const fieldOptions = y => y
+  .option('name',          { type: 'string', describe: 'Preset name' })
+  .option('description',   { type: 'string', describe: 'Preset description' })
+  .option('currency',      { type: 'string', describe: 'ISO currency code, e.g. USD' })
+  .option('item',          { type: 'string', array: true, describe: 'Line item as "Label=12.50" (repeatable, max 20)' })
+  .option('items-json',    { type: 'string', describe: 'Line items as JSON: [{"label":"Haircut","amount":30}]' })
+  .option('active',        { type: 'boolean', describe: 'Preset is available to agents and the AI' })
+  .option('managers-only', { type: 'boolean', describe: 'Only managers can change amounts at send time' });
+
+export const applePayPresetCommand = {
+  command:  'apple-pay-preset <subcommand>',
+  describe: 'Manage pre-canned Apple Pay orders',
+  builder:  yargs => yargs
+    .command({
+      command: 'list',
+      describe: 'List preset orders',
+      builder: y => y.option('active-only', { type: 'boolean', default: false }),
+      handler: runCommand(async argv => {
+        const rows = await messagingGet(listPath(argv.activeOnly));
+        const list = Array.isArray(rows) ? rows : [];
+        console.log(list.length ? `\n${list.map(formatPreset).join('\n\n')}\n` : '\nNo preset orders.\n');
+      }),
+    })
+    .command({
+      command: 'get <id>',
+      describe: 'Show one preset order',
+      handler: runCommand(async argv => { console.log(`\n${formatPreset(await messagingGet(presetPath(argv.id)))}\n`); }),
+    })
+    .command({
+      command: 'create',
+      describe: 'Create a preset order',
+      builder: y => fieldOptions(y).demandOption('name'),
+      handler: runCommand(async argv => {
+        const body = presetBody(argv);
+        if (!body.lineItems || !body.lineItems.length) throw new Error('Provide at least one --item "Label=12.50" (or --items-json)');
+        console.log(`\nCreated:\n${formatPreset(await messagingPost('/ApplePayPresetOrders', body))}\n`);
+      }),
+    })
+    .command({
+      command: 'update <id>',
+      describe: 'Update a preset order (only passed fields change)',
+      builder: fieldOptions,
+      handler: runCommand(async argv => {
+        const body = presetBody(argv);
+        if (!Object.keys(body).length) throw new Error('Pass at least one field to change');
+        console.log(`\nUpdated:\n${formatPreset(await messagingPut(presetPath(argv.id), body))}\n`);
+      }),
+    })
+    .command({
+      command: 'delete <id>',
+      describe: 'Delete a preset order',
+      handler: runCommand(async argv => { await messagingDel(presetPath(argv.id)); console.log(`\nDeleted preset ${Number(argv.id)}.\n`); }),
+    })
+    .demandCommand(1),
+  handler: () => {},
+};

package/lib/commands/billing-automation.js

@@ -136,6 +136,16 @@ async function setReceipts(subscriptionId, args) {
   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',
@@ -161,6 +171,8 @@ export const billingAutomationCommand = {
       .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'] },

package/lib/commands/entitlement.js

@@ -166,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');
@@ -250,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 | report-packages | 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/logs.js

@@ -362,8 +362,6 @@ function parsePositiveIntFlag(flagName, rawValue, { max } = {}) {
 // emails/sms isn't wrongly flagged as "fires into the void" when defaults
 // actually cover it.
 function hasAnyRecipient({ emails, sms, webhook, teams, mobileUserIds, hasGlobalDefaultContacts }) {
-// also cover webhook, which that component's check omits).
-function hasAnyRecipient({ emails, sms, webhook, mobileUserIds, teams }) {
   return Boolean(
     (emails && String(emails).trim()) ||
     (sms && String(sms).trim()) ||
@@ -374,8 +372,6 @@ function hasAnyRecipient({ emails, sms, webhook, mobileUserIds, teams }) {
     // ResolveRecipients) -- if there's at least one global-default contact with a phone or
     // email, a rule with both blank is NOT actually silent, even though neither field is set.
     ((!emails || !String(emails).trim()) && (!sms || !String(sms).trim()) && hasGlobalDefaultContacts)
-    (mobileUserIds && String(mobileUserIds).trim()) ||
-    teams
   );
 }
 
@@ -532,10 +528,6 @@ async function createAlertRule(argv) {
   if (!hasAnyRecipient({ emails: argv.emails, sms: argv.sms, webhook: argv.webhook, teams: argv.teams, mobileUserIds: argv.mobileUserIds, hasGlobalDefaultContacts: hasDefaults })
       && !argv.noRecipientsOk) {
     console.error('No notification channel given (--emails, --sms, --webhook, --teams, or --mobile-user-ids), and no global-default contact exists to fall back to — this rule would fire but notify no one.');
-  // HIGH: a rule with zero notification channels fires into the void.
-  if (!hasAnyRecipient({ emails: argv.emails, sms: argv.sms, webhook: argv.webhook, mobileUserIds: argv.mobileUserIds, teams: argv.teams })
-      && !argv.noRecipientsOk) {
-    console.error('No notification channel given (--emails, --sms, --webhook, --teams, or --mobile-user-ids) — this rule would fire but notify no one.');
     console.error('If that\'s intentional (e.g. you only want it visible in Alert History), pass --no-recipients-ok to proceed anyway.');
     console.error('To set up global defaults so a blank --emails/--sms is covered automatically: velaro logs contacts add --name alex --phone +1... --email alex@velaro.com --global');
     process.exit(1);
@@ -658,9 +650,6 @@ async function updateAlertRule(argv) {
   if (!hasAnyRecipient({ emails: body.notifyEmails, sms: body.notifyPhoneNumbers, webhook: body.notifyWebhookUrl, teams: body.notifyTeams, mobileUserIds: body.notifyMobileUserIds, hasGlobalDefaultContacts: hasDefaults })
       && !argv.noRecipientsOk) {
     console.error('This update would leave the rule with no notification channel (--emails, --sms, --webhook, --teams, or --mobile-user-ids), and no global-default contact exists to fall back to — it would fire but notify no one.');
-  if (!hasAnyRecipient({ emails: body.notifyEmails, sms: body.notifyPhoneNumbers, webhook: body.notifyWebhookUrl, mobileUserIds: body.notifyMobileUserIds, teams: body.notifyTeams })
-      && !argv.noRecipientsOk) {
-    console.error('This update would leave the rule with no notification channel (--emails, --sms, --webhook, --teams, or --mobile-user-ids) — it would fire but notify no one.');
     console.error('If that\'s intentional, pass --no-recipients-ok to proceed anyway.');
     process.exit(1);
   }

package/lib/commands/mcp-key.js

@@ -106,21 +106,6 @@ const mcpKeyInstallCommand = {
     const result  = await request('POST', '/McpApiKeys', payload, env);
     const rawKey  = result.rawKey;
 
-    // Claude Code reads user-scope MCP server definitions from the
-    // top-level "mcpServers" key in ~/.claude.json — NOT from
-    // ~/.claude/settings.json (that file is for permissions/hooks/env,
-    // and any mcpServers entry written there is silently ignored).
-    // prod  → entry named "velaro"
-    // staging → entry named "velaro-staging"
-    const serverName    = env === 'prod' ? 'velaro' : `velaro-${env}`;
-    const claudeJsonPath = path.join(os.homedir(), '.claude.json');
-    let claudeJson = {};
-    if (fs.existsSync(claudeJsonPath)) {
-      try { claudeJson = JSON.parse(fs.readFileSync(claudeJsonPath, 'utf8')); } catch {}
-    }
-
-    claudeJson.mcpServers = claudeJson.mcpServers || {};
-    claudeJson.mcpServers[serverName] = {
     // Claude Code reads MCP server definitions from the top-level "mcpServers" key
     // in ~/.claude.json (NOT ~/.claude/settings.json — that file has no effect here).
     // This is the same shape `claude mcp add` itself writes.
@@ -152,8 +137,7 @@ const mcpKeyInstallCommand = {
       },
     };
 
-    fs.mkdirSync(path.dirname(claudeJsonPath), { recursive: true });
-    fs.writeFileSync(claudeJsonPath, JSON.stringify(claudeJson, null, 2));
+    fs.mkdirSync(path.dirname(configPath), { recursive: true });
     // Claude Code itself writes ~/.claude.json continuously (history, project state),
     // so this must never be a plain in-place write: write to a temp file and rename,
     // which is atomic on the same filesystem — a crash or concurrent write mid-save

package/lib/commands/workflow.js

@@ -1,5 +1,5 @@
 import fs                          from 'node:fs';
-import { getCredentials, messagingGet, messagingPost, messagingPut } from '../api.js';
+import { getCredentials, messagingGet, messagingPost, messagingPut, messagingDel } from '../api.js';
 import { requireFeature }          from '../subscription.js';
 import { runCommand }              from '../run.js';
 import { applyFollowUpOptions }    from '../ai-followups.js';
@@ -18,8 +18,9 @@ export const workflowCommand = {
       .command(workflowNodeOptionsCommand)
       .command(workflowIntegrityScanCommand)
       .command(workflowAiFollowupsCommand)
+      .command(workflowScheduleCommand)
       .command(siteAiFollowupsCommand)
-      .demandCommand(1, 'Specify a subcommand: list, get, create, enable, disable, node-options, integrity-scan, ai-followups, ai-followups-site'),
+      .demandCommand(1, 'Specify a subcommand: list, get, create, enable, disable, node-options, integrity-scan, ai-followups, ai-followups-site, schedule'),
   handler: () => {},
 };
 
@@ -358,3 +359,124 @@ const workflowIntegrityScanCommand = {
     }
   }),
 };
+
+// ── schedule (workflow schedule priority; messaging owns /Workflows/schedule/*) ──────────────
+// Mirrors the velaro MCP tools workflow_schedule_resolve / _timeline / _validate / _banner / _override_save / _override_list / _override_delete.
+// An older messaging answers 404/501: print "not available" instead of failing.
+
+const NOT_AVAILABLE = "Workflow scheduling is not available on this site's version.";
+
+async function scheduleTolerant(fn) {
+  try {
+    return await fn();
+  } catch (err) {
+    if (/->\s*(404|501)\b|\b(404|501)\b/.test(String(err?.message))) { console.log(NOT_AVAILABLE); return undefined; }
+    throw err;
+  }
+}
+
+const qs = (o) => new URLSearchParams(Object.entries(o).filter(([, v]) => v !== undefined && v !== '')).toString();
+
+const workflowScheduleCommand = {
+  command:  'schedule <subcommand>',
+  describe: 'Workflow schedule priority: set, get, delete, validate, resolve, timeline, gaps',
+  builder:  (yargs) =>
+    yargs
+      .command({
+        command:  'set',
+        describe: 'Create/update a SwitchWorkflow schedule override (run another workflow on given dates)',
+        builder:  (y) => y
+          .option('id',       { type: 'number', describe: 'Existing override id to update (omit to create)' })
+          .option('schedule', { type: 'number', demandOption: true, describe: 'Shared schedule id' })
+          .option('workflow', { type: 'number', demandOption: true, describe: 'Target workflow id to run' })
+          .option('name',     { type: 'string' })
+          .option('start',    { type: 'string', demandOption: true, describe: 'YYYY-MM-DD' })
+          .option('end',      { type: 'string', describe: 'YYYY-MM-DD' }),
+        handler:  runCommand(async (argv) => {
+          await requireFeature('enableAutomation', 'Workflows');
+          const body = { sharedScheduleId: argv.schedule, name: argv.name, startDate: argv.start, endDate: argv.end, action: 3, targetWorkflowId: argv.workflow };
+          const r = await scheduleTolerant(() => argv.id
+            ? messagingPut(`/ScheduleOverride/${argv.id}`, body)
+            : messagingPost('/ScheduleOverride', body));
+          if (r !== undefined) console.log(JSON.stringify(r, null, 2));
+        }),
+      })
+      .command({
+        command:  'get',
+        describe: 'List this site\'s SwitchWorkflow schedule overrides',
+        handler:  runCommand(async () => {
+          await requireFeature('enableAutomation', 'Workflows');
+          const r = await scheduleTolerant(() => messagingGet('/ScheduleOverride?action=3'));
+          if (r !== undefined) console.log(JSON.stringify(r, null, 2));
+        }),
+      })
+      .command({
+        command:  'delete',
+        describe: 'Delete a schedule override by id (site admins only)',
+        builder:  (y) => y.option('id', { type: 'number', demandOption: true }),
+        handler:  runCommand(async (argv) => {
+          await requireFeature('enableAutomation', 'Workflows');
+          const r = await scheduleTolerant(async () => { await messagingDel(`/ScheduleOverride/${argv.id}`); return { success: true, deleted: argv.id }; });
+          if (r !== undefined) console.log(JSON.stringify(r, null, 2));
+        }),
+      })
+      .command({
+        command:  'validate',
+        describe: 'Dry-run a draft override (or no override: list current gaps) without saving',
+        builder:  (y) => y
+          .option('trigger',  { type: 'string', default: 'conversation_opened' })
+          .option('channel',  { type: 'string' })
+          .option('schedule', { type: 'number', describe: 'Shared schedule id of the draft override' })
+          .option('workflow', { type: 'number', describe: 'Target workflow id of the draft override' })
+          .option('name',     { type: 'string' })
+          .option('start',    { type: 'string', describe: 'YYYY-MM-DD' })
+          .option('end',      { type: 'string', describe: 'YYYY-MM-DD' }),
+        handler:  runCommand(async (argv) => {
+          await requireFeature('enableAutomation', 'Workflows');
+          const override = argv.schedule && argv.workflow && argv.start
+            ? { sharedScheduleId: argv.schedule, name: argv.name, startDate: argv.start, endDate: argv.end, action: 3, targetWorkflowId: argv.workflow }
+            : undefined;
+          const r = await scheduleTolerant(() => messagingPost('/Workflows/schedule/validate', { trigger: argv.trigger, channel: argv.channel, override }));
+          if (r !== undefined) console.log(JSON.stringify(r, null, 2));
+        }),
+      })
+      .command({
+        command:  'resolve',
+        describe: 'Which workflow runs at a date/time?',
+        builder:  (y) => y
+          .option('trigger', { type: 'string', demandOption: true })
+          .option('channel', { type: 'string' })
+          .option('at',      { type: 'string', describe: 'ISO date-time (default now)' })
+          .option('tz',      { type: 'string', describe: 'IANA time zone' }),
+        handler:  runCommand(async (argv) => {
+          await requireFeature('enableAutomation', 'Workflows');
+          const r = await scheduleTolerant(() => messagingGet('/Workflows/schedule/resolve?' + qs({ trigger: argv.trigger, channel: argv.channel, at: argv.at, tz: argv.tz })));
+          if (r !== undefined) console.log(JSON.stringify(r, null, 2));
+        }),
+      })
+      .command({
+        command:  'timeline',
+        describe: 'Winner timeline, gaps and conflicts over a date range',
+        builder:  (y) => y
+          .option('trigger', { type: 'string', demandOption: true })
+          .option('channel', { type: 'string' })
+          .option('from',    { type: 'string' })
+          .option('to',      { type: 'string' }),
+        handler:  runCommand(async (argv) => {
+          await requireFeature('enableAutomation', 'Workflows');
+          const r = await scheduleTolerant(() => messagingGet('/Workflows/schedule/timeline?' + qs({ trigger: argv.trigger, channel: argv.channel, from: argv.from, to: argv.to })));
+          if (r !== undefined) console.log(JSON.stringify(r, null, 2));
+        }),
+      })
+      .command({
+        command:  'gaps',
+        describe: 'Upcoming gaps where no workflow will run',
+        handler:  runCommand(async () => {
+          await requireFeature('enableAutomation', 'Workflows');
+          const r = await scheduleTolerant(() => messagingGet('/Workflows/schedule/banner'));
+          if (r !== undefined) console.log(JSON.stringify(r, null, 2));
+        }),
+      })
+      .demandCommand(1, 'Specify: set, get, delete, validate, resolve, timeline, gaps'),
+  handler: () => {},
+};

package/lib/messaging-routes.test.js

@@ -9,7 +9,7 @@ import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 
 const dir = path.join(path.dirname(fileURLToPath(import.meta.url)), 'commands');
-const MESSAGING_ONLY = ['/Teams/List', '/Deployment', '/Users/List', '/Workflows/List', '/Rules', '/Ticket/knowledge-overrides', '/UserStatus/admin', '/api/ivr/config', '/WooCommerce/billing', '/WooCommerce/auth', '/diagnostics/test-magento', '/voice/admin', '/api/enterprise-reports', '/avatar/groups', '/avatar/workflows', '/avatar/group-overrides', '/Recruiting', '/superadmin/logs/insights', '/ApplePayConfig'];
+const MESSAGING_ONLY = ['/Teams/List', '/Deployment', '/Users/List', '/Workflows/List', '/Rules', '/Ticket/knowledge-overrides', '/UserStatus/admin', '/api/ivr/config', '/WooCommerce/billing', '/WooCommerce/auth', '/diagnostics/test-magento', '/voice/admin', '/api/enterprise-reports', '/avatar/groups', '/avatar/workflows', '/avatar/group-overrides', '/Recruiting', '/superadmin/logs/insights', '/ApplePayPresetOrders', '/ApplePayConfig'];
 
 test('messaging-only routes are never called through the admin api helpers', () => {
   const offenders = [];

package/package.json

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