feat(twenty-partners): submit-partner-application HTTP logic function (#21040)

## Summary Adds a public `POST /partner-applications` HTTP logic function on the twenty-partners SDK app that receives applications from the website wizard and idempotently upserts the Partner / Person / Company graph in the partners workspace. Also introduces the validated **Category** taxonomy on `partnerScope` (additive, prod-safe) plus the legacy→new migration tooling. Companion PR (website side): #21039 ### Logic function - `defineLogicFunction({ httpRouteTriggerSettings: { path: '/partner-applications', httpMethod: 'POST', isAuthRequired: false, forwardedRequestHeaders: ['x-application-secret'] } })`. - Authenticates via shared-secret header (`X-Application-Secret` ↔ `PARTNER_APPLICATION_SECRET` workspace variable). Twenty's `isAuthRequired: true` only accepts user-session JWTs, so the handler enforces auth itself. - Idempotent upsert keyed on `Person.emails.primaryEmail`: - missing email → create Company → Person → Partner - existing Person, no Partner → create Company + Partner, link - existing Person + Partner → update Partner fields; preserve staff-owned columns (`validationStage`, `reviewed`, `ranking`, `partnerTier`, `lastMatchAt`) by omitting them from the update - Create-time defaults preserved on resubmit: `slug = slugify(companyName)` ("YC Agency" → "yc-agency"), `reviewed = false`, `partnerTier = 'NEW'`. - Currency conversion to `{ amountMicros, currencyCode: 'USD' }` for `hourlyRate` + `projectBudgetMin`. ### Categories (`partnerScope`) — additive, prod-safe - Adds 5 validated category options — `ADVISORY`, `SOLUTIONING`, `DEVELOPMENT`, `HOSTING`, `SUPPORT` — to the `partnerScope` MULTI_SELECT **without removing** the legacy options (there is production data on them). Field relabeled **"Categories"**. The website form only emits the new values. - **Migration tooling** (run deliberately, *not* in CI): `scripts/migrate-partner-scope.ts` remaps existing records legacy→new — dry-run by default, `MIGRATE_APPLY=1` to write, two-pass (collect-then-apply, no mutate-while-paginating). `scripts/partner-scope-map.ts` is the single mapping source; `import-from-tft.ts` now routes imported scope through it so the TFT import never re-introduces retired values. Removing the legacy options is deferred until after the migration has run + been verified. ### applicationNotes - New `applicationNotes` TEXT field holds the wizard's single free-text "anything else" note (the handler passes it through directly). `deploymentExpertise` was dropped from the handler input/validation/builders (the column is retained for now, pending the same migration cleanup). ### Application variable - Declares `PARTNER_APPLICATION_SECRET` with `isSecret: true` so each workspace sets the value via Settings → Apps → Twenty Partners → Variables. Twenty encrypts at rest and merges the decrypted value into the handler's `process.env` at execution time (workspace value wins over container env). ### Code quality (from review) - One shared `slugify` (`scripts/slugify.ts`, the import's algorithm) used by both the handler and the import, so the `slug` identity key can't diverge across paths. - Unit-test tier: `vitest.unit.config.ts` (no `globalSetup`) + `yarn test:unit`, so the pure `mapLegacyScope` test runs without a live server (the integration suite stays server-backed). ## Demo 📹 _Screen recording of the wizard end-to-end (open → walk steps → submit → Partner record lands):_ https://github.com/user-attachments/assets/7458dd86-e3ff-47b5-9878-0eb134ff38e3 ### Tests - Integration tests against a local Twenty workspace: missing-/wrong-secret auth rejections, create flow (asserts slug + `reviewed: false` + `partnerTier: 'NEW'`), update-on-resubmit + staff-column preservation, new category values stored, `applicationNotes` stored, bad-input shape. - Pure `mapLegacyScope` unit test via `yarn test:unit` (no server). ## Test plan - [ ] Install / upgrade the app on the target workspace; set `PARTNER_APPLICATION_SECRET` in Settings → Apps → Twenty Partners → Variables - [ ] `curl -i -X POST <workspace-url>/s/partner-applications -H 'X-Application-Secret: <secret>' -H 'Content-Type: application/json' -d '{"firstName":"Test","lastName":"User","email":"test@example.com","companyName":"YC Agency","partnerScope":["ADVISORY"],"applicationNotes":"hi"}'` → `HTTP/1.1 201` + `{"ok":true,"created":true,"partnerId":"..."}` - [ ] Partner record shows `name: "YC Agency"`, `slug: "yc-agency"`, `validationStage: APPLICATION`, `reviewed: false`, `partnerTier: 'NEW'`, `partnerScope: ["ADVISORY"]`, `applicationNotes: "hi"` - [ ] Re-curl same email with `city: "Paris"` → `created: false`, `Partner.city` updated, staff-owned columns untouched - [ ] Wrong / missing secret → `200` + `{"ok":false,"reason":"unauthorized"}` - [ ] `yarn test:unit` green (no server); `yarn migrate:partner-scope` dry-run lists any legacy→new remaps without writing
2026-06-02 14:35:28 +04:00
parent 7e034f711f
commit 4f47885054
16 changed files with 1062 additions and 12 deletions
@@ -14,6 +14,7 @@
    "lint": "oxlint -c .oxlintrc.json .",
    "lint:fix": "oxlint --fix -c .oxlintrc.json .",
    "test": "vitest run",
+    "test:unit": "vitest run --config vitest.unit.config.ts",
    "test:watch": "vitest",
    "seed": "tsx src/scripts/seed.ts",
    "seed:prod": "ENV_FILE=.env.prod tsx src/scripts/seed.ts",
@@ -22,11 +23,14 @@
    "import:dryrun": "tsx src/scripts/import-from-tft.ts",
    "import:dryrun:prod": "ENV_FILE=.env.prod tsx src/scripts/import-from-tft.ts",
    "import:apply": "IMPORT_APPLY=1 tsx src/scripts/import-from-tft.ts",
-    "import:apply:prod": "ENV_FILE=.env.prod IMPORT_APPLY=1 tsx src/scripts/import-from-tft.ts"
+    "import:apply:prod": "ENV_FILE=.env.prod IMPORT_APPLY=1 tsx src/scripts/import-from-tft.ts",
+    "migrate:partner-scope": "tsx src/scripts/migrate-partner-scope.ts",
+    "migrate:partner-scope:prod": "ENV_FILE=.env.prod tsx src/scripts/migrate-partner-scope.ts"
  },
  "dependencies": {
    "twenty-client-sdk": "2.4.0",
-    "twenty-sdk": "2.4.0"
+    "twenty-sdk": "2.4.0",
+    "zod": "^4.1.11"
  },
  "devDependencies": {
    "@types/node": "^24.7.2",
@@ -10,4 +10,12 @@ export default defineApplication({
  universalIdentifier: APPLICATION_UNIVERSAL_IDENTIFIER,
  displayName: APP_DISPLAY_NAME,
  description: APP_DESCRIPTION,
+  applicationVariables: {
+    PARTNER_APPLICATION_SECRET: {
+      universalIdentifier: '2026a052-9f01-4d18-b6a7-31c3a5b1c7d2',
+      description:
+        'Shared secret required in the X-Application-Secret header on POST /partner-applications. Must match the website route\'s PARTNER_APPLICATION_SECRET env var. Set per-workspace in Settings → Apps → Twenty Partners → Variables.',
+      isSecret: true,
+    },
+  },
 });
@@ -0,0 +1,250 @@
+import { CoreApiClient } from 'twenty-client-sdk/core';
+import { afterEach, beforeAll, describe, expect, it } from 'vitest';
+
+import {
+  handler,
+  type SubmitPartnerApplicationInput,
+  type SubmitPartnerApplicationResult,
+} from '../submit-partner-application.logic-function';
+
+const TEST_SECRET = 'test-secret-abc123';
+process.env.PARTNER_APPLICATION_SECRET = TEST_SECRET;
+
+const client = new CoreApiClient();
+
+const baseInput = (overrides: Partial<SubmitPartnerApplicationInput> = {}): SubmitPartnerApplicationInput => ({
+  firstName: 'Ada',
+  lastName: 'Lovelace',
+  email: 'ada.test@example.com',
+  companyName: 'Analytical Engines Ltd',
+  ...overrides,
+});
+
+const authedEvent = (input: SubmitPartnerApplicationInput) => ({
+  body: input,
+  headers: { 'x-application-secret': TEST_SECRET },
+});
+
+const createdPartnerIds: string[] = [];
+const createdPersonIds: string[] = [];
+const createdCompanyIds: string[] = [];
+
+async function cleanup(): Promise<void> {
+  for (const id of createdPartnerIds.splice(0)) {
+    await client.mutation({ destroyPartner: { __args: { id }, id: true } }).catch(() => {});
+  }
+  for (const id of createdPersonIds.splice(0)) {
+    await client.mutation({ destroyPerson: { __args: { id }, id: true } }).catch(() => {});
+  }
+  for (const id of createdCompanyIds.splice(0)) {
+    await client.mutation({ destroyCompany: { __args: { id }, id: true } }).catch(() => {});
+  }
+}
+
+async function trackCreated(result: SubmitPartnerApplicationResult): Promise<void> {
+  if (!result.ok) return;
+  createdPartnerIds.push(result.partnerId);
+  const fetched = await client.query({
+    partner: {
+      __args: { filter: { id: { eq: result.partnerId } } },
+      id: true,
+      company: { id: true },
+      persons: { edges: { node: { id: true } } },
+    },
+  });
+  const node = fetched.partner;
+  if (!node) return;
+  if (node.company) createdCompanyIds.push(node.company.id);
+  for (const edge of node.persons?.edges ?? []) createdPersonIds.push(edge.node.id);
+}
+
+beforeAll(async () => {
+  await client.query({ partners: { __args: { first: 1 }, edges: { node: { id: true } } } });
+});
+
+afterEach(async () => {
+  await cleanup();
+});
+
+describe('submit-partner-application handler — auth', () => {
+  it('returns unauthorized when the x-application-secret header is missing', async () => {
+    const result = await handler({ body: baseInput({ email: 'noauth@example.com' }), headers: {} });
+    expect(result.ok).toBe(false);
+    if (result.ok) return;
+    expect(result.reason).toBe('unauthorized');
+  });
+
+  it('returns unauthorized when the x-application-secret header is wrong', async () => {
+    const result = await handler({
+      body: baseInput({ email: 'badauth@example.com' }),
+      headers: { 'x-application-secret': 'nope' },
+    });
+    expect(result.ok).toBe(false);
+    if (result.ok) return;
+    expect(result.reason).toBe('unauthorized');
+  });
+});
+
+describe('submit-partner-application handler — upsert', () => {
+  it('creates Company, Person, and Partner on first submission and returns created: true', async () => {
+    const result = await handler(authedEvent(baseInput({ email: 'create.case@example.com', companyName: 'YC Agency' })));
+    await trackCreated(result);
+
+    expect(result.ok).toBe(true);
+    if (!result.ok) return;
+    expect(result.created).toBe(true);
+    expect(result.partnerId).toMatch(/^[0-9a-f-]{36}$/);
+
+    const partner = await client.query({
+      partner: {
+        __args: { filter: { id: { eq: result.partnerId } } },
+        id: true,
+        name: true,
+        slug: true,
+        validationStage: true,
+        reviewed: true,
+        partnerTier: true,
+        company: { id: true, name: true },
+        persons: { edges: { node: { id: true, name: { firstName: true, lastName: true }, emails: { primaryEmail: true } } } },
+      },
+    });
+    const node = partner.partner;
+    expect(node?.name).toBe('YC Agency');
+    expect(node?.slug).toBe('yc-agency');
+    expect(node?.validationStage).toBe('APPLICATION');
+    expect(node?.reviewed).toBe(false);
+    expect(node?.partnerTier).toBe('NEW');
+    expect(node?.company?.name).toBe('YC Agency');
+    expect(node?.persons?.edges).toHaveLength(1);
+    const personNode = node?.persons?.edges?.[0]?.node;
+    expect(personNode?.emails?.primaryEmail).toBe('create.case@example.com');
+    expect(personNode?.name?.firstName).toBe('Ada');
+    expect(personNode?.name?.lastName).toBe('Lovelace');
+  });
+
+  it('returns created: false and updates fields on resubmission for the same email', async () => {
+    const first = await handler(authedEvent(baseInput({ email: 'update.case@example.com', city: 'London' })));
+    await trackCreated(first);
+    expect(first.ok).toBe(true);
+    if (!first.ok) return;
+
+    const second = await handler(
+      authedEvent(
+        baseInput({
+          email: 'update.case@example.com',
+          city: 'Paris',
+          partnerScope: ['ADVISORY', 'SOLUTIONING'],
+          typeOfTeam: 'SOLO',
+          hourlyRate: 175,
+        }),
+      ),
+    );
+    expect(second.ok).toBe(true);
+    if (!second.ok) return;
+    expect(second.created).toBe(false);
+    expect(second.partnerId).toBe(first.partnerId);
+
+    const partner = await client.query({
+      partner: {
+        __args: { filter: { id: { eq: second.partnerId } } },
+        id: true,
+        city: true,
+        partnerScope: true,
+        typeOfTeam: true,
+        hourlyRate: { amountMicros: true, currencyCode: true },
+      },
+    });
+    const node = partner.partner;
+    expect(node?.city).toBe('Paris');
+    expect(node?.partnerScope).toEqual(['ADVISORY', 'SOLUTIONING']);
+    expect(node?.typeOfTeam).toBe('SOLO');
+    expect(node?.hourlyRate).toEqual({ amountMicros: 175_000_000, currencyCode: 'USD' });
+  });
+
+  it('preserves staff-owned columns (validationStage, ranking, reviewed) on resubmission', async () => {
+    const first = await handler(authedEvent(baseInput({ email: 'staff.preserve@example.com' })));
+    await trackCreated(first);
+    expect(first.ok).toBe(true);
+    if (!first.ok) return;
+
+    await client.mutation({
+      updatePartner: {
+        __args: {
+          id: first.partnerId,
+          data: { validationStage: 'VALIDATED', reviewed: true, ranking: 'RATING_4' },
+        },
+        id: true,
+      },
+    });
+
+    const second = await handler(authedEvent(baseInput({ email: 'staff.preserve@example.com', city: 'Berlin' })));
+    expect(second.ok).toBe(true);
+    if (!second.ok) return;
+
+    const partner = await client.query({
+      partner: {
+        __args: { filter: { id: { eq: second.partnerId } } },
+        validationStage: true,
+        reviewed: true,
+        ranking: true,
+        city: true,
+      },
+    });
+    const node = partner.partner;
+    expect(node?.validationStage).toBe('VALIDATED');
+    expect(node?.reviewed).toBe(true);
+    expect(node?.ranking).toBe('RATING_4');
+    expect(node?.city).toBe('Berlin');
+  });
+
+  it('accepts new category values and stores applicationNotes', async () => {
+    const result = await handler(
+      authedEvent(
+        baseInput({
+          email: 'cat.test@example.com',
+          partnerScope: ['ADVISORY', 'SOLUTIONING'],
+          applicationNotes: 'Workspace https://app.twenty.com/ws · refs: Acme',
+        }),
+      ),
+    );
+    expect(result.ok).toBe(true);
+    if (!result.ok) return;
+    await trackCreated(result);
+
+    const fetched = await client.query({
+      partner: {
+        __args: { filter: { id: { eq: result.partnerId } } },
+        partnerScope: true,
+        applicationNotes: true,
+      },
+    });
+    const node = fetched.partner;
+    expect(node?.partnerScope).toEqual(
+      expect.arrayContaining(['ADVISORY', 'SOLUTIONING']),
+    );
+    expect(node?.applicationNotes).toContain('Acme');
+  });
+
+  it('rejects a legacy scope value as invalid_input', async () => {
+    const result = await handler(
+      authedEvent(baseInput({ email: 'legacy@example.com', partnerScope: ['APPS'] })),
+    );
+    expect(result.ok).toBe(false);
+    if (result.ok) return;
+    expect(result.reason).toBe('invalid_input');
+  });
+
+  it('returns ok: false on malformed input (empty email)', async () => {
+    const result = await handler(
+      authedEvent({
+        firstName: 'Ada',
+        lastName: 'Lovelace',
+        email: '',
+        companyName: 'Analytical Engines Ltd',
+      }),
+    );
+    expect(result.ok).toBe(false);
+    if (result.ok) return;
+    expect(result.reason).toBe('invalid_input');
+  });
+});
@@ -0,0 +1,73 @@
+import { describe, expect, it } from 'vitest';
+
+import { submitPartnerApplicationSchema } from '../submit-partner-application.logic-function';
+
+const base = {
+  firstName: 'Ada',
+  lastName: 'Lovelace',
+  email: 'ada@example.com',
+  companyName: 'Analytical Engines',
+};
+
+describe('submitPartnerApplicationSchema', () => {
+  it('accepts a minimal valid application', () => {
+    expect(submitPartnerApplicationSchema.safeParse(base).success).toBe(true);
+  });
+
+  it('accepts the new partnerScope categories', () => {
+    const result = submitPartnerApplicationSchema.safeParse({
+      ...base,
+      partnerScope: ['ADVISORY', 'SOLUTIONING', 'HOSTING'],
+    });
+    expect(result.success).toBe(true);
+  });
+
+  it('rejects legacy / unknown partnerScope values', () => {
+    expect(
+      submitPartnerApplicationSchema.safeParse({ ...base, partnerScope: ['APPS'] })
+        .success,
+    ).toBe(false);
+  });
+
+  it('rejects an unknown typeOfTeam', () => {
+    expect(
+      submitPartnerApplicationSchema.safeParse({ ...base, typeOfTeam: 'FREELANCE' })
+        .success,
+    ).toBe(false);
+  });
+
+  it('rejects an unknown country but accepts a known one with languages', () => {
+    expect(
+      submitPartnerApplicationSchema.safeParse({ ...base, country: 'ATLANTIS' })
+        .success,
+    ).toBe(false);
+    expect(
+      submitPartnerApplicationSchema.safeParse({
+        ...base,
+        country: 'FRANCE',
+        languages: ['ENGLISH', 'FRENCH'],
+      }).success,
+    ).toBe(true);
+  });
+
+  it('requires a non-empty email and companyName', () => {
+    expect(
+      submitPartnerApplicationSchema.safeParse({ ...base, email: '' }).success,
+    ).toBe(false);
+    expect(
+      submitPartnerApplicationSchema.safeParse({ ...base, companyName: '' })
+        .success,
+    ).toBe(false);
+  });
+
+  it('accepts optional notes and commercials', () => {
+    const result = submitPartnerApplicationSchema.safeParse({
+      ...base,
+      applicationNotes: 'Looking forward to partnering.',
+      hourlyRate: 150,
+      projectBudgetMin: 5000,
+      skills: ['React', 'PostgreSQL'],
+    });
+    expect(result.success).toBe(true);
+  });
+});
@@ -0,0 +1,273 @@
+import { CoreApiClient, type CoreSchema } from 'twenty-client-sdk/core';
+import { defineLogicFunction } from 'twenty-sdk/define';
+import { z } from 'zod';
+
+import { slugify } from '../scripts/slugify';
+
+export const SUBMIT_PARTNER_APPLICATION_LOGIC_FUNCTION_ID =
+  '7b1e2c5f-3a14-4f7d-8e91-0b5e2a3c4d76';
+
+const PARTNER_COUNTRY_VALUES = [
+  'AFGHANISTAN','ALBANIA','ALGERIA','ANDORRA','ANGOLA','ANTIGUA_AND_BARBUDA','ARGENTINA','ARMENIA','AUSTRALIA','AUSTRIA','AZERBAIJAN','BAHAMAS','BAHRAIN','BANGLADESH','BARBADOS','BELARUS','BELGIUM','BELIZE','BENIN','BHUTAN','BOLIVIA','BOSNIA_AND_HERZEGOVINA','BOTSWANA','BRAZIL','BRUNEI','BULGARIA','BURKINA_FASO','BURUNDI','CAMBODIA','CAMEROON','CANADA','CAPE_VERDE','CENTRAL_AFRICAN_REPUBLIC','CHAD','CHILE','CHINA','COLOMBIA','COMOROS','CONGO','DR_CONGO','COSTA_RICA','CROATIA','CUBA','CYPRUS','CZECH_REPUBLIC','DENMARK','DJIBOUTI','DOMINICA','DOMINICAN_REPUBLIC','ECUADOR','EGYPT','EL_SALVADOR','EQUATORIAL_GUINEA','ERITREA','ESTONIA','ESWATINI','ETHIOPIA','FIJI','FINLAND','FRANCE','GABON','GAMBIA','GEORGIA','GERMANY','GHANA','GREECE','GRENADA','GUATEMALA','GUINEA','GUINEA_BISSAU','GUYANA','HAITI','HONDURAS','HUNGARY','ICELAND','INDIA','INDONESIA','IRAN','IRAQ','IRELAND','ISRAEL','ITALY','IVORY_COAST','JAMAICA','JAPAN','JORDAN','KAZAKHSTAN','KENYA','KIRIBATI','KOSOVO','KUWAIT','KYRGYZSTAN','LAOS','LATVIA','LEBANON','LESOTHO','LIBERIA','LIBYA','LIECHTENSTEIN','LITHUANIA','LUXEMBOURG','MADAGASCAR','MALAWI','MALAYSIA','MALDIVES','MALI','MALTA','MARSHALL_ISLANDS','MAURITANIA','MAURITIUS','MEXICO','MICRONESIA','MOLDOVA','MONACO','MONGOLIA','MONTENEGRO','MOROCCO','MOZAMBIQUE','MYANMAR','NAMIBIA','NAURU','NEPAL','NETHERLANDS','NEW_ZEALAND','NICARAGUA','NIGER','NIGERIA','NORTH_KOREA','NORTH_MACEDONIA','NORWAY','OMAN','PAKISTAN','PALAU','PALESTINE','PANAMA','PAPUA_NEW_GUINEA','PARAGUAY','PERU','PHILIPPINES','POLAND','PORTUGAL','QATAR','ROMANIA','RUSSIA','RWANDA','SAINT_KITTS_AND_NEVIS','SAINT_LUCIA','SAINT_VINCENT','SAMOA','SAN_MARINO','SAO_TOME_AND_PRINCIPE','SAUDI_ARABIA','SENEGAL','SERBIA','SEYCHELLES','SIERRA_LEONE','SINGAPORE','SLOVAKIA','SLOVENIA','SOLOMON_ISLANDS','SOMALIA','SOUTH_AFRICA','SOUTH_KOREA','SOUTH_SUDAN','SPAIN','SRI_LANKA','SUDAN','SURINAME','SWEDEN','SWITZERLAND','SYRIA','TAIWAN','TAJIKISTAN','TANZANIA','THAILAND','TIMOR_LESTE','TOGO','TONGA','TRINIDAD_AND_TOBAGO','TUNISIA','TURKEY','TURKMENISTAN','TUVALU','UGANDA','UKRAINE','UNITED_ARAB_EMIRATES','UNITED_KINGDOM','UNITED_STATES','URUGUAY','UZBEKISTAN','VANUATU','VATICAN','VENEZUELA','VIETNAM','YEMEN','ZAMBIA','ZIMBABWE',
+] as const;
+
+const PARTNER_LANGUAGE_VALUES = [
+  'ENGLISH','FRENCH','GERMAN','SPANISH','PORTUGUESE','ITALIAN','DUTCH','ARABIC','CHINESE','JAPANESE','RUSSIAN','HINDI',
+] as const;
+
+const PARTNER_SCOPE_VALUES = [
+  'ADVISORY','SOLUTIONING','DEVELOPMENT','HOSTING','SUPPORT',
+] as const;
+const PARTNER_TYPE_OF_TEAM_VALUES = ['SOLO','AGENCY'] as const;
+
+// The request contract. zod is the single source of truth: it validates the
+// incoming body at runtime and the input type is inferred from it, so the two
+// can never drift. Enum-valued fields are constrained to the same option sets
+// the Partner object accepts.
+export const submitPartnerApplicationSchema = z.object({
+  firstName: z.string().trim().min(1),
+  lastName: z.string(),
+  email: z.string().trim().min(1),
+  companyName: z.string().trim().min(1),
+  domainName: z.string().optional(),
+  linkedin: z.string().optional(),
+  city: z.string().optional(),
+  country: z.enum(PARTNER_COUNTRY_VALUES).optional(),
+  languages: z.array(z.enum(PARTNER_LANGUAGE_VALUES)).optional(),
+  typeOfTeam: z.enum(PARTNER_TYPE_OF_TEAM_VALUES).optional(),
+  partnerScope: z.array(z.enum(PARTNER_SCOPE_VALUES)).optional(),
+  skills: z.array(z.string()).optional(),
+  applicationNotes: z.string().optional(),
+  hourlyRate: z.number().optional(),
+  projectBudgetMin: z.number().optional(),
+  calendarLink: z.string().optional(),
+});
+
+export type SubmitPartnerApplicationInput = z.infer<
+  typeof submitPartnerApplicationSchema
+>;
+
+export type SubmitPartnerApplicationResult =
+  | { ok: true; created: boolean; partnerId: string }
+  | { ok: false; reason: string };
+
+function isNonEmptyString(value: unknown): value is string {
+  return typeof value === 'string' && value.trim().length > 0;
+}
+
+function toMicros(usd: number | undefined): { amountMicros: number; currencyCode: 'USD' } | undefined {
+  if (typeof usd !== 'number' || !Number.isFinite(usd) || usd < 0) return undefined;
+  return { amountMicros: Math.round(usd * 1_000_000), currencyCode: 'USD' };
+}
+
+function buildApplicationNotes(input: SubmitPartnerApplicationInput): string | null {
+  return isNonEmptyString(input.applicationNotes) ? input.applicationNotes.trim() : null;
+}
+
+// Mirrors the subset of Partner{Create,Update}Input this handler writes. The
+// enum-typed columns are narrowed from the validated string inputs below.
+type PartnerFieldsForUpsert = {
+  name: string;
+  linkedin?: { primaryLinkUrl: string };
+  city?: string;
+  country?: CoreSchema.PartnerCountryEnum;
+  languagesSpoken?: CoreSchema.PartnerLanguagesSpokenEnum[];
+  typeOfTeam?: CoreSchema.PartnerTypeOfTeamEnum;
+  partnerScope?: CoreSchema.PartnerPartnerScopeEnum[];
+  skills?: string[];
+  hourlyRate?: { amountMicros: number; currencyCode: 'USD' };
+  projectBudgetMin?: { amountMicros: number; currencyCode: 'USD' };
+  calendarLink?: { primaryLinkUrl: string };
+  applicationNotes?: string | null;
+};
+
+function buildPartnerFields(input: SubmitPartnerApplicationInput): PartnerFieldsForUpsert {
+  const fields: PartnerFieldsForUpsert = {
+    name: input.companyName.trim(),
+  };
+  if (isNonEmptyString(input.linkedin)) fields.linkedin = { primaryLinkUrl: input.linkedin.trim() };
+  if (isNonEmptyString(input.city)) fields.city = input.city.trim();
+  // validate() has already checked these against the allowed value sets, so
+  // narrowing the validated strings to their enum types here is sound.
+  if (input.country !== undefined) fields.country = input.country as CoreSchema.PartnerCountryEnum;
+  if (input.languages !== undefined && input.languages.length > 0)
+    fields.languagesSpoken = input.languages as CoreSchema.PartnerLanguagesSpokenEnum[];
+  if (input.typeOfTeam !== undefined) fields.typeOfTeam = input.typeOfTeam as CoreSchema.PartnerTypeOfTeamEnum;
+  if (input.partnerScope !== undefined && input.partnerScope.length > 0)
+    fields.partnerScope = input.partnerScope as CoreSchema.PartnerPartnerScopeEnum[];
+  if (input.skills !== undefined && input.skills.length > 0) fields.skills = input.skills.filter(isNonEmptyString);
+  const hourly = toMicros(input.hourlyRate);
+  if (hourly) fields.hourlyRate = hourly;
+  const min = toMicros(input.projectBudgetMin);
+  if (min) fields.projectBudgetMin = min;
+  if (isNonEmptyString(input.calendarLink)) fields.calendarLink = { primaryLinkUrl: input.calendarLink.trim() };
+  const notes = buildApplicationNotes(input);
+  if (notes !== null) fields.applicationNotes = notes;
+  return fields;
+}
+
+type SubmitPartnerApplicationEvent = {
+  headers?: Record<string, string | undefined>;
+  body?: unknown;
+};
+
+const APPLICATION_SECRET_HEADER = 'x-application-secret';
+
+export const handler = async (
+  event: SubmitPartnerApplicationEvent | SubmitPartnerApplicationInput,
+): Promise<SubmitPartnerApplicationResult> => {
+  // Accept either { body, headers } (HTTP) or a flat input object (direct call from tests).
+  const looksLikeEvent =
+    typeof event === 'object' &&
+    event !== null &&
+    ('body' in event || 'headers' in event);
+
+  const headers = looksLikeEvent
+    ? (event as SubmitPartnerApplicationEvent).headers ?? {}
+    : {};
+  const rawInput = looksLikeEvent
+    ? (event as SubmitPartnerApplicationEvent).body
+    : event;
+
+  // Shared-secret guard. The Twenty SDK's isAuthRequired flag only accepts
+  // user-session JWTs, not workspace API keys, so we authenticate at the
+  // handler level via a custom header allowlisted in forwardedRequestHeaders.
+  const expectedSecret = process.env.PARTNER_APPLICATION_SECRET;
+  if (!isNonEmptyString(expectedSecret)) {
+    return { ok: false, reason: 'unauthorized' };
+  }
+  const providedSecret = headers[APPLICATION_SECRET_HEADER];
+  if (providedSecret !== expectedSecret) {
+    return { ok: false, reason: 'unauthorized' };
+  }
+
+  const parsed = submitPartnerApplicationSchema.safeParse(rawInput);
+  if (!parsed.success) {
+    return { ok: false, reason: 'invalid_input' };
+  }
+  const input = parsed.data;
+
+  try {
+    const client = new CoreApiClient();
+    const email = input.email.trim();
+    const partnerFields = buildPartnerFields(input);
+
+    const personLookup = await client.query({
+      people: {
+        __args: {
+          filter: { emails: { primaryEmail: { eq: email } } },
+          first: 1,
+        },
+        edges: {
+          node: {
+            id: true,
+            partner: { id: true, company: { id: true } },
+          },
+        },
+      },
+    });
+
+    const existingEdge = personLookup.people?.edges?.[0]?.node;
+
+    if (existingEdge && existingEdge.partner) {
+      const partnerId = existingEdge.partner.id;
+      await client.mutation({
+        updatePartner: {
+          __args: { id: partnerId, data: partnerFields },
+          id: true,
+        },
+      });
+      await client.mutation({
+        updatePerson: {
+          __args: {
+            id: existingEdge.id,
+            data: {
+              name: { firstName: input.firstName.trim(), lastName: input.lastName.trim() },
+            },
+          },
+          id: true,
+        },
+      });
+      return { ok: true, created: false, partnerId };
+    }
+
+    const companyData: CoreSchema.CompanyCreateInput = { name: input.companyName.trim() };
+    if (isNonEmptyString(input.domainName)) {
+      companyData.domainName = { primaryLinkUrl: input.domainName.trim() };
+    }
+    const companyResult = await client.mutation({
+      createCompany: { __args: { data: companyData }, id: true },
+    });
+    const companyId = companyResult.createCompany?.id;
+    if (companyId === undefined) {
+      throw new Error('createCompany did not return an id');
+    }
+
+    const partnerResult = await client.mutation({
+      createPartner: {
+        __args: {
+          data: {
+            ...partnerFields,
+            slug: slugify(input.companyName),
+            validationStage: 'APPLICATION',
+            reviewed: false,
+            partnerTier: 'NEW',
+            companyId,
+          },
+        },
+        id: true,
+      },
+    });
+    const partnerId = partnerResult.createPartner?.id;
+    if (partnerId === undefined) {
+      throw new Error('createPartner did not return an id');
+    }
+
+    if (existingEdge) {
+      await client.mutation({
+        updatePerson: {
+          __args: {
+            id: existingEdge.id,
+            data: {
+              partnerId,
+              name: { firstName: input.firstName.trim(), lastName: input.lastName.trim() },
+            },
+          },
+          id: true,
+        },
+      });
+    } else {
+      await client.mutation({
+        createPerson: {
+          __args: {
+            data: {
+              name: { firstName: input.firstName.trim(), lastName: input.lastName.trim() },
+              emails: { primaryEmail: email },
+              partnerId,
+              companyId,
+            },
+          },
+          id: true,
+        },
+      });
+    }
+
+    return { ok: true, created: true, partnerId };
+  } catch (err) {
+    return { ok: false, reason: err instanceof Error ? err.message : String(err) };
+  }
+};
+
+export default defineLogicFunction({
+  universalIdentifier: SUBMIT_PARTNER_APPLICATION_LOGIC_FUNCTION_ID,
+  name: 'submit-partner-application',
+  description: 'Receive a partner application from the website and idempotently upsert Partner / Person / Company.',
+  timeoutSeconds: 15,
+  handler,
+  httpRouteTriggerSettings: {
+    path: '/partner-applications',
+    httpMethod: 'POST',
+    isAuthRequired: false,
+    forwardedRequestHeaders: [APPLICATION_SECRET_HEADER],
+  },
+});
@@ -84,7 +84,7 @@ export default defineObject({
      universalIdentifier: '500021ad-ca42-4fd3-8727-392dd26b722a',
      type: FieldType.MULTI_SELECT,
      name: 'partnerScope',
-      label: 'Partner Scope',
+      label: 'Categories',
      icon: 'IconListCheck',
      isNullable: true,
      options: [
@@ -93,6 +93,11 @@ export default defineObject({
        { id: 'c88bf189-8be4-4431-aa03-85928f8b2a52', value: 'DATA_MIGRATION', label: 'Data migration', position: 2, color: 'turquoise' },
        { id: 'a7fd9429-c26f-49ab-bf52-4d591f5ca7a0', value: 'HOSTING_ENVIRONMENT', label: 'Hosting environment', position: 3, color: 'purple' },
        { id: '9e416a39-05c6-4c80-9f36-99b5b60c26ec', value: 'WORKFLOWS', label: 'Workflows', position: 4, color: 'orange' },
+        { id: 'b1000001-0000-4000-8000-0000000000a1', value: 'ADVISORY', label: 'Advisory & Discovery', position: 5, color: 'blue' },
+        { id: 'b1000002-0000-4000-8000-0000000000a2', value: 'SOLUTIONING', label: 'Solutioning', position: 6, color: 'green' },
+        { id: 'b1000003-0000-4000-8000-0000000000a3', value: 'DEVELOPMENT', label: 'Custom Development', position: 7, color: 'turquoise' },
+        { id: 'b1000004-0000-4000-8000-0000000000a4', value: 'HOSTING', label: 'Hosting & Infrastructure', position: 8, color: 'purple' },
+        { id: 'b1000005-0000-4000-8000-0000000000a5', value: 'SUPPORT', label: 'Training & Adoption', position: 9, color: 'pink' },
      ],
    },
    {
@@ -471,6 +476,14 @@ export default defineObject({
      icon: 'IconFileText',
      isNullable: true,
    },
+    {
+      universalIdentifier: 'a0000011-0000-4000-8000-000000000011',
+      type: FieldType.TEXT,
+      name: 'applicationNotes',
+      label: 'Application Notes',
+      icon: 'IconClipboardText',
+      isNullable: true,
+    },
    {
      universalIdentifier: 'a0000010-0000-4000-8000-000000000010',
      type: FieldType.DATE_TIME,
@@ -0,0 +1,23 @@
+import { describe, expect, it } from 'vitest';
+
+import { mapLegacyScope } from '../partner-scope-map';
+
+describe('mapLegacyScope', () => {
+  it('maps each legacy value to its new category', () => {
+    expect(mapLegacyScope(['APPS'])).toEqual(['DEVELOPMENT']);
+    expect(mapLegacyScope(['DATA_MODEL'])).toEqual(['SOLUTIONING']);
+    expect(mapLegacyScope(['DATA_MIGRATION'])).toEqual(['SOLUTIONING']);
+    expect(mapLegacyScope(['WORKFLOWS'])).toEqual(['SOLUTIONING']);
+    expect(mapLegacyScope(['HOSTING_ENVIRONMENT'])).toEqual(['HOSTING']);
+  });
+
+  it('de-duplicates collapsed values', () => {
+    expect(mapLegacyScope(['DATA_MODEL', 'DATA_MIGRATION', 'WORKFLOWS'])).toEqual([
+      'SOLUTIONING',
+    ]);
+  });
+
+  it('passes through already-migrated values unchanged', () => {
+    expect(mapLegacyScope(['ADVISORY', 'HOSTING'])).toEqual(['ADVISORY', 'HOSTING']);
+  });
+});
@@ -27,6 +27,9 @@ config({ path: process.env.ENV_FILE ?? '.env.local' });

 import { CoreApiClient } from 'twenty-client-sdk/core';

+import { mapLegacyScope } from './partner-scope-map';
+import { slugify } from './slugify';
+
 const requireEnv = (name: string): string => {
  const value = process.env[name];
  if (!value) throw new Error(`Missing ${name} env var`);
@@ -99,13 +102,6 @@ const LOCAL_OPTIONS: Record<string, Set<string>> = {
  quoteStatus: new Set(['WIP', 'INTERVIEW_SCHEDULED', 'UNDER_CUSTOMER_PARTNER_REVIEW', 'APPROVED', 'REJECTED']),
 };

-const slugify = (s: string): string =>
-  s
-    .toLowerCase()
-    .trim()
-    .replace(/[^a-z0-9]+/g, '-')
-    .replace(/^-+|-+$/g, '');
-
 const edges = (result: any, key: string): any[] =>
  (result?.[key]?.edges ?? []).map((e: any) => e.node);

@@ -378,8 +374,11 @@ async function main() {
    // Timezone band -> geographic region(s). Unmapped/OTHER -> no region.
    const region = TIMEZONE_TO_REGION[p.partnerTimezone] ?? [];
    // A partner scoped for hosting is, by definition, a self-host expert.
-    const scope = Array.isArray(p.partnerScope) ? p.partnerScope : [];
-    const deploymentExpertise = scope.includes('HOSTING_ENVIRONMENT') ? ['SELF_HOST'] : [];
+    const rawScope = Array.isArray(p.partnerScope) ? p.partnerScope : [];
+    // Map legacy TFT categories to the validated set so the import never
+    // re-introduces retired values.
+    const scope = mapLegacyScope(rawScope);
+    const deploymentExpertise = rawScope.includes('HOSTING_ENVIRONMENT') ? ['SELF_HOST'] : [];
    const data: Record<string, unknown> = {
      name: [p.name?.firstName, p.name?.lastName].filter(Boolean).join(' ').trim() || 'Unknown partner',
      slug,
@@ -0,0 +1,79 @@
+// Remap legacy partnerScope values to the validated categories.
+//
+//   yarn migrate:partner-scope          # dry-run against .env.local
+//   MIGRATE_APPLY=1 yarn migrate:partner-scope
+//   yarn migrate:partner-scope:prod     # dry-run against .env.prod
+//
+// Adding the new options is done in partner.object.ts (additive). This script
+// rewrites existing records old→new so the old options can later be removed.
+import { config } from 'dotenv';
+config({ path: process.env.ENV_FILE ?? '.env.local' });
+
+import { CoreApiClient } from 'twenty-client-sdk/core';
+import { fileURLToPath } from 'url';
+
+import { mapLegacyScope } from './partner-scope-map';
+
+const requireEnv = (name: string): string => {
+  const value = process.env[name];
+  if (!value) throw new Error(`Missing ${name} env var`);
+  return value;
+};
+
+async function main() {
+  const apply = process.env.MIGRATE_APPLY === '1';
+  const url = `${requireEnv('TWENTY_PARTNERS_API_URL').replace(/\/$/, '')}/graphql`;
+  const client = new CoreApiClient({
+    url,
+    headers: { Authorization: `Bearer ${requireEnv('TWENTY_PARTNERS_API_KEY')}` },
+  });
+  console.log(`[migrate-scope] target: ${url} — ${apply ? 'APPLY' : 'dry-run'}`);
+
+  // Pass 1: page through ALL partners read-only and collect those that need remapping.
+  type Pending = { id: string; current: string[]; next: string[] };
+  const pending: Pending[] = [];
+  let after: string | null = null;
+  // eslint-disable-next-line no-constant-condition
+  while (true) {
+    const data: any = await client.query({
+      partners: {
+        __args: after ? { first: 50, after } : { first: 50 },
+        edges: { node: { id: true, partnerScope: true }, cursor: true },
+        pageInfo: { hasNextPage: true, endCursor: true },
+      },
+    } as any);
+    const edges = data.partners?.edges ?? [];
+    for (const edge of edges) {
+      const id = edge.node.id as string;
+      const current = (edge.node.partnerScope ?? []) as string[];
+      const next = mapLegacyScope(current);
+      const isChanged =
+        next.length !== current.length || next.some((v, i) => v !== current[i]);
+      if (!isChanged) continue;
+      pending.push({ id, current, next });
+      console.log(`[migrate-scope] ${id}: ${JSON.stringify(current)} -> ${JSON.stringify(next)}`);
+    }
+    if (!data.partners?.pageInfo?.hasNextPage) break;
+    after = data.partners.pageInfo.endCursor;
+  }
+
+  // Pass 2: apply the remapping mutations (only when MIGRATE_APPLY=1).
+  if (apply) {
+    for (const { id, next } of pending) {
+      await client.mutation({
+        updatePartner: { __args: { id, data: { partnerScope: next } }, id: true },
+      } as any);
+    }
+  }
+
+  console.log(`[migrate-scope] ${apply ? 'updated' : 'would update'} ${pending.length} partner(s)`);
+  if (!apply) console.log('[migrate-scope] re-run with MIGRATE_APPLY=1 to apply');
+}
+
+// Only run when invoked directly (so unit tests can import mapLegacyScope safely).
+if (process.argv[1] === fileURLToPath(import.meta.url)) {
+  main().catch((err) => {
+    console.error(err);
+    process.exit(1);
+  });
+}
@@ -0,0 +1,19 @@
+// Legacy -> validated partnerScope category mapping. Single source of truth,
+// shared by the migration script (rewrites existing records) and the TFT import
+// (so it never writes retired legacy values back in).
+export const LEGACY_SCOPE_MAP: Record<string, string> = {
+  APPS: 'DEVELOPMENT',
+  DATA_MODEL: 'SOLUTIONING',
+  DATA_MIGRATION: 'SOLUTIONING',
+  WORKFLOWS: 'SOLUTIONING',
+  HOSTING_ENVIRONMENT: 'HOSTING',
+};
+
+export function mapLegacyScope(values: ReadonlyArray<string>): string[] {
+  const out: string[] = [];
+  for (const value of values) {
+    const mapped = LEGACY_SCOPE_MAP[value] ?? value;
+    if (!out.includes(mapped)) out.push(mapped);
+  }
+  return out;
+}
@@ -0,0 +1,11 @@
+// Shared slug helper. Algorithm is intentionally kept simple (no NFKD
+// normalization) so that slugs produced by the import script and by the
+// partner-application handler are byte-for-byte identical. The import uses
+// slug as an idempotency/upsert key (partnerIdBySlug), so the algorithm must
+// never change for existing data.
+export const slugify = (s: string): string =>
+  s
+    .toLowerCase()
+    .trim()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '');
@@ -0,0 +1,116 @@
+---
+name: twenty-lead-intro-call-summary
+description: Turn a sales/discovery-call transcript into a faithful, structured qualification brief for Twenty's partner/CRM pipeline. Use this whenever the user has a call recording or transcript — including a meetily recordings folder or a transcripts.json — and wants to summarize, recap, qualify, or extract a brief from a prospect/discovery call. Trigger even when they don't say "brief": phrases like "summarize this call", "what did we learn from the X call", "qualify this lead from the call", "turn this transcript into something I can hand a partner", or pointing at a transcript file all count. Produces a tight deal one-pager (company, needs, implementation complexity, does-it-need-a-partner, partner-facing brief) plus an appendix (product/GTM feedback, terminology, quotes). It is a faithful extraction, not a lossy summary.
+trigger: /twenty-lead-intro-call-summary
+---
+
+# twenty-lead-intro-call-summary
+
+Turn a discovery/sales-call transcript into a **qualification brief** that (a) loses no
+decision-relevant detail and (b) can be used to qualify the deal and hand it to an
+implementation partner. Designed for Twenty's partner/CRM pipeline, tuned for messy,
+label-less ASR transcripts (e.g. meetily exports).
+
+The output is two parts: a tight **Part A deal one-pager** (everything the deal/partner
+work needs) and a **Part B appendix** (not deal-specific: product feedback, terminology,
+quotes). The structure is what prevents loss — a "summary that loses nothing" is a
+contradiction, so this is a *structured extraction* against a fixed schema where every
+dimension has a slot and gaps are marked rather than silently dropped.
+
+## Step 1 — Get the transcript
+
+The transcript is provided by the user — usually pasted text, or a path they point you at
+(a `.txt`/`.vtt`/`.srt`, or a meetily recording folder / `transcripts.json`). If they give a
+path, read it: a meetily `transcripts.json` is `{ "segments": [ { "text": ... } ] }` —
+concatenate the `text` values in order; for `.vtt`/`.srt`, drop the cue numbers and
+timecodes.
+
+**If no transcript is provided, ask for it before doing anything else.** Don't fabricate or
+proceed without one.
+
+For very long transcripts, read the whole thing before writing — coverage is the point.
+
+## Step 2 — Produce the brief
+
+Follow these rules and fill this exact schema. Why each rule matters is noted, because
+faithful extraction depends on judgment, not rote form-filling.
+
+**Rules**
+- Extract ONLY what is in the transcript. Never invent or assume. If a field isn't covered,
+  write "Not discussed." (Visible gaps beat confident fabrication — a missing field is a
+  signal to ask on the next call.)
+- Separate stated FACTS from your INFERENCES; mark any inference "(inferred)". (Downstream
+  matching trusts the facts; don't contaminate them with guesses.)
+- Preserve specifics verbatim: numbers, dates, names + roles, tool/CRM names, prices,
+  budgets, exact requirements. Don't round or paraphrase numbers. (Specifics are where
+  nuance and matching signal live; paraphrase kills them.)
+- Use the customer's own words for needs and objections; quote pivotal lines.
+- Don't smooth over contradictions or vagueness — note them. (A flagged contradiction is
+  more useful than a falsely tidy summary.)
+- If the transcript has NO speaker labels, infer from context who is the vendor (Twenty)
+  and who is the prospect, and attribute accordingly. Names get garbled by speech-to-text —
+  flag any uncertain name with "(uncertain)" and never invent a name.
+- Keep PART A tight — it's the one-pager the deal/partner work runs on. Push everything not
+  specific to this deal (product/website feedback, terminology, supporting quotes) to
+  PART B. State each fact once; never repeat it across sections.
+
+**Output (use these exact headers)**
+
+```
+== PART A — DEAL ONE-PAGER ==
+
+1. ONE-LINE SUMMARY
+2. COMPANY — name, what they do, size/employees, HQ + countries of operation, industry
+3. PEOPLE ON THE CALL — name, role/title, side (Twenty vs prospect); infer roles if
+   unlabeled and flag uncertain names
+4. CURRENT SITUATION — what CRM/tools they use today; specific pains
+5. WHY THEY'RE INTERESTED IN TWENTY
+6. WHAT THEY WANT — bulleted needs/requirements, verbatim where possible
+7. IMPLEMENTATION COMPLEXITY (for partner matching)
+   - Deployment: cloud / self-host / both / unclear  (+ the evidence)
+   - Data model: custom objects, multi-tenant, row-level security, migrations
+   - Integrations / custom apps needed
+   - Workflows / automation needs
+   - Scale: number of seats/users
+   - Region + language the partner would need to cover
+8. COMMERCIALS — budget or prices discussed, plan tier (Pro/Org/Enterprise), seat count,
+   deal value, who pays
+9. TIMELINE & DECISION — key dates, decision-makers, urgency, decision process
+10. OBJECTIONS / RISKS / FEARS — including anything that could kill the deal
+11. ALTERNATIVES — competitors or other options they're weighing
+12. DOES THIS DEAL NEED A PARTNER? — yes / no / maybe + why; and if yes, what kind
+    (scope, region, language, seniority/tier)
+13. NEXT STEPS / OPEN QUESTIONS / FOLLOW-UPS
+14. PARTNER-FACING BRIEF — a 2-4 sentence narrative a partner can skim to decide yes/no,
+    drawn only from PART A
+
+== PART B — APPENDIX (not deal-specific) ==
+
+15. PRODUCT / WEBSITE / GTM FEEDBACK — any feedback on the product, pricing page, website
+    wording, onboarding, or trial; capture even if off-topic for qualification
+16. TERMINOLOGY / DOMAIN-LANGUAGE NOTES — words used on the call that mean different things
+    to each side or carry domain-specific meaning (e.g. "partner", "donor", jargon)
+17. KEY VERBATIM QUOTES — 3-8 direct quotes that capture intent, needs, or objections
+```
+
+## Step 3 — Output and save
+
+Print the brief in the conversation. Then offer to save it as Markdown — default to a
+sibling of the source (e.g. next to the recording) or, for Twenty work, the
+`partners-experience/research/` folder, named `YYYY-MM-DD-<company>-call-summary.md`. Don't
+write the file unless the user wants it saved.
+
+## How the fields map to the Partner model (for matching)
+
+Section 7 + 12 are the matching axes: `Deployment → deploymentExpertise`, the scope needs →
+`partnerScope`, `Region + language` → partner region/languages, scale → capacity, the
+"needs a partner?" tier → `partnerTier`. Keeping these explicit is what lets the brief drop
+straight into the opportunity→partner handover flow.
+
+## Notes
+
+- This is tuned for Twenty discovery calls, but the schema generalizes — swap the vendor
+  framing in section 5/12 if reused elsewhere.
+- The worked reference example lives at
+  `partners-experience/research/2026-05-21-tsf-call-summary-final.md` (and the prompt alone
+  at `partners-experience/research/call-summary-prompt.md`).
@@ -0,0 +1,36 @@
+---
+name: twenty-partner-design-doc
+description: Use when turning a qualified Twenty lead — a call-summary brief plus any client braindump/docs — into an implementation design doc a partner can scope and quote from. Trigger when pointed at a lead folder (e.g. partners-experience/<LEAD>/) and asked to "draft a design doc", "translate this into Twenty terms", "scope this for a partner", or "prep the partner handoff" for a discovery-qualified prospect. Chains after twenty-lead-intro-call-summary.
+trigger: /twenty-partner-design-doc
+---
+
+# twenty-partner-design-doc
+
+Turn a qualified lead's materials into a **design doc**: a translation of the customer's needs into **Twenty terms** that an implementation **partner reads to scope and quote** the work.
+
+**The doctrine — what to produce, the 12-section structure, the rules, the verification process, and the common mistakes — lives in `design-doc-doctrine.md` in this folder. Read it and follow it.** This file is only the Claude Code wrapper: how to gather inputs, which tools to use for each step, and where to save.
+
+## Inputs
+
+- A lead folder (e.g. `partners-experience/<LEAD>/`) containing a `twenty-lead-intro-call-summary` output plus any braindump / docs / notes.
+- If there is a raw transcript but no brief, run **twenty-lead-intro-call-summary** first — this skill chains after it.
+- Read everything. Convert `.docx` with `textutil -convert txt "<file>" -output /tmp/out.txt` (macOS) or an equivalent extractor.
+
+## Steps
+
+1. **Gather** — read all source materials in full. Coverage is the point.
+2. **Extract needs, grounded** — facts vs inferences (`(inf.)`); never invent. Per the doctrine.
+3. **Draft** the doc in the doctrine's 12-section structure, applying every rule in the doctrine.
+4. **Verify load-bearing claims live** — use **WebFetch** against the Twenty doc map in the doctrine's Verification section before asserting any capability. Build the §11 appendix as you go.
+5. **Reconcile discrepancies** — sources that disagree (call vs braindump; a name differing across/within sources) get flagged both ways, never silently resolved.
+6. **Resolve ❓ with the operator** — after a full v1 draft, use **AskUserQuestion** to ask the Twenty team member the unknowns a Twenty insider can answer; leave customer-facing unknowns as ❓. **If running autonomously** (no operator — a subagent/batch run), skip the questions and leave every unknown as ❓ in the body and §11.
+7. **Self-check, then save** — scan the output for: an em dash, a bare `~`, first-person voice outside customer quotes, local file paths, a header that isn't the four-field table, a point repeated across sections instead of a §N cross-reference, a leftover glossary / domain-language section, runtime/env-var mechanics that belong in the technical phase, and any capability claim stated as fact without a §11 source. Fix, then save to the lead folder as `YYYY-MM-DD-<lead>-design-doc.md`.
+
+## Worked example
+
+Reference: `partners-experience/TSF/2026-05-26-tsf-design-doc.md` shows the target **coverage, flag discipline, and §11 verification appendix**. It predates the current concision / table-header / no-glossary / no-em-dash rules, so where its formatting differs, **follow this doctrine over the example.**
+
+## Notes
+
+- Chain: **twenty-lead-intro-call-summary → twenty-partner-design-doc**; the output feeds the opportunity→partner handover (`designDocStatus` / `designDocUrl`).
+- **Phase 2:** `design-doc-doctrine.md` is written to be portable. A future `defineSkill` in this app (a sibling `*.skill.ts` in `src/skills/`) would import it as its `content`, driving an in-product agent — with a verify logic-function tool replacing the WebFetch step, and a Workflow Action triggering it when sales toggles `partnerEligible`. Keep doctrine changes in that file so both the Claude Code skill and the `defineSkill` stay in sync.
@@ -0,0 +1,130 @@
+# Design-doc doctrine: translating a lead into Twenty terms
+
+**Portable doctrine.** This file is tool-agnostic. It defines *what* a Twenty partner design doc is, its structure, the rules, and how to verify it. Two consumers use it: the Claude Code skill `twenty-partner-design-doc` (see `SKILL.md` in this folder), and, in a later phase, the `content` of a Twenty `defineSkill` driving an in-product agent. Keep it free of any one tool's mechanics (no file paths, no tool names).
+
+## Purpose
+
+Produce a **design doc** that translates a qualified lead's needs into **Twenty terms** (data model, views, automations, integrations, permissions, reporting, hosting) so an implementation **partner can scope and quote** the work.
+
+**Core principle:** identify *all* the work with **no blindspots**, **ground every claim** in the source or in live Twenty docs, and **present options rather than prescribe**. The partner quotes off this doc, so a confident-but-wrong capability claim or a hidden requirement is the worst failure.
+
+**Stay on the client's outcome.** Every line must change what the partner *builds* or what the client *receives*. The doc is a design, not a meeting record: a requirement's backstory (why the vendor or a third party does or doesn't satisfy it) is not a build input. Capture the **consequence**, cut the backstory.
+
+The doc is **partner-facing** and may be forwarded verbatim. It is a *suggestion to make scoping easier*, not a spec that constrains how the partner builds.
+
+## Output structure (fixed)
+
+**Header: a compact table, not a stack of bold lines.** Four fields only:
+
+| Field | Value |
+|---|---|
+| Lead | name (one-line description of who they are) |
+| Date | YYYY-MM-DD |
+| Author | Twenty (partnerships) |
+| Status | one short line (e.g. "Draft for partner review") |
+
+Keep the header to those four fields. The Status line stays short: a load-bearing caveat (e.g. "data model is an inference pending discovery") goes in the "What this is" callout, not in the header cell. Do not list source materials, internal timelines, or who-promised-what: not load-bearing, not customer-safe (the doc is forwarded verbatim).
+
+After the table, one **"What this is"** callout framing the doc as a partner-scoping suggestion across the full surface, *not* an MVP.
+
+Flag legend: 🟥 heavy / product-constrained · ❓ open question to resolve before quoting · `(inf.)` modelling inference.
+
+1. **Context**: the 30-second read: who they are, what they want, deployment requirement, scale, language/region.
+2. **Data model in Twenty terms**: the core. Present objects as a **table, one row per object**: `Object | Std/Custom | Represents | Key fields (traceable, (inf.)-tagged) | Core relations`. Spell out SELECT option sets. **Model the relationships, not just the fields**: who introduced/sourced a record (e.g. an ambassador to Opportunity `sourcedBy` link), parent/child, ownership carry as much scoping signal as the attributes. State product constraints inline (no formula fields; custom objects auto-get attachments/notes/tasks/timeline). Where a customer term collides with a Twenty term (their "partner" = a donor), note the mapping inline at first use; do **not** add a glossary section for it.
+3. **Views & navigation**: pipelines/kanban, tables, per-record page layouts.
+4. **Automations**: only the automations the customer named; give Workflow-or-logic-function for each. Name the automation and its trigger; defer runtime and build mechanics (see *Scope altitude*).
+5. **Integrations** *(conditional: include only when the customer explicitly names an external system to connect)*: external systems to Twenty: direction, *indicative* mechanism (not prescriptive), data flow, risks/unknowns. **If no integration is named, omit this section entirely and renumber the rest**; never infer integrations as a default. If you spot a likely one, raise it as a single ❓ in §10, not a whole section.
+6. **Roles, permissions & RLS**: map named roles to Twenty's object / field / row-level model; answer "do we need RLS?" against verified, plan-gated capability.
+7. **Reporting & analytics**: map reporting asks to native Dashboards; flag gaps (ratios needing rollups; export/sharing limits), each with a solution.
+8. **Hosting & compliance**: cloud vs self-host, data-residency requirement (verify), GDPR. Flag contradictions.
+9. **Suggested phasing**: "(the partner's call, not Twenty's)" layers, labelled a suggestion.
+10. **Open questions / blindspot-killers**: the list a partner must resolve before pricing.
+11. **References & verification**: a table mapping each load-bearing claim to its source doc, plus an explicit list of what the docs could NOT confirm (the ❓s).
+
+Scale each section to its content. **Coverage of surface area matters more than depth per item.**
+
+## Rules (and why each matters)
+
+- **Be concise: maximum signal per word.** Say a lot in few words. Cut throat-clearing, scene-setting, hedges, and feature-tour prose; prefer a table or a tight clause to a paragraph. Length is not coverage: a short doc that names every requirement beats a long one that pads each. A hesitant buyer reads a focused doc; a bloated one reads as cost.
+- **Never repeat yourself.** State each fact, constraint, or claim once, in its home section; elsewhere point to it by section number (§N) rather than restate. §10 (open questions) and §11 (references) are deliberate roll-ups: there, give the pointer and the decision the item gates, not a re-explanation of the body. Repetition is the main source of bloat, and two copies of a claim drift out of sync.
+- **Scope altitude: name the decision, defer the mechanics.** A design doc scopes the work; it is not the technical implementation spec. State the *decision* and its *cost or scope consequence*; leave the implementation nitty-gritty (specific env-var names, runtime internals, isolation models, SDK function signatures) to the later technical phase. Example: "production automations need a sandboxed/serverless logic-function backend, an infra cost that belongs in the platform workstream" carries the quote signal; the exact `LOGIC_FUNCTION_TYPE` / `LAMBDA` / region/role/key settings do not belong in a scoping doc. Deep mechanics inflate length and date fast without changing the quote.
+- **Ground everything; tag inferences `(inf.)`; never grow scope.** The partner quotes off this, so an invented field or requirement inflates the quote or sets a false expectation. If the *concept* is from the source but the *field name* is yours, that is an inference: tag it. Values lifted from the source (the customer's own category list becoming SELECT options) are *grounded*; only names/fields you coin are inferences.
+- **Record the design consequence, not the backstory.** State a requirement and the **client's path** that follows from it; do not litigate *why* it's true. When a requirement traces to vendor-internal or third-party detail (corporate structure, legal domicile, ownership, internal commercial arrangements, who-confirms-what-with-whom), keep only the consequence: it is a commercial matter, not a build input, however much airtime it got on the call. (E.g. *"client needs a European vendor"* becomes *"partner-hosted EU self-host is the path; managed cloud only under a European-contracting arrangement"*, **not** a write-up of the vendor's statutes / HQ / ownership / sign-off.) An open item the client is waiting on is recorded as the **decision it gates** (a ❓ in §10), not as a narrative of the vendor's situation.
+- **Database discipline: reuse and extend standard objects; add a custom object only at a genuine wall.** Company / Person / Opportunity plus the built-in Notes / Tasks / Timeline cover most CRM needs; every new object multiplies build and maintenance. A **human actor is a Person with a role flag before it is a new object**: create an object only when it needs its own pipeline or reporting. Name the wall when you add one.
+- **When the brief is thin, under-reach the inferred model; don't fill the gap.** A blurry situation (no discovery call, sparse notes) is a reason to model the *fewest, most certain* objects and leave the rest as ❓ open questions, not to compensate with an elaborate inferred domain. An over-detailed inference reads as scope and cost the customer never asked for and can scare a hesitant buyer off. Lead with standard objects plus the one or two custom objects the domain unmistakably needs; everything else is a question to confirm, not a row in the table. Say plainly, up front, that the model is a minimal starting sketch to validate.
+- **Present build approaches; don't prescribe.** An automation can be a no-code Workflow *or* a logic function in an app: say both. Prescribing one penalizes a partner who would do the other. The doc identifies the *need*, not the *build*.
+- **Every problem carries a path; never a dead-end flag.** If you flag a constraint (e.g. dashboards can't share externally), pair it with at least one solution (CSV export, a front-component, a public site on the API) or a question that resolves it. A flag with no path is useless to someone pricing the work.
+- **Flag what an approach can't satisfy.** The doc's value is surfacing walls and limits per requirement so the partner prices around them, not picking the one true solution.
+- **Partner-facing voice.** Say **"Twenty," never first person** ("we / our / ours"). **No local file paths** in the output: cite shareable `docs.twenty.com` URLs only. (Customer quotes that contain "we/our" are fine: they are quotes.)
+- **No characterisations or asides; only requirements and capabilities.** The doc is customer-forwardable, so keep out the source chat's off-hand remarks: characterisations of the buyer (budget, temperament, sophistication), named comparisons to competing vendors, and internal partnerships notes (deadlines, who promised what). If price-sensitivity or a competitor displacement genuinely shapes the build, state it neutrally as a requirement (e.g. cost is a selection criterion), never as a quote or judgement.
+- **Verify before asserting capability.** Any "Twenty can / can't / has / lacks X" that moves the quote must be verified live (see Verification). **Undocumented ≠ impossible.**
+
+## Formatting
+
+- One line per paragraph: **no mid-sentence hard wraps** (they render as broken lines).
+- **Never use em dashes (the long dash).** Restructure the sentence, or use a colon, comma, parentheses, or a period instead.
+- **Never a bare `~`** for "approximately": GitHub markdown pairs `~...~` into strikethrough. Write "around" / "about".
+- Mark unverified capability claims ❓, never as fact.
+
+## Verification
+
+Any statement of the form **"Twenty can / can't / has / lacks X"** that changes the partner's quote MUST be verified **live** before it is stated as fact. Model training is stale on a fast-moving product; the worst failure is a confident, authoritative-sounding claim that is wrong.
+
+**Source hierarchy (what to trust, in order):**
+1. **Live docs** (`docs.twenty.com`): primary truth. For the highest-stakes claims, read the page's primary text rather than trust a summary.
+2. **Established Twenty SDK build patterns** (hands-on): build-level facts the customer docs omit (no formula fields; custom objects auto-get attachments/notes/tasks/timeline; two-file relations).
+3. **The Twenty operator** (a Twenty team member): best for "is it shipped / internal / undocumented."
+4. **Model training**: never the sole basis for a high-stakes claim.
+
+**Right doc layer (the trap):** capabilities live in two layers, so check the right one.
+- **Product capabilities** (what the CRM does for the *customer*): the **user guide + pricing page**. Covers roles / row-level permissions, dashboards, plans, hosting, data residency.
+- **App capabilities** (what an *app* can define): the **developer/extend** docs. Covers field types, fields, logic functions, views, page layouts.
+Checking only the app layer is how "row-level not supported" (wrong) happens: row-level is a **product feature on the Organization plan**. The converse also holds: SDK build patterns *are* sufficient to assert **build-layer** facts even when the customer docs are silent (e.g. auto system relations), so do not demote a well-established build fact to ❓.
+
+**Always verify (the load-bearing checklist), live, every run:**
+1. Field types & constraints (e.g. no formula/computed fields).
+2. Standard-object extension & relabeling (add fields ✓; relabel / edit built-in SELECT options?).
+3. Roles & permissions: object / field / row-level, and plan-gating (which tier).
+4. Dashboards & reporting: chart/widget types, beta status, export / external-sharing limits.
+5. Automation surfaces: Workflows vs logic functions, what each can do.
+6. Integration mechanisms: webhooks, HTTP triggers, scheduled functions, connections.
+7. Hosting & deployment: cloud plans & regions / **EU data residency**, self-host availability & requirements.
+Plus: any other capability claim the draft makes that carries a 🟥 or ❓ flag.
+
+**Fallback chain:**
+- Docs confirm → state it as fact; record the source in §11.
+- Docs silent or ambiguous → ask the operator (if available).
+- Operator unavailable or unsure → render it as a ❓ open question. **Never assert.** When you fetched a page and it was simply *silent*, record that as "docs silent (URL)" rather than leaving the claim unsourced.
+
+**§11 appendix format:** a `Claim (§) | Verified against` table, then an explicit "**Could not be confirmed in public docs (❓: check with Twenty directly):**" list. Unverified items stay ❓ in the body too, never silently promoted to fact. Cite the **human-readable (non-`.md`) URL** here: the `.md` twin is for *your* fetch, not for the partner (a `.md` link renders as raw markdown in a browser).
+
+**Where to verify (Twenty doc map):** docs base = `https://docs.twenty.com/`. Fetch **`<path>.md`** for the clean markdown twin (the form to prefer). Paths:
+- Product / user-guide: `user-guide/dashboards/overview` · `user-guide/dashboards/capabilities/widgets` · `user-guide/permissions-access/how-tos/permissions-faq` · `user-guide/data-model/overview` · `user-guide/data-model/capabilities/fields` · `user-guide/data-migration/how-tos/export-your-data`
+- Developer / extend: `developers/extend/apps/data/objects` · `developers/extend/apps/data/extending-objects` · `developers/extend/apps/data/relations` · `developers/extend/apps/logic/logic-functions` · `developers/extend/apps/logic/connections` · `developers/extend/apps/layout/views` · `developers/extend/apps/layout/page-layouts` · `developers/extend/apps/config/roles`
+- Self-host: `developers/self-host/self-host`
+- Pricing & plans: `https://twenty.com/pricing` (**marketing page, no `.md`**; fetch as HTML).
+If a `.md` 404s, drop the suffix or re-derive from the docs index: the map can go stale.
+
+## Common mistakes
+
+| Mistake | Reality / fix |
+|---|---|
+| "Twenty isn't a BI tool" / "can't do row-level" | Stale training. Twenty has Dashboards; row-level is on the Organization plan. **Verify live.** |
+| Checked only the app-SDK doc for a product capability | Row-level lives in the product/pricing layer. **Verify the right layer.** |
+| Added fields not in the source | Scope growth, wrong quote. Ground every field; tag inferences `(inf.)`. |
+| Made a human actor (e.g. ambassador) its own object by default | A human is a Person + role flag first; an object only if it needs its own pipeline/reporting. |
+| Flagged an automation as "Workflow" | Prescribes the build, penalizes app-builders. Present both. |
+| Flagged a limit with no fix | Dead-end flag. Pair every problem with a path. |
+| Spelled out runtime/env-var mechanics (e.g. `LOGIC_FUNCTION_TYPE` / `LAMBDA`, region/role/key) | Wrong altitude. Name the decision + its cost; defer the mechanics to the technical phase. |
+| Same point restated across sections | State it once in its home section; cross-reference by §N. |
+| Padded prose / feature-tour narration | Maximum signal per word. State the content; cut the scene-setting. |
+| Added a domain-language map / glossary section | Removed. Note a genuine term collision inline in §2; no standalone glossary. |
+| First-person "not ours" in a partner doc | Say "Twenty." The doc is forwarded verbatim. |
+| Local file paths in the output | Mean nothing to a partner. Cite `docs.twenty.com` only. |
+| `§2` as prose; fields modelled but not relationships | Use a per-object field **table**; model the links, not just attributes. |
+| Hard-wrapped mid-sentence / used `~` / used an em dash | Broken lines / accidental strikethrough / banned dash. One line per paragraph; "around" not `~`; colon or comma, never an em dash. |
+| Wrote up the vendor's corporate status / legal domicile / ownership / sign-off | Backstory, not a build input. Record only the **consequence**: requirement → the client's path; gate the open item as a ❓ in §10. |
+| Filled a thin brief with an elaborate inferred model | Over-reach scares a hesitant buyer with unrequested scope. Model the few certain objects; flag the rest as ❓; say it's a minimal sketch. |
+| Added an Integrations section with connectors the customer never named | Integrations is conditional, not default. Omit it absent a named system; at most flag one ❓. |
+| Kept buyer characterisations / competitor asides / internal timelines | Not customer-safe. State needs neutrally; cut the rest. |
+| Listed source materials / who-promised-what in the header, or stacked it as bold lines | Header is a four-field table. Not customer-safe content goes nowhere. |
@@ -0,0 +1,15 @@
+import tsconfigPaths from 'vite-tsconfig-paths';
+import { defineConfig } from 'vitest/config';
+
+// Pure unit tests — no server required, no globalSetup.
+export default defineConfig({
+  plugins: [
+    tsconfigPaths({
+      projects: ['tsconfig.spec.json'],
+      ignoreConfigErrors: true,
+    }),
+  ],
+  test: {
+    include: ['src/**/*.test.ts'],
+  },
+});
@@ -4086,6 +4086,7 @@ __metadata:
    typescript: "npm:^5.9.3"
    vite-tsconfig-paths: "npm:^4.2.1"
    vitest: "npm:^3.1.1"
+    zod: "npm:^4.1.11"
  languageName: unknown
  linkType: soft