@velaro/cli 1.2.0 → 1.4.8

package/lib/commands/kb.js

@@ -1,309 +1,450 @@
-import { readFileSync }    from 'fs';
-import { basename }        from 'path';
-import { get, post, del }  from '../api.js';
-import { requireFeature }  from '../subscription.js';
-import { runCommand }      from '../run.js';
-import { articleCommand }  from './article.js';
-
-export const kbCommand = {
-  command:  'kb <subcommand>',
-  describe: 'Manage knowledge base — articles, Q&A pairs, bot overrides, and custom content',
-  builder:  (yargs) =>
-    yargs
-      .command(articleCommand)
-      .command(qnaCommand)
-      .command(overrideCommand)
-      .command(contentCommand)
-      .command(reindexCommand)
-      .demandCommand(1, 'Specify a subcommand: article, qna, override, content, reindex'),
-  handler: () => {},
-};
-
-// ────────────────────────────────────────────────────────────────────────────
-// Reindex — re-embed all KB articles with the current embedding model
-// ────────────────────────────────────────────────────────────────────────────
-
-const reindexCommand = {
-  command:  'reindex',
-  describe: 'Re-embed KB articles or scraper/ingestion content (use after embedding model upgrade)',
-  builder:  (y) =>
-    y
-      .option('all', {
-        type:     'boolean',
-        describe: 'Reindex ALL sites (Velaro staff only)',
-        default:  false,
-      })
-      .option('site', {
-        type:     'number',
-        describe: 'Reindex a specific site by ID (Velaro staff only)',
-      })
-      .option('ingestion', {
-        type:     'boolean',
-        describe: 'Reindex scraper/ingestion Azure Search indexers instead of KB articles',
-        default:  false,
-      }),
-  handler: runCommand(async (argv) => {
-    if (argv.ingestion) {
-      if (argv.all) {
-        console.log('Starting bulk ingestion reindex for all sites — runs in background.');
-        console.log('Watch server logs ([ReindexAllIngestion]) for progress.\n');
-        const result = await post('/DatabaseTool/ReindexAllIngestionIndexes', {});
-        console.log(result.message ?? 'Queued.');
-      } else if (argv.site) {
-        console.log(`Reindexing scraper/ingestion index for site ${argv.site}…`);
-        const result = await post(`/DatabaseTool/ReindexIngestionIndex/${argv.site}`, {});
-        if (result.success) {
-          console.log(`✅ Triggered ${result.indexersRun} indexer(s) — re-processing in background.`);
-        } else {
-          console.error(`❌ Failed: ${result.message}`);
-        }
-      } else {
-        console.error('--ingestion requires --site <id> or --all (Velaro staff only)');
-        process.exit(1);
-      }
-    } else if (argv.all) {
-      console.log('Starting bulk KB reindex for all sites — this runs in the background.');
-      console.log('Watch server logs ([ReindexAllKb]) for progress.\n');
-      const result = await post('/DatabaseTool/ReindexAllKb', {});
-      console.log(result.message ?? 'Queued.');
-    } else if (argv.site) {
-      console.log(`Reindexing KB articles for site ${argv.site}…`);
-      const result = await post(`/DatabaseTool/ReindexKb/${argv.site}`, {});
-      if (result.success) {
-        console.log(`✅ Done — ${result.articles} articles reindexed.`);
-      } else {
-        console.error(`❌ Failed: ${result.message}`);
-      }
-    } else {
-      console.log("Reindexing your site's KB articles\u2026");
-      const result = await post('/KBSearchIndex/reindex', {});
-      if (result.success === false) {
-        console.error(`❌ Failed: ${result.message}`);
-      } else {
-        console.log(`✅ Done — ${result.articles ?? result.count ?? 'all'} articles reindexed.`);
-      }
-    }
-  }),
-};
-
-// ────────────────────────────────────────────────────────────────────────────
-// Q&A
-// ────────────────────────────────────────────────────────────────────────────
-
-const qnaCommand = {
-  command:  'qna <subcommand>',
-  describe: 'Manage Q&A knowledge pairs',
-  builder:  (yargs) =>
-    yargs
-      .command({
-        command:  'list',
-        describe: 'List Q&A pairs',
-        builder:  (y) => y.option('bot-id', { type: 'number', describe: 'Filter by bot ID' }),
-        handler:  runCommand(async (argv) => {
-          await requireFeature('enableKnowledgeBase', 'Knowledge Base');
-          const params = argv['bot-id'] ? `?aiConfigurationId=${argv['bot-id']}` : '';
-          const items  = await get(`/api/BotQnA${params}`);
-          if (!items?.length) { console.log('No Q&A pairs found.'); return; }
-
-          console.log(`\nFound ${items.length} Q&A pair(s):\n`);
-          for (const item of items) {
-            console.log(`  [${item.id}] Q: ${truncate(item.question, 70)}`);
-            console.log(`       A: ${truncate(item.answer, 70)}\n`);
-          }
-        }),
-      })
-      .command({
-        command:  'add',
-        describe: 'Add a Q&A pair',
-        builder:  (y) =>
-          y
-            .option('bot-id',   { type: 'number', demandOption: true, describe: 'Bot ID' })
-            .option('question', { type: 'string', demandOption: true, describe: 'Question text' })
-            .option('answer',   { type: 'string', demandOption: true, describe: 'Answer text' }),
-        handler: runCommand(async (argv) => {
-          await requireFeature('enableKnowledgeBase', 'Knowledge Base');
-          const result = await post('/api/BotQnA', {
-            aiConfigurationId: argv['bot-id'],
-            question:          argv.question,
-            answer:            argv.answer,
-          });
-          console.log(`Q&A pair added: [${result.id}]`);
-        }),
-      })
-      .command({
-        command:  'delete <id>',
-        describe: 'Delete a Q&A pair',
-        builder:  (y) => y.positional('id', { type: 'number', describe: 'Q&A pair ID' }),
-        handler: runCommand(async (argv) => {
-          await requireFeature('enableKnowledgeBase', 'Knowledge Base');
-          await del(`/api/BotQnA/${argv.id}`);
-          console.log(`Q&A pair ${argv.id} deleted.`);
-        }),
-      })
-      .demandCommand(1, 'Specify a subcommand: list, add, delete'),
-  handler: () => {},
-};
-
-// ────────────────────────────────────────────────────────────────────────────
-// Overrides — authoritative facts that take priority over KB search
-// ────────────────────────────────────────────────────────────────────────────
-
-const overrideCommand = {
-  command:  'override <subcommand>',
-  describe: 'Manage bot knowledge overrides (authoritative facts)',
-  builder:  (yargs) =>
-    yargs
-      .command({
-        command:  'list',
-        describe: 'List knowledge overrides',
-        handler:  runCommand(async () => {
-          await requireFeature('enableKnowledgeBase', 'Knowledge Base');
-          const items = await get('/Ticket/knowledge-overrides');
-          if (!items?.length) { console.log('No overrides found.'); return; }
-
-          console.log(`\nFound ${items.length} override(s):\n`);
-          for (const item of items) {
-            const status = item.isActive ? 'active  ' : 'inactive';
-            const expiry = item.expiresAt ? `  expires ${new Date(item.expiresAt).toLocaleDateString()}` : '';
-            console.log(`  [${item.id}] ${status}  ${truncate(item.title ?? item.content, 60)}${expiry}`);
-          }
-        }),
-      })
-      .command({
-        command:  'add',
-        describe: 'Add a knowledge override',
-        builder:  (y) =>
-          y
-            .option('title',   { type: 'string', demandOption: true, describe: 'Override title' })
-            .option('content', { type: 'string', demandOption: true, describe: 'Authoritative content' })
-            .option('expires', { type: 'string',                     describe: 'Expiry date (ISO 8601, e.g. 2026-12-31)' }),
-        handler: runCommand(async (argv) => {
-          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);
-          console.log(`Override added: [${result.id}] "${argv.title}"`);
-        }),
-      })
-      .command({
-        command:  'delete <id>',
-        describe: 'Delete a knowledge override',
-        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}`);
-          console.log(`Override ${argv.id} deleted.`);
-        }),
-      })
-      .demandCommand(1, 'Specify a subcommand: list, add, delete'),
-  handler: () => {},
-};
-
-// ────────────────────────────────────────────────────────────────────────────
-// Custom content — push arbitrary text/files into the site's KB index
-// ────────────────────────────────────────────────────────────────────────────
-// Note: content goes into the site's default index (determined server-side by
-// SiteId). Index selection is not yet supported by this API endpoint.
-
-const contentCommand = {
-  command:  'content <subcommand>',
-  describe: 'Push custom text or files into the knowledge base index',
-  builder:  (yargs) =>
-    yargs
-      .command({
-        command:  'ingest',
-        describe: 'Push a file or text snippet into the KB index',
-        builder:  (y) =>
-          y
-            .option('file', {
-              describe: 'Path to a .txt or .md file to ingest',
-              type:     'string',
-            })
-            .option('text', {
-              describe: 'Inline text content to ingest (alternative to --file)',
-              type:     'string',
-            })
-            .option('content-id', {
-              describe: 'Stable ID for this document (used for dedup/updates). Defaults to filename.',
-              type:     'string',
-            })
-            .option('title', {
-              describe: 'Document title shown when bot attributes this content. Defaults to filename.',
-              type:     'string',
-            })
-            .option('source-url', {
-              describe: 'Canonical URL to show when bot cites this content',
-              type:     'string',
-            })
-            .check((argv) => {
-              if (!argv.file && !argv.text) throw new Error('Provide either --file or --text');
-              if (argv.file && argv.text)   throw new Error('Use --file or --text, not both');
-              return true;
-            }),
-        handler: runCommand(async (argv) => {
-          await requireFeature('enableKnowledgeBase', 'Knowledge Base');
-
-          let text, defaultId, defaultTitle;
-          if (argv.file) {
-            text         = readFileSync(argv.file, 'utf8');
-            defaultId    = basename(argv.file);
-            defaultTitle = basename(argv.file);
-          } else {
-            text         = argv.text;
-            defaultId    = `inline-${Date.now()}`;
-            defaultTitle = defaultId;
-          }
-
-          const contentId = argv['content-id'] || defaultId;
-          const title     = argv.title          || defaultTitle;
-
-          const result = await post('/AzureIndexes/IngestContent', {
-            contentId,
-            title,
-            text,
-            sourceUrl: argv['source-url'] || undefined,
-          });
-
-          if (result.unchanged) {
-            console.log(`Unchanged: "${title}" — content hash matches, no re-embedding needed.`);
-          } else {
-            console.log(`Indexed:   "${title}"  [${contentId}]`);
-            console.log(`           ${result.chunks} chunk(s) embedded and searchable immediately.`);
-          }
-        }),
-      })
-      .command({
-        command:  'list',
-        describe: 'List all custom content documents in the KB index',
-        handler:  runCommand(async () => {
-          await requireFeature('enableKnowledgeBase', 'Knowledge Base');
-          const items = await get('/AzureIndexes/IngestContent');
-          if (!items?.length) { console.log('No custom content found.'); return; }
-
-          console.log(`\nFound ${items.length} document(s):\n`);
-          for (const item of items) {
-            const indexed = item.lastIndexedAt ? new Date(item.lastIndexedAt).toLocaleDateString() : 'never';
-            const status  = item.lastError ? `  error: ${item.lastError}` : '';
-            console.log(`  [${item.contentId}]  chunks=${item.chunkCount ?? '?'}  indexed=${indexed}${status}`);
-            if (item.title && item.title !== item.contentId) console.log(`    "${item.title}"`);
-          }
-        }),
-      })
-      .command({
-        command:  'remove <content-id>',
-        describe: 'Remove a custom content document from the KB index',
-        builder:  (y) => y.positional('content-id', { type: 'string', describe: 'Content ID to remove' }),
-        handler:  runCommand(async (argv) => {
-          await requireFeature('enableKnowledgeBase', 'Knowledge Base');
-          await del(`/AzureIndexes/IngestContent/${encodeURIComponent(argv['content-id'])}`);
-          console.log(`Removed "${argv['content-id']}" from the index.`);
-        }),
-      })
-      .demandCommand(1, 'Specify a subcommand: ingest, list, remove'),
-  handler: () => {},
-};
-
-function truncate(str, max) {
-  if (!str) return '—';
-  return str.length <= max ? str : str.slice(0, max - 1) + '…';
-}
+import { readFileSync }    from 'fs';
+import { basename }        from 'path';
+import { get, post, del, messagingGet, messagingPost, messagingDel }  from '../api.js';
+import { requireFeature }  from '../subscription.js';
+import { runCommand }      from '../run.js';
+import { articleCommand }  from './article.js';
+
+export const kbCommand = {
+  command:  'kb <subcommand>',
+  describe: 'Manage knowledge base — articles, Q&A pairs, bot overrides, and custom content',
+  builder:  (yargs) =>
+    yargs
+      .command(articleCommand)
+      .command(qnaCommand)
+      .command(overrideCommand)
+      .command(contentCommand)
+      .command(reindexCommand)
+      .command(settingsCommand)
+      .command(statusCommand)
+      .command(swapConnectionCommand)
+      .command(tenantCommand)
+      .demandCommand(1, 'Specify a subcommand: article, qna, override, content, reindex, settings, status, swap-connection, tenant'),
+  handler: () => {},
+};
+
+// ────────────────────────────────────────────────────────────────────────────
+// Tenant — the KB tenant linked to the current site (one per site, created once).
+// Built 2026-08-25 after a KB tenant-creation 500 on staging had to be diagnosed
+// entirely via ad-hoc curl + browser — there was no CLI way to even check whether
+// a site already has a linked tenant before calling `kb tenant create`.
+// ────────────────────────────────────────────────────────────────────────────
+
+const tenantCommand = {
+  command:  'tenant <subcommand>',
+  describe: 'Manage the KB tenant linked to the current site (one per site)',
+  builder:  (yargs) =>
+    yargs
+      .command({
+        command:  'current',
+        describe: 'Show the KB tenant linked to the current site, if any',
+        handler:  runCommand(async () => {
+          const t = await get('/api/kb/tenants/current');
+          console.log(JSON.stringify(t, null, 2));
+        }),
+      })
+      .command({
+        command:  'create',
+        describe: 'Create a new KB tenant for the current site (fails with a clear error if one already exists)',
+        builder:  (y) =>
+          y.option('company-name', { type: 'string', demandOption: true, describe: 'Company name shown as the KB title' }),
+        handler: runCommand(async (argv) => {
+          const result = await post('/api/kb/tenants', { companyName: argv['company-name'] });
+          console.log(JSON.stringify(result, null, 2));
+        }),
+      })
+      .command({
+        command:  'unlink',
+        describe: 'Unlink the current site from its KB tenant WITHOUT deleting any data (company name, subdomain, articles, topics all preserved) — use before `kb tenant create` when the linked tenant is stale/missing from the connected KB database. Reversible via a Velaro-admin relink.',
+        handler: runCommand(async () => {
+          const result = await del('/api/kb/tenants/unlink');
+          console.log(JSON.stringify(result, null, 2));
+        }),
+      })
+      .demandCommand(1, 'Specify: current, create, or unlink'),
+  handler: () => {},
+};
+
+// ────────────────────────────────────────────────────────────────────────────
+// Reindex — re-embed all KB articles with the current embedding model
+// ────────────────────────────────────────────────────────────────────────────
+
+const reindexCommand = {
+  command:  'reindex',
+  describe: 'Re-embed KB articles or scraper/ingestion content (use after embedding model upgrade)',
+  builder:  (y) =>
+    y
+      .option('all', {
+        type:     'boolean',
+        describe: 'Reindex ALL sites (Velaro staff only)',
+        default:  false,
+      })
+      .option('site', {
+        type:     'number',
+        describe: 'Reindex a specific site by ID (Velaro staff only)',
+      })
+      .option('ingestion', {
+        type:     'boolean',
+        describe: 'Reindex scraper/ingestion Azure Search indexers instead of KB articles',
+        default:  false,
+      }),
+  handler: runCommand(async (argv) => {
+    if (argv.ingestion) {
+      if (argv.all) {
+        console.log('Starting bulk ingestion reindex for all sites — runs in background.');
+        console.log('Watch server logs ([ReindexAllIngestion]) for progress.\n');
+        const result = await post('/DatabaseTool/ReindexAllIngestionIndexes', {});
+        console.log(result.message ?? 'Queued.');
+      } else if (argv.site) {
+        console.log(`Reindexing scraper/ingestion index for site ${argv.site}…`);
+        const result = await post(`/DatabaseTool/ReindexIngestionIndex/${argv.site}`, {});
+        if (result.success) {
+          console.log(`✅ Triggered ${result.indexersRun} indexer(s) — re-processing in background.`);
+        } else {
+          console.error(`❌ Failed: ${result.message}`);
+        }
+      } else {
+        console.error('--ingestion requires --site <id> or --all (Velaro staff only)');
+        process.exit(1);
+      }
+    } else if (argv.all) {
+      console.log('Starting bulk KB reindex for all sites — this runs in the background.');
+      console.log('Watch server logs ([ReindexAllKb]) for progress.\n');
+      const result = await post('/DatabaseTool/ReindexAllKb', {});
+      console.log(result.message ?? 'Queued.');
+    } else if (argv.site) {
+      console.log(`Reindexing KB articles for site ${argv.site}…`);
+      const result = await messagingPost(`/Scraper/superadmin/kb/reindex/${argv.site}`, {});
+      if (result?.queued) {
+        console.log(`✅ Queued — full re-ingest running in background for site ${argv.site}.`);
+      } else {
+        console.error(`❌ Failed: ${result?.error ?? 'unknown error'}`);
+      }
+    } else {
+      console.log("Reindexing your site's KB articles\u2026");
+      const result = await post('/KBSearchIndex/reindex', {});
+      if (result.success === false) {
+        console.error(`❌ Failed: ${result.message}`);
+      } else {
+        console.log(`✅ Done — ${result.articles ?? result.count ?? 'all'} articles reindexed.`);
+      }
+    }
+  }),
+};
+
+// ────────────────────────────────────────────────────────────────────────────
+// Status — which physical DB this environment's KB is actually connected to
+// ────────────────────────────────────────────────────────────────────────────
+
+const statusCommand = {
+  command:  'status',
+  describe: 'Show KB connection diagnostics: which server/database this environment is actually using (KBConnectionHolder can point at either the primary or alternate DB — this shows which one is live right now)',
+  handler:  runCommand(async () => {
+    const s = await get('/api/kb/status');
+    console.log(JSON.stringify(s, null, 2));
+  }),
+};
+
+const swapConnectionCommand = {
+  command:  'swap-connection',
+  describe: 'Toggle which physical database this environment\'s KB is connected to (primary vs. alternate, per KBConnectionHolder). Built 2026-08-18 after staging was found silently connected to PRODUCTION\'s KB database (KnowledgeBaseConnectionString, not _Staging) with no CLI/API way to check or fix it except a raw REST call.',
+  builder:  (y) =>
+    y
+      .option('use-alternate', { type: 'boolean', demandOption: true, describe: 'true = use the alternate (KnowledgeBaseConnectionString_Staging) DB; false = use primary' })
+      .option('yes', { type: 'boolean', default: false, describe: 'Skip the confirmation prompt (for scripting)' }),
+  handler: runCommand(async (argv) => {
+    const before = await get('/api/kb/status');
+    console.log(`Currently connected to: ${before.server} / ${before.database} (alternate: ${before.isAlternate})`);
+
+    if (!argv.yes) {
+      console.log(`\nAbout to switch to ${argv['use-alternate'] ? 'ALTERNATE' : 'PRIMARY'}. Re-run with --yes to confirm.`);
+      return;
+    }
+
+    const result = await post('/DatabaseTool/KBSwapConnection', { useAlternate: argv['use-alternate'] });
+    console.log(`✅ Switched. Now connected to: ${result.current.server} / ${result.current.database} (alternate: ${result.current.isAlternate})`);
+  }),
+};
+
+// ────────────────────────────────────────────────────────────────────────────
+// Settings — branding, domain, layout, SEO/analytics
+// ────────────────────────────────────────────────────────────────────────────
+
+const settingsCommand = {
+  command:  'settings <subcommand>',
+  describe: 'View or update Knowledge Base settings (branding, domain, layout, SEO/analytics)',
+  builder:  (yargs) =>
+    yargs
+      .command({
+        command:  'get',
+        describe: 'Show current KB settings',
+        handler:  runCommand(async () => {
+          const s = await get('/api/kb/settings');
+          console.log(JSON.stringify(s, null, 2));
+        }),
+      })
+      .command({
+        command:  'set',
+        describe: 'Update KB settings. Fetches current settings first and merges — unspecified flags keep their current value.',
+        builder:  (y) =>
+          y
+            .option('theme-color',   { type: 'string', describe: 'Hex color, e.g. "#4c75ab"' })
+            .option('theme-preset',  { type: 'string', describe: 'Curated preset id (informational only — theme-color is what renders)' })
+            .option('header-text',   { type: 'string' })
+            .option('domain',        { type: 'string', describe: 'Custom domain, e.g. help.acme.com. Pass "" to clear.' })
+            .option('topic-layout',  { type: 'string', choices: ['grid', 'list'] })
+            .option('article-layout', { type: 'string', choices: ['table', 'cards'] })
+            .option('meta-description', { type: 'string', describe: 'Default SEO meta description (max 300 chars)' })
+            .option('ga4-id', { type: 'string', describe: 'Google Analytics 4 Measurement ID, format G-XXXXXXXXXX' }),
+        handler: runCommand(async (argv) => {
+          const current = await get('/api/kb/settings');
+          const merged = {
+            companyName:        current.companyName ?? '',
+            themeColor:         argv['theme-color']    ?? current.themeColor    ?? '',
+            themePreset:        argv['theme-preset']   ?? current.themePreset   ?? null,
+            headerText:         argv['header-text']    ?? current.headerText    ?? '',
+            returnLinkText:     current.returnLinkText  ?? '',
+            returnLinkUrl:      current.returnLinkUrl   ?? '',
+            logoUrl:            current.logoUrl         ?? '',
+            domain:             argv.domain             ?? current.domain       ?? '',
+            topicLayout:        argv['topic-layout']   ?? current.topicLayout   ?? 'grid',
+            articleLayout:      argv['article-layout'] ?? current.articleLayout ?? 'table',
+            showLastUpdated:    current.showLastUpdated ?? true,
+            enableLiveChat:     current.enableLiveChat  ?? false,
+            liveChatGroupId:    current.liveChatGroupId ?? 0,
+            enableKbBot:        current.enableKbBot     ?? false,
+            kbChatWindowId:     current.kbChatWindowId  ?? 0,
+            seoMetaDescription: argv['meta-description'] ?? current.seoMetaDescription ?? '',
+            ga4MeasurementId:   argv['ga4-id']            ?? current.ga4MeasurementId   ?? '',
+          };
+          await post('/api/kb/settings', merged);
+          console.log('✅ KB settings updated.');
+        }),
+      })
+      .demandCommand(1, 'Specify: get or set'),
+  handler: () => {},
+};
+
+// ────────────────────────────────────────────────────────────────────────────
+// Q&A
+// ────────────────────────────────────────────────────────────────────────────
+
+const qnaCommand = {
+  command:  'qna <subcommand>',
+  describe: 'Manage Q&A knowledge pairs',
+  builder:  (yargs) =>
+    yargs
+      .command({
+        command:  'list',
+        describe: 'List Q&A pairs (site-wide -- BotQnA has no per-bot scoping)',
+        handler:  runCommand(async () => {
+          await requireFeature('enableKnowledgeBase', 'Knowledge Base');
+          const items = await messagingGet('/BotQnA');
+          if (!items?.length) { console.log('No Q&A pairs found.'); return; }
+
+          console.log(`\nFound ${items.length} Q&A pair(s):\n`);
+          for (const item of items) {
+            console.log(`  [${item.id}] Q: ${truncate(item.question, 70)}`);
+            console.log(`       A: ${truncate(item.answer, 70)}\n`);
+          }
+        }),
+      })
+      .command({
+        command:  'add',
+        describe: 'Add a Q&A pair',
+        builder:  (y) =>
+          y
+            .option('question', { type: 'string', demandOption: true, describe: 'Question text' })
+            .option('answer',   { type: 'string', demandOption: true, describe: 'Answer text' }),
+        handler: runCommand(async (argv) => {
+          await requireFeature('enableKnowledgeBase', 'Knowledge Base');
+          // BotQnAItem has no per-bot column -- pairs are site-wide, not scoped to one bot.
+          const result = await messagingPost('/BotQnA', {
+            question: argv.question,
+            answer:   argv.answer,
+          });
+          console.log(`Q&A pair added: [${result.id}]`);
+        }),
+      })
+      .command({
+        command:  'delete <id>',
+        describe: 'Delete a Q&A pair',
+        builder:  (y) => y.positional('id', { type: 'number', describe: 'Q&A pair ID' }),
+        handler: runCommand(async (argv) => {
+          await requireFeature('enableKnowledgeBase', 'Knowledge Base');
+          await messagingDel(`/BotQnA/${argv.id}`);
+          console.log(`Q&A pair ${argv.id} deleted.`);
+        }),
+      })
+      .demandCommand(1, 'Specify a subcommand: list, add, delete'),
+  handler: () => {},
+};
+
+// ────────────────────────────────────────────────────────────────────────────
+// Overrides — authoritative facts that take priority over KB search
+// ────────────────────────────────────────────────────────────────────────────
+
+const overrideCommand = {
+  command:  'override <subcommand>',
+  describe: 'Manage bot knowledge overrides (authoritative facts)',
+  builder:  (yargs) =>
+    yargs
+      .command({
+        command:  'list',
+        describe: 'List knowledge overrides',
+        handler:  runCommand(async () => {
+          await requireFeature('enableKnowledgeBase', 'Knowledge Base');
+          const items = await get('/Ticket/knowledge-overrides');
+          if (!items?.length) { console.log('No overrides found.'); return; }
+
+          console.log(`\nFound ${items.length} override(s):\n`);
+          for (const item of items) {
+            const status = item.isActive ? 'active  ' : 'inactive';
+            const expiry = item.expiresAt ? `  expires ${new Date(item.expiresAt).toLocaleDateString()}` : '';
+            console.log(`  [${item.id}] ${status}  ${truncate(item.title ?? item.content, 60)}${expiry}`);
+          }
+        }),
+      })
+      .command({
+        command:  'add',
+        describe: 'Add a knowledge override',
+        builder:  (y) =>
+          y
+            .option('title',   { type: 'string', demandOption: true, describe: 'Override title' })
+            .option('content', { type: 'string', demandOption: true, describe: 'Authoritative content' })
+            .option('expires', { type: 'string',                     describe: 'Expiry date (ISO 8601, e.g. 2026-12-31)' }),
+        handler: runCommand(async (argv) => {
+          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);
+          console.log(`Override added: [${result.id}] "${argv.title}"`);
+        }),
+      })
+      .command({
+        command:  'delete <id>',
+        describe: 'Delete a knowledge override',
+        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}`);
+          console.log(`Override ${argv.id} deleted.`);
+        }),
+      })
+      .demandCommand(1, 'Specify a subcommand: list, add, delete'),
+  handler: () => {},
+};
+
+// ────────────────────────────────────────────────────────────────────────────
+// Custom content — push arbitrary text/files into the site's KB index
+// ────────────────────────────────────────────────────────────────────────────
+// Use --index to target a specific logical index (e.g. "tri-tool").
+// Omit to push to the site's default index.
+
+const contentCommand = {
+  command:  'content <subcommand>',
+  describe: 'Push custom text or files into the knowledge base index',
+  builder:  (yargs) =>
+    yargs
+      .command({
+        command:  'ingest',
+        describe: 'Push a file or text snippet into the KB index',
+        builder:  (y) =>
+          y
+            .option('file', {
+              describe: 'Path to a .txt or .md file to ingest',
+              type:     'string',
+            })
+            .option('text', {
+              describe: 'Inline text content to ingest (alternative to --file)',
+              type:     'string',
+            })
+            .option('content-id', {
+              describe: 'Stable ID for this document (used for dedup/updates). Defaults to filename.',
+              type:     'string',
+            })
+            .option('title', {
+              describe: 'Document title shown when bot attributes this content. Defaults to filename.',
+              type:     'string',
+            })
+            .option('source-url', {
+              describe: 'Canonical URL to show when bot cites this content',
+              type:     'string',
+            })
+            .option('index', {
+              describe: 'Logical index name to push content into (e.g. "tri-tool"). Defaults to site primary index.',
+              type:     'string',
+            })
+            .check((argv) => {
+              if (!argv.file && !argv.text) throw new Error('Provide either --file or --text');
+              if (argv.file && argv.text)   throw new Error('Use --file or --text, not both');
+              return true;
+            }),
+        handler: runCommand(async (argv) => {
+          await requireFeature('enableKnowledgeBase', 'Knowledge Base');
+
+          let text, defaultId, defaultTitle;
+          if (argv.file) {
+            text         = readFileSync(argv.file, 'utf8');
+            defaultId    = basename(argv.file);
+            defaultTitle = basename(argv.file);
+          } else {
+            text         = argv.text;
+            defaultId    = `inline-${Date.now()}`;
+            defaultTitle = defaultId;
+          }
+
+          const contentId = argv['content-id'] || defaultId;
+          const title     = argv.title          || defaultTitle;
+
+          const result = await messagingPost('/AzureIndexes/IngestContent', {
+            contentId,
+            title,
+            text,
+            sourceUrl: argv['source-url'] || undefined,
+            indexName: argv.index || undefined,
+          });
+
+          if (result.unchanged) {
+            console.log(`Unchanged: "${title}" — content hash matches, no re-embedding needed.`);
+          } else {
+            console.log(`Indexed:   "${title}"  [${contentId}]`);
+            console.log(`           ${result.chunks} chunk(s) embedded and searchable immediately.`);
+          }
+        }),
+      })
+      .command({
+        command:  'list',
+        describe: 'List all custom content documents in the KB index',
+        handler:  runCommand(async () => {
+          await requireFeature('enableKnowledgeBase', 'Knowledge Base');
+          const items = await messagingGet('/AzureIndexes/IngestContent');
+          if (!items?.length) { console.log('No custom content found.'); return; }
+
+          console.log(`\nFound ${items.length} document(s):\n`);
+          for (const item of items) {
+            const indexed = item.lastIndexedAt ? new Date(item.lastIndexedAt).toLocaleDateString() : 'never';
+            const status  = item.lastError ? `  error: ${item.lastError}` : '';
+            console.log(`  [${item.contentId}]  chunks=${item.chunkCount ?? '?'}  indexed=${indexed}${status}`);
+            if (item.title && item.title !== item.contentId) console.log(`    "${item.title}"`);
+          }
+        }),
+      })
+      .command({
+        command:  'remove <content-id>',
+        describe: 'Remove a custom content document from the KB index',
+        builder:  (y) => y.positional('content-id', { type: 'string', describe: 'Content ID to remove' }),
+        handler:  runCommand(async (argv) => {
+          await requireFeature('enableKnowledgeBase', 'Knowledge Base');
+          await messagingDel(`/AzureIndexes/IngestContent/${encodeURIComponent(argv['content-id'])}`);
+          console.log(`Removed "${argv['content-id']}" from the index.`);
+        }),
+      })
+      .demandCommand(1, 'Specify a subcommand: ingest, list, remove'),
+  handler: () => {},
+};
+
+function truncate(str, max) {
+  if (!str) return '—';
+  return str.length <= max ? str : str.slice(0, max - 1) + '…';
+}