@velaro/mcp-server 0.6.93 → 0.6.95

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@velaro/mcp-server",
-  "version": "0.6.93",
+  "version": "0.6.95",
   "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": {

package/server.js

@@ -151,6 +151,18 @@ function extractLogEntries(response) {
   return [];
 }
 
+/**
+ * Body for PUT avatar/groups|workflows/{id}/override. Merge by default (only passed fields change, "" clears one);
+ * `replace: true` replaces the whole override. Mirrors cli/lib/commands/avatar.js.
+ */
+function avatarOverrideBody(args) {
+  const body = { merge: args.replace !== true };
+  for (const k of ['providerSlug', 'avatarId', 'personalityPresetSlug', 'voiceId', 'displayName', 'backgroundMode', 'backgroundValue']) {
+    if (args[k] !== undefined) body[k] = args[k];
+  }
+  return body;
+}
+
 async function messagingRequest(method, path, body) {
   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.'
@@ -1715,6 +1727,8 @@ For multiSelect dynamic options: the variable named in dynamicOptionsVariable mu
         v20_site_id:    { type: 'number', description: 'V20 site ID to migrate TO (defaults to the authenticated site)' },
         dry_run:        { type: 'boolean', description: 'Preview what would be created without creating. Default: false.' },
         enable:         { type: 'boolean', description: 'Enable created workflows immediately. Default: false.' },
+        include_non_routing: { type: 'boolean', description: 'Also migrate v10 rules with IsRouting=false (group-assignment rules). Default: false.' },
+        route_bot_groups_to_team: { type: 'boolean', description: 'Route to the v20 team named after the v10 group even if it had a v10 bot. Default: false.' },
         team_mappings:  { type: 'array',  description: 'Override auto-resolution: [{v10GroupId, v20TeamId}]', items: { type: 'object' } },
         ai_config_mappings: { type: 'array', description: 'Override auto-resolution: [{v10GroupId, v20AiConfigId}]', items: { type: 'object' } },
       },
@@ -1729,10 +1743,25 @@ For multiSelect dynamic options: the variable named in dynamicOptionsVariable mu
       properties: {
         v10_site_id: { type: 'number', description: 'V10 (Livefluence) site ID' },
         v20_site_id: { type: 'number', description: 'V20 site ID to match against (for name suggestions)' },
+        include_non_routing: { type: 'boolean', description: 'Also include v10 rules with IsRouting=false. Default: false.' },
       },
       required: ['v10_site_id'],
     },
   },
