Add Diarize connector docs

src/components/templates/agent-connectors/_setup-diarize.mdx

@@ -0,0 +1,78 @@
+import { Steps, Aside, Tabs, TabItem } from '@astrojs/starlight/components'
+
+Register your Diarize API key with Scalekit so it can authenticate and proxy transcription requests on behalf of your users. Unlike OAuth connectors, Diarize uses API key authentication — there is no redirect URI or OAuth flow.
+
+<Steps>
+1. ### Get a Diarize API key
+
+   - Sign in to [diarize.io](https://diarize.io) and go to **Settings** → **API Keys**.
+
+   - Click **+ Create New Key**, give it a name (e.g., `Agent Auth`), and confirm.
+
+   - Copy the key value — store it securely, as you will not be able to view it again.
+
+   ![Diarize.io settings page showing the API Keys section with an existing key and the Create New Key button](@/assets/docs/agent-connectors/diarize/create-api-key.png)
+
+2. ### Create a connection in Scalekit
+
+   - In [Scalekit dashboard](https://app.scalekit.com), go to **Agent Auth** → **Create Connection**. Find **Diarize** and click **Create**.
+
+   - Note the **Connection name** — you will use this as `connection_name` in your code (e.g., `diarize`).
+
+   - Click **Save**.
+
+   ![Scalekit connection configuration for Diarize showing the connection name and API Key authentication type](@/assets/docs/agent-connectors/diarize/add-credentials.png)
+
+3. ### Add a connected account
+
+   Connected accounts link a specific user identifier in your system to a Diarize API key. Add accounts via the dashboard for testing, or via the Scalekit API in production.
+
+   **Via dashboard (for testing)**
+
+   - Open the connection you created and click the **Connected Accounts** tab → **Add account**.
+
+   - Fill in:
+     - **Your User's ID** — a unique identifier for this user in your system (e.g., `user_123`)
+     - **API Key** — the Diarize API key you copied in step 1
+
+   - Click **Create Account**.
+
+   ![Add connected account form for Diarize in Scalekit dashboard showing User ID and API Key fields](@/assets/docs/agent-connectors/diarize/add-connected-account.png)
+
+   **Via API (for production)**
+
+   <Tabs syncKey="tech-stack">
+     <TabItem label="Node.js">
+       ```typescript
+       // Never hard-code API keys — read from secure storage or user input
+       const diarizeApiKey = getUserDiarizeKey(); // retrieve from your secure store
+
+       await scalekit.actions.upsertConnectedAccount({
+         connectionName: 'diarize',
+         identifier: 'user_123',       // your user's unique ID
+         credentials: { token: diarizeApiKey },
+       });
+       ```
+     </TabItem>
+     <TabItem label="Python">
+       ```python
+       # Never hard-code API keys — read from secure storage or user input
+       diarize_api_key = get_user_diarize_key()  # retrieve from your secure store
+
+       scalekit_client.actions.upsert_connected_account(
+           connection_name="diarize",
+           identifier="user_123",
+           credentials={"token": diarize_api_key}
+       )
+       ```
+     </TabItem>
+   </Tabs>
+
+   <Aside type="tip" title="Production usage tip">
+     In production, call `upsert_connected_account` (Python) / `upsertConnectedAccount` (Node.js) when a user connects their Diarize account — for example, after they paste their API key into a settings page in your app.
+   </Aside>
+</Steps>
+
+<Aside type="note" title="Supported media sources">
+  Diarize supports YouTube, X (Twitter), Instagram, and TikTok URLs. Direct audio or video file URLs are not supported — the URL must point to a public post on one of these platforms.
+</Aside>

src/components/templates/agent-connectors/_usage-diarize.mdx

@@ -0,0 +1,135 @@
+import { Tabs, TabItem, Aside } from '@astrojs/starlight/components'
+
+Connect a user's Diarize account and transcribe audio and video content through Scalekit tools. Scalekit handles API key storage and tool execution automatically — you never handle credentials in your application code.
+
+Diarize is primarily used through Scalekit tools. Use `execute_tool` to submit transcription jobs, poll for completion, and download results in any supported format.
+
+## Tool calling
+
+Use this connector when you want an agent to transcribe and diarize audio or video from YouTube, X, Instagram, or TikTok.
+
+- Use `diarize_create_transcription_job` to submit a URL for transcription. Returns an `id` (job ID) and an `estimatedTime` (in seconds) for how long processing will take.
+- Use `diarize_get_job_status` to poll until `status` is `COMPLETED` or `FAILED`. Use `estimatedTime` to set a sensible timeout — do not give up before that time has elapsed.
+- Use `diarize_download_transcript` to retrieve the result once complete. Choose `json` for structured speaker diarization data, or `txt`, `srt`, `vtt` for plain-text and subtitle formats.
+
+<Tabs syncKey="tech-stack">
+  <TabItem label="Python">
+    ```python title="examples/diarize_transcribe.py"
+    import os, time
+    from scalekit.client import ScalekitClient
+
+    scalekit_client = ScalekitClient(
+        client_id=os.environ["SCALEKIT_CLIENT_ID"],
+        client_secret=os.environ["SCALEKIT_CLIENT_SECRET"],
+        env_url=os.environ["SCALEKIT_ENV_URL"],
+    )
+
+    connected_account = scalekit_client.actions.get_or_create_connected_account(
+        connection_name="diarize",
+        identifier="user_123",
+    ).connected_account
+
+    # Step 1: Submit a transcription job
+    create_result = scalekit_client.actions.execute_tool(
+        tool_name="diarize_create_transcription_job",
+        connected_account_id=connected_account.id,
+        tool_input={
+            "url": "https://www.youtube.com/watch?v=example",
+            "language": "en",   # optional — omit for auto-detection
+            "num_speakers": 2,  # optional — improves speaker diarization
+        },
+    )
+    job_id = create_result.result["id"]
+    estimated_seconds = create_result.result.get("estimatedTime", 120)
+    deadline = time.time() + estimated_seconds * 2
+    print(f"Job {job_id} submitted. Estimated: {estimated_seconds}s")
+
+    # Step 2: Poll until complete
+    while True:
+        if time.time() > deadline:
+            raise TimeoutError(f"Job {job_id} timed out after {estimated_seconds * 2}s")
+        time.sleep(15)
+        status_result = scalekit_client.actions.execute_tool(
+            tool_name="diarize_get_job_status",
+            connected_account_id=connected_account.id,
+            tool_input={"job_id": job_id},
+        )
+        status = status_result.result["status"]
+        print("Status:", status)
+        if status == "COMPLETED":
+            break
+        if status == "FAILED":
+            raise RuntimeError(f"Job {job_id} failed")
+
+    # Step 3: Download the diarized transcript
+    transcript_result = scalekit_client.actions.execute_tool(
+        tool_name="diarize_download_transcript",
+        connected_account_id=connected_account.id,
+        tool_input={"job_id": job_id, "format": "json"},
+    )
+    # handle the transcript_result
+    ```
+  </TabItem>
+  <TabItem label="Node.js">
+    ```typescript title="examples/diarize_transcribe.ts"
+    import { ScalekitClient } from '@scalekit-sdk/node';
+    import 'dotenv/config';
+
+    const scalekit = new ScalekitClient(
+      process.env.SCALEKIT_ENV_URL!,
+      process.env.SCALEKIT_CLIENT_ID!,
+      process.env.SCALEKIT_CLIENT_SECRET!
+    );
+    const actions = scalekit.actions;
+
+    const { connectedAccount } = await actions.getOrCreateConnectedAccount({
+      connectionName: 'diarize',
+      identifier: 'user_123',
+    });
+
+    // Step 1: Submit a transcription job
+    const createResult = await actions.executeTool({
+      toolName: 'diarize_create_transcription_job',
+      connectedAccountId: connectedAccount.id,
+      toolInput: {
+        url: 'https://www.youtube.com/watch?v=example',
+        language: 'en',   // optional — omit for auto-detection
+        num_speakers: 2,  // optional — improves speaker diarization
+      },
+    });
+    const jobId = createResult.data.id;
+    const estimatedSeconds = createResult.data.estimatedTime ?? 120;
+    const deadline = Date.now() + estimatedSeconds * 2 * 1000;
+    console.log(`Job ${jobId} submitted. Estimated: ${estimatedSeconds}s`);
+
+    // Step 2: Poll until complete
+    let status = 'PENDING';
+    while (status !== 'COMPLETED' && status !== 'FAILED') {
+      if (Date.now() > deadline) throw new Error(`Job ${jobId} timed out after ${estimatedSeconds * 2}s`);
+      await new Promise(r => setTimeout(r, 15_000));
+      const statusResult = await actions.executeTool({
+        toolName: 'diarize_get_job_status',
+        connectedAccountId: connectedAccount.id,
+        toolInput: { job_id: jobId },
+      });
+      status = statusResult.data.status;
+      console.log('Status:', status);
+    }
+    if (status === 'FAILED') throw new Error(`Job ${jobId} failed`);
+
+    // Step 3: Download the diarized transcript
+    const transcriptResult = await actions.executeTool({
+      toolName: 'diarize_download_transcript',
+      connectedAccountId: connectedAccount.id,
+      toolInput: { job_id: jobId, format: 'json' },
+    });
+    // handle the transcriptResult
+    ```
+  </TabItem>
+</Tabs>
+
+<Aside type="note" title="Polling guidance">
+  The `estimatedTime` field (in seconds) tells you how long processing is expected to take. For a 49-minute episode, `estimatedTime` may be around 891 seconds (~15 minutes). Wait at least that long before treating the job as timed out.
+</Aside>
+
+## Scalekit tools

src/components/templates/agent-connectors/index.ts

@@ -10,6 +10,7 @@ export { default as SetupClickupSection } from './_setup-clickup.mdx'
 export { default as SetupConfluenceSection } from './_setup-confluence.mdx'
 export { default as SetupDatabricksSection } from './_setup-databricks.mdx'
 export { default as SetupDiscordSection } from './_setup-discord.mdx'
+export { default as SetupDiarizeSection } from './_setup-diarize.mdx'
 export { default as SetupDropboxSection } from './_setup-dropbox.mdx'
 export { default as SetupExaSection } from './_setup-exa.mdx'
 export { default as SetupFigmaSection } from './_setup-figma.mdx'
@@ -68,6 +69,7 @@ export { default as UsageClariCopilotSection } from './_usage-clari_copilot.mdx'
 export { default as UsageClickupSection } from './_usage-clickup.mdx'
 export { default as UsageConfluenceSection } from './_usage-confluence.mdx'
 export { default as UsageDatabricksSection } from './_usage-databricks.mdx'
+export { default as UsageDiarizeSection } from './_usage-diarize.mdx'
 export { default as UsageDiscordSection } from './_usage-discord.mdx'
 export { default as UsageDropboxSection } from './_usage-dropbox.mdx'
 export { default as UsageExaSection } from './_usage-exa.mdx'

src/content/docs/reference/agent-connectors/diarize.mdx

@@ -1,5 +1,8 @@
 ---
 title: Diarize
+description: Connect to Diarize to transcribe and diarize audio and video content from YouTube, X, Instagram, and TikTok.
+sidebar:
+  label: Diarize
 tableOfContents: true
 head:
   - tag: style
@@ -14,18 +17,29 @@ head:
 
 import { Card, CardGrid, Tabs, TabItem, Badge, Steps, Aside, Code } from '@astrojs/starlight/components'
 import { Accordion, AccordionItem } from 'accessible-astro-components'
+import { SetupDiarizeSection } from '@components/templates'
+import { UsageDiarizeSection } from '@components/templates'
 
 <div class="grid grid-cols-5 gap-4 items-center">
  <div class="col-span-4">
-  Connect to Diarize to transcribe and diarize audio and video content from YouTube, X, Instagram, and TikTok. Submit transcription jobs and retrieve results in JSON, TXT, SRT, or VTT format.
+  Connect to Diarize to transcribe and diarize audio and video content from YouTube, X, Instagram, and TikTok. Submit transcription jobs and retrieve results in JSON, TXT, SRT, or VTT format with speaker labels and word-level timestamps.
  </div>
  <div class="flex justify-center">
   <img src="https://cdn.scalekit.com/sk-connect/assets/provider-icons/diarize.svg" width="64" height="64" alt="Diarize logo" />
  </div>
 </div>
 
-Supports authentication: <Badge text="Bearer Token" />
+Supports authentication: <Badge text="API Key" />
 
+![Diarize connector card shown in Scalekit's Create Connection search](@/assets/docs/agent-connectors/diarize/scalekit-search-diarize.png)
+
+## Set up the agent connector
+
+<SetupDiarizeSection />
+
+## Usage
+
+<UsageDiarizeSection />
 
 ## Tool list
 
@@ -35,29 +49,23 @@ Submit a new transcription and diarization job for an audio or video URL (YouTub
 
 | Name | Type | Required | Description |
 | --- | --- | --- | --- |
-| `language` | string | No | Language code for transcription (e.g. 'en', 'es', 'fr'). Defaults to auto-detection if not provided. |
-| `num_speakers` | integer | No | Expected number of speakers in the audio. Helps improve diarization accuracy. |
-| `schema_version` | string | No | Optional schema version to use for tool execution |
-| `tool_version` | string | No | Optional tool version to use for execution |
 | `url` | string | Yes | The URL of the audio or video content to transcribe (e.g. YouTube, X, Instagram, TikTok link) |
+| `language` | string | No | Language code for transcription (e.g. `en`, `es`, `fr`). Defaults to auto-detection if not provided. |
+| `num_speakers` | integer | No | Expected number of speakers in the audio. Helps improve diarization accuracy. |
 
-## `diarize_download_transcript`
+## `diarize_get_job_status`
 
-Download the transcript output for a completed transcription job in JSON, TXT, SRT, or VTT format, including speaker diarization, segments, and word-level timestamps.
+Retrieve the current status of a transcription job by its job ID. Returns job state (`PENDING`, `PROCESSING`, `COMPLETED`, `FAILED`), metadata, and an `estimatedTime` field (in seconds) indicating how long processing is expected to take. Use `estimatedTime` to determine polling frequency and max wait duration — for example, a 49-minute episode may have an `estimatedTime` of ~891 s (~15 mins), so the agent should wait at least that long before giving up.
 
 | Name | Type | Required | Description |
 | --- | --- | --- | --- |
-| `format` | string | No | Output format for the transcript. Supported formats: 'json', 'txt', 'srt', 'vtt'. |
-| `job_id` | string | Yes | The unique ID of the completed transcription job |
-| `schema_version` | string | No | Optional schema version to use for tool execution |
-| `tool_version` | string | No | Optional tool version to use for execution |
+| `job_id` | string | Yes | The unique ID of the transcription job to check |
 
-## `diarize_get_job_status`
+## `diarize_download_transcript`
 
-Retrieve the current status of a transcription job by its job ID. Returns job state (pending, processing, completed, failed), metadata, and an estimatedTime field (in seconds) indicating how long processing is expected to take. Use estimatedTime to determine polling frequency and max wait duration — for example, a 49-minute episode may have an estimatedTime of ~891s (~15 mins), so the agent should wait at least that long before giving up.
+Download the transcript output for a completed transcription job in JSON, TXT, SRT, or VTT format, including speaker diarization, segments, and word-level timestamps.
 
 | Name | Type | Required | Description |
 | --- | --- | --- | --- |
-| `job_id` | string | Yes | The unique ID of the transcription job to check |
-| `schema_version` | string | No | Optional schema version to use for tool execution |
-| `tool_version` | string | No | Optional tool version to use for execution |
+| `job_id` | string | Yes | The unique ID of the completed transcription job |
+| `format` | string | No | Output format: `json` (default), `txt`, `srt`, or `vtt` |