@velaro/cli 1.4.84 → 1.4.86

package/bin/velaro.js

@@ -110,9 +110,15 @@ import { senderDomainHealthCommand } from '../lib/commands/sender-domain-health.
 import { contactsCommand }          from '../lib/commands/contacts.js';
 import { contactListCommand }       from '../lib/commands/contact-list.js';
 import { startUpdateCheck }  from '../lib/update-check.js';
-import { printBannerIfFirstRun } from '../lib/banner.js';
+import { printBanner, printBannerIfFirstRun } from '../lib/banner.js';
+import { createRequire } from 'module';
 
-printBannerIfFirstRun();
+// Banner on first run, and on the "front door" commands (bare `velaro`, help, login, update).
+// Never on data commands or --version: their output is parsed by scripts.
+const cliVersion = createRequire(import.meta.url)('../package.json').version;
+const firstArg = process.argv[2];
+const frontDoor = !firstArg || ['help', '--help', '-h', 'login', 'update'].includes(firstArg);
+if (!printBannerIfFirstRun() && frontDoor) printBanner({ version: cliVersion });
 
 const printUpdateNoticeIfStale = startUpdateCheck();
 

package/lib/banner.js

@@ -20,42 +20,52 @@ function configFileIsSafeToOverwrite() {
   }
 }
 
-// Pure ASCII (0-127) block-letter wordmark. Do not add box-drawing/unicode chars.
-const ART = [
-  " __      __  ______  __       ______   ______   ______  ",
-  "/\\ \\    /\\ \\/\\  ___\\/\\ \\     /\\  __ \\ /\\  == \\ /\\  __ \\ ",
-  "\\ \\ \\___\\ \\ \\ \\  __\\\\ \\ \\____\\ \\  __ \\\\ \\  __< \\ \\ \\/\\ \\",
-  " \\ \\_____\\ \\_\\ \\_____\\ \\_____\\\\ \\_\\ \\_\\\\ \\_\\ \\_\\\\ \\_____\\",
-  "  \\/_____/\\/_/\\/_____/\\/_____/ \\/_/\\/_/ \\/_/ /_/ \\/_____/",
-];
+// Pure ASCII (0-127) so it renders in every Windows/PowerShell codepage. Letters are composed from
+// per-letter rows so the wordmark can never misalign; each row gets its own gradient colour.
+const GLYPHS = {
+  V: ['__      __', '\\ \\    / /', ' \\ \\  / / ', '  \\ \\/ /  ', '   \\  /   ', '    \\/    '],
+  E: [' ______ ', '|  ____|', '| |__   ', '|  __|  ', '| |____ ', '|______|'],
+  L: [' _       ', '| |      ', '| |      ', '| |      ', '| |____  ', '|______| '],
+  A: ['          ', '    /\\    ', '   /  \\   ', '  / /\\ \\  ', ' / ____ \\ ', '/_/    \\_\\'],
+  R: [' _____   ', '|  __ \\  ', '| |__) | ', '|  _  /  ', '| | \\ \\  ', '|_|  \\_\\ '],
+  O: ['  ____   ', ' / __ \\  ', '| |  | | ', '| |  | | ', '| |__| | ', ' \\____/  '],
+};
+const WORD = 'VELARO';
+const ART = Array.from({ length: 6 }, (_, row) => WORD.split('').map((ch) => GLYPHS[ch][row]).join(' ').replace(/\s+$/, ''));
 
+// Brand gradient, top to bottom: Velaro blue -> cyan -> green (ANSI 256 colours).
+const GRADIENT = [27, 33, 39, 45, 49, 48];
 const TAGLINE = 'AI-native customer engagement -- command line';
 
