docs: cohort synchronisation

docs/docs/third-party-integrations/cohort-synchronisation/_category_.json

@@ -0,0 +1,4 @@
+{
+    "label": "Cohort Synchronisation",
+    "position": 15
+}

docs/docs/third-party-integrations/cohort-synchronisation/amplitude.md

@@ -0,0 +1,77 @@
+---
+title: Amplitude Cohort Synchronisation
+description: Synchronise Amplitude cohorts into Flagsmith as segments
+sidebar_label: Amplitude
+sidebar_position: 3
+---
+
+# Amplitude
+
+Flagsmith is available as a cohort destination in Amplitude's catalogue. Once connected, every Amplitude cohort you
+synchronise appears in Flagsmith as a segment, and Amplitude keeps its members up to date for you.
+
+Read the [cohort synchronisation overview](/third-party-integrations/cohort-synchronisation) first for how synchronised
+segments behave.
+
+:::tip
+
+Flagsmith matches cohort members to identities by identifier, so the Amplitude `user_id` must be the same value your
+application uses as the Flagsmith [identity](/flagsmith-concepts/identities) identifier.
+
+:::
+
+## 1. Create a synchronisation key in Flagsmith
+
+1. Go to the **Segments** page in your project and click **Create Segment**.
+2. Choose **Amplitude**.
+3. Select the environment you want to synchronise cohorts into.
+4. Create a synchronisation key: give it a name, such as "Amplitude production", and copy the key value. It is shown
+   only once. If the environment already has a key that you created earlier and still have, you can reuse it instead.
+
+![Connect Amplitude modal](/img/cohort-synchronisation/connect-amplitude-modal.png)
+
+## 2. Add Flagsmith as a destination in Amplitude
+
+1. In Amplitude, go to **Data > Catalog > Destinations** and find **Flagsmith** in the cohort destinations catalogue.
+2. Give the destination a recognisable name. Including the Flagsmith environment name is a good idea, because the key
+   decides which environment the cohorts are synchronised into.
+3. Paste your synchronisation key into the **Cohort sync api key** field.
+4. Check the **Identifier Mapping**. Amplitude's **User ID** must map to the Flagsmith **Identifier**.
+
+![Amplitude destination catalogue showing Flagsmith](/img/cohort-synchronisation/amplitude-destination-catalogue.png)
+
+![Amplitude Flagsmith destination configuration](/img/cohort-synchronisation/amplitude-destination-config.png)
+
+:::warning The key decides the environment
+
+Every cohort sent to this destination is synchronised into the environment its key belongs to, and nothing in Amplitude
+shows which one that is. To synchronise cohorts into a second environment, create a key there and add a second Flagsmith
+destination for it.
+
+:::
+
+## 3. Synchronise a cohort
+
+1. In Amplitude, open the cohort you want to target and click **Target users**.
+2. Select your Flagsmith destination.
+3. Choose the cadence, then click **Sync**:
+
+   - **One-Time Sync** sends the cohort's current members once.
+   - **Scheduled Sync** resends the membership every hour or every day.
+   - **Real-Time Sync** resends the membership every minute.
+
+   Scheduled and real time syncs keep the Flagsmith segment up to date on their own. With a one-time sync, later changes
+   to the cohort do not reach Flagsmith until you synchronise it again.
+
+![Amplitude Define Cadence dialog](/img/cohort-synchronisation/amplitude-define-cadence.png)
+
+Shortly after the first synchronisation, a segment named after your cohort appears on the **Segments** page of your
+project, ready to be used in
+[segment overrides](/third-party-integrations/cohort-synchronisation#using-a-synchronised-segment).
+
+## Notes
+
+- Each cohort synchronisation you set up in Amplitude creates its own segment in Flagsmith. Synchronising the same
+  cohort to a second destination creates a second segment.
+- If you delete a synchronised segment in Flagsmith, stop the cohort synchronisation in Amplitude as well. Otherwise
+  Amplitude reports the synchronisation as failing and may pause it.

docs/docs/third-party-integrations/cohort-synchronisation/csv-import.md

@@ -0,0 +1,62 @@
+---
+title: CSV Import
+description: Create a Flagsmith segment from a CSV list of identifiers
+sidebar_label: CSV Import
+sidebar_position: 2
+---
+
+# CSV Import
+
+Upload a list of identifiers and Flagsmith turns it into a segment you can use to override features. Use this when the
+group of users you want to target is a list you can export, such as beta signups from a spreadsheet, accounts from your
+CRM, or the users named in a support ticket.
+
+Read the [cohort synchronisation overview](/third-party-integrations/cohort-synchronisation) first for how synchronised
+segments behave.
+
+## Preparing your file
+
+Your CSV file needs one column holding the identifiers of the users you want to target. These must be the same values
+your application uses to identify users with Flagsmith, otherwise the segment will not match anyone.
+
+Other columns are ignored, so you can upload an export without stripping it down first. Files can be up to 10 MB.
+
+## Creating the segment
+
+1. Go to the **Segments** page in your project and click **Create Segment**.
+2. Choose **From a CSV list**.
+3. Give the segment a name and, optionally, a description.
+4. Select the environment the identities should be targeted in.
+5. Drag your CSV file onto the upload area, or click **Select file** to browse for it.
+6. Check the **Identifier column** that Flagsmith has picked, and change it if the identifiers are in a different
+   column. Untick **First row contains headers** if your file starts with data rather than column names.
+7. Review the preview and the number of identifiers detected, then click **Create Segment**.
+
+![Creating a segment from a CSV list](/img/cohort-synchronisation/csv-create-segment.png)
+
+:::warning Choose the environment carefully
+
+The identities you upload are only targeted in the environment you select, and that choice cannot be changed later. To
+target the same list in another environment, create a second segment there and upload the same file.
+
+:::
+
+## Updating the members
+
+Membership only changes when you upload a new file, so re-upload whenever your list has moved on.
+
+1. Open the segment from the **Segments** page.
+2. Under **Update the list**, click **Replace file** and choose your new CSV file.
+3. Confirm the identifier column and header setting, review the preview, then click **Synchronise**.
+
+![Re-synchronising a CSV segment](/img/cohort-synchronisation/csv-resynchronise.png)
+
+Each upload replaces the membership rather than adding to it. Identifiers in the new file become the members of the
+segment, and any identity that is missing from it loses the segment. To add people to the segment, upload a file that
+contains both the existing members and the new ones.
+
+## Notes
+
+- Rows with an empty identifier, and identifiers that appear more than once, are ignored.
+- The identifiers are matched to identities exactly, so watch for stray whitespace or differences in case in your
+  export.

docs/docs/third-party-integrations/cohort-synchronisation/index.md

@@ -0,0 +1,106 @@
+---
+title: Cohort Synchronisation
+description: Synchronise cohorts from a CSV file or your analytics platform into Flagsmith as segments
+sidebar_label: Overview
+sidebar_position: 1
+---
+
+# Cohort Synchronisation
+
+Cohort synchronisation lets you target feature flags at a group of users that you have defined outside Flagsmith. You
+can upload a list of identifiers as a CSV file, or connect an analytics platform and synchronise a cohort you have
+already built there. Either way, the group arrives in Flagsmith as a segment that you can use to override features.
+
+This is useful when membership of the group depends on data Flagsmith does not hold. You can roll out to the power users
+your analytics platform has identified, run a beta with a list of customers from your CRM, or turn a feature off for the
+accounts named in a support ticket.
+
+:::info
+
+Cohort synchronisation is available on paid plans.
+
+:::
+
+:::warning Synchronised segments belong to one environment
+
+You choose the environment when you set the segment up, and it cannot be changed afterwards. The segment has no members
+in any other environment, so an override you add in, say, Production will not match anyone if the segment was
+synchronised into Development. To target the same group in another environment, set the segment up again there.
+
+:::
+
+## Supported sources
+
+- [CSV import](/third-party-integrations/cohort-synchronisation/csv-import)
+- [Amplitude](/third-party-integrations/cohort-synchronisation/amplitude)
+
+## Creating a synchronised segment
+
+Every source starts in the same place. Go to the **Segments** page in your project, click **Create Segment**, and choose
+how you want to define the segment.
+
+![Create Segment source options](/img/cohort-synchronisation/create-segment-sources.png)
+
+Choosing anything other than **Manually** creates a synchronised segment, and the steps that follow depend on the source
+you picked.
+
+## How it works
+
+- **Each cohort becomes a segment.** Flagsmith creates the segment when you upload your first CSV file, or when your
+  analytics platform sends the cohort for the first time. The segment appears on your Segments page alongside your other
+  segments and can be used in segment overrides in the same way.
+- **The source owns the membership.** You cannot edit the segment's rules in Flagsmith. To change who belongs to it,
+  upload a new CSV file or change the cohort definition in your analytics platform.
+- **Members are matched by identity identifier.** Each entry is matched to the Flagsmith
+  [identity](/flagsmith-concepts/identities) with the same identifier, so your application must identify users with the
+  same value that the source sends.
+- **Synchronisation is scoped to one environment.** You choose the environment when you set the segment up, and members
+  are synchronised into that environment only. The segment will not match anyone in your other environments.
+- **Updates arrive differently per source.** A connected analytics platform sends membership changes on its own
+  schedule, so its segments stay up to date on their own. A CSV segment changes only when you upload a new file.
+- **Changes are applied in the background.** A large membership can take a few minutes to be reflected in full.
+
+## Synchronisation keys
+
+Analytics platforms authenticate with Flagsmith using a **cohort synchronisation key**. CSV uploads do not need one,
+because you are already signed in to the dashboard.
+
+- Keys are created per environment and work for any supported analytics platform.
+- The key value is shown only once, at creation. Store it securely. If you lose it, create a new key.
+- You can create several keys per environment, and revoke any of them at any time from **Environment Settings >
+  Cohorts**. Revoking a key immediately stops the synchronisation that uses it.
+- Creating and revoking keys requires the _Manage segment overrides_ permission for the environment and the _Manage
+  segments_ permission for the project.
+
+![Environment Settings Cohorts tab](/img/cohort-synchronisation/environment-settings-cohorts.png)
+
+## Using a synchronised segment
+
+Once the first synchronisation completes, the segment appears on the **Segments** page of your project, labelled with
+the source it came from.
+
+![Segments page with a synchronised segment](/img/cohort-synchronisation/synchronised-segment-list.png)
+
+From there it behaves like any other segment. Click on a feature in the connected environment, go to the **Segment
+Overrides** tab, and create an override for it. Identities that belong to the segment, and that your application
+identifies with the same identifier, will receive the overridden flags.
+
+Keep in mind:
+
+- The segment only has members in the environment you chose when you set it up.
+- Membership reflects the last synchronisation, not the current state of your data.
+
+## Deleting a synchronised segment
+
+Delete the segment from the **Segments** page like any other segment. Flagsmith removes its membership data as part of
+the deletion.
+
+If the segment was fed by an analytics platform, stop the cohort synchronisation there as well. If the platform keeps
+sending updates for a segment that no longer exists, Flagsmith rejects them, and the platform will report the
+synchronisation as failing and may pause it.
+
+## Revoking access
+
+To stop all synchronisation from analytics platforms into an environment, revoke its synchronisation keys in
+**Environment Settings > Cohorts**. Existing segments and their members stay in place, but no further membership updates
+are accepted for a revoked key.

frontend/web/components/modals/ConnectCohortProviderModal/ConnectCohortProviderModal.tsx

@@ -15,8 +15,6 @@ import {
 } from './providers'
 import './ConnectCohortProviderModal.scss'
 
-const SEGMENTS_DOCS_URL = 'https://docs.flagsmith.com/basic-features/segments'
-
 type ConnectCohortProviderModalProps = {
   projectId: number | string
   provider: CohortProviderKey
@@ -127,8 +125,8 @@ const ConnectCohortProviderModal: FC<ConnectCohortProviderModalProps> = ({
       </div>
       <ModalHR />
       <div className='modal-footer d-flex align-items-center justify-content-between'>
-        <Link href={SEGMENTS_DOCS_URL} target='_blank'>
-          Learn about Segments
+        <Link href={config.docsUrl} target='_blank'>
+          Learn about cohort synchronisation
         </Link>
         <Button onClick={() => closeModal()} data-test='connect-provider-done'>
           Done

frontend/web/components/modals/ConnectCohortProviderModal/providers.ts

@@ -11,6 +11,7 @@ export type CohortProviderAuthRow = {
 export type CohortProviderConfig = {
   label: string
   authRows: CohortProviderAuthRow[]
+  docsUrl: string
   // Providers where the user pastes a URL themselves carry an endpoint;
   // Amplitude calls Flagsmith's portal-registered endpoints instead.
   endpoint?: {
@@ -29,6 +30,8 @@ export const COHORT_PROVIDERS: Record<CohortProviderKey, CohortProviderConfig> =
       authRows: [
         { label: 'API key', mono: true, value: '{YOUR_SYNCHRONISATION_KEY}' },
       ],
+      docsUrl:
+        'https://docs.flagsmith.com/third-party-integrations/cohort-synchronisation/amplitude',
       endpointStepBody:
         'In Amplitude, open Data → Destinations and add Flagsmith as a cohort destination. Paste your synchronisation key when asked for the API key.',
       endpointStepTitle: 'Add Flagsmith as a destination in Amplitude',
@@ -43,6 +46,8 @@ export const COHORT_PROVIDERS: Record<CohortProviderKey, CohortProviderConfig> =
         { label: 'Username', value: 'Any value' },
         { label: 'Password', mono: true, value: '{YOUR_SYNCHRONISATION_KEY}' },
       ],
+      docsUrl:
+        'https://docs.flagsmith.com/third-party-integrations/cohort-synchronisation',
       endpoint: {
         fieldTitle: 'Webhook URL',
         path: 'cohort-sync/mixpanel/webhook/',