@velaro/mcp-server 2.0.1 → 2.0.3

package/fetch-retry.js

@@ -0,0 +1,23 @@
+// 429-aware fetch for the customer MCP (mcp/server.js). Same behavior as fetchRetry429 in
+// mcp/log-search.js, which is staff-only and not published (log-search.js must stay byte-identical
+// with cli/lib/log-search.js, so this small helper is a separate file rather than an import of it).
+
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+
+/**
+ * fetch that retries ONLY 429 (honouring Retry-After, seconds, capped at 30 s) for up to `retries` attempts and returns the final Response.
+ * `init` may be a function so each attempt gets a fresh AbortSignal.
+ */
+export async function fetchRetry429(url, init = {}, { retries = 3, fetchImpl = fetch, sleepImpl = sleep } = {}) {
+  for (let attempt = 0; ; attempt++) {
+    const res = await fetchImpl(url, typeof init === 'function' ? init() : init);
+    if (res.status === 429 && attempt < retries) {
+      // Number(null) is 0, which would turn a 429 without Retry-After into an immediate retry: a missing header means the 5 s default.
+      const raw = res.headers?.get?.('retry-after');
+      const ra = raw == null || raw === '' ? NaN : Number(raw);
+      await sleepImpl(Math.min(Number.isFinite(ra) && ra >= 0 ? ra : 5, 30) * 1000);
+      continue;
+    }
+    return res;
+  }
+}

package/messaging-base.js

@@ -1,7 +1,7 @@
 // Resolves the velaro-messaging API base for the MCP server.
 //
 // Incident 2026-10-23: the staging MCP was configured with VELARO_ADMIN_API only. Every tool that
-// lives in velaro-messaging (magento_diagnose, salesforce_diagnose, sap_diagnose, ...) either threw
+// lives in velaro-messaging (the integration diagnose tools, ...) either threw
 // "VELARO_MESSAGING_API is not configured" or, on older installs, called the ADMIN host and got a
 // bare 404 for /diagnostics/test-magento. The messaging base is fully determined by which admin
 // environment this process talks to, so derive it instead of requiring a second env var.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@velaro/mcp-server",