+  {
+    name: 'livefluence_create_teams',
+    description: 'Copy v10 (Livefluence) groups to v20 teams on a site. v10 is read-only; idempotent by name; "Default Group" maps to the site default team; members are not copied. Use dry_run=true first.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        v10_site_id: { type: 'number', description: 'V10 (Livefluence) site ID to copy FROM' },
+        v20_site_id: { type: 'number', description: 'V20 site ID to create teams on' },
+        group_names: { type: 'array', items: { type: 'string' }, description: 'Group names to copy (default: every non-deleted v10 group)' },
+        dry_run:     { type: 'boolean', description: 'Preview without creating. Default: false.' },
+      },
+      required: ['v10_site_id', 'v20_site_id'],
+    },
+  },
 
   // ── Smart Routing Engine ──────────────────────────────────────────────────
   {
@@ -3328,19 +3357,24 @@ For multiSelect dynamic options: the variable named in dynamicOptionsVariable mu
   },
   {
     name: 'avatar_get_group_effective',
-    description: 'Show the effective avatar settings for a group (group override field, else site default) and whether an override exists.',
-    inputSchema: { type: 'object', properties: { groupId: { type: 'number' } }, required: ['groupId'] },
+    description: 'Show the effective avatar settings (person, personality, voice, display name, backdrop) for a group, layered perWorkflow ?? perGroup ?? perSite. Pass workflowId too to see what a conversation in that workflow inside that group gets. Also returns whether each override exists.',
+    inputSchema: { type: 'object', properties: { groupId: { type: 'number', description: 'Team (group) id.' }, workflowId: { type: 'number', description: 'Optional workflow id to layer on top of the group.' } }, required: ['groupId'] },
   },
   {
     name: 'avatar_set_group_override',
-    description: 'Override avatar/personality/provider for one group. Omitted fields inherit the site default.',
+    description: 'Override the avatar person/personality/voice/display name/backdrop for one group (a group is a Team). Only the fields you pass change (merge); pass an empty string to clear one field back to the site default. A library avatarId always uses the velaro provider. Backdrop: backgroundMode none|color|gradient|image with backgroundValue (hex, "#a,#b", or an https image URL).',
     inputSchema: {
       type: 'object',
       properties: {
         groupId: { type: 'number' },
         providerSlug: { type: 'string' },
-        avatarId: { type: 'string' },
+        avatarId: { type: 'string', description: 'Library slug (see avatar_list_library), e.g. priya.' },
         personalityPresetSlug: { type: 'string' },
+        voiceId: { type: 'string', description: 'ElevenLabs voice id.' },
+        displayName: { type: 'string', description: 'Visitor-facing avatar name.' },
+        backgroundMode: { type: 'string', description: 'none | color | gradient | image. "none" = explicitly no backdrop.' },
+        backgroundValue: { type: 'string', description: 'Hex color, "#a,#b" gradient, or https image URL.' },
+        replace: { type: 'boolean', description: 'true = replace the whole override (omitted fields inherit) instead of merging.' },
       },
       required: ['groupId'],
     },
@@ -3350,9 +3384,38 @@ For multiSelect dynamic options: the variable named in dynamicOptionsVariable mu
     description: 'Reset one group to the site default avatar settings (removes its override).',
     inputSchema: { type: 'object', properties: { groupId: { type: 'number' } }, required: ['groupId'] },
   },
+  {
+    name: 'avatar_get_workflow_effective',
+    description: 'Show the effective avatar settings for a workflow (workflow override, else its group, else site). Pass groupId to include a group override beneath the workflow.',
+    inputSchema: { type: 'object', properties: { workflowId: { type: 'number' }, groupId: { type: 'number' } }, required: ['workflowId'] },
+  },
+  {
+    name: 'avatar_set_workflow_override',
+    description: 'Override the avatar person/personality/voice/display name/backdrop for one workflow (wins over its group and the site). Same fields and merge semantics as avatar_set_group_override. Example: library avatar priya with the Timken HR office backdrop https://admin.velaro.com/avatar-backdrops/timken-hr-office.png for the recruiter workflow.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        workflowId: { type: 'number' },
+        providerSlug: { type: 'string' },
+        avatarId: { type: 'string' },
+        personalityPresetSlug: { type: 'string' },
+        voiceId: { type: 'string' },
+        displayName: { type: 'string' },
+        backgroundMode: { type: 'string', description: 'none | color | gradient | image' },
+        backgroundValue: { type: 'string' },
+        replace: { type: 'boolean' },
+      },
+      required: ['workflowId'],
+    },
+  },
+  {
+    name: 'avatar_reset_workflow',
+    description: 'Reset one workflow to its group / site default avatar settings (removes its override).',
+    inputSchema: { type: 'object', properties: { workflowId: { type: 'number' } }, required: ['workflowId'] },
+  },
   {
     name: 'avatar_reset_all_overrides',
-    description: 'Reset ALL group overrides for the calling site back to the site default.',
+    description: 'Reset ALL group and workflow overrides for the calling site back to the site default.',
     inputSchema: { type: 'object', properties: {} },
   },
 
@@ -5177,18 +5240,138 @@ For multiSelect dynamic options: the variable named in dynamicOptionsVariable mu
       required: ['listingId'],
     },
   },
