Initial commit: YouTube Studio Flow (backend, frontend, infrastructure, docs)

documentation/YouTube Studio Flow/02 - Features/06 - Collaborators.md

@@ -0,0 +1,41 @@
+# Collaborators
+
+## User Perspective
+Collaborators are people who appear in videos (guests, co-hosts, sponsors). Defining them centrally allows description templates to include their links automatically via tokens.
+
+### Collaborator Fields
+- Name (required)
+- YouTube link (full URL)
+- Twitch, Instagram, TikTok, Twitter/X, Bluesky links
+- Discord handle
+- Aliases (alternate names/handles)
+- Notes
+
+### Usage in Descriptions
+In Variable-type blocks, use tokens like `{collab.youtube}`, `{collab.name}` etc. These are resolved based on which collaborators are assigned to the video via `Video.collaboratorIds`.
+
+## Developer Perspective
+
+### Tracking
+Collaborators are assigned to videos via `Video.collaboratorIds` — a JSON string array on the `Video` row. There is no separate join table. This single field drives both description rendering and the `collaboratorId` filter on the video list. Use the `array_contains` Prisma operator when querying it.
+
+### Token Mapping
+| Token | Resolves to |
+|---|---|
+| `{collab.name}` | Collaborator.name |
+| `{collab.youtube}` | Full URL: `https://www.youtube.com/@handle` (not just handle) |
+| `{collab.twitch}` | Collaborator.twitchLink |
+| `{collab.instagram}` | Collaborator.instagramLink |
+| `{collab.tiktok}` | Collaborator.tiktokLink |
+| `{collab.twitter}` | Collaborator.twitterLink |
+| `{collab.bluesky}` | Collaborator.blueskyLink |
+| `{collab.discord}` | Collaborator.discordHandle |
+| `{collab.aliases}` | Joined alias list |
+| `{collab.notes}` | Collaborator.notes |
+
+**Note:** `{collab.handle}` is a deprecated token. It was renamed to `{collab.youtube}`. Blocks still using `{collab.handle}` will not resolve.
+
+## Related
+- [[02 - Description Engine]]
+- [[05 - Collaborators API]]
+- [[07 - Render Engine]] (architecture)