-function colorize(line) {
-  // Velaro brand blue/cyan (ANSI 256 color 39), reset after.
-  return `\x1b[38;5;39m${line}\x1b[0m`;
+function colorize(line, row) {
+  return `\x1b[1;38;5;${GRADIENT[row % GRADIENT.length]}m${line}\x1b[0m`;
 }
 
-export function printBanner() {
-  // Non-TTY (piped/redirected output, e.g. `velaro ... | jq`) must stay
-  // completely silent on stdout — machine-readable command output (several
-  // commands emit JSON via console.log) must never be prefixed with banner
-  // text. Only decorate a real interactive terminal.
+/**
+ * Print the banner on an interactive terminal. Non-TTY (piped/redirected output, e.g.
+ * `velaro ... | jq`) stays completely silent on stdout - machine-readable output must never be
+ * prefixed with banner text.
+ */
+export function printBanner({ version } = {}) {
   if (!process.stdout.isTTY) return;
 
-  console.log('');
-  for (const line of ART) {
-    console.log(colorize(line));
-  }
-  console.log(colorize(`  ${TAGLINE}`));
-  console.log('');
+  const out = ['', ...ART.map((line, i) => colorize(line, i)),
+    `\x1b[38;5;245m  ${TAGLINE}${version ? `   v${version}` : ''}\x1b[0m`, ''];
+  console.log(out.join('\n'));
+}
+
+/** Banner as a plain string for postinstall, which writes straight to the terminal device. */
+export function bannerText(version) {
+  return ['', ...ART.map((line, i) => colorize(line, i)),
+    `\x1b[38;5;245m  ${TAGLINE}${version ? `   v${version}` : ''}\x1b[0m`,
+    '\x1b[38;5;39m  Installed. Run `velaro login` to get started, `velaro --help` for everything else.\x1b[0m', ''].join('\n');
 }
 
 export function printBannerIfFirstRun() {
   const cfg = readConfig();
 
   if (cfg && cfg._bannerShown === true) {
-    return;
+    return false;
   }
 
   printBanner();
@@ -73,4 +83,5 @@ export function printBannerIfFirstRun() {
       // Non-fatal — worst case the banner shows again next run.
     }
   }
+  return true;
 }

package/lib/banner.test.js

@@ -0,0 +1,24 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { bannerText } from './banner.js';
+
+const strip = (s) => s.replace(/\x1b\[[0-9;]*m/g, '');
+
+test('banner is pure ASCII and spells VELARO in six rows', () => {
+  const text = strip(bannerText('9.9.9'));
+  assert.ok(/^[\x00-\x7f]*$/.test(text), 'banner must stay ASCII so every Windows codepage renders it');
+  const art = text.split('\n').filter((l) => /[\\/|_]/.test(l)).slice(0, 6);
+  assert.equal(art.length, 6);
+  assert.ok(text.includes('v9.9.9'));
+});
+
+test('banner stays silent when stdout is not a TTY (piped output must be machine-readable)', async () => {
+  const { printBanner } = await import('./banner.js');
+  const lines = [];
+  const orig = console.log;
+  const tty = process.stdout.isTTY;
+  console.log = (...a) => lines.push(a.join(' '));
+  process.stdout.isTTY = false;
+  try { printBanner({ version: '1' }); } finally { console.log = orig; process.stdout.isTTY = tty; }
+  assert.deepEqual(lines, []);
+});

package/lib/commands/agent.js

@@ -1,4 +1,4 @@
-import { get, post, messagingPost, getCredentials }  from '../api.js';
+import { get, post, messagingGet, messagingPost, getCredentials }  from '../api.js';
 import { runCommand }  from '../run.js';
 
 const VALID_STATUSES = ['Available', 'Away', 'Offline'];
@@ -32,8 +32,8 @@ export const agentCommand = {
       describe: 'List agents and their current availability',
       handler:  runCommand(async () => {
         const [agents, teams] = await Promise.all([
-          get('/Users/List'),
-          get('/Teams/List'),
+          messagingGet('/Users/List'),
+          messagingGet('/Teams/List'),
         ]);
 
         const teamMap = Object.fromEntries(teams.map(t => [t.id, t.name]));
@@ -104,7 +104,7 @@ export const agentCommand = {
         .option('id',     { type: 'number', demandOption: true, describe: 'Agent user ID' })
         .option('status', { type: 'string', demandOption: true, describe: 'Available | Away | Offline', choices: VALID_STATUSES }),
       handler: runCommand(async (argv) => {
-        await post('/UserStatus/admin', { userId: argv.id, status: argv.status });
+        await messagingPost('/UserStatus/admin', { userId: argv.id, status: argv.status });
         console.log(`Agent ${argv.id} set to ${argv.status}.`);
       }),
     })

package/lib/commands/avatar.js

@@ -29,7 +29,9 @@ export const avatarCommand = {
         console.log(`  Voice ID:      ${data.voiceId || '(site default)'}`);
         console.log(`  Enabled:       ${data.enabled ? 'yes' : 'no'}`);
         console.log(`  "Call me":     ${data.showCallMeOption ? 'yes' : 'no'}`);
-        console.log(`  Callback window: ${data.callbackConfirmWindowMinutes} min\n`);
+        console.log(`  Callback window: ${data.callbackConfirmWindowMinutes} min`);
+        console.log(`  Max minutes/mo:   ${data.maxAvatarMinutesPerMonth ?? '(plan default)'}`);
+        console.log(`  Max TTS chars/mo: ${data.maxAvatarTtsChars ?? '(plan default)'}\n`);
       }),
     })
     .command({
@@ -71,5 +73,27 @@ export const avatarCommand = {
         console.log(`\n✓ AI Video Avatar disabled for site ${argv.site}\n`);
       }),
     })