+  // -- Job Board hosted pages (package "job-board-hosted", default OFF: 403 for a site without it) --
+  {
+    name: 'jobboard_hosted_status',
+    description: 'Hosted public job pages for this site: is the package included, are the pages published, and the opaque board link, sitemap, Indeed feed and Google feed URLs (the feed URLs contain a secret key). Returns { entitled, enabled, boardUrl, sitemapUrl, indeedFeedUrl, googleFeedUrl, publicApplyEnabled, eeocSelfIdAvailable, liveListings }; { entitled:false } without the package.',
+    inputSchema: { type: 'object', properties: {}, required: [] },
+  },
+  {
+    name: 'jobboard_hosted_set',
+    description: 'Publish or unpublish the hosted job pages (apply-if-present). enabled=true issues the opaque board link and feed key the first time. regenerateLink=true issues a NEW board link and every old hosted URL answers 404 (administrators only). Requires the Job Board hosted pages package (403 otherwise).',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        enabled: { type: 'boolean' },
+        regenerateLink: { type: 'boolean', description: 'Retire the current board link and issue a new one (administrators only)' },
+      },
+      required: [],
+    },
+  },
+  {
+    name: 'jobboard_rotate_feed_key',
+    description: 'Rotate the outbound feed key: the current Indeed and Google feed URLs stop working immediately and the response carries the new ones. Administrators only; requires the Job Board hosted pages package (403 otherwise).',
+    inputSchema: { type: 'object', properties: {}, required: [] },
+  },
+  {
+    name: 'jobboard_set_listing_pay',
+    description: 'Set or clear the pay range of a job listing (pay transparency): shown on the hosted page and in its schema.org baseSalary. A manual value is never overwritten by a feed sync. Pass clear=true to remove it. Requires the Job Board hosted pages package (403 otherwise); 404 for an id that is not on this site.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        listingId: { type: 'number' },
+        min: { type: 'number', description: 'Minimum (or only) amount, greater than 0' },
+        max: { type: 'number', description: 'Maximum amount, at least min (optional)' },
+        currency: { type: 'string', description: '3-letter ISO code, default USD' },
+        period: { type: 'string', description: 'Hour | Day | Week | Month | Year' },
+        clear: { type: 'boolean', description: 'Remove the stated pay' },
+      },
+      required: ['listingId'],
+    },
+  },
   {
     name: 'jobboard_move_application_stage',
-    description: 'Move a candidate application to a new HR/agency-side pipeline stage on the applicant Kanban board (Applied, Screened, Interview, Offer, Hired, Rejected).',
+    description: 'Move a candidate application to a new HR/agency-side pipeline stage on the applicant Kanban board. Default stages: Applied, Screened, Interview, Offer, Hired, Rejected; a site with the Job board pipeline package uses its own configured stage keys (see jobboard_pipeline_get). Optional note is recorded in the stage history.',
     inputSchema: {
       type: 'object',
       properties: {
         applicationId: { type: 'number' },
-        stage: { type: 'string', description: 'Applied | Screened | Interview | Offer | Hired | Rejected' },
+        stage: { type: 'string', description: 'A stage key from jobboard_pipeline_get (default list: Applied | Screened | Interview | Offer | Hired | Rejected)' },
+        note: { type: 'string', description: 'Optional note recorded in the stage history (2000 characters max)' },
       },
       required: ['applicationId', 'stage'],
     },
   },