-  "version": "2.0.1",
+  "version": "2.0.3",
   "description": "Velaro MCP server — connect Claude and other AI agents directly to your Velaro account: KB, workflows, bots, conversations, contacts, routing, and more.",
   "type": "module",
   "bin": {
@@ -43,11 +43,12 @@
   "files": [
     "server.js",
     "tool-annotations.js",
-    "log-search.js",
+    "fetch-retry.js",
     "messaging-base.js",
     "parity/loader.js",
     "parity/*.customer.js",
     "workflow-schedule.js",
+    "report-explain.json",
     "server.json",
     "README.md"
   ],

package/parity/activity.customer.js

@@ -1,4 +1,4 @@
-// velaro activity: integration activity logs and settings audit trail for the authenticated site. The CLI --site staff mode is the existing staff tool support_integration_logs.
+// velaro activity: integration activity logs and settings audit trail for the authenticated site. The CLI --site mode is staff-only and is not part of this package.
 // Parity module (CLI group -> MCP tools).
 
 const enc = encodeURIComponent;

package/report-explain.json

@@ -0,0 +1,232 @@
+{
+  "experience-impact": {
+    "name": "Experience Impact",
+    "answers": "How staffing and adherence affect what customers feel, as a 0 to 100 Experience Index.",
+    "sources": "Work Schedules and presence, chat queue timing, missed chats, and CSAT from ticket replies and 1-5 survey ratings (questions tagged csat or star_rating).",
+    "prerequisites": "Work Schedules for agents; a survey with a 1-5 CSAT or star question attached to post-chat or a workflow, or ticket CSAT requests turned on; chat traffic in range.",
+    "interpret": "Weights: service level 30, adherence 25, CSAT 25, missed chats 20; a signal with no data drops out. CSAT needs 5+ responses to count. Response rate = rated survey submissions / all survey submissions. Actual agents below scheduled while missed chats rise = staffing gap.",
+    "whyZero": "CSAT empty: no CSAT survey configured; survey exists but nobody answered; answers came in with no 1-5 rating question; fewer than 5 responses; or the range predates the survey. Surveyed but unrated? Managers run the CSAT backfill (survey ratings only, not ticket CSAT): preview, then apply, via the report banner, `velaro report-backfill csat`, or MCP report_backfill. Adherence empty: no Work Schedules.",
+    "fix": "Add a 1-5 star or CSAT question to the post-chat survey, enable ticket CSAT requests, widen the range, then fix the weakest component.",
+    "related": "Schedule Adherence, Service Level, Missed Chats, Surveys & NPS, Sentiment, Agent Performance"
+  },
+  "conversations": {
+    "name": "Conversations",
+    "answers": "How many conversations came in, on which channels and when.",
+    "sources": "Every conversation record on your account, grouped by channel, team, bot or agent, and time.",
+    "prerequisites": "At least one deployed channel (chat widget, SMS, email, voice, social).",
+    "interpret": "Overview shows totals and trend; Breakdown splits by channel, team and handler. Look at peaks by hour and day to plan staffing. Rising volume with flat staffing predicts longer waits.",
+    "whyZero": "No channel deployed or no traffic; the date range or team filter is too narrow; or you lack access to that team's data.",
+    "fix": "Widen the range, clear filters, confirm the deployment is live and the widget loads on your site.",
+    "related": "Service Level, Missed Chats, Visitor Traffic"
+  },
+  "missed": {
+    "name": "Missed Chats",
+    "answers": "Visitors who asked for help and got no live answer, and why.",
+    "sources": "Chat requests that ended without an agent or bot response, plus offline or unanswered conversations.",
+    "prerequisites": "Live chat deployed with agents or routing configured.",
+    "interpret": "Overview gives the missed count and rate. Breakdown shows time of day and team. Analysis groups likely causes such as nobody online, queue timeout, or visitor left. A missed spike at one hour points to a coverage gap.",
+    "whyZero": "Genuinely none, no chat traffic, or a bot answers everything so nothing reaches an agent queue.",
+    "fix": "Add agents or schedules for peak hours, review routing and after-hours behavior, enable offline message capture.",
+    "related": "Service Level, Experience Impact, Agent Availability"
+  },
+  "agent-performance": {
+    "name": "Agent Performance",
+    "answers": "How each agent handles conversations: volume, handle time, response speed and quality.",
+    "sources": "Conversations assigned to and handled by each agent, message timestamps, and survey scores where collected.",
+    "prerequisites": "Agents added to the account and handling chats.",
+    "interpret": "Compare an agent against the team over several weeks, not one day. Pair handle time with CSAT: fast and unhappy is a quality problem, slow and happy may be complex work.",
+    "whyZero": "Agent has no assigned chats in range, was not online, or the filter excludes their team. Quality scores need survey data.",
+    "fix": "Check routing assigns chats to that agent and that they set themselves available.",
+    "related": "Response Time, Agent Utilization, Surveys & NPS"
+  },
+  "response-time": {
+    "name": "Response Time",
+    "answers": "How quickly customers get a first reply and how long replies take afterwards.",
+    "sources": "Message timestamps between the customer's message and the first agent or bot reply.",
+    "prerequisites": "Chats with at least one reply.",
+    "interpret": "Look at the median and the slow tail together. A fine average with a long tail means some customers wait far too long.",
+    "whyZero": "No replies in range, or chats were only bot-handled and excluded from agent timing.",
+    "fix": "Add coverage at slow hours, turn on auto-greeting, review the routing capacity limit.",
+    "related": "Service Level, Agent Performance"
+  },
+  "service-level": {
+    "name": "Service Level",
+    "answers": "The share of chats answered within your target time.",
+    "sources": "Queue entry and first-answer timestamps compared with your configured service level threshold.",
+    "prerequisites": "A service level threshold in report settings and chats that enter an agent queue.",
+    "interpret": "A common target is 80 percent answered in 30 seconds. Check the trend by hour to find breaches.",
+    "whyZero": "No chats were queued for agents in the range, or no threshold is set.",
+    "fix": "Set the threshold, then staff to the hours that breach it.",
+    "related": "Response Time, Missed Chats, Experience Impact"
+  },
+  "sentiment": {
+    "name": "Sentiment",
+    "answers": "The overall tone of customer messages, by contact and by agent.",
+    "sources": "AI sentiment scoring of conversation messages.",
+    "prerequisites": "Sentiment reporting enabled on your plan and enough conversations to score.",
+    "interpret": "Watch the trend and the share of negative conversations. Use By Agent for coaching, By Contact to spot at-risk customers. Sentiment is inferred from text, so treat single scores as hints.",
+    "whyZero": "Feature not enabled, conversations too short to score, or scoring has not run yet for recent chats.",
+    "fix": "Confirm the plan includes it, widen the range, check again after the next processing cycle.",
+    "related": "Customer Health, Surveys & NPS, Experience Impact"
+  },
+  "health": {
+    "name": "Customer Health",
+    "answers": "Which contacts look healthy or at risk based on recent interactions.",
+    "sources": "Conversation frequency, sentiment, unresolved issues and survey results per contact.",
+    "prerequisites": "Contacts with conversation history.",
+    "interpret": "Low scores with rising contact frequency are the first to act on. Scores are relative to your own customers.",
+    "whyZero": "New account with little history, or sentiment data is not yet available.",
+    "fix": "Allow history to accumulate and enable surveys to add a direct signal.",
+    "related": "Sentiment, Surveys & NPS, Intelligence Suite"
+  },
+  "surveys": {
+    "name": "Surveys & NPS",
+    "answers": "What customers say in surveys: CSAT, NPS and custom questions, and how many respond.",
+    "sources": "Survey answers collected after chats, through workflows, standalone links or email.",
+    "prerequisites": "At least one active survey (post-chat CSAT, NPS or custom) delivered on a channel.",
+    "interpret": "Read the average with the response count and response rate. NPS is promoters minus detractors. Under about 30 responses, trends are noisy.",
+    "whyZero": "No survey enabled, survey not attached to the channel or workflow, nobody responded, or the range predates the survey. The visitor may close the chat before the survey shows.",
+    "fix": "Enable a short post-chat survey on every staffed channel, test it yourself, and keep questions to one or two.",
+    "related": "Experience Impact, Sentiment, Missed Chats"
+  },
+  "tickets": {
+    "name": "Tickets",
+    "answers": "Ticket volume, status, age and resolution speed.",
+    "sources": "Tickets created from email, forms, chats and manual entry.",
+    "prerequisites": "Ticketing or an email inbox connected.",
+    "interpret": "Watch open backlog and time to resolve. A growing backlog with steady intake means capacity is short.",
+    "whyZero": "Ticketing not enabled, no inbox connected, or no tickets in range.",
+    "fix": "Connect an inbox or enable ticket creation from forms and chat.",
+    "related": "Conversations, Agent Performance"
+  },
+  "calls": {
+    "name": "Calls",
+    "answers": "Phone call volume, duration, answered and missed calls.",
+    "sources": "Call records from your connected phone line or voice integration.",
+    "prerequisites": "A provisioned phone line or connected voice integration.",
+    "interpret": "Compare answered against missed by hour. Long durations may signal complexity or unresolved issues.",
+    "whyZero": "No phone line connected or no calls in range.",
+    "fix": "Connect a number and confirm it routes into Velaro.",
+    "related": "IVR, Voice"
+  },
+  "ivr": {
+    "name": "IVR",
+    "answers": "How callers move through your phone menus and where they drop off.",
+    "sources": "IVR call events for each menu step and outcome.",
+    "prerequisites": "An IVR configured on a phone line.",
+    "interpret": "A high drop-off at one step suggests a confusing prompt. Many transfers to an agent from one option shows demand to automate.",
+    "whyZero": "No IVR configured or no calls reached it.",
+    "fix": "Complete IVR setup, place a test call, then re-check.",
+    "related": "Calls, Voice"
+  },
+  "account-utilization": {
+    "name": "Account Utilization",
+    "answers": "How much of your plan (agents, bots, AI usage, channels) you are using.",
+    "sources": "Plan limits compared with measured usage on your account.",
+    "prerequisites": "Administrator or manager access.",
+    "interpret": "Near 100 percent means you may need a higher limit; very low usage means features you pay for are idle.",
+    "whyZero": "Feature not enabled yet or no usage in range.",
+    "fix": "Turn on unused features or request a limit increase.",
+    "related": "Agent Utilization"
+  },
+  "agent-availability": {
+    "name": "Agent Availability",
+    "answers": "When agents were online, away or offline.",
+    "sources": "Agent presence and status changes.",
+    "prerequisites": "Agents logging in to the workspace.",
+    "interpret": "Compare online time with scheduled time and chat demand to find coverage gaps.",
+    "whyZero": "Agents did not log in or the selected agents are not in range.",
+    "fix": "Confirm agents sign in and set their status to available.",
+    "related": "Schedule Adherence, Agent Utilization, Missed Chats"
+  },
+  "agent-utilization": {
+    "name": "Agent Utilization",
+    "answers": "How busy agents are compared with their capacity.",
+    "sources": "Concurrent chat load and online time per agent.",
+    "prerequisites": "Administrator or manager access; agents handling chats.",
+    "interpret": "Around 60 to 80 percent is healthy. Above that risks long waits and burnout, well below means spare capacity.",
+    "whyZero": "Agents were not online or not given chats.",
+    "fix": "Rebalance routing and capacity limits.",
+    "related": "Agent Availability, Agent Performance"
+  },
+  "visitor-traffic": {
+    "name": "Visitor Traffic",
+    "answers": "Who is visiting pages that have the Velaro widget and how many start chats.",
+    "sources": "Visitor tracking from the widget script on your site.",
+    "prerequisites": "Visitor tracking enabled and the widget installed on your pages.",
+    "interpret": "Compare visits with chats started to find pages where engagement is low.",
+    "whyZero": "Widget not installed on those pages, tracking not enabled, or an ad blocker or consent setting blocks it.",
+    "fix": "Verify the embed code on the live page and the tracking setting.",
+    "related": "Conversations"
+  },
+  "schedule-adherence": {
+    "name": "Schedule Adherence",
+    "answers": "Whether agents were online when scheduled.",
+    "sources": "Work Schedules compared with agent presence, plus approved exceptions.",
+    "prerequisites": "Work Schedules assigned to agents; the site time zone set correctly.",
+    "interpret": "Adherence is minutes available during scheduled time divided by scheduled minutes. Approved exceptions are excluded. Use Intraday for now and Timeline for the day's detail.",
+    "whyZero": "No schedules assigned, agents not scheduled in range, or time zone mismatch.",
+    "fix": "Create and assign schedules and check the time zone.",
+    "related": "Experience Impact, Agent Availability, Service Level"
+  },
+  "chat-intelligence": {
+    "name": "Chat Intelligence",
+    "answers": "What topics customers ask about, trends, and where the bot or KB falls short.",
+    "sources": "AI topic grouping of conversations and missed topics.",
+    "prerequisites": "Enough conversations (typically dozens) and the feature enabled.",
+    "interpret": "Rising themes show new demand. Missed topics are KB gaps: write or ingest content for them. Recommendations can be applied or dismissed.",
+    "whyZero": "Too little traffic, feature not enabled, or analysis has not run.",
+    "fix": "Widen the range and allow the next analysis run.",
+    "related": "Intelligence Suite, Conversation Efficiency"
+  },
+  "conversation-efficiency": {
+    "name": "Conversation Efficiency",
+    "answers": "How efficiently conversations are resolved and where time is lost.",
+    "sources": "Message counts, handle time, transfers and outcomes.",
+    "prerequisites": "Conversations with agent involvement.",
+    "interpret": "Agents shows who is above or below the norm, Correlation shows what drives long chats, Recommendations suggests actions.",
+    "whyZero": "No handled conversations in range.",
+    "fix": "Widen the range or pick a team with traffic.",
+    "related": "Agent Performance, Chat Intelligence"
+  },
+  "intelligence": {
+    "name": "Intelligence Suite",
+    "answers": "AI analysis across agents, customers, knowledge gaps, volume forecasts, revenue impact, competitors and channels.",
+    "sources": "Conversation history, surveys, and connected commerce or CRM data where present.",
+    "prerequisites": "Feature enabled on the plan and a few weeks of data. Revenue Impact needs a commerce or CRM integration.",
+    "interpret": "Treat each tab as guidance. Predictive Volume is a forecast, not a guarantee. Revenue Impact is an estimate from connected data.",
+    "whyZero": "Not enough history, missing integration, or feature not enabled.",
+    "fix": "Connect the relevant integration and allow data to accumulate.",
+    "related": "Customer Health, Chat Intelligence"
+  },
+  "operations": {
+    "name": "Operations Center",
+    "answers": "Live view of queues, agents and conversations right now.",
+    "sources": "Real-time presence and queue state.",
+    "prerequisites": "Workforce management enabled.",
+    "interpret": "Use it for moment-to-moment staffing. A rising queue with idle agents suggests a routing problem.",
+    "whyZero": "No active conversations or agents online.",
+    "fix": "Confirm agents are online and routing is active.",
+    "related": "Agent Availability, Service Level"
+  },
+  "voice": {
+    "name": "Voice",
+    "answers": "Individual call history and voice usage and billing.",
+    "sources": "Call log and voice minute usage.",
+    "prerequisites": "Voice enabled with a phone number.",
+    "interpret": "Call Log for detail, Usage for minutes against your plan.",
+    "whyZero": "No voice line or no calls.",
+    "fix": "Set up a voice number.",
+    "related": "Calls, IVR"
+  },
+  "email-subscriptions": {
+    "name": "Email Reports",
+    "answers": "Scheduled report summaries emailed to you.",
+    "sources": "The same data as the reports, summarized on your schedule.",
+    "prerequisites": "Access to the underlying report; some are manager or admin only.",
+    "interpret": "Each email links back to the full report.",
+    "whyZero": "Subscription not saved, the report is not on your plan, or it had no data for the period.",
+    "fix": "Re-save the subscription and check spam filtering for noreply@velaro.com.",
+    "related": "All reports"
+  }
+}

package/server.js

@@ -40,7 +40,7 @@
  *   VELARO_MCP_MODE=http PORT=3000 node server.js
  */
 
-import { buildRawLogQuery, describeRawMeta, fetchRetry429, resolveLogWindow } from './log-search.js';
+import { fetchRetry429 } from './fetch-retry.js';
 import { Server }            from '@modelcontextprotocol/sdk/server/index.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 import {
@@ -54,51 +54,12 @@ import { loadParity, runParity } from './parity/loader.js';
 import { resolveMessagingApi } from './messaging-base.js';
 import { buildResolvePath, buildTimelinePath, buildOverrideBody, buildValidateBody, buildBannerPath, buildOverrideListPath, tolerant, VALIDATE_PATH, OVERRIDE_PATH } from './workflow-schedule.js';
 
-// Default was 'https://help.velaro.com'. Renamed to the recognizable admin API hostname for
-// clarity during the 2026-09-10 Donaldson bot Calendly status investigation
-// (docs/qa/chatbot-hallucinated-booking-donaldson-bot.md) — but this is NOT a functional fix and
-// does NOT explain that incident: live-verified same day that 'https://help.velaro.com' and
-// 'https://api-admin-us-east.velaro.com' are the SAME deployment (identical /api/health build SHA,
-// and /Calendly/superadmin/status returns 401 — auth-gated, not 404 — on both hosts). Whatever
-// caused that investigation's status/reality contradiction, it was NOT this default resolving to a
-// broken or different host; that theory is disproven. Left as a naming clarity improvement only.
+// Production admin API by default; set VELARO_ADMIN_API to target staging.
 const API_BASE      = process.env.VELARO_ADMIN_API     || 'https://api-admin-us-east.velaro.com';
 const MESSAGING_API = resolveMessagingApi(process.env.VELARO_MESSAGING_API, API_BASE);
 const MCP_KEY       = process.env.VELARO_MCP_KEY;
 const JWT           = process.env.VELARO_JWT;
 
-// mcp/staff-server.js defaults to staging instead -- the two servers' defaults intentionally
-// differ, but a zero-result lookup gives no hint which environment was actually searched
-// either way. See ENV_LABEL in staff-server.js for the incident this class of confusion caused
-// (a real production customer read as "doesn't exist" from a staging-scoped search).
-const ENV_LABEL = API_BASE.includes('staging') ? 'staging' : 'production';
-
-// Known admin API hosts, for tools that let a caller explicitly target one environment
-// regardless of what this server process's own API_BASE is configured to (see the `env` param
-// on the calendly_* superadmin tools below). Deliberately NOT used as a default anywhere —
-// defaulting env-selectable tools to one hardcoded environment while every other tool in this
-// file follows the single global API_BASE would recreate the exact bug being fixed here: an
-// operator configured for one environment would silently get a DIFFERENT environment's answer
-// from just these tools with no indication anything was different.
-const ADMIN_API_HOSTS = {
-  staging:    'https://velaro-admin-staging.azurewebsites.net',
-  production: 'https://api-admin-us-east.velaro.com',
-};
-
-/// Resolves an optional `env` tool argument to a target admin API base. Throws on an unrecognized
-/// value instead of silently falling through to API_BASE (the JS default-parameter behavior of
-/// `api(..., base)` when `base` is `undefined`) — a typo like `env: 'prod'` must not silently run
-/// a DESTRUCTIVE call (calendly_disconnect) against whatever this server defaults to while telling
-/// the caller it targeted a different environment. `hasOwnProperty` (not truthiness) also closes
-/// the prototype-chain edge case (`env: 'constructor'`, `env: 'toString'`, etc.).
-function resolveAdminBase(env) {
-  if (env === undefined || env === null) return API_BASE;
-  if (!Object.prototype.hasOwnProperty.call(ADMIN_API_HOSTS, env)) {
-    throw new Error(`Unknown env "${env}" — use "staging" or "production" (or omit it to use this server's configured default).`);
-  }
-  return ADMIN_API_HOSTS[env];
-}
-
 if (!MCP_KEY && !JWT) {
   process.stderr.write('ERROR: Set VELARO_MCP_KEY=vel_live_... or VELARO_JWT=<token>\n');
   process.exit(1);
@@ -115,15 +76,6 @@ function formatHealthRow(item) {
   return `  ${(item.slug ?? '?').padEnd(14)}  ${(item.status ?? '?').padEnd(14)}  ${ms.padStart(7)}  ${ts}  ${item.detail ?? ''}`.trimEnd();
 }
 
-function parseDuration(s) {
-  const m = /^(\d+)(m|h|d)$/i.exec(String(s ?? '2h').trim());
-  if (!m) return 2 * 3600 * 1000;
-  const n = parseInt(m[1], 10);
-  if (m[2] === 'm') return n * 60 * 1000;
-  if (m[2] === 'h') return n * 3600 * 1000;
-  return n * 24 * 3600 * 1000;
-}
-
 async function messagingApi(path, opts = {}) {  // opts.timeoutMs: log searches pass 40000 (server scan budget 12 s + 6 s AI search)
   if (!MESSAGING_API) throw new Error(
     'VELARO_MESSAGING_API is not configured. Add "VELARO_MESSAGING_API": "https://velaro-messaging-api-staging.azurewebsites.net" to your MCP env config.'
@@ -133,7 +85,6 @@ async function messagingApi(path, opts = {}) {  // opts.timeoutMs: log searches
     method: opts.method ?? 'GET',
     headers: {
       Authorization: authHeader(),
-      'X-Internal-SiteId': '1032',
       ...(opts.body ? { 'Content-Type': 'application/json' } : {}),
     },
     body: opts.body ? JSON.stringify(opts.body) : undefined,
@@ -142,22 +93,11 @@ async function messagingApi(path, opts = {}) {  // opts.timeoutMs: log searches
   const res = (opts.method ?? 'GET') === 'GET' ? await fetchRetry429(`${MESSAGING_API}${path}`, init) : await fetch(`${MESSAGING_API}${path}`, init());
   if (!res.ok) {
     const text = await res.text().catch(() => '');
-    throw new Error(`Velaro Logger ${path} -> ${res.status}: ${text.slice(0, 300)}`);
+    throw new Error(`Messaging API ${path} -> ${res.status}: ${text.slice(0, 300)}`);
   }
   return res.json();
 }
 
-// FIXED 2026-09-24: velaro-messaging's /superadmin/logs/search used to return a bare JSON array
-// for some queries and {entries, nextCursor} for others, depending on which internal code path
-// served the request (see that repo's LogsController.cs ENVELOPE SHAPE comment). It now always
-// returns {entries, nextCursor} -- this helper also accepts a bare array so callers degrade
-// gracefully rather than throwing if ever pointed at an older deploy.
-function extractLogEntries(response) {
-  if (Array.isArray(response)) return response;
-  if (response && Array.isArray(response.entries)) return response.entries;
-  return [];
-}
-
 /** Body for POST/PUT ApplePayPresetOrders: only passed fields; the server computes the total. */
 function applePayPresetBody(args) {
   const body = {};
@@ -334,51 +274,9 @@ async function api(method, path, body, base = API_BASE) {
   return text ? JSON.parse(text) : null;
 }
 
-// ── Livefluence migration helpers ─────────────────────────────────────────────
-
 import { fileURLToPath as _ftu } from 'node:url';
 import { join as _join, dirname as _dirname } from 'node:path';
-import { readFileSync as _readFileSync, existsSync as _existsSync } from 'node:fs';
-
-const _migrationsDir = _join(_dirname(_ftu(import.meta.url)), '..', 'cli', 'lib', 'migrations');
-
-function loadMigrationProfile(slug) {
-  if (!slug) throw new Error('Provide customer slug (azenta, amscro, bluefire, donaldson) or a custom profile object.');
-  const file = _join(_migrationsDir, `${slug}.json`);
-  if (!_existsSync(file)) {
-    throw new Error(`Migration profile "${slug}" not found. Available: azenta, amscro, bluefire, donaldson`);
-  }
-  return JSON.parse(_readFileSync(file, 'utf8'));
-}
-
-function mcpResolveTokens(tokenMap, items, idField, nameField) {
-  const out = {};
-  for (const [token, name] of Object.entries(tokenMap)) {
-    const match = (items ?? []).find(i => i[nameField]?.toLowerCase() === name.toLowerCase());
-    out[`@${token}`] = match ? String(match[idField]) : null;
-  }
-  return out;
-}
-
-function mcpResolveValue(value, aiMap, teamMap) {
-  if (!value) return value;
-  const out = {};
-  for (const [k, v] of Object.entries(value)) {
-    if (typeof v === 'string' && v.startsWith('@')) {
-      out[k] = aiMap[v] ?? teamMap[v] ?? v;
-    } else {
-      out[k] = v;
-    }
-  }
-  return out;
-}
-
-function mcpFindUnresolved(value) {
-  if (!value) return [];
-  return Object.entries(value)
-    .filter(([, v]) => v === null || (typeof v === 'string' && v.startsWith('@')))
-    .map(([k]) => k);
-}
+import { readFileSync as _readFileSync } from 'node:fs';
 
 // The hosted gateway requires an initialized session (Mcp-Session-Id + MCP-Protocol-Version) on
 // every call after "initialize". Cache one per process and re-initialize when it expires (404).
@@ -1739,8 +1637,6 @@ For multiSelect dynamic options: the variable named in dynamicOptionsVariable mu
         },
         buttonLabel: { type: 'string', description: 'Optional action button label' },
         buttonUrl:   { type: 'string', description: 'Optional action button URL (required if buttonLabel is set)' },
-        mentions:    { type: 'array', description: 'People to @mention (real Teams notification). Velaro staff only. Uses the ops Teams sender instead of a webhook.', items: { type: 'object', properties: { user: { type: 'string', description: 'Entra object id or UPN, e.g. andrea@velaro.com' }, name: { type: 'string', description: 'Display name shown in the @mention' } }, required: ['user'] } },
-        destination: { type: 'string', description: 'Named channel in the DevOps team instead of General: prs, workflows, deploys, alerts, qa, general. Velaro staff only; uses the ops Teams sender instead of a webhook.' },
       },
       required: ['title'],
     },
@@ -2607,7 +2503,7 @@ For multiSelect dynamic options: the variable named in dynamicOptionsVariable mu
     },
   },
 
-  // ── Integration Diagnostics (Velaro staff) ────────────────────────────────
+  // ── Integration Diagnostics ────────────────────────────────
   {
     name: 'integration_activity_list',
     description: 'List integration activity log entries (auth events, rate limits, config errors, AI skill calls). Fastest way to diagnose why a specific integration is failing — check this before App Insights.',
@@ -3277,7 +3173,7 @@ For multiSelect dynamic options: the variable named in dynamicOptionsVariable mu
   },
   {
     name: 'velaro_diagnostic_start',
-    description: 'START HERE for any "broken", "fix", "not working", "error", or "why is X failing" request. Returns the Velaro diagnostic runbook: which log tool to check first, query patterns for common symptoms (exceptions, AI skill errors, Hangfire failures, SignalR hub down, campaign issues), and the rule "check logs before reading code." Call this before touching any source file.',
+    description: 'START HERE for any "broken", "not working", "error", or "why is X failing" request about your Velaro site. Returns the diagnostic runbook: which activity log, health and report tools to check first for integration, channel, bot and routing problems.',
     inputSchema: { type: 'object', properties: {}, required: [] },
   },
 
@@ -3797,7 +3693,7 @@ For multiSelect dynamic options: the variable named in dynamicOptionsVariable mu
   },
   {
     name: 'usage_alerts',
-    description: 'Plan-limit alerts for the authenticated site: every metered resource at or above its warning threshold (80%+), with used/limit, percent, level (warning | critical | limit) and whether overage is billed. Same rules as the usage-limit emails and the dashboard banner. Use to answer "are they near a limit?" or "why did they get a usage email?". Read-only. To raise a limit, a customer uses Billing > Contact Account Manager; staff use support_set_limit.',
+    description: 'Plan-limit alerts for the authenticated site: every metered resource at or above its warning threshold (80%+), with used/limit, percent, level (warning | critical | limit) and whether overage is billed. Same rules as the usage-limit emails and the dashboard banner. Use to answer "are they near a limit?" or "why did they get a usage email?". Read-only. To raise a limit, use Billing > Contact Account Manager.',
   },
   {
     name: 'billing_contacts_list',
@@ -4167,6 +4063,77 @@ For multiSelect dynamic options: the variable named in dynamicOptionsVariable mu
       required: ['contactId'],
     },
   },