-    .demandCommand(1, 'Specify a subcommand: get | enable | disable'),
+    .command({
+      command:  'set',
+      describe: "Set a site's monthly avatar caps (finite only, audited)",
+      builder:  y => y
+        .option('site',          { type: 'number', demandOption: true, describe: 'Site ID' })
+        .option('max-minutes',   { type: 'number', describe: 'Monthly avatar video minutes cap (whole number 1-100000)' })
+        .option('max-tts-chars', { type: 'number', describe: 'Monthly avatar TTS character cap (whole number 1-100000000)' }),
+      handler:  runCommand(async argv => {
+        const body = {};
+        for (const [opt, key, max] of [['max-minutes', 'maxAvatarMinutesPerMonth', 100000], ['max-tts-chars', 'maxAvatarTtsChars', 100000000]]) {
+          if (argv[opt] === undefined) continue;
+          if (!Number.isInteger(argv[opt]) || argv[opt] < 1 || argv[opt] > max) throw new Error(`--${opt} must be a whole number between 1 and ${max} (never unlimited)`);
+          body[key] = argv[opt];
+        }
+        if (!Object.keys(body).length) throw new Error('Provide --max-minutes and/or --max-tts-chars');
+        const data = await request('POST', `/Avatar/superadmin/config?siteId=${argv.site}`, body);
+        if (!data.success) throw new Error(data.error || 'Set avatar caps failed');
+        console.log(`\n✓ Avatar caps updated for site ${argv.site}`);
+        console.log(`  Max minutes/mo:   ${data.maxAvatarMinutesPerMonth}`);
+        console.log(`  Max TTS chars/mo: ${data.maxAvatarTtsChars}\n`);
+      }),
+    })
+    .demandCommand(1, 'Specify a subcommand: get | enable | disable | set'),
 };

package/lib/commands/check.js