+  // -- Job Board pipeline (package "job-board-pipeline", default OFF: 403 job_board_pipeline_not_entitled without it, except jobboard_pipeline_get) --
+  {
+    name: 'jobboard_pipeline_get',
+    description: 'The recruiter pipeline stages for this site. Returns { entitled, source: "default"|"caseType", caseTypeId, stages:[{key,label,color,applicantVisible,applicantLabel}] }. Without the Job board pipeline package it returns the default list with entitled:false (stage moves still work on the default stages).',
+    inputSchema: { type: 'object', properties: {}, required: [] },
+  },
+  {
+    name: 'jobboard_pipeline_set',
+    description: 'Replace the pipeline stages (1 to 12, unique keys up to 64 characters). Removing a stage that still holds applications is refused with a 400 naming the count; move them first. Requires the Job board pipeline package (403 otherwise). Applicants see only stages with applicantVisible=true (using applicantLabel or label); every other stage shows as In review.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        stages: {
+          type: 'array',
+          description: 'The full ordered stage list',
+          items: {
+            type: 'object',
+            properties: {
+              key: { type: 'string' },
+              label: { type: 'string' },
+              color: { type: 'string', description: '#rrggbb (optional)' },
+              applicantVisible: { type: 'boolean' },
+              applicantLabel: { type: 'string', description: 'Name applicants see (optional)' },
+            },
+            required: ['key', 'label'],
+          },
+        },
+      },
+      required: ['stages'],
+    },
+  },
+  {
+    name: 'jobboard_application_history',
+    description: 'Stage, note and assignment history of one application, newest first: { events:[{id,kind:"Stage"|"Note"|"Assign",fromStage,toStage,actorType:"User"|"ApiKey"|"CaseSync"|"System",actorId,at,note}] }. For an Assign event the new recruiter is in note (empty = unassigned) and toStage is only the stage at that time. Requires the Job board pipeline package (403 otherwise); 404 for an id not on this site.',
+    inputSchema: { type: 'object', properties: { applicationId: { type: 'number' } }, required: ['applicationId'] },
+  },
+  {
+    name: 'jobboard_application_note',
+    description: 'Add an internal note to an application (1 to 2000 characters). Never shown to the applicant. Requires the Job board pipeline package (403 otherwise).',
+    inputSchema: {
+      type: 'object',
+      properties: { applicationId: { type: 'number' }, note: { type: 'string' } },
+      required: ['applicationId', 'note'],
+    },
+  },
+  {
+    name: 'jobboard_application_assign',
+    description: 'Assign a recruiter to an application (free text up to 200 characters, for example an email). Pass assignedTo as null or an empty string to unassign. Requires the Job board pipeline package (403 otherwise).',
+    inputSchema: {
+      type: 'object',
+      properties: { applicationId: { type: 'number' }, assignedTo: { type: ['string', 'null'] } },
+      required: ['applicationId'],
+    },
+  },
+  {
+    name: 'jobboard_retention_get',
+    description: 'Applicant record retention settings: { enabled, dryRun, retentionDays, isFederalContractor, legalHold, floorDays, effectiveDays, lastRunAt, lastRunDeleted, lastRunWouldDelete }. Records are never deleted before 1 year (2 years for federal contractors; 29 CFR 1602.14), so effectiveDays is never below floorDays. Requires the Job board pipeline package (403 otherwise).',
+    inputSchema: { type: 'object', properties: {}, required: [] },
+  },
+  {
+    name: 'jobboard_retention_set',
+    description: 'Change retention settings (apply-if-present). retentionDays below the legal floor is accepted and the floor applies. legalHold=true stops all deletion. Administrators only; requires the Job board pipeline package (403 otherwise).',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        enabled: { type: 'boolean' },
+        dryRun: { type: 'boolean', description: 'Count only, never delete' },
+        retentionDays: { type: 'number' },
+        isFederalContractor: { type: 'boolean' },
+        legalHold: { type: 'boolean' },
+        confirm: { type: 'boolean', description: 'Required true when dryRun=false or legalHold=false (this can start real deletion or lift a hold)' },
+      },
+      required: [],
+    },
+  },
+  {
+    name: 'jobboard_retention_run',
+    description: 'Run retention now. dryRun defaults to true: counts what is due and deletes nothing. dryRun=false really deletes records past retention (never before the legal floor, never under a legal hold). Returns counts only: { dryRun, due, deleted, resumesDeleted, skippedLegalHold, floorDays }. Administrators only; requires the Job board pipeline package (403 otherwise).',
+    inputSchema: { type: 'object', properties: { dryRun: { type: 'boolean', description: 'Default true' }, confirm: { type: 'boolean', description: 'Required true when dryRun=false (permanently deletes records)' } }, required: [] },
+  },
 
   // ── Velaro Appointments ──────────────────────────────────────────────────────
   // Backend: server/Velaro.Messaging/Controllers/AppointmentsController.cs.