+  // -- Current Sales (time-boxed bot override Q&A + per-customer coupons). Site comes from the credential, never an arg. --
+  {
+    name: 'site_sale_list',
+    description: "List this site's Current Sales (temporary sales or discounts the bot answers about deterministically until they end).",
+    inputSchema: { type: 'object', properties: {}, required: [] },
+  },
+  {
+    name: 'site_sale_create',
+    description: 'Create a Current Sale: while active, the bot answers sales, discount and coupon questions from this definition and can issue per-customer coupons (Magento sites mint a real cart price rule). It stops at the end time. Times are UTC; convert from Pacific.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        name:             { type: 'string', description: 'Sale name shown to customers' },
+        description:      { type: 'string', description: 'Short description the bot can quote' },
+        appliesTo:        { type: 'string', enum: ['all','category','products'], description: 'Scope of the sale' },
+        appliesToValue:   { type: 'string', description: 'Category name or comma-separated product identifiers when appliesTo is category or products' },
+        discountType:     { type: 'string', enum: ['percentage','fixed_amount','free_shipping'], description: 'Kind of discount' },
+        discountValue:    { type: 'number', description: 'Percent or fixed amount (ignored for free_shipping)' },
+        startsAtUtc:      { type: 'string', description: 'ISO 8601 start time in UTC (convert from Pacific)' },
+        endsAtUtc:        { type: 'string', description: 'ISO 8601 end time in UTC; the sale stops answering at this time' },
+        couponCode:       { type: 'string', description: 'Optional shared coupon code' },
+        autoGenerateCoupons:   { type: 'boolean', description: 'Let the bot issue a unique coupon per customer' },
+        maxCouponsPerCustomer: { type: 'number', description: 'Max coupons the bot issues to one customer' },
+        couponUsageLimit:      { type: 'number', description: 'Times each coupon can be used' },
+        couponExpiresHours:    { type: 'number', description: 'Hours before an issued coupon expires' },
+      },
+      required: ['name', 'discountType', 'startsAtUtc', 'endsAtUtc'],
+    },
+  },
+  {
+    name: 'site_sale_update',
+    description: 'Update a Current Sale by id. Omit a field to leave it unchanged.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        id: { type: 'number', description: 'Sale ID from site_sale_list. Required.' },
+        name:             { type: 'string', description: 'Sale name shown to customers' },
+        description:      { type: 'string', description: 'Short description the bot can quote' },
+        appliesTo:        { type: 'string', enum: ['all','category','products'], description: 'Scope of the sale' },
+        appliesToValue:   { type: 'string', description: 'Category name or comma-separated product identifiers when appliesTo is category or products' },
+        discountType:     { type: 'string', enum: ['percentage','fixed_amount','free_shipping'], description: 'Kind of discount' },
+        discountValue:    { type: 'number', description: 'Percent or fixed amount (ignored for free_shipping)' },
+        startsAtUtc:      { type: 'string', description: 'ISO 8601 start time in UTC (convert from Pacific)' },
+        endsAtUtc:        { type: 'string', description: 'ISO 8601 end time in UTC; the sale stops answering at this time' },
+        couponCode:       { type: 'string', description: 'Optional shared coupon code' },
+        autoGenerateCoupons:   { type: 'boolean', description: 'Let the bot issue a unique coupon per customer' },
+        maxCouponsPerCustomer: { type: 'number', description: 'Max coupons the bot issues to one customer' },
+        couponUsageLimit:      { type: 'number', description: 'Times each coupon can be used' },
+        couponExpiresHours:    { type: 'number', description: 'Hours before an issued coupon expires' },
+      },
+      required: ['id'],
+    },
+  },
+  {
+    name: 'site_sale_end',
+    description: 'End a Current Sale now. The bot stops answering from it immediately.',
+    inputSchema: {
+      type: 'object',
+      properties: { id: { type: 'number', description: 'Sale ID. Required.' } },
+      required: ['id'],
+    },
+  },
+  {
+    name: 'site_sale_delete',
+    description: 'Delete a Current Sale by id.',
+    inputSchema: {
+      type: 'object',
+      properties: { id: { type: 'number', description: 'Sale ID. Required.' } },
+      required: ['id'],
+    },
+  },
   {
     name: 'pickup_get_config',
     description: 'Get this site\'s Pickup & Reminder Texting configuration (default cadence, max reminders, message template, enabled state, quiet-hours override). Returns null/404 if no config has been created yet -- use pickup_update_config to create one.',
@@ -5432,12 +5399,12 @@ async function handleTool(name, args) {
       return await rpc('workflow_update_node', args);
 
     // ── Surveys ──────────────────────────────────────────────────────────
-    // Direct messagingGet/Post/Del calls (like notifications_get/ai_config_staff_get above) —
+    // Direct messagingGet/Post/Del calls (like notifications_get above) —
     // site isolation is enforced server-side by SurveysController's [Authorize]-scoped SiteId
     // (ClientControllerBase), never passed by the client. Note: SurveysController's global
     // [Authorize] does not accept vel_live_* service keys (only a handful of controllers opt
     // into that manually) — these tools need VELARO_JWT, same requirement as the existing
-    // notifications_get/ai_config_staff_get tools they're modeled on.
+    // notifications_get tool they're modeled on.
     case 'ai_followups_site_get': {
       const r = await messagingGet('/SiteSettings/AiFollowUps');
       return JSON.stringify({ enabled: r?.enabled ?? null }, null, 2);
@@ -5995,16 +5962,6 @@ reply: ${r?.reply}`;
     }
 
     case 'teams_notify_card': {
-      if ((args.mentions && args.mentions.length) || args.destination) {
-        const r = await api('POST', '/TeamsMessaging/Card', {
-          title: args.title,
-          facts: (args.fields || []).map(f => ({ label: f.label, value: f.value })),
-          actionUrl: args.buttonUrl, actionLabel: args.buttonLabel,
-          destination: args.destination,
-          mentions: (args.mentions || []).map(m => ({ user: m.user, name: m.name })),
-        });
-        return r?.sent ? `Card sent via ${r.path}${r.warnings?.length ? ' (' + r.warnings.join('; ') + ')' : ''}.` : `Send failed: ${r?.error || 'unknown error'}`;
-      }
       const webhooks = await api('GET', '/TeamsNotification');
       if (!Array.isArray(webhooks) || !webhooks.length)
         return 'No Teams webhooks configured. Go to Integrations → Microsoft Teams to add one, or call velaro teams create <name> <webhookUrl> via CLI.';
@@ -7389,7 +7346,9 @@ reply: ${r?.reply}`;
     }
 
     case 'report_explain': {
-      const all = JSON.parse(_readFileSync(_join(_dirname(_ftu(import.meta.url)), '..', 'cli', 'lib', 'report-explain.json'), 'utf8'));
+      // Packaged copy (mcp/report-explain.json, kept identical to cli/lib/report-explain.json by
+      // scripts/validate-cli-mcp-syntax.js). The old '../cli/lib' path does not exist in a package install.
+      const all = JSON.parse(_readFileSync(_join(_dirname(_ftu(import.meta.url)), 'report-explain.json'), 'utf8'));
       const key = String(args.report ?? '').trim().toLowerCase();
       if (!key) return Object.entries(all).map(([k, r]) => `${k}: ${r.name}`).join('\n');
       const r = all[key];
@@ -8305,8 +8264,7 @@ ${JSON.stringify(result, null, 2)}`;
         lines.push('Recent payments:');
         s.recentSessions.forEach(p => lines.push(`  ${(p.amountCents/100).toFixed(2)}  ${p.status}  ${p.createdAt?.slice(0,10)}`));
       }
-      // Note: QB sync, deferred revenue, and internal accounting details are omitted here.
-      // Use billing_plan_status_internal in staff-server.js for those.
+      // QB sync, deferred revenue, and internal accounting details are intentionally omitted.
       return lines.join('\n');
     }
 
@@ -8454,6 +8412,66 @@ ${JSON.stringify(result, null, 2)}`;
       return JSON.stringify(history, null, 2);
     }
 
+    case 'site_sale_list': {
+      const result = await messagingGet('/SiteSales');
+      return JSON.stringify(result, null, 2);
+    }
+
+    case 'site_sale_create': {
+      if (!args.name || !args.discountType || !args.startsAtUtc || !args.endsAtUtc) return 'name, discountType, startsAtUtc and endsAtUtc are required.';
+      // Field names must match the SiteSales request on the messaging API exactly (undefined is dropped by JSON).
+      const body = {
+        name: args.name,
+        description: args.description,
+        appliesTo: args.appliesTo,
+        appliesToValue: args.appliesToValue,
+        discountType: args.discountType,
+        discountValue: args.discountValue,
+        startsAtUtc: args.startsAtUtc,
+        endsAtUtc: args.endsAtUtc,
+        couponCode: args.couponCode,
+        autoGenerateCoupons: args.autoGenerateCoupons,
+        maxCouponsPerCustomer: args.maxCouponsPerCustomer,
+        couponUsageLimit: args.couponUsageLimit,
+        couponExpiresHours: args.couponExpiresHours,
+      };
+      const result = await messagingPost('/SiteSales', body);
+      return JSON.stringify(result, null, 2);
+    }
+
+    case 'site_sale_update': {
+      if (args.id == null) return 'id is required.';
+      const body = {
+        name: args.name,
+        description: args.description,
+        appliesTo: args.appliesTo,
+        appliesToValue: args.appliesToValue,
+        discountType: args.discountType,
+        discountValue: args.discountValue,
+        startsAtUtc: args.startsAtUtc,
+        endsAtUtc: args.endsAtUtc,
+        couponCode: args.couponCode,
+        autoGenerateCoupons: args.autoGenerateCoupons,
+        maxCouponsPerCustomer: args.maxCouponsPerCustomer,
+        couponUsageLimit: args.couponUsageLimit,
+        couponExpiresHours: args.couponExpiresHours,
+      };
+      const result = await messagingPut(`/SiteSales/${encodeURIComponent(args.id)}`, body);
+      return JSON.stringify(result, null, 2);
+    }
+
+    case 'site_sale_end': {
+      if (args.id == null) return 'id is required.';
+      const result = await messagingPost(`/SiteSales/${encodeURIComponent(args.id)}/end`, {});
+      return JSON.stringify(result, null, 2);
+    }
+
+    case 'site_sale_delete': {
+      if (args.id == null) return 'id is required.';
+      const result = await messagingDel(`/SiteSales/${encodeURIComponent(args.id)}`);
+      return JSON.stringify(result, null, 2);
+    }
+
     case 'pickup_get_config': {
       const config = await messagingGet('/PickupNotifications/Config').catch(err => {
         if (String(err.message).includes(' 404')) return null;
@@ -9120,41 +9138,21 @@ ${JSON.stringify(result, null, 2)}`;
 
 const DIAGNOSTIC_RUNBOOK = `# Velaro Diagnostic Runbook
 
-## ALWAYS DO THIS FIRST before reading any code on a "broken" / "fix" / "not working" request
-
-### Step 0 — Start here every time
-1. \`logs_appinsights_query\` env=staging → \`exceptions | where timestamp > ago(1h) | take 20\`
-2. \`logs_loggly_search\` → \`tag:velaro-messaging-Staging ERROR\` (last 1h)
-3. \`mcp__velaro__get_diagnostic\` or \`velaro ops\` for Hangfire queue / deploy version
-
-Reading code without checking logs first = debugging blind.
-
-### Step 1 — Pick the right log source
-| Symptom | Tool | Query pattern |
-|---|---|---|
-| Exceptions / 500s in admin | logs_appinsights_query env=staging | exceptions \| where timestamp > ago(1h) \| take 20 |
-| Exceptions / 500s in messaging | logs_appinsights_query env=messaging-production | exceptions \| where timestamp > ago(1h) \| take 20 |
-| AI skill errors | logs_loggly_search | tag:velaro-messaging-Staging SkillInvoked |
-| Campaign / Hangfire failures | logs_loggly_search | tag:velaro-messaging-Staging Hangfire |
-| IVR / SignalR hub down | signalr_diagnostics instance=both hub=MessengerHub |
-| Prod exceptions | logs_appinsights_query env=production | exceptions \| take 20 |
-| Secure forms errors | logs_appinsights_query env=secure-forms | exceptions \| take 20 |
-| Scraper / automation errors | logs_appinsights_query env=automation-production | exceptions \| take 20 |
-
-### Step 2 — SignalR alerts
-Alerts: SignalR-CapSaturation-PAGE, SignalR-ServiceError-PAGE, SignalR-Quota95-PAGE are wired to velaro-ci-runners (Partner Success Core Benefits sub).
-Use \`signalr_diagnostics hub=MessengerHub\` or \`hub=EngagementHub\` to check live connection counts.
+Check what Velaro already recorded before changing any configuration.
 
-### Step 3 — Integration issues
-Use \`mcp__velaro__get_conversations\` or activity log endpoint \`/Integration/Logs/{slug}?severity=Error\` before digging into skill files.
+1. Integration failures: \`integration_activity_list\` with severity=Error (filter by integration slug), then
+   \`integration_skill_logs\` for AI skill calls that failed.
+2. Channel or integration connectivity: \`integration_health\` (pass run=true with a slug to probe now).
+3. Bot problems: \`bot_recent_errors\` and \`bot_skill_usage\`.
+4. Volume or service-level changes: \`kpi_snapshot\` and \`service_level_report\`.
+5. Routing questions: \`routing_explain_decision\` / \`routing_get_decision_log\`.
 
-### Step 4 — Only read code if logs are clean
-If all log sources are quiet → then read source code to find the bug.`;
+If these show nothing unusual, contact Velaro support with the time window and conversation ids you checked.`;
 
 const PROMPTS = [
   {
     name: 'diagnostic_runbook',
-    description: 'Velaro diagnostic runbook — which log tool to use first, query patterns for common symptoms, SignalR alert reference. ALWAYS consult this before reading code on any "broken" or "fix" request.',
+    description: 'Velaro diagnostic runbook: which activity log, health and report tools to check first when something on your site is not working.',
     arguments: [],
   },
 ];

package/tool-annotations.js

@@ -16,59 +16,48 @@ const READ_TOKENS = new Set([
 
 // Names that contain a read-looking token but change state (checked before READ_TOKENS).
 const MUTATING = new Set([
-  'report_schedule_upsert', 'report_subscription_update', 'report_subscription_delete', 'report_export_start',
-  'report_backfill', 'report_data_export', 'executive_insights_subscribe', 'velaro_diagnostic_start',
-  'apple_test_control', 'kb_capture_screenshot', 'business_action_route', 'business_action_execute',
-  'netsuite_cti_generate_url', 'netsuite_m2m_init', 'netsuite_m2m_save', 'index_integrity_repair',
-  'klaviyo_migration_run', 'sitesync_blob_push', 'sitesync_blob_import', 'chat_intelligence_draft_article',
-  'teams_phone_set_config', 'webflow_set_config', 'notion_set_config', 'monday_set_field_mapping',
-  'teams_push_settings_update', 'teams_channel_config_update', 'routing_team_update_config',
-  'pickup_update_config', 'payment_recovery_update_config', 'recruiting_sync_jobs',
-  'ai_config_set_reply_format', 'ai_model_set_site_thinking', 'ai_model_set_site_pin',
-  'entitlement_reconcile', 'entitlement_sync_stripe', 'entitlement_backfill_subscriptions',
-  'calendly_configure', 'acuity_configure', 'ms_bookings_configure', 'magento_set_sidebar_fields',
+  'report_schedule_upsert', 'report_subscription_update', 'report_subscription_delete',
+  'report_export_start', 'report_backfill', 'report_data_export', 'executive_insights_subscribe',
+  'velaro_diagnostic_start', 'business_action_route', 'business_action_execute', 'netsuite_cti_generate_url',
+  'netsuite_m2m_init', 'netsuite_m2m_save', 'index_integrity_repair', 'klaviyo_migration_run',
+  'chat_intelligence_draft_article', 'teams_phone_set_config', 'webflow_set_config', 'notion_set_config',
+  'monday_set_field_mapping', 'teams_push_settings_update', 'teams_channel_config_update',
+  'routing_team_update_config', 'pickup_update_config', 'payment_recovery_update_config',
+  'recruiting_sync_jobs', 'ai_config_set_reply_format', 'magento_set_sidebar_fields',
   'zoom_phone_set_config',
+  'site_sale_create', 'site_sale_update', 'site_sale_end',
 ]);
 
 // Names that look like writes but only read (checked before the write rules).
 const READ_ONLY_EXPLICIT = new Set([
-  'activity_logs', 'ai_field_extraction_fields', 'billing_subscription_invoice_send_log', 'billing_subscription_recognition_schedule',
-  'billing_subscription_payment_history', 'billing_subscription_invoice_history', 'billing_subscription_subscription_history',
-  'billing_subscription_upcoming', 'cobrowse_show', 'keyword_intelligence_top', 'keyword_intelligence_conversations',
-  'knowledge_advisor_advise', 'migrate_export', 'migrate_workflows_list', 'migrate_rules_list', 'quality_sentiment',
-  'quality_agent_performance', 'quality_low_scores', 'quality_calibration',
-  'appointments_find_open_slots', 'appointments_list', 'compliance_redaction_test', 'compliance_status',
-  'compliance_signatures', 'compliance_redaction_events', 'compliance_redaction_status',
-  'shopify_widget_activation_url', 'klaviyo_savings_calculator', 'routing_simulate_inactivity',
-  'outlook_calendar_get_available_range', 'ms_bookings_check_availability_range', 'copilot_studio_test',
-  'notion_test_token', 'teams_phone_test_config', 'webflow_test_config', 'magento_test_connection',
-  'outlook_calendar_test_connection', 'scraper_verify_token', 'bigcommerce_check_refundable',
-  'sitesync_blob_list', 'kb_advise_knowledge_strategy', 'index_move_status', 'index_mixed_content',
-  'index_search', 'netsuite_m2m_verify', 'bot_skill_usage', 'bot_full_diagnostic', 'bot_recent_errors',
-  'logs_loggly_search', 'logs_appinsights_query', 'velaro_logs_search', 'executive_brief', 'friction_radar',
-  'tour_insights', 'kpi_snapshot', 'site_info', 'case_board', 'case_list_types', 'ai_spend_report',
-  'agent_availability_report', 'missed_chat_diagnostics', 'sse_visitor_diagnostic', 'signalr_diagnostics',
-  'ivr_agent_availability', 'contactlist_get', 'ai_model_resolver_map', 'ai_model_effective_for_site',
-  'calendly_get_status', 'acuity_get_status', 'outlook_calendar_status', 'ms_bookings_status',
-  'service_level_report', 'call_activity_report', 'callrail_get_attributions',
-  'product_sync_status', 'report_export_status', 'report_data_export', 'coupon_grant_list', 'coupon_grant_get',
-  'automation_draft_list', 'focus_get_draft_pregeneration_report', 'teams_push_settings_get',
-  'call_center_team_breakdown', 'call_center_channel_breakdown', 'outbound_activity_for_contact',
-  'integration_skill_logs', 'support_integration_logs', 'site_integration_logs', 'magento_activity_logs',
-  'support_site_deployments', 'support_schedule_adherence', 'support_site_agents', 'support_site_activity',
-  'chat_intelligence_themes', 'chat_intelligence_recommendations', 'index_move_preview', 'index_split_preview',
-  'canned_learning_suggestions', 'canned_learning_teams', 'canned_learning_edit_summary',
-  'chat_topics_group_suggestions', 'chat_topics_suggestions', 'enterprise_reports', 'image_analysis_limits',
-  'avatar_session_readiness', 'recruiting_ats_failures', 'jobboard_application_history',
-  'recruiting_download_resume', 'routing_inactivity_transfers', 'entitlement_enterprise_reports_package',
-  'compliance_attestation', 'livefluence_conversion_advisor', 'copilot_studio_ask',
-  'skill_routing_simulate', 'squarespace_test_connection', 'woocommerce_logs', 'site_builder_connect_info',
+  'activity_logs', 'ai_field_extraction_fields', 'keyword_intelligence_top',
+  'keyword_intelligence_conversations', 'knowledge_advisor_advise', 'quality_sentiment',
+  'quality_agent_performance', 'quality_low_scores', 'quality_calibration', 'appointments_find_open_slots',
+  'appointments_list', 'compliance_redaction_test', 'compliance_status', 'compliance_signatures',
+  'compliance_redaction_events', 'compliance_redaction_status', 'shopify_widget_activation_url',
+  'klaviyo_savings_calculator', 'routing_simulate_inactivity', 'outlook_calendar_get_available_range',
+  'ms_bookings_check_availability_range', 'copilot_studio_test', 'notion_test_token',
+  'teams_phone_test_config', 'webflow_test_config', 'magento_test_connection', 'scraper_verify_token',
+  'kb_advise_knowledge_strategy', 'index_move_status', 'index_mixed_content', 'index_search',
+  'netsuite_m2m_verify', 'bot_skill_usage', 'bot_recent_errors', 'executive_brief', 'friction_radar',
+  'kpi_snapshot', 'site_info', 'case_board', 'case_list_types', 'ivr_agent_availability', 'contactlist_get',
+  'service_level_report', 'call_activity_report', 'callrail_get_attributions', 'product_sync_status',
+  'report_export_status', 'report_data_export', 'automation_draft_list',
+  'focus_get_draft_pregeneration_report', 'teams_push_settings_get', 'call_center_team_breakdown',
+  'call_center_channel_breakdown', 'outbound_activity_for_contact', 'integration_skill_logs',
+  'magento_activity_logs', 'chat_intelligence_themes', 'chat_intelligence_recommendations',
+  'index_move_preview', 'index_split_preview', 'canned_learning_suggestions', 'canned_learning_teams',
+  'canned_learning_edit_summary', 'chat_topics_group_suggestions', 'chat_topics_suggestions',
+  'enterprise_reports', 'recruiting_ats_failures', 'jobboard_application_history',
+  'recruiting_download_resume', 'routing_inactivity_transfers', 'compliance_attestation',
+  'copilot_studio_ask', 'skill_routing_simulate', 'squarespace_test_connection', 'woocommerce_logs',
+  'site_builder_connect_info',
 ]);
 
 // Write tools that are additive even though their name carries a destructive-looking token.
 const NON_DESTRUCTIVE_EXPLICIT = new Set([
-  'safety_settings_test', 'safety_need_help', 'canned_learning_record_edit', 'hangfire_retry_job',
-  'netsuite_suiteapp_download', 'chat_topics_reclassify',
+  'safety_settings_test', 'safety_need_help', 'canned_learning_record_edit', 'netsuite_suiteapp_download',
+  'chat_topics_reclassify',
 ]);
 
 const DESTRUCTIVE_TOKENS = new Set([
@@ -93,14 +82,12 @@ const NOT_IDEMPOTENT_TOKENS = new Set([
 ]);
 
 // Tools that reach a system outside the caller's Velaro account (third-party APIs, email/SMS/chat delivery, CRMs).
-const OPEN_WORLD = new RegExp('^(' + [
-  'calendly', 'acuity', 'outlook', 'ms_bookings', 'bigcommerce', 'shopify', 'magento', 'sap', 'netsuite',
-  'monday', 'notion', 'teams', 'slack', 'webflow', 'klaviyo', 'callrail', 'copilot_studio', 'scraper',
-  'site_scraper', 'apple', 'mobile_ota', 'code_push', 'jobboard', 'recruiting', 'payment_recovery',
-  'pickup_notify', 'email_queue_replay', 'email_inbox', 'entitlement_sync_stripe', 'logs_loggly',
-  'logs_appinsights', 'livefluence', 'telephony', 'kb_capture_screenshot', 'business_action',
-  'sitesync', 'email_delivery', 'campaign_sender_auth', 'ivr_update_line',
-].join('|') + ')');
+const OPEN_WORLD_PREFIXES = [
+  'outlook', 'ms_bookings', 'shopify', 'magento', 'netsuite', 'monday', 'notion', 'teams', 'slack',
+  'webflow', 'klaviyo', 'callrail', 'copilot_studio', 'scraper', 'apple', 'jobboard', 'recruiting',
+  'payment_recovery', 'pickup_notify', 'telephony', 'business_action', 'campaign_sender_auth',
+  'ivr_update_line',
+];
 
 const ACRONYMS = {
   kb: 'KB', ai: 'AI', ivr: 'IVR', sap: 'SAP', crm: 'CRM', sse: 'SSE', api: 'API', cti: 'CTI', m2m: 'M2M',
@@ -117,29 +104,45 @@ export function titleFor(name) {
     .join(' ');
 }
 
-export function annotationsFor(name) {
-  const t = tokens(name);
-  const has = (set) => t.some((x) => set.has(x));
-  const readOnly = READ_ONLY_EXPLICIT.has(name)
-    || (!MUTATING.has(name) && has(READ_TOKENS) && !has(DESTRUCTIVE_TOKENS) && !has(ADDITIVE_TOKENS));
-  const openWorldHint = OPEN_WORLD.test(name);
-  if (readOnly) {
-    return { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint };
+// Builds the rule set. The public package uses the base rules only; mcp/staff-tool-annotations.js (never
+// published) adds the staff tools' entries, so no staff tool name ships in this file (guard:
+// scripts/validate-mcp-no-staff-tools.js).
+export function makeAnnotator(extra = {}) {
+  const mutating = new Set([...MUTATING, ...(extra.mutating ?? [])]);
+  const readOnlyExplicit = new Set([...READ_ONLY_EXPLICIT, ...(extra.readOnly ?? [])]);
+  const nonDestructiveExplicit = new Set([...NON_DESTRUCTIVE_EXPLICIT, ...(extra.nonDestructive ?? [])]);
+  const openWorld = new RegExp('^(' + [...OPEN_WORLD_PREFIXES, ...(extra.openWorldPrefixes ?? [])].join('|') + ')');
+
+  function annotationsFor(name) {
+    const t = tokens(name);
+    const has = (set) => t.some((x) => set.has(x));
+    const readOnly = readOnlyExplicit.has(name)
+      || (!mutating.has(name) && has(READ_TOKENS) && !has(DESTRUCTIVE_TOKENS) && !has(ADDITIVE_TOKENS));
+    const openWorldHint = openWorld.test(name);
+    if (readOnly) {
+      return { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint };
+    }
+    const additive = nonDestructiveExplicit.has(name) || (has(ADDITIVE_TOKENS) && !has(DESTRUCTIVE_TOKENS));
+    return {
+      readOnlyHint: false,
+      destructiveHint: !additive,
+      idempotentHint: !has(NOT_IDEMPOTENT_TOKENS),
+      openWorldHint,
+    };
   }
-  const additive = NON_DESTRUCTIVE_EXPLICIT.has(name) || (has(ADDITIVE_TOKENS) && !has(DESTRUCTIVE_TOKENS));
-  return {
-    readOnlyHint: false,
-    destructiveHint: !additive,
-    idempotentHint: !has(NOT_IDEMPOTENT_TOKENS),
-    openWorldHint,
-  };
-}
 
-// Returns the tool with `title` and `annotations` filled in; a hand-written value on the tool wins.
-export function withAnnotations(tool) {
-  return {
-    ...tool,
-    title: tool.title ?? titleFor(tool.name),
-    annotations: { ...annotationsFor(tool.name), ...(tool.annotations ?? {}) },
-  };
+  // Returns the tool with `title` and `annotations` filled in; a hand-written value on the tool wins.
+  function withAnnotations(tool) {
+    return {
+      ...tool,
+      title: tool.title ?? titleFor(tool.name),
+      annotations: { ...annotationsFor(tool.name), ...(tool.annotations ?? {}) },
+    };
+  }
+
+  return { annotationsFor, withAnnotations };
 }
+
+const BASE = makeAnnotator();
+export const annotationsFor = BASE.annotationsFor;
+export const withAnnotations = BASE.withAnnotations;

package/log-search.js

@@ -1,252 +0,0 @@
-// Complete Velaro Logger reads (2026-10-14).
-//
-// WHY: velaro-messaging's /superadmin/logs/search and /internal/logs/search silently under-reported text queries.
-// Proven live that day: q=[HttpFallback] over 3.9 h returned 0-2 rows while 136 existed, and q=AsrsNegotiateFailed
-// (no level) returned 0 while 4 existed. The AI-search path only saw the newest 1,000 candidates and its answer was
-// final; the exact path only saw the newest 5,000 rows of the window before filtering. Neither said so.
-//
-// TWO MODES, picked automatically from the first response:
-//  * CURSOR mode (server with velaro-messaging PR #2510, response carries `truncated`/`scannedRows`): the server scans the
-//    window newest-first applying level/site AND text (as an escaped regex, which also forces the exact path) while it
-//    scans, reports `truncated`, and returns `nextCursor` whenever more rows may exist. We follow the cursor until it is
-//    null, so a 2 h window is a handful of requests instead of hundreds.
-//  * BISECT mode (older server): never send q=; push level/site/etc server side; includeTotal=true reports
-//    totalCountCapped for a slice; a capped slice is bisected until none is capped; text is filtered client side.
-// Either way the result says COMPLETE or INCOMPLETE, so a 0 is never ambiguous. Hard caps: maxRequests and maxSeconds.
-//
-// KEEP IN SYNC: this file is duplicated byte for byte in mcp/log-search.js (the npm packages ship separately);
-// cli/lib/log-search.test.js fails if the two copies drift.
-
-const MIN_SLICE_MS = 2000;
-
-export const escapeRegex = (s) => String(s).replace(/[\\^$.*+?()[\]{}|]/g, '\\$&');
-
-const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
-const tsOf = (e) => { const t = Date.parse(e.timestamp ?? e.LogTimestamp ?? ''); return Number.isNaN(t) ? 0 : t; };
-
-/**
- * fetch that retries ONLY 429 (honouring Retry-After, seconds, capped at 30 s) for up to `retries` attempts and returns the final Response.
- * `init` may be a function so each attempt gets a fresh AbortSignal.
- */
-export async function fetchRetry429(url, init = {}, { retries = 3, fetchImpl = fetch, sleepImpl = sleep } = {}) {
-  for (let attempt = 0; ; attempt++) {
-    const res = await fetchImpl(url, typeof init === 'function' ? init() : init);
-    if (res.status === 429 && attempt < retries) {
-      // Number(null) is 0, which would turn a 429 without Retry-After into an immediate retry: a missing header means the 5 s default.
-      const raw = res.headers?.get?.('retry-after');
-      const ra = raw == null || raw === '' ? NaN : Number(raw);
-      await sleepImpl(Math.min(Number.isFinite(ra) && ra >= 0 ? ra : 5, 30) * 1000);
-      continue;
-    }
-    return res;
-  }
-}
-
-/** fetchRetry429 + JSON. Any non-2xx throws an Error carrying `.status` and the response text. */
-export async function fetchJsonRetry(url, init = {}, opts = {}) {
-  const res = await fetchRetry429(url, init, opts);
-  if (!res.ok) {
-    const err = new Error(`HTTP ${res.status}: ${(await res.text().catch(() => '')).slice(0, 400)}`);
-    err.status = res.status;
-    throw err;
-  }
-  return res.json();
-}
-
-/**
- * @param {object} o
- * @param {(query: string) => Promise<any>} o.fetchJson  GET `...search?<query>` and return parsed JSON (caller adds auth/timeout)
- * @param {Date} o.from
- * @param {Date} o.to
- * @param {object} [o.params]  server-side filters: level, siteId, source, integration, platform, environment, correlationId
- * @param {string} [o.contains] case-insensitive substring of the message
- * @param {string} [o.regex]    regex on the message
- * @param {string} [o.logger]   substring of the logger name
- * @param {number} [o.maxRequests=200]
- * @param {number} [o.maxSeconds=120]   wall-clock budget for the whole read
- * @param {number} [o.wanted=Infinity]  CURSOR mode: stop once this many matches were collected (newest first); the result is then `satisfied`
- */
-export async function completeLogSearch({ fetchJson, from, to, params = {}, contains, regex, logger, maxRequests = 200, maxSeconds = 120, wanted = Infinity }) {
-  const server = {};
-  for (const k of ['level', 'siteId', 'source', 'integration', 'platform', 'environment', 'correlationId']) {
-    if (params[k] !== undefined && params[k] !== null && params[k] !== '') server[k] = String(k === 'level' ? String(params[k]).toUpperCase() : params[k]);
-  }
-  const byId = new Map();
-  const unresolved = [];
-  const started = Date.now();
-  let requests = 0;
-  let slices = 0;
-  let scanned = 0;
-  let budgetExhausted = false;
-  let timeExhausted = false;
-
-  const canRequest = () => {
-    if (requests >= maxRequests) { budgetExhausted = true; return false; }
-    if ((Date.now() - started) / 1000 >= maxSeconds && requests > 0) { timeExhausted = true; return false; }
-    return true;
-  };
-  const norm = (r) => (Array.isArray(r) ? { entries: r } : (r || {}));
-  const add = (e) => byId.set(e.id ?? `${e.timestamp}|${e.message}`, e);
-
-  // ---- text handling shared by both modes ----
-  const textQ = regex ?? (contains ? escapeRegex(contains) : undefined);
-  const textLogger = logger ? escapeRegex(logger) : undefined;
-
-  // ---- probe: first CURSOR-mode page, doubles as the new-server detector ----
-  const cursorQuery = (cursor) => {
-    const q = new URLSearchParams({ from: from.toISOString(), to: to.toISOString(), take: '500', ...server });
-    if (textQ) q.set('q', textQ);
-    if (textLogger) q.set('logger', textLogger);
-    if (textQ || textLogger) q.set('regex', 'true'); // regex also forces the exact path (the AI-search path is never consulted)
-    q.set('fallthrough', 'false');
-    if (cursor) q.set('cursor', cursor);
-    return q.toString();
-  };
-
-  let mode = 'bisect';
-  let satisfied = false;
-  let cursorDone = false;
-
-  if (canRequest()) {
-    requests++;
-    const probe = norm(await fetchJson(cursorQuery(null)));
-    if (typeof probe.truncated === 'boolean') {
-      mode = 'cursor';
-      scanned += Number(probe.scannedRows ?? 0);
-      for (const e of probe.entries ?? []) add(e);
-      let page = probe;
-      let cursor = probe.nextCursor || null;
-      for (;;) {
-        // The ONLY way a cursor read is COMPLETE: the last page said truncated === false and carried no cursor. `truncated: true` with no
-        // cursor means the server stopped scanning (deadline/cap) and could not say where to continue: INCOMPLETE, never COMPLETE.
-        if (!cursor) {
-          if (page.truncated === false) cursorDone = true;
-          else unresolved.push('the server stopped scanning (truncated) without a cursor to continue from');
-          break;
-        }
-        if (byId.size >= wanted) { satisfied = true; break; }
-        if (!canRequest()) { unresolved.push(`cursor ${cursor} (${timeExhausted ? 'time budget' : 'request budget'})`); break; }
-        requests++;
-        const next = norm(await fetchJson(cursorQuery(cursor)));
-        scanned += Number(next.scannedRows ?? 0);
-        for (const e of next.entries ?? []) add(e);
-        if (next.nextCursor && next.nextCursor === cursor) {
-          unresolved.push('no progress: the server returned the cursor it was given (its scan budget ended before reaching any row)');
-          break;
-        }
-        page = next;
-        cursor = next.nextCursor || null;
-      }
-      slices = 1;
-    }
-  }
-
-  // ---- BISECT mode (older server) ----
-  if (mode === 'bisect' && !budgetExhausted) {
-    const call = async (a, b, cursor, total) => {
-      if (!canRequest()) return null;
-      requests++;
-      const q = new URLSearchParams({ from: a.toISOString(), to: b.toISOString(), take: '500', ...server });
-      if (total) q.set('includeTotal', 'true');
-      if (cursor) q.set('cursor', cursor);
-      return norm(await fetchJson(q.toString()));
-    };
-    const walk = async (a, b) => {
-      const r = await call(a, b, null, true);
-      if (!r) { unresolved.push(`${a.toISOString()}..${b.toISOString()} (${timeExhausted ? 'time' : 'request'} budget)`); return; }
-      if (r.totalCountCapped === true && (b - a) > MIN_SLICE_MS) {
-        const mid = new Date(a.getTime() + Math.floor((b - a) / 2));
-        await walk(a, mid);
-        await walk(mid, b);
-        return;
-      }
-      if (r.totalCountCapped === true) unresolved.push(`${a.toISOString()}..${b.toISOString()} (still capped at <=2s: a log storm; add level/site)`);
-      slices++;
-      scanned += Number(r.totalCount ?? (r.entries?.length ?? 0));
-      for (const e of r.entries ?? []) add(e);
-      let cursor = r.nextCursor;
-      while (cursor) {
-        const r2 = await call(a, b, cursor, false);
-        if (!r2) { unresolved.push(`${a.toISOString()}..${b.toISOString()} (budget while paging)`); break; }
-        for (const e of r2.entries ?? []) add(e);
-        cursor = r2.nextCursor;
-      }
-    };
-    await walk(from, to);
-  }
-
-  let rows = [...byId.values()];
-  const msg = (e) => String(e.message ?? e.Message ?? '');
-  if (mode === 'bisect') {
-    if (contains) { const c = contains.toLowerCase(); rows = rows.filter((e) => msg(e).toLowerCase().includes(c)); }
-    if (regex) { const re = new RegExp(regex, 'i'); rows = rows.filter((e) => re.test(msg(e))); }
-    if (logger) { const l = logger.toLowerCase(); rows = rows.filter((e) => String(e.logger ?? e.Logger ?? '').toLowerCase().includes(l)); }
-  }
-  rows.sort((x, y) => tsOf(y) - tsOf(x)); // compare as instants: fractional-second digit counts differ between rows
-
-  const complete = mode === 'cursor' ? (cursorDone && unresolved.length === 0) : (unresolved.length === 0 && !budgetExhausted && !timeExhausted);
-  return { entries: rows, fetched: byId.size, scanned, requests, slices, mode, complete, satisfied, unresolved, budgetExhausted, timeExhausted };
-}
-
-/** One line a human or an LLM can trust: says COMPLETE or INCOMPLETE and how much the SERVER actually scanned. */
-export function describeCompleteness(r) {
-  const base = `${r.entries.length} matched (${r.fetched} fetched; server scanned ${r.scanned} rows) in ${r.requests} request(s), ${r.mode} mode`;
-  if (r.satisfied) return `${base}; showing the newest matches, more may exist beyond what was asked for (stopped early on purpose).`;
-  return r.complete
-    ? `${base}; COMPLETE (the whole window was covered), so 0 matches means nothing was logged.`
-    : `${base}; INCOMPLETE (${r.unresolved.length} part(s) not covered${r.budgetExhausted ? ', request budget exhausted' : ''}${r.timeExhausted ? ', time budget exhausted' : ''}): narrow the window or add level/site; a short or empty result is NOT proof of absence.`;
-}
-
-/** For raw (server-side q=) responses: surfaces searchPath/scannedRows/truncated so a 0 is never ambiguous. */
-export function describeRawMeta(resp) {
-  if (!resp || Array.isArray(resp) || resp.scannedRows === undefined) {
-    return 'server did not report scan metadata (older deploy): treat an empty or short result as unverified, use the complete mode.';
-  }
-  const t = resp.truncated === true;
-  // exact=false: the answer involves the AI-search index, which is best-effort (written behind, can lag, misses text that starts mid-word).
-  const bestEffort = resp.exact === false ? ' exact=false (answered from the best-effort search index: it can lag and misses text that starts mid-word, so treat counts as a floor, not exact)' : '';
-  return `searchPath=${resp.searchPath} scannedRows=${resp.scannedRows} truncated=${t}${t ? ' (NOT proof of absence; continue with nextCursor or narrow the window)' : ''}${bestEffort}${resp.nextCursor ? ' nextCursor=present' : ''}`;
-}
-
-// ── Time window + raw query building (shared by server.js and staff-server.js velaro_logs_search) ──
-// Bug fixed 2026-10-21: the tool only honored `last` and silently ignored from/to, so an explicit
-// historical range returned the newest entries instead. from/to accept an ISO timestamp or a
-// relative duration (30m, 2h, 1d = that long ago). `to` defaults to now, `from` to to - last (2h).
-const DUR_RE = /^(\d+)(m|h|d)$/i;
-const durMs = (s) => {
-  const m = DUR_RE.exec(String(s).trim());
-  const n = parseInt(m[1], 10);
-  const u = m[2].toLowerCase();
-  return u === 'm' ? n * 60000 : u === 'h' ? n * 3600000 : n * 86400000;
-};
-function parseWhen(label, v, nowMs) {
-  const s = String(v).trim();
-  if (DUR_RE.test(s)) return new Date(nowMs - durMs(s));
-  const d = new Date(s);
-  if (Number.isNaN(d.getTime())) throw new Error(`Invalid ${label} "${v}": use an ISO timestamp (2026-10-20T00:00:00Z) or a relative duration like 2h.`);
-  return d;
-}
-export function resolveLogWindow(args = {}, nowMs = Date.now()) {
-  const given = (v) => v !== undefined && v !== null && String(v).trim() !== '';
-  const to = given(args.to) ? parseWhen('to', args.to, nowMs) : new Date(nowMs);
-  const lastMs = DUR_RE.test(String(args.last ?? '').trim()) ? durMs(args.last) : 2 * 3600000;
-  const from = given(args.from) ? parseWhen('from', args.from, nowMs) : new Date(to.getTime() - lastMs);
-  if (from.getTime() >= to.getTime()) throw new Error(`Invalid window: from (${from.toISOString()}) must be before to (${to.toISOString()}).`);
-  return { from, to };
-}
-
-// Query string for GET /superadmin/logs/search (same params as /internal/logs/search).
-export function buildRawLogQuery(args, from, to) {
-  const params = new URLSearchParams({ from: from.toISOString(), to: to.toISOString(), take: String(args.take ?? 50) });
-  if (args.q)             params.set('q',             args.q);
-  if (args.level)         params.set('level',         String(args.level).toUpperCase());
-  if (args.logger)        params.set('logger',        args.logger);
-  if (args.integration)   params.set('integration',   args.integration);
-  if (args.siteId)        params.set('siteId',        String(args.siteId));
-  if (args.source)        params.set('source',        args.source);
-  if (args.platform)      params.set('platform',      args.platform);
-  if (args.environment)   params.set('environment',   args.environment);
-  if (args.correlationId) params.set('correlationId', args.correlationId);
-  if (args.regex)         params.set('regex',         'true');
-  return params.toString();
-}