@shuffl/api-contracts 0.1.0 → 0.2.1

package/dist/permissions.js

@@ -54,7 +54,7 @@ const foundation = [
     ],
     ['users.get', 'users:read', 'read', 'Read a person'],
     ['users.list', 'users:read', 'read', 'List people'],
-    ['workspaces.current', null, 'read', 'Read this token’s workspace'],
+    ['teams.current', null, 'read', 'Read this token’s team'],
 ];
 // Permissions checked by another Shuffl protocol rather than a public HTTP
 // procedure (#187): one API key reaches the MCP server only when it carries
@@ -65,13 +65,153 @@ const protocols = [
 export const protocolPermissionIds = protocols.map(([id]) => id);
 export const alwaysAllowedPermissions = [
     'permissions.list',
-    'workspaces.current',
+    'teams.current',
 ];
+// What an operation does, for the ones whose registry entry carries no
+// confirmation sentence (#1151). The API key picker, MCP tool list and
+// Mello's findActions all read it; a derived "Save" or "Get" left the
+// assistant unable to find a directory change by its words.
+const operationDescriptions = {
+    'access.get': "Read one person's workspace role and app access",
+    'access.slackWaiting': 'List Slack members waiting for access to Shuffl',
+    'assistant.conversations': 'List your conversations with Mello',
+    'assistant.delete': 'Delete one of your conversations with Mello',
+    'assistant.history': 'Read the messages in one of your conversations with Mello',
+    'assistant.send': 'Ask Mello a question in a conversation',
+    'assistant.stop': 'Stop an answer Mello is still writing',
+    'badges.decideRequest': 'Approve or decline a request for a badge',
+    'badges.hideOwn': 'Hide or show one of your badges on your profile',
+    'badges.ofPerson': "List a person's badges",
+    'badges.request': 'Ask for a badge',
+    'badges.revoke': 'Take a badge back from a person',
+    'badges.setHidden': 'Hide or show a badge for the whole workspace',
+    'celebrations.deliveries': 'List the celebration messages Shuffl sent',
+    'celebrations.mine': 'List the celebrations you received',
+    'celebrations.preferences': 'Read your birthday and work anniversary sharing preferences',
+    'celebrations.preview': 'Preview a celebration message',
+    'celebrations.program': 'Read the Celebrations settings',
+    'celebrations.refresh': 'Look for new birthdays and work anniversaries to celebrate now',
+    'celebrations.review': 'Review upcoming birthdays and work anniversaries',
+    'celebrations.savePreferences': 'Save your birthday and work anniversary sharing preferences',
+    'communities.archive': 'Archive a community',
+    'communities.join': 'Join a community',
+    'communities.leave': 'Leave a community',
+    'communities.members': "List a community's members",
+    'communities.ofPerson': 'List the communities a person belongs to',
+    'communities.setVisibility': 'Show or hide a community on your profile',
+    'communities.sync': "Sync a community's members with its Slack channel now",
+    'credentials.api.list': "List the workspace's API keys and what each can do",
+    'credentials.api.revoke': 'Revoke an API key',
+    'exports.team': "Export the workspace's programs, people and introduction history",
+    'hr.command': 'Claim, release, reply to, note, categorize, resolve or reopen an HR request',
+    'hr.get': 'Read one HR request and its messages',
+    'hr.list': 'List the HR requests you asked or can answer',
+    'hr.readiness': 'Check whether HR requests have a destination and someone to answer them',
+    'hr.renameTeam': 'Rename the HR team employees send requests to',
+    'hr.settings': 'Read the HR team name and who answers HR requests',
+    'hr.shareSources': 'List your recent Mello conversations that an HR request can include',
+    'identities.list': 'List the Slack and web accounts linked to a person',
+    'identities.slackAccounts': 'List Slack accounts that can be linked to people',
+    'identities.webAccounts': 'List web accounts that can be linked to people',
+    'integrations.authorize': 'Get the link that connects Slack, Google Drive or Notion to the workspace',
+    'invitations.cancel': 'Cancel a pending workspace invitation',
+    'invitations.candidates': 'List people in the directory who can be invited to the workspace',
+    'invitations.list': 'List pending workspace invitations',
+    'knowledge.connections.list': 'List connected Knowledge providers',
+    'knowledge.connections.request': 'Ask an administrator to connect a Knowledge source',
+    'knowledge.connections.requests': 'List requests to connect a Knowledge source',
+    'knowledge.policies.coverage': 'Check which common HR policies Knowledge covers',
+    'knowledge.sources.get': 'Read a Knowledge source',
+    'knowledge.sources.history': "List a Knowledge source's versions",
+    'knowledge.sources.importWebsite': 'Import a website page into Knowledge for review',
+    'knowledge.sources.list': 'List Knowledge sources',
+    'knowledge.sources.refresh': 'Refresh a Knowledge source from its connected provider',
+    'knowledge.sources.save': 'Save a Knowledge source draft',
+    'knowledge.sources.search': 'Search Knowledge sources by title',
+    'knowledge.sources.withdraw': 'Withdraw a published Knowledge source',
+    'knowledge.uploads.appendPart': 'Upload the next part of a Knowledge file',
+    'knowledge.uploads.complete': 'Finish a Knowledge file upload and start reading it',
+    'knowledge.uploads.create': 'Start uploading a file to Knowledge',
+    'knowledge.uploads.get': 'Read the progress of a Knowledge file upload',
+    'knowledge.uploads.retry': 'Retry reading a Knowledge file that failed',
+    'notifications.preferences': 'Read your notification preferences',
+    'notifications.save': 'Save a notification preference',
+    'onboarding.answerCheckIn': 'Answer your onboarding program’s help check-in: all good, or ask HR for help',
+    'onboarding.assignBuddy': 'Assign an onboarding buddy to a new hire',
+    'onboarding.candidates': 'List people who could be enrolled in onboarding',
+    'onboarding.enrollmentPreview': 'Preview enrolling a new hire in onboarding',
+    'onboarding.mine': 'Read your own onboarding plan and buddy asks',
+    'onboarding.person': "Read a new hire's onboarding plan",
+    'onboarding.previewEnrollment': 'Preview the onboarding steps for a new hire',
+    'onboarding.program': 'Read the Onboarding program settings',
+    'onboarding.remove': 'Remove a new hire from onboarding',
+    'onboarding.respondBuddy': 'Accept or decline being an onboarding buddy',
+    'onboarding.retry': 'Retry a failed onboarding step',
+    'onboarding.update': "Change a new hire's onboarding start date or time zone",
+    'operations.activity': "Read the workspace's recent audit activity",
+    'operations.status': 'Read the workspace delivery and provider health summary',
+    'profiles.cover.delete': 'Remove your profile cover picture',
+    'profiles.photo.delete': 'Remove your profile photo',
+    'profiles.positions.delete': 'Remove a past position from your profile',
+    'profiles.positions.save': 'Add or change a past position on your profile',
+    'profiles.save': 'Save your own profile: pronouns, location, phone, bio, interests, links and what you are working on',
+    'programs.people': 'List the people in a program and whether they take part',
+    'programs.schedulePreview': "Preview a program's upcoming rounds",
+    'reports.answerFeedback': "Read feedback on Mello's answers",
+    'reports.connections': 'Read Connections insights',
+    'reports.knowledge': 'Read Knowledge activity',
+    'reports.knowledgeSource': 'Read activity for one Knowledge source',
+    'reports.needsYou': 'Read HR request and Knowledge draft insights',
+    'reports.onboarding': 'Read Onboarding insights',
+    'reports.overview': 'Read the workspace overview figures',
+    'reports.people': 'Read People insights: headcount, teams and growth',
+    'runs.details': 'Read one introduction round and its pairs',
+    'runs.history.get': 'Read one introduction round imported from the previous Shuffl',
+    'runs.history.list': 'List introduction rounds imported from the previous Shuffl',
+    'runs.list': "List a program's introduction rounds",
+    'support.assign': 'Assign a Shuffl support conversation',
+    'support.close': 'Close a Shuffl support conversation',
+    'support.create': 'Start a support conversation with Shuffl',
+    'support.get': 'Read one Shuffl support conversation',
+    'support.list': "List the workspace's support conversations with Shuffl",
+    'support.reply': 'Reply in a Shuffl support conversation',
+    'sync.current': 'Read the People sync provider, its last sync and what it found',
+    'sync.request': 'Ask for a People sync provider Shuffl does not support yet',
+    'sync.run': 'Sync People from the connected provider now',
+    'team.launchPost': 'Read the launch announcement for the workspace',
+    'teams.connectionPermissions': 'List connections whose permissions are behind what Shuffl asks for',
+    'teams.initialize': 'Finish setting up a new workspace',
+    'teams.rename': 'Rename the workspace',
+    'teams.saveAgentSetup': 'Choose the built-in assistant or an external agent for the workspace',
+    'teams.saveSlackJoinAccess': 'Choose whether Slack members can join Shuffl on their own',
+    'teams.saveSlackProfileLink': 'Turn the Shuffl profile link on Slack profiles on or off',
+    'teams.setup': "Read the workspace's setup checklist",
+    'teams.slackChannels': 'List community channels in the connected Slack and what each would become',
+    'teams.slackJoinAccess': 'Read whether Slack members can join Shuffl on their own',
+    'teams.slackProfileLink': 'Read the Shuffl profile link setting for Slack profiles',
+    'teams.status': 'Pause or resume the whole workspace',
+    'units.archive': 'Archive a team or department in the People directory',
+    'units.list': 'List the teams and departments in the People directory',
+    'units.save': 'Create or rename a team or department in the People directory',
+    'users.activity': "Read a person's recent activity in Shuffl",
+    'users.blockedPairs': 'List pairs of people who are never introduced',
+    'users.blockPair': 'Stop two people from being introduced to each other',
+    'users.details': "Read one person's People directory record",
+    'users.filterOptions': 'List the teams, departments, managers and locations People can filter by',
+    'users.managerHistory': "Read a person's recorded manager history",
+    'users.managers': 'List the managers in the People directory',
+    'users.page': 'List people in the People directory: search, or filter by team, department, manager, location, access or workspace role such as owner, admin or HR responder',
+    'users.participants': 'List the people who take part in programs',
+    'users.participation': 'Opt a person in to or out of a program',
+    'users.profile': "Edit a person's profile as an administrator",
+    'users.save': "Change someone's People directory record as an administrator: name, job title, manager, team, department or start date",
+};
 function definition(id, scope, access, description) {
     return {
         access,
         alwaysAllowed: alwaysAllowedPermissions.includes(id),
         description: description ??
+            operationDescriptions[id] ??
             id
                 .slice(id.lastIndexOf('.') + 1)
                 .replace(/([A-Z])/g, ' $1')
@@ -98,6 +238,41 @@ export const permissionDefinitionSchema = z.object({
     scope: scopeSchema.nullable(),
 });
 export const permissionById = new Map(permissionCatalog.map((p) => [p.id, p]));
+// #1082: what an outside agent needs to set a team up end to end. The
+// MCP consent screen offers these as one choice, and the agent setup guide
+// lists them. Each still runs with the connected person's role, and sending,
+// publishing or inviting is marked so the agent asks first.
+export const teamSetupPermissions = [
+    'teams.setup',
+    'teams.saveAgentSetup',
+    'teams.slackChannels',
+    'teams.moveSlackChannels',
+    'knowledge.uploads.create',
+    'knowledge.uploads.appendPart',
+    'knowledge.uploads.complete',
+    'knowledge.uploads.get',
+    'knowledge.sources.importWebsite',
+    'knowledge.sources.list',
+    'knowledge.sources.get',
+    'knowledge.sources.write',
+    'knowledge.sources.publish',
+    'assistant.send',
+    'invitations.create',
+    'invitations.list',
+    'pulse.program',
+    'pulse.saveProgram',
+    'channels.list',
+    'programs.options',
+    'programs.create',
+    'onboarding.program',
+    'onboarding.saveProgram',
+    'celebrations.program',
+    'celebrations.preview',
+    'celebrations.save',
+];
+// Writes that remove, stop or withdraw something. MCP marks them destructive
+// and Mello's Run control asks again before running one.
+export const destructiveOperation = /\.(archive|withdraw|revoke|cancel|cancelSubscription|close|delete|disconnect|unlink|pause|blockPair|stop|stopKnownFailures)$/;
 export function scopesForPermissions(permissions) {
     return [
         ...new Set(permissions

package/dist/schemas.d.ts

@@ -12,7 +12,7 @@ export declare const strategySchema: z.ZodEnum<{
     "unit-weighted-one-host-per-group": "unit-weighted-one-host-per-group";
     "within-unit": "within-unit";
 }>;
-export declare const scheduleSchema: z.ZodObject<{
+export declare const nativeScheduleSchema: z.ZodObject<{
     anchor: z.ZodString;
     frequency: z.ZodEnum<{
         days: "days";
@@ -26,6 +26,120 @@ export declare const scheduleSchema: z.ZodObject<{
     interval: z.ZodNumber;
     timezone: z.ZodString;
 }, z.core.$strip>;
+export declare const legacyMonthlyCalendarSchema: z.ZodObject<{
+    boundary: z.ZodEnum<{
+        end: "end";
+        start: "start";
+    }>;
+    hour: z.ZodNumber;
+    minute: z.ZodNumber;
+    second: z.ZodNumber;
+    timezone: z.ZodString;
+    weekday: z.ZodNumber;
+}, z.core.$strict>;
+export declare const legacyMonthlyScheduleSchema: z.ZodUnion<readonly [z.ZodObject<{
+    calendar: z.ZodObject<{
+        boundary: z.ZodEnum<{
+            end: "end";
+            start: "start";
+        }>;
+        hour: z.ZodNumber;
+        minute: z.ZodNumber;
+        second: z.ZodNumber;
+        timezone: z.ZodString;
+        weekday: z.ZodNumber;
+    }, z.core.$strict>;
+    frequency: z.ZodLiteral<"legacy-monthly">;
+    insufficientOptInsNotice: z.ZodObject<{
+        future: z.ZodNullable<z.ZodBoolean>;
+        pending: z.ZodNullable<z.ZodBoolean>;
+    }, z.core.$strict>;
+    interval: z.ZodLiteral<1>;
+    timezone: z.ZodString;
+    version: z.ZodLiteral<1>;
+    anchor: z.ZodISODateTime;
+    origin: z.ZodOptional<z.ZodLiteral<"source-pending">>;
+}, z.core.$strict>, z.ZodObject<{
+    calendar: z.ZodObject<{
+        boundary: z.ZodEnum<{
+            end: "end";
+            start: "start";
+        }>;
+        hour: z.ZodNumber;
+        minute: z.ZodNumber;
+        second: z.ZodNumber;
+        timezone: z.ZodString;
+        weekday: z.ZodNumber;
+    }, z.core.$strict>;
+    frequency: z.ZodLiteral<"legacy-monthly">;
+    insufficientOptInsNotice: z.ZodObject<{
+        future: z.ZodNullable<z.ZodBoolean>;
+        pending: z.ZodNullable<z.ZodBoolean>;
+    }, z.core.$strict>;
+    interval: z.ZodLiteral<1>;
+    timezone: z.ZodString;
+    version: z.ZodLiteral<1>;
+    anchor: z.ZodNullable<z.ZodISODateTime>;
+    origin: z.ZodLiteral<"operator-future-start">;
+}, z.core.$strict>]>;
+export declare const scheduleSchema: z.ZodUnion<readonly [z.ZodObject<{
+    anchor: z.ZodString;
+    frequency: z.ZodEnum<{
+        days: "days";
+        hours: "hours";
+        minutes: "minutes";
+        "monthly-date": "monthly-date";
+        "monthly-last-weekday": "monthly-last-weekday";
+        "monthly-weekday": "monthly-weekday";
+        weeks: "weeks";
+    }>;
+    interval: z.ZodNumber;
+    timezone: z.ZodString;
+}, z.core.$strip>, z.ZodUnion<readonly [z.ZodObject<{
+    calendar: z.ZodObject<{
+        boundary: z.ZodEnum<{
+            end: "end";
+            start: "start";
+        }>;
+        hour: z.ZodNumber;
+        minute: z.ZodNumber;
+        second: z.ZodNumber;
+        timezone: z.ZodString;
+        weekday: z.ZodNumber;
+    }, z.core.$strict>;
+    frequency: z.ZodLiteral<"legacy-monthly">;
+    insufficientOptInsNotice: z.ZodObject<{
+        future: z.ZodNullable<z.ZodBoolean>;
+        pending: z.ZodNullable<z.ZodBoolean>;
+    }, z.core.$strict>;
+    interval: z.ZodLiteral<1>;
+    timezone: z.ZodString;
+    version: z.ZodLiteral<1>;
+    anchor: z.ZodISODateTime;
+    origin: z.ZodOptional<z.ZodLiteral<"source-pending">>;
+}, z.core.$strict>, z.ZodObject<{
+    calendar: z.ZodObject<{
+        boundary: z.ZodEnum<{
+            end: "end";
+            start: "start";
+        }>;
+        hour: z.ZodNumber;
+        minute: z.ZodNumber;
+        second: z.ZodNumber;
+        timezone: z.ZodString;
+        weekday: z.ZodNumber;
+    }, z.core.$strict>;
+    frequency: z.ZodLiteral<"legacy-monthly">;
+    insufficientOptInsNotice: z.ZodObject<{
+        future: z.ZodNullable<z.ZodBoolean>;
+        pending: z.ZodNullable<z.ZodBoolean>;
+    }, z.core.$strict>;
+    interval: z.ZodLiteral<1>;
+    timezone: z.ZodString;
+    version: z.ZodLiteral<1>;
+    anchor: z.ZodNullable<z.ZodISODateTime>;
+    origin: z.ZodLiteral<"operator-future-start">;
+}, z.core.$strict>]>]>;
 export declare const keepApartRelationshipSchema: z.ZodEnum<{
     department: "department";
     "know-each-other": "know-each-other";
@@ -52,6 +166,7 @@ export declare const fineTuneSchema: z.ZodObject<{
         fof: "fof";
     }>;
 }, z.core.$strict>;
+export declare const maximumMatchingIterations = 1000;
 export declare const matchSchema: z.ZodObject<{
     fineTune: z.ZodOptional<z.ZodObject<{
         commonGround: z.ZodUnion<readonly [z.ZodLiteral<0>, z.ZodLiteral<1>, z.ZodLiteral<2>]>;
@@ -98,6 +213,7 @@ export declare const programInput: z.ZodObject<{
     channelId: z.ZodString;
     channelName: z.ZodString;
     includeBios: z.ZodBoolean;
+    includeSchedulingLink: z.ZodOptional<z.ZodBoolean>;
     intro: z.ZodString;
     match: z.ZodObject<{
         fineTune: z.ZodOptional<z.ZodObject<{
@@ -142,7 +258,7 @@ export declare const programInput: z.ZodObject<{
         }>>;
     }, z.core.$strict>;
     name: z.ZodString;
-    schedule: z.ZodObject<{
+    schedule: z.ZodUnion<readonly [z.ZodObject<{
         anchor: z.ZodString;
         frequency: z.ZodEnum<{
             days: "days";
@@ -155,7 +271,51 @@ export declare const programInput: z.ZodObject<{
         }>;
         interval: z.ZodNumber;
         timezone: z.ZodString;
-    }, z.core.$strip>;
+    }, z.core.$strip>, z.ZodUnion<readonly [z.ZodObject<{
+        calendar: z.ZodObject<{
+            boundary: z.ZodEnum<{
+                end: "end";
+                start: "start";
+            }>;
+            hour: z.ZodNumber;
+            minute: z.ZodNumber;
+            second: z.ZodNumber;
+            timezone: z.ZodString;
+            weekday: z.ZodNumber;
+        }, z.core.$strict>;
+        frequency: z.ZodLiteral<"legacy-monthly">;
+        insufficientOptInsNotice: z.ZodObject<{
+            future: z.ZodNullable<z.ZodBoolean>;
+            pending: z.ZodNullable<z.ZodBoolean>;
+        }, z.core.$strict>;
+        interval: z.ZodLiteral<1>;
+        timezone: z.ZodString;
+        version: z.ZodLiteral<1>;
+        anchor: z.ZodISODateTime;
+        origin: z.ZodOptional<z.ZodLiteral<"source-pending">>;
+    }, z.core.$strict>, z.ZodObject<{
+        calendar: z.ZodObject<{
+            boundary: z.ZodEnum<{
+                end: "end";
+                start: "start";
+            }>;
+            hour: z.ZodNumber;
+            minute: z.ZodNumber;
+            second: z.ZodNumber;
+            timezone: z.ZodString;
+            weekday: z.ZodNumber;
+        }, z.core.$strict>;
+        frequency: z.ZodLiteral<"legacy-monthly">;
+        insufficientOptInsNotice: z.ZodObject<{
+            future: z.ZodNullable<z.ZodBoolean>;
+            pending: z.ZodNullable<z.ZodBoolean>;
+        }, z.core.$strict>;
+        interval: z.ZodLiteral<1>;
+        timezone: z.ZodString;
+        version: z.ZodLiteral<1>;
+        anchor: z.ZodNullable<z.ZodISODateTime>;
+        origin: z.ZodLiteral<"operator-future-start">;
+    }, z.core.$strict>]>]>;
 }, z.core.$strip>;
 export declare const profileSchema: z.ZodObject<{
     asks: z.ZodOptional<z.ZodString>;
@@ -171,6 +331,7 @@ export declare const programPatch: z.ZodObject<{
     channelId: z.ZodOptional<z.ZodString>;
     channelName: z.ZodOptional<z.ZodString>;
     includeBios: z.ZodOptional<z.ZodBoolean>;
+    includeSchedulingLink: z.ZodOptional<z.ZodBoolean>;
     intro: z.ZodOptional<z.ZodString>;
     match: z.ZodOptional<z.ZodObject<{
         fineTune: z.ZodOptional<z.ZodNullable<z.ZodObject<{

package/dist/schemas.js

@@ -14,7 +14,7 @@ export const strategySchema = z.enum([
     'unit-weighted-multiple-hosts-per-group',
     'unit-lottery-weighted',
 ]);
-export const scheduleSchema = z
+export const nativeScheduleSchema = z
     .object({
     anchor: z.string().max(100),
     frequency: z.enum([
@@ -40,6 +40,61 @@ export const scheduleSchema = z
         });
     }
 });
+export const legacyMonthlyCalendarSchema = z
+    .strictObject({
+    boundary: z.enum(['start', 'end']),
+    hour: z.number().int().min(0).max(527),
+    minute: z.number().int().min(0).max(59),
+    second: z.number().int().min(0).max(59),
+    timezone: z.string().min(1).max(100),
+    weekday: z.number().int().min(0).max(6),
+})
+    .superRefine((rule, ctx) => {
+    try {
+        if (rule.boundary === 'end' && rule.hour > 23)
+            throw new Error();
+        if (/^[+-]/.test(rule.timezone))
+            throw new Error();
+        Temporal.Instant.fromEpochMilliseconds(0).toZonedDateTimeISO(rule.timezone);
+    }
+    catch {
+        ctx.addIssue({
+            code: 'custom',
+            message: 'Invalid preserved monthly calendar',
+        });
+    }
+});
+const monthlyScheduleFields = {
+    calendar: legacyMonthlyCalendarSchema,
+    frequency: z.literal('legacy-monthly'),
+    insufficientOptInsNotice: z.strictObject({
+        future: z.boolean().nullable(),
+        pending: z.boolean().nullable(),
+    }),
+    interval: z.literal(1),
+    timezone: z.string().min(1).max(100),
+    version: z.literal(1),
+};
+export const legacyMonthlyScheduleSchema = z
+    .union([
+    z.strictObject({
+        ...monthlyScheduleFields,
+        anchor: z.iso.datetime({ offset: true }),
+        origin: z.literal('source-pending').optional(),
+    }),
+    z.strictObject({
+        ...monthlyScheduleFields,
+        anchor: z.iso.datetime({ offset: true }).nullable(),
+        origin: z.literal('operator-future-start'),
+    }),
+])
+    .refine((rule) => rule.timezone === rule.calendar.timezone, 'Monthly timezone differs');
+// Parsing a persisted rule does not authorize creation; only the bound importer
+// can create legacy schedules. Ordinary writes may retain an existing rule.
+export const scheduleSchema = z.union([
+    nativeScheduleSchema,
+    legacyMonthlyScheduleSchema,
+]);
 export const keepApartRelationshipSchema = z.enum([
     'reporting-line',
     'team',
@@ -73,17 +128,19 @@ export const fineTuneSchema = z.strictObject({
         .enum(['any', 'fof', 'far'])
         .describe('any: anyone new. fof: friends of friends first (people in common). far: far corners first (nobody in common).'),
 });
+export const maximumMatchingIterations = 1000;
 export const matchSchema = z
     .strictObject({
     fineTune: fineTuneSchema.optional(),
     groupSize: z.number().int().min(2).max(8),
-    iterations: z.number().int().min(1).max(50),
+    iterations: z.number().int().min(1).max(maximumMatchingIterations),
     keepApart: keepApartSchema.optional(),
     maxGroupSize: z.number().int().min(2).max(8),
     strategy: strategySchema,
     unitIds: z.array(z.string().trim().min(1).max(200)).max(20).optional(),
     unitKind: z.enum(['department', 'team']).optional(),
 })
+    .refine((x) => !currentStrategies.includes(x.strategy) || x.iterations <= 50, 'Purpose matching supports at most 50 search attempts')
     .refine((x) => x.maxGroupSize >= x.groupSize, 'Maximum group size must be at least the target size')
     .refine((x) => (!x.strategy.startsWith('unit-') && x.strategy !== 'hosted') ||
     !!x.unitIds?.length, 'Choose at least one team or department')
@@ -102,6 +159,8 @@ export const programInput = z.object({
     channelId: z.string().regex(/^[CG][A-Z0-9]+$/),
     channelName: z.string().trim().min(1).max(100),
     includeBios: z.boolean(),
+    // Omission preserves an existing program's choice; new programs default on.
+    includeSchedulingLink: z.boolean().optional(),
     intro: z.string().trim().min(1).max(2000),
     match: matchSchema,
     name: z.string().trim().min(1).max(120),
@@ -125,12 +184,18 @@ export const programPatch = z.strictObject({
     channelId: programInput.shape.channelId.optional(),
     channelName: programInput.shape.channelName.optional(),
     includeBios: z.boolean().optional(),
+    includeSchedulingLink: z.boolean().optional(),
     intro: programInput.shape.intro.optional(),
     match: z
         .strictObject({
         fineTune: fineTuneSchema.partial().nullable().optional(),
         groupSize: z.number().int().min(2).max(8).optional(),
-        iterations: z.number().int().min(1).max(50).optional(),
+        iterations: z
+            .number()
+            .int()
+            .min(1)
+            .max(maximumMatchingIterations)
+            .optional(),
         keepApart: keepApartSchema.nullable().optional(),
         maxGroupSize: z.number().int().min(2).max(8).optional(),
         strategy: strategySchema.optional(),