@@ -6924,7 +7107,10 @@ async function handleTool(name, args) {
 
     // ── Livefluence Migration ──────────────────────────────────────────────
     case 'livefluence_export': {
-      const qs = args.v20_site_id ? `?v20SiteId=${args.v20_site_id}` : '';
+      const params = [];
+      if (args.v20_site_id) params.push(`v20SiteId=${args.v20_site_id}`);
+      if (args.include_non_routing) params.push('includeNonRouting=true');
+      const qs = params.length ? `?${params.join('&')}` : '';
       const data = await api('GET', `/DatabaseTool/V10Export/${args.v10_site_id}${qs}`);
       const lines = [
         `V10 Site ${data.v10SiteId} — ${data.ruleCount} routing rule(s), ${data.groupCount} group(s)`,
@@ -6949,6 +7135,16 @@ async function handleTool(name, args) {
       return lines.join('\n');
     }
 
+    case 'livefluence_create_teams': {
+      const result = await api('POST', '/DatabaseTool/V10CreateTeams', {
+        v10SiteId:  args.v10_site_id,
+        v20SiteId:  args.v20_site_id,
+        dryRun:     args.dry_run ?? false,
+        groupNames: args.group_names ?? [],
+      });
+      return JSON.stringify(result, null, 2);
+    }
+
     case 'livefluence_seed_url_rules': {
       const result = await api('POST', '/DatabaseTool/V10SeedUrlRules', {
         siteId: args.site_id, aiConfigId: args.ai_config_id, dryRun: !!args.dry_run, rules: args.rules,
@@ -6962,6 +7158,8 @@ async function handleTool(name, args) {
         v20SiteId:        args.v20_site_id ?? null,
         dryRun:           args.dry_run  ?? false,
         enable:           args.enable   ?? false,
+        includeNonRouting:    args.include_non_routing ?? false,
+        routeBotGroupsToTeam: args.route_bot_groups_to_team ?? false,
         teamMappings:     args.team_mappings     ?? [],
         aiConfigMappings: args.ai_config_mappings ?? [],
       });
@@ -6977,6 +7175,7 @@ async function handleTool(name, args) {
         for (const item of result.createdItems) {
           lines.push(`  [#${item.priority}] ${item.ruleName}${item.workflowId ? ` → id=${item.workflowId}` : ''}`);
           lines.push(`    Action: ${item.action}${item.v2AiConfigId ? `, aiConfigId=${item.v2AiConfigId}` : ''}${item.v2TeamId ? `, teamId=${item.v2TeamId}` : ''}`);
+          for (const u of item.unconverted ?? []) lines.push(`    not converted: ${u}`);
         }
         lines.push('');
       }
@@ -8771,12 +8970,17 @@ async function handleTool(name, args) {
       return JSON.stringify(await messagingRequest('POST', '/avatar/site-default', {
         providerSlug: args.providerSlug, avatarId: args.avatarId, personalityPresetSlug: args.personalityPresetSlug }), null, 2);
     case 'avatar_get_group_effective':
-      return JSON.stringify(await messagingRequest('GET', `/avatar/groups/${Number(args.groupId)}/effective`), null, 2);
+      return JSON.stringify(await messagingRequest('GET', `/avatar/groups/${Number(args.groupId)}/effective${args.workflowId != null ? `?workflowId=${Number(args.workflowId)}` : ''}`), null, 2);
     case 'avatar_set_group_override':
-      return JSON.stringify(await messagingRequest('PUT', `/avatar/groups/${Number(args.groupId)}/override`, {
-        providerSlug: args.providerSlug, avatarId: args.avatarId, personalityPresetSlug: args.personalityPresetSlug }), null, 2);
+      return JSON.stringify(await messagingRequest('PUT', `/avatar/groups/${Number(args.groupId)}/override`, avatarOverrideBody(args)), null, 2);
     case 'avatar_reset_group':
       return JSON.stringify(await messagingRequest('DELETE', `/avatar/groups/${Number(args.groupId)}/override`), null, 2);
+    case 'avatar_get_workflow_effective':
+      return JSON.stringify(await messagingRequest('GET', `/avatar/workflows/${Number(args.workflowId)}/effective${args.groupId != null ? `?groupId=${Number(args.groupId)}` : ''}`), null, 2);
+    case 'avatar_set_workflow_override':
+      return JSON.stringify(await messagingRequest('PUT', `/avatar/workflows/${Number(args.workflowId)}/override`, avatarOverrideBody(args)), null, 2);
+    case 'avatar_reset_workflow':
+      return JSON.stringify(await messagingRequest('DELETE', `/avatar/workflows/${Number(args.workflowId)}/override`), null, 2);
     case 'avatar_reset_all_overrides':
       return JSON.stringify(await messagingRequest('POST', '/avatar/group-overrides/reset-all', {}), null, 2);
 
@@ -10512,10 +10716,115 @@ async function handleTool(name, args) {
       return JSON.stringify(r, null, 2);
     }
 
+    case 'jobboard_hosted_status': {
+      const r = await messagingGet('/Recruiting/Hosted');
+      return JSON.stringify(r, null, 2);
+    }
+    case 'jobboard_hosted_set': {
+      const body = {};
+      if (args.enabled !== undefined) body.enabled = Boolean(args.enabled);
+      if (args.regenerateLink) body.regenerateSlug = true;
+      if (!Object.keys(body).length) throw new Error('Specify enabled and/or regenerateLink (use jobboard_hosted_status to read).');
+      const r = await messagingPut('/Recruiting/Hosted', body);
+      return JSON.stringify(r, null, 2);
+    }
+    case 'jobboard_rotate_feed_key': {
+      const r = await messagingPost('/Recruiting/Hosted/FeedKey/Rotate', {});
+      return JSON.stringify(r, null, 2);
+    }
+    case 'jobboard_set_listing_pay': {
+      const id = Number(args.listingId);
+      if (!Number.isInteger(id) || id <= 0) throw new Error('listingId must be a positive integer.');
+      let body;
+      if (args.clear) {
+        body = { clear: true };
+      } else {
+        const lo = Number(args.min);
+        if (args.min === undefined || !Number.isFinite(lo) || lo <= 0) throw new Error('min must be a number greater than 0 (or pass clear=true).');
+        body = { salaryMin: lo };
+        if (args.max !== undefined) {
+          const hi = Number(args.max);
+          if (!Number.isFinite(hi) || hi < lo) throw new Error('max must be a number greater than or equal to min.');
+          body.salaryMax = hi;
+        }
+        const cur = String(args.currency ?? 'USD').trim().toUpperCase();
+        if (!/^[A-Z]{3}$/.test(cur)) throw new Error('currency must be a 3-letter ISO code such as USD.');
+        body.salaryCurrency = cur;
+        const per = ['Hour', 'Day', 'Week', 'Month', 'Year'].find((p) => p.toLowerCase() === String(args.period ?? '').trim().toLowerCase());
+        if (!per) throw new Error('period must be one of: Hour, Day, Week, Month, Year.');
+        body.salaryPeriod = per;
+      }
+      const r = await messagingPut(`/Recruiting/Jobs/${id}/Pay`, body);
+      return JSON.stringify(r, null, 2);
+    }
+
     case 'jobboard_move_application_stage': {
-      const app = await messagingPut(`/Recruiting/Applications/${args.applicationId}/Stage`, { stage: args.stage });
+      const id = Number(args.applicationId);
+      if (!Number.isInteger(id) || id <= 0) throw new Error('applicationId must be a positive integer.');
+      const stage = String(args.stage ?? '').trim();
+      if (!stage) throw new Error('stage is required.');
+      const body = { stage };
+      if (args.note !== undefined && String(args.note).trim()) {
+        if (String(args.note).length > 2000) throw new Error('note must be 2000 characters or fewer.');
+        body.note = String(args.note).trim();
+      }
+      const app = await messagingPut(`/Recruiting/Applications/${id}/Stage`, body);
       return JSON.stringify(app, null, 2);
     }
+    case 'jobboard_pipeline_get': {
+      return JSON.stringify(await messagingGet('/Recruiting/Pipeline'), null, 2);
+    }
+    case 'jobboard_pipeline_set': {
+      const stages = args.stages;
+      if (!Array.isArray(stages) || stages.length < 1 || stages.length > 12) throw new Error('stages must be an array of 1 to 12 stages.');
+      const keys = new Set();
+      for (const s of stages) {
+        if (!s || typeof s.key !== 'string' || !s.key.trim() || s.key.length > 64) throw new Error('every stage needs a key (up to 64 characters).');
+        if (typeof s.label !== 'string' || !s.label.trim()) throw new Error(`stage ${s.key} needs a label.`);
+        if (keys.has(s.key)) throw new Error(`duplicate stage key: ${s.key}.`);
+        keys.add(s.key);
+      }
+      return JSON.stringify(await messagingPut('/Recruiting/Pipeline', { stages }), null, 2);
+    }
+    case 'jobboard_application_history': {
+      const id = Number(args.applicationId);
+      if (!Number.isInteger(id) || id <= 0) throw new Error('applicationId must be a positive integer.');
+      return JSON.stringify(await messagingGet(`/Recruiting/Applications/${id}/History`), null, 2);
+    }
+    case 'jobboard_application_note': {
+      const id = Number(args.applicationId);
+      if (!Number.isInteger(id) || id <= 0) throw new Error('applicationId must be a positive integer.');
+      const note = String(args.note ?? '').trim();
+      if (!note || note.length > 2000) throw new Error('note must be 1 to 2000 characters.');
+      return JSON.stringify(await messagingPost(`/Recruiting/Applications/${id}/Notes`, { note }), null, 2);
+    }
+    case 'jobboard_application_assign': {
+      const id = Number(args.applicationId);
+      if (!Number.isInteger(id) || id <= 0) throw new Error('applicationId must be a positive integer.');
+      const who = String(args.assignedTo ?? '').trim();
+      if (who.length > 200) throw new Error('assignedTo must be 200 characters or fewer.');
+      return JSON.stringify(await messagingPut(`/Recruiting/Applications/${id}/Assign`, { assignedTo: who || null }), null, 2);
+    }
+    case 'jobboard_retention_get': {
+      return JSON.stringify(await messagingGet('/Recruiting/Retention'), null, 2);
+    }
+    case 'jobboard_retention_set': {
+      const body = {};
+      for (const k of ['enabled', 'dryRun', 'isFederalContractor', 'legalHold']) if (args[k] !== undefined) body[k] = Boolean(args[k]);
+      if (args.retentionDays !== undefined) {
+        const n = Number(args.retentionDays);
+        if (!Number.isInteger(n) || n < 1 || n > 36500) throw new Error('retentionDays must be a whole number from 1 to 36500.');
+        body.retentionDays = n;
+      }
+      if (!Object.keys(body).length) throw new Error('Specify at least one retention setting (use jobboard_retention_get to read).');
+      if ((body.dryRun === false || body.legalHold === false) && args.confirm !== true) throw new Error('dryRun=false or legalHold=false can start real deletion of applicant records or lift a legal hold. Preview with jobboard_retention_run first, then repeat with confirm=true.');
+      return JSON.stringify(await messagingPut('/Recruiting/Retention', body), null, 2);
+    }
+    case 'jobboard_retention_run': {
+      const dry = args.dryRun === undefined ? true : Boolean(args.dryRun);
+      if (!dry && args.confirm !== true) throw new Error('dryRun=false permanently deletes applicant records past retention. Preview first (dryRun=true), then repeat with confirm=true.');
+      return JSON.stringify(await messagingPost(`/Recruiting/Retention/Run?dryRun=${dry ? 'true' : 'false'}`, {}), null, 2);
+    }
 
     // -- Velaro Appointments --
     case 'appointments_manual_book': {