@@ -21,7 +21,7 @@ export const checkCommand = {
   handler:  runCommand(async () => {
     const [sub, apiStatus] = await Promise.all([
       getSubscription().catch(() => null),
-      get('/Status').catch(() => null),
+      messagingGet('/api/health').catch(() => null),
     ]);
 
     if (!sub) {
@@ -37,13 +37,13 @@ export const checkCommand = {
     if (apiStatus) {
       ok(`API reachable`);
     } else {
-      warn('API did not respond to /Status');
+      warn('Messaging API did not respond to /api/health');
     }
 
     // ── Deployments ─────────────────────────────────────────────────────────
     console.log('\n── Deployments ───────────────────────────────────────────────');
     try {
-      const [deps, teams] = await Promise.all([get('/Deployment'), get('/Teams/List')]);
+      const [deps, teams] = await Promise.all([messagingGet('/Deployment'), messagingGet('/Teams/List')]);
       const teamMap = Object.fromEntries((teams ?? []).map(t => [t.id, t.name]));
       if (deps?.length) {
         for (const d of deps) {
@@ -75,7 +75,7 @@ export const checkCommand = {
       try {
         const [qna, overrides] = await Promise.all([
           messagingGet('/BotQnA').catch(() => []),
-          get('/Ticket/knowledge-overrides').catch(() => []),
+          messagingGet('/Ticket/knowledge-overrides').catch(() => []),
         ]);
         ok(`${qna?.length ?? 0} Q&A pair(s)  ·  ${overrides?.length ?? 0} override(s)`);
       } catch { warn('Could not load knowledge base'); }
@@ -87,7 +87,7 @@ export const checkCommand = {
     console.log('\n── Workflows ─────────────────────────────────────────────────');
     if (sub.enableAutomation) {
       try {
-        const workflows = (await get('/Workflows/List') ?? []).filter(w => !w.isTemplate);
+        const workflows = (await messagingGet('/Workflows/List') ?? []).filter(w => !w.isTemplate);
         const enabled   = workflows.filter(w => w.enabled).length;
         const disabled  = workflows.length - enabled;
         if (workflows.length) {
@@ -108,7 +108,7 @@ export const checkCommand = {
     console.log('\n── Routing Rules ─────────────────────────────────────────────');
     if (sub.enableWorkflowRules) {
       try {
-        const rules = await get('/Rules/List');
+        const rules = await messagingGet('/Rules/List');
         if (rules?.length) {
           ok(`${rules.length} routing rule(s) configured`);
         } else {
@@ -138,7 +138,7 @@ export const checkCommand = {
     // ── IVR detail ───────────────────────────────────────────────────────────
     if (sub.enableIvr) {
       try {
-        const ivr = await get('/api/ivr/config');
+        const ivr = await messagingGet('/api/ivr/config');
         if (ivr?.phoneNumber) {
           console.log(`\n── IVR Config ────────────────────────────────────────────────`);
           ok(`Phone: ${ivr.phoneNumber}`);
@@ -151,7 +151,7 @@ export const checkCommand = {
     // ── Agents ───────────────────────────────────────────────────────────────
     console.log('\n── Agents ────────────────────────────────────────────────────');
     try {
-      const agents = await get('/Users/List');
+      const agents = await messagingGet('/Users/List');
       const online  = (agents ?? []).filter(a => a.status === 'Available').length;
       const away    = (agents ?? []).filter(a => a.status === 'Away').length;
       const offline = (agents ?? []).length - online - away;

package/lib/commands/deployment.js

@@ -1,4 +1,4 @@
-import { get, post }  from '../api.js';
+import { messagingGet as get, messagingPost as post } from '../api.js';
 import { runCommand } from '../run.js';
 
 export const deploymentCommand = {

package/lib/commands/kb.js

@@ -294,7 +294,7 @@ const overrideCommand = {
         describe: 'List knowledge overrides',
         handler:  runCommand(async () => {
           await requireFeature('enableKnowledgeBase', 'Knowledge Base');
-          const items = await get('/Ticket/knowledge-overrides');
+          const items = await messagingGet('/Ticket/knowledge-overrides');
           if (!items?.length) { console.log('No overrides found.'); return; }
 
           console.log(`\nFound ${items.length} override(s):\n`);
@@ -317,7 +317,7 @@ const overrideCommand = {
           await requireFeature('enableKnowledgeBase', 'Knowledge Base');
           const payload = { title: argv.title, content: argv.content, isActive: true };
           if (argv.expires) payload.expiresAt = new Date(argv.expires).toISOString();
-          const result = await post('/Ticket/knowledge-overrides', payload);
+          const result = await messagingPost('/Ticket/knowledge-overrides', payload);
           console.log(`Override added: [${result.id}] "${argv.title}"`);
         }),
       })
@@ -327,7 +327,7 @@ const overrideCommand = {
         builder:  (y) => y.positional('id', { type: 'number', describe: 'Override ID' }),
         handler: runCommand(async (argv) => {
           await requireFeature('enableKnowledgeBase', 'Knowledge Base');
-          await del(`/Ticket/knowledge-overrides/${argv.id}`);
+          await messagingDel(`/Ticket/knowledge-overrides/${argv.id}`);
           console.log(`Override ${argv.id} deleted.`);
         }),
       })

package/lib/commands/magento.js

@@ -10,7 +10,7 @@
  *   velaro magento diagnose         Live connection diagnostic (token, /rest/V1, scopes)
  */
 
-import { request } from '../api.js';
+import { request, messagingRequest } from '../api.js';
 
 const GRN  = '\x1b[32m';
 const RED  = '\x1b[31m';
@@ -164,7 +164,7 @@ async function diagnoseHandler(argv) {
   }
   try {
     // Messaging DiagController: GET diagnostics/test-magento?siteId=<id>
-    const r = await request('GET', `/diagnostics/test-magento?siteId=${encodeURIComponent(siteId)}`);
+    const r = await messagingRequest('GET', `/diagnostics/test-magento?siteId=${encodeURIComponent(siteId)}`);
     console.log(`\n${BOLD}Magento diagnostic (site ${siteId})${RST}\n`);
     console.log(JSON.stringify(r, null, 2));
     console.log('');

package/lib/commands/rule.js

@@ -1,4 +1,4 @@
-import { get, post, del } from '../api.js';
+import { messagingGet as get, messagingPost as post, messagingDel as del } from '../api.js';
 import { requireFeature }  from '../subscription.js';
 import { runCommand }      from '../run.js';
 

package/lib/commands/site.js

@@ -32,7 +32,7 @@ export const siteCommand = {
   handler:  runCommand(async () => {
     const [sub, agents] = await Promise.all([
       messagingGet('/Subscription'),
-      get('/Users/List'),
+      messagingGet('/Users/List'),
     ]);
 
     // Active features — friendly names only, no internal flag names

package/lib/commands/team.js

@@ -1,4 +1,4 @@
-import { get, post }  from '../api.js';
+import { messagingGet as get, messagingPost as post } from '../api.js';
 import { runCommand } from '../run.js';
 
 export const teamCommand = {

package/lib/commands/woocommerce.js

@@ -10,7 +10,7 @@
  *   velaro woocommerce logs                View integration activity logs
  */
 
-import { request } from '../api.js';
+import { request, messagingRequest } from '../api.js';
 
 const GRN  = '\x1b[32m';
 const RED  = '\x1b[31m';
@@ -25,7 +25,7 @@ const RST  = '\x1b[0m';
 async function statusHandler(_argv) {
   // /WooCommerce/billing/status resolves site from the JWT — no siteId param needed.
   // Returns: billingStatus, planName, oauthConnected, hasActiveSubscription.
-  const r = await request('GET', `/WooCommerce/billing/status`);
+  const r = await messagingRequest('GET', `/WooCommerce/billing/status`);
   if (!r) {
     console.log('\nNo WooCommerce connection found for this site.\n');
     return;
@@ -49,7 +49,7 @@ async function connectHandler(argv) {
     return;
   }
   try {
-    const r = await request('GET', `/WooCommerce/auth/start?storeUrl=${encodeURIComponent(argv.storeUrl)}`);
+    const r = await messagingRequest('GET', `/WooCommerce/auth/start?storeUrl=${encodeURIComponent(argv.storeUrl)}`);
     if (!r?.authUrl) {
       console.error(`${RED}✗ Server did not return an authUrl — check that the store URL is correct${RST}`);
       process.exitCode = 1;
@@ -70,7 +70,7 @@ async function connectHandler(argv) {
 async function disconnectHandler(argv) {
   const params = argv.site ? `?siteId=${argv.site}` : '';
   try {
-    await request('POST', `/WooCommerce/auth/disconnect${params}`, {});
+    await messagingRequest('POST', `/WooCommerce/auth/disconnect${params}`, {});
     console.log(`\n${GRN}✓ WooCommerce store disconnected${RST}\n`);
   } catch (e) {
     console.error(`\n${RED}✗ Disconnect failed: ${e.message}${RST}\n`);
@@ -110,7 +110,7 @@ async function ordersHandler(argv) {
   }
   const q = argv.id ?? argv.email;
   const limit = Math.min(50, argv.limit ?? 10);
-  const orders = await request('GET', `/WooCommerce/data/orders/search?q=${encodeURIComponent(q)}&limit=${limit}`);
+  const orders = await messagingRequest('GET', `/WooCommerce/data/orders?email=${encodeURIComponent(q)}&limit=${limit}`);
   if (!Array.isArray(orders) || orders.length === 0) {
     console.log(`\nNo orders found for "${q}".\n`);
     return;
@@ -135,7 +135,7 @@ async function productsHandler(argv) {
     return;
   }
   const limit = Math.min(50, argv.limit ?? 10);
-  const products = await request('GET', `/WooCommerce/data/products?search=${encodeURIComponent(argv.query)}&limit=${limit}`);
+  const products = await messagingRequest('GET', `/WooCommerce/data/products?query=${encodeURIComponent(argv.query)}&limit=${limit}`);
   if (!Array.isArray(products) || products.length === 0) {
     console.log(`\nNo products found for "${argv.query}".\n`);
     return;

package/lib/messaging-routes.test.js

@@ -0,0 +1,28 @@
+// Regression (2026-10-11): `velaro team list` / `deployment list` / `rule list` / `agent list` etc.
+// 404'd on every environment because they called the ADMIN api for routes that only exist on the
+// MESSAGING api. Admin has no controller for these prefixes; any command using admin get/post/del
+// (or request()) for one of them is broken.
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import fs from 'node:fs';
+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'];
+
+test('messaging-only routes are never called through the admin api helpers', () => {
+  const offenders = [];
+  for (const f of fs.readdirSync(dir).filter(n => n.endsWith('.js'))) {
+    const src = fs.readFileSync(path.join(dir, f), 'utf8');
+    // `get`/`post`/`del` imported unaliased from api.js are the ADMIN helpers.
+    const imp = /import\s*\{([^}]*)\}\s*from\s*'\.\.\/api\.js'/.exec(src);
+    const specifiers = imp ? imp[1].split(',').map(s => s.trim()) : [];
+    const importsAdminHelpers = specifiers.some(s => ['get', 'post', 'del'].includes(s));
+    for (const route of MESSAGING_ONLY) {
+      const admin = new RegExp(String.raw`(?<![A-Za-z])(${importsAdminHelpers ? 'get|post|del|' : ''}request\('(?:GET|POST|PUT|DELETE)',)\s*\(?\s*['"\`]${route.replace(/[/.]/g, '\\$&')}`);
+      if (admin.test(src)) offenders.push(`${f}: ${route}`);
+    }
+  }
+  assert.deepEqual(offenders, [], `messaging-only routes called via the admin api:\n${offenders.join('\n')}`);
+});

package/lib/update-check.js

@@ -6,6 +6,9 @@
 
 import { readConfig, writeConfig } from './config.js';
 import { createRequire }           from 'module';
+import { spawn }                   from 'child_process';
+import { realpathSync }            from 'fs';
+import { fileURLToPath }          from 'url';
 
 const require = createRequire(import.meta.url);
 const { version: currentVersion } = require('../package.json');
@@ -43,16 +46,41 @@ export function startUpdateCheck() {
   };
 }
 
+// A registry install lives under node_modules; a dev checkout (npm link) resolves to the repo.
+export function isRegistryInstall() {
+  try {
+    return /[\\/]node_modules[\\/]@velaro[\\/]cli[\\/]/.test(realpathSync(fileURLToPath(import.meta.url)));
+  } catch {
+    return false;
+  }
+}
+
 function printNoticeIfStale(latest) {
   if (!latest || latest === currentVersion) return;
   if (!isNewer(latest, currentVersion)) return;
 
+  // Keep registry installs current automatically (opt out: VELARO_NO_AUTO_UPDATE=1). Detached and
+  // silent so it never slows or breaks the command that just ran; the next run is the new version.
+  if (isRegistryInstall() && !process.env.VELARO_NO_AUTO_UPDATE && !process.env.CI) {
+    try {
+      const child = spawn(process.platform === 'win32' ? 'npm.cmd' : 'npm', ['install', '-g', '@velaro/cli@latest'],
+        { detached: true, stdio: 'ignore', shell: process.platform === 'win32' });
+      child.on('error', () => {});
+      child.unref();
+      process.stderr.write(`\n  Velaro CLI ${currentVersion} → ${latest}: updating in the background (VELARO_NO_AUTO_UPDATE=1 to disable).\n\n`);
+      return;
+    } catch {
+      // fall through to the manual notice
+    }
+  }
+
   process.stderr.write(
     `\n  Update available: ${currentVersion} → ${latest}\n` +
-    `  Run: npm install -g @velaro/cli@latest\n\n`
+    (isRegistryInstall()
+      ? `  Run: npm install -g @velaro/cli@latest\n\n`
+      : `  This is a dev checkout (npm link): git pull in velaro-admin/cli, or switch to the registry install: npm install -g @velaro/cli@latest\n\n`)
   );
 }
-
 function isNewer(a, b) {
   const pa = a.split('.').map(Number);
   const pb = b.split('.').map(Number);

package/package.json

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

package/scripts/postinstall.js

@@ -1,12 +1,25 @@
-// Best-effort banner on install. Must NEVER throw — a postinstall failure
-// can fail the entire `npm install` for the end user.
+// Best-effort banner on install/upgrade. Must NEVER throw - a postinstall failure can fail the
+// whole `npm install`. npm hides a lifecycle script's stdout, so write straight to the terminal
+// device (the same trick other CLIs use) and fall back to stderr.
+import { openSync, writeSync, closeSync } from 'node:fs';
+import { createRequire } from 'node:module';
+
 try {
-  const { printBannerIfFirstRun } = await import('../lib/banner.js');
-  printBannerIfFirstRun();
+  const { bannerText } = await import('../lib/banner.js');
+  const { version } = createRequire(import.meta.url)('../package.json');
+  const text = bannerText(version) + '\n';
+  let wrote = false;
+  try {
+    const fd = openSync(process.platform === 'win32' ? '\\\\.\\CON' : '/dev/tty', 'w');
+    try { writeSync(fd, text); wrote = true; } finally { closeSync(fd); }
+  } catch {
+    // no controlling terminal (CI, piped install) - fall through
+  }
+  if (!wrote && !process.env.CI) process.stderr.write(text);
 } catch (err) {
   try {
     process.stderr.write(`[velaro] postinstall banner skipped: ${err && err.message ? err.message : err}\n`);
   } catch {
-    // swallow — nothing more we can do
+    // swallow - nothing more we can do
   }
 }