codexkit 1.0.0

package/.codex/skills/cloudflare/references/realtime-sfu/configuration.md

@@ -0,0 +1,63 @@
+# Configuration & Deployment
+
+## Wrangler Setup
+
+```toml
+name = "my-calls-app"
+main = "src/index.ts"
+compatibility_date = "2024-01-01"
+
+[vars]
+CALLS_APP_ID = "your-app-id"
+MAX_WEBCAM_BITRATE = "1200000"
+MAX_WEBCAM_FRAMERATE = "24"
+MAX_WEBCAM_QUALITY_LEVEL = "1080"
+
+# Set secret: wrangler secret put CALLS_APP_SECRET
+
+[[durable_objects.bindings]]
+name = "ROOM"
+class_name = "Room"
+```
+
+## Deploy
+
+```bash
+wrangler login
+wrangler secret put CALLS_APP_SECRET
+wrangler deploy
+```
+
+## Environment Variables
+
+**Required:**
+- `CALLS_APP_ID`: From dashboard
+- `CALLS_APP_SECRET`: From dashboard (secret)
+
+**Optional:**
+- `MAX_WEBCAM_BITRATE` (default: 1200000)
+- `MAX_WEBCAM_FRAMERATE` (default: 24)
+- `MAX_WEBCAM_QUALITY_LEVEL` (default: 1080)
+- `TURN_SERVICE_ID`: TURN service
+- `TURN_SERVICE_TOKEN`: TURN auth (secret)
+
+## TURN Configuration
+
+```javascript
+const pc = new RTCPeerConnection({
+  iceServers: [
+    { urls: 'stun:stun.cloudflare.com:3478' },
+    {
+      urls: [
+        'turn:turn.cloudflare.com:3478?transport=udp',
+        'turn:turn.cloudflare.com:3478?transport=tcp',
+        'turns:turn.cloudflare.com:5349?transport=tcp'
+      ],
+      username: turnUsername,
+      credential: turnCredential
+    }
+  ]
+});
+```
+
+**Ports:** 3478 (UDP/TCP), 53 (UDP), 80 (TCP), 443 (TLS), 5349 (TLS)

package/.codex/skills/cloudflare/references/realtime-sfu/gotchas.md

@@ -0,0 +1,75 @@
+# Gotchas & Troubleshooting
+
+## Common Issues
+
+**Slow connect (~1.8s):** First STUN delayed (consensus forming), normal, subsequent faster
+**USE-CANDIDATE delay (Chrome):** CF detects DTLS ClientHello early to compensate
+
+**No media flow checklist:**
+1. SDP exchange done? 2. `pc.connectionState === 'connected'`? 3. Tracks added before offer? 4. Browser perms? 5. `chrome://webrtc-internals`
+
+**Track not RX checklist:**
+1. Published OK? 2. Track ID shared? 3. Session IDs match? 4. `pc.ontrack` before answer? 5. Renegotiation done?
+
+## Debug
+
+`chrome://webrtc-internals`: ICE pairs, DTLS, media stats, bandwidth
+
+Logging:
+```ts
+pc.addEventListener('icecandidateerror', (e) => console.error('ICE err:', e));
+pc.addEventListener('connectionstatechange', () => console.log('Conn:', pc.connectionState));
+pc.addEventListener('iceconnectionstatechange', () => console.log('ICE:', pc.iceConnectionState));
+```
+
+Quality:
+```ts
+setInterval(async () => {
+  const stats = await pc.getStats();
+  stats.forEach(r => {
+    if (r.type === 'inbound-rtp' && r.kind === 'video')
+      console.log('Loss:', r.packetsLost, 'Jitter:', r.jitter, 'Bytes:', r.bytesReceived);
+  });
+}, 1000);
+```
+
+## Security
+
+❌ Never expose App Secret client-side (use backend env vars, Wrangler secrets)
+Track IDs = capabilities, authz required:
+```ts
+app.post('/api/sessions/:sid/tracks', async (req, res) => {
+  for (const t of req.body.tracks)
+    if (!await canAccessTrack(req.user.id, t.trackName)) return res.status(403).json({error: 'Unauth'});
+  // CF API call
+});
+```
+Validate session ownership, timeouts, cleanup abandoned
+
+## Pricing & Limits
+
+Free: 1TB/mo egress. Paid: $0.05/GB. Inbound free. TURN free w/SFU. No participant/track limits (client bandwidth/CPU bound). Optimize: bitrates, simulcast, adaptive, cleanup
+
+## vs Traditional SFUs
+
+| Aspect | Traditional | Cloudflare |
+|--------|------------|------------|
+| Deploy | Single region | 310+ DCs |
+| Route | Manual | Anycast |
+| SDK | Often required | Pure WebRTC |
+| Arch | Rooms | Sessions/tracks |
+| Scale | Vertical/horiz | Auto global |
+| TURN | Separate | Integrated |
+| State | Centralized | Distributed |
+
+## Quick Ref
+
+```bash
+POST /v1/apps/{appId}/sessions/new  # Create
+POST .../sessions/{sid}/tracks/new  # Pub: {sessionDescription, tracks: [{location:'local',trackName}]}
+POST .../sessions/{sid}/tracks/new  # Sub: {tracks:[{location:'remote',trackName,sessionId}]}
+PUT .../sessions/{sid}/renegotiate  # Renegotiate
+PUT .../sessions/{sid}/tracks/close # Close
+```
+
+CF SFU: unopinionated, full WebRTC control, max flexibility, needs fundamentals

package/.codex/skills/cloudflare/references/realtime-sfu/patterns.md

@@ -0,0 +1,102 @@
+# Patterns & Use Cases
+
+## Architecture
+
+```
+Client (WebRTC) <---> CF Edge <---> Backend (HTTP)
+                           |
+                    CF Backbone (310+ DCs)
+                           |
+                    Other Edges <---> Other Clients
+```
+
+Anycast: Last-mile <50ms (95%), no region select, NACK shield, distributed consensus
+
+Cascading trees auto-scale to millions:
+```
+Publisher -> Edge A -> Edge B -> Sub1
+                    \-> Edge C -> Sub2,3
+```
+
+## Use Cases
+
+**1:1:** A creates session+publishes, B creates+subscribes to A+publishes, A subscribes to B
+**N:N:** All create session+publish, backend broadcasts track IDs, all subscribe to others
+**1:N:** Publisher creates+publishes, viewers each create+subscribe (no fan-out limit)
+**Breakout:** Same PeerConnection! Backend closes/adds tracks, no recreation
+
+## Backend
+
+Express:
+```js
+app.post('/api/new-session', async (req, res) => {
+  const r = await fetch(`${CALLS_API}/apps/${process.env.CALLS_APP_ID}/sessions/new`,
+    {method: 'POST', headers: {'Authorization': `Bearer ${process.env.CALLS_APP_SECRET}`}});
+  res.json(await r.json());
+});
+```
+
+Workers:
+```ts
+export default {
+  async fetch(req: Request, env: Env) {
+    return fetch(`https://rtc.live/v1/apps/${env.CALLS_APP_ID}/sessions/new`,
+      {method: 'POST', headers: {'Authorization': `Bearer ${env.CALLS_APP_SECRET}`}});
+  }
+};
+```
+
+DO Presence:
+```ts
+export class Room {
+  sessions = new Map(); // sessionId -> {userId, tracks: [{trackName, kind}]}
+
+  async fetch(req: Request) {
+    const {pathname} = new URL(req.url);
+    if (pathname === '/join') {
+      const {sessionId, userId} = await req.json();
+      this.sessions.set(sessionId, {userId, tracks: []});
+      const existingTracks = Array.from(this.sessions.entries())
+        .filter(([id]) => id !== sessionId)
+        .flatMap(([id, data]) => data.tracks.map(t => ({...t, sessionId: id})));
+      return Response.json({existingTracks});
+    }
+    if (pathname === '/publish') {
+      const {sessionId, tracks} = await req.json();
+      this.sessions.get(sessionId)?.tracks.push(...tracks); // Notify others via WS
+      return new Response('OK');
+    }
+  }
+}
+```
+
+## Advanced
+
+Bandwidth mgmt:
+```ts
+const s = pc.getSenders().find(s => s.track?.kind === 'video');
+const p = s.getParameters();
+if (!p.encodings) p.encodings = [{}];
+p.encodings[0].maxBitrate = 1200000; p.encodings[0].maxFramerate = 24;
+await s.setParameters(p);
+```
+
+Simulcast (CF auto-forwards best layer):
+```ts
+pc.addTransceiver('video', {direction: 'sendonly', sendEncodings: [
+  {rid: 'high', maxBitrate: 1200000},
+  {rid: 'med', maxBitrate: 600000, scaleResolutionDownBy: 2},
+  {rid: 'low', maxBitrate: 200000, scaleResolutionDownBy: 4}
+]});
+```
+
+DataChannel:
+```ts
+const dc = pc.createDataChannel('chat', {ordered: true, maxRetransmits: 3});
+dc.onopen = () => dc.send(JSON.stringify({type: 'chat', text: 'Hi'}));
+dc.onmessage = (e) => console.log('RX:', JSON.parse(e.data));
+```
+
+Integrations: R2 for recording `env.R2_BUCKET.put(...)`, Queues for analytics
+
+Perf: 100-250ms connect, ~50ms latency (95%), 200-400ms glass-to-glass, no participant limit (client: 10-50 tracks)

package/.codex/skills/cloudflare/references/realtimekit/README.md

@@ -0,0 +1,81 @@
+# Cloudflare RealtimeKit
+
+Expert guidance for building real-time video and audio applications using **Cloudflare RealtimeKit** - a comprehensive SDK suite for adding customizable live video and voice to web or mobile applications.
+
+## Overview
+
+RealtimeKit is Cloudflare's SDK suite built on Realtime SFU, abstracting WebRTC complexity with fast integration, pre-built UI components, global performance (300+ cities), and production features (recording, transcription, chat, polls).
+
+**Use cases**: Team meetings, webinars, social video, audio calls, interactive plugins
+
+## Core Concepts
+
+- **App**: Workspace grouping meetings, participants, presets, recordings. Use separate Apps for staging/production
+- **Meeting**: Re-usable virtual room. Each join creates new **Session**
+- **Session**: Live meeting instance. Created on first join, ends after last leave
+- **Participant**: User added via REST API. Returns `authToken` for client SDK. **Do not reuse tokens**
+- **Preset**: Reusable permission/UI template (permissions, meeting type, theme). Applied at participant creation
+- **Peer ID** (`id`): Unique per session, changes on rejoin
+- **Participant ID** (`userId`): Persistent across sessions
+
+## Quick Start
+
+### 1. Create App & Meeting (Backend)
+
+```bash
+# Create app
+curl -X POST 'https://api.cloudflare.com/client/v4/accounts/<account_id>/realtime/kit/apps' \
+  -H 'Authorization: Bearer <api_token>' \
+  -d '{"name": "My RealtimeKit App"}'
+
+# Create meeting
+curl -X POST 'https://api.cloudflare.com/client/v4/accounts/<account_id>/realtime/kit/<app_id>/meetings' \
+  -H 'Authorization: Bearer <api_token>' \
+  -d '{"title": "Team Standup"}'
+
+# Add participant
+curl -X POST 'https://api.cloudflare.com/client/v4/accounts/<account_id>/realtime/kit/<app_id>/meetings/<meeting_id>/participants' \
+  -H 'Authorization: Bearer <api_token>' \
+  -d '{"name": "Alice", "preset_name": "host"}'
+# Returns: { authToken }
+```
+
+### 2. Client Integration
+
+**React**:
+```tsx
+import { RtkMeeting } from '@cloudflare/realtimekit-react-ui';
+
+function App() {
+  return <RtkMeeting authToken="<participant_auth_token>" onLeave={() => {}} />;
+}
+```
+
+**Core SDK**:
+```typescript
+import RealtimeKitClient from '@cloudflare/realtimekit';
+
+const meeting = new RealtimeKitClient({ authToken: '<token>', video: true, audio: true });
+await meeting.join();
+```
+
+## In This Reference
+
+- [Configuration](./configuration.md) - Setup, installation, wrangler config
+- [API](./api.md) - Meeting object, REST API, SDK methods
+- [Patterns](./patterns.md) - Common workflows, code examples
+- [Gotchas](./gotchas.md) - Common issues, troubleshooting
+
+## See Also
+
+- [Workers](../workers/) - Backend integration
+- [D1](../d1/) - Meeting metadata storage
+- [R2](../r2/) - Recording storage
+- [KV](../kv/) - Session management
+
+## Reference Links
+
+- **Official Docs**: https://developers.cloudflare.com/realtime/realtimekit/
+- **API Reference**: https://developers.cloudflare.com/api/resources/realtime_kit/
+- **Examples**: https://github.com/cloudflare/realtimekit-web-examples
+- **Dashboard**: https://dash.cloudflare.com/?to=/:account/realtime/kit

package/.codex/skills/cloudflare/references/realtimekit/api.md

@@ -0,0 +1,164 @@
+# RealtimeKit API Reference
+
+Complete API reference for Meeting object, REST endpoints, and SDK methods.
+
+## Meeting Object API
+
+### `meeting.self` - Local Participant
+
+```typescript
+// Properties: id, userId, name, audioEnabled, videoEnabled, screenShareEnabled, audioTrack, videoTrack, screenShareTracks, roomJoined, roomState
+// Methods
+await meeting.self.enableAudio() / disableAudio() / enableVideo() / disableVideo() / enableScreenShare() / disableScreenShare()
+await meeting.self.setName("Name")  // Before join only
+await meeting.self.setDevice(device)
+const devices = await meeting.self.getAllDevices() / getAudioDevices() / getVideoDevices() / getSpeakerDevices()
+// Events: 'roomJoined', 'audioUpdate', 'videoUpdate', 'screenShareUpdate', 'deviceUpdate', 'deviceListUpdate'
+meeting.self.on('roomJoined', () => {})
+meeting.self.on('audioUpdate', ({ audioEnabled, audioTrack }) => {})
+```
+
+### `meeting.participants` - Remote Participants
+
+**Collections**:
+```typescript
+meeting.participants.joined / active / waitlisted / pinned  // Maps
+const participants = meeting.participants.joined.toArray()
+const count = meeting.participants.joined.size()
+const p = meeting.participants.joined.get('peer-id')
+```
+
+**Participant Properties**:
+```typescript
+participant.id / userId / name
+participant.audioEnabled / videoEnabled / screenShareEnabled
+participant.audioTrack / videoTrack / screenShareTracks
+```
+
+**Events**:
+```typescript
+meeting.participants.joined.on('participantJoined', (participant) => {})
+meeting.participants.joined.on('participantLeft', (participant) => {})
+```
+
+### `meeting.meta` - Metadata
+```typescript
+meeting.meta.meetingId / meetingTitle / meetingStartedTimestamp
+```
+
+### `meeting.chat` - Chat
+```typescript
+meeting.chat.messages  // Array
+await meeting.chat.sendTextMessage("Hello") / sendImageMessage(file)
+meeting.chat.on('chatUpdate', ({ message, messages }) => {})
+```
+
+### `meeting.polls` - Polling
+```typescript
+meeting.polls.items  // Array
+await meeting.polls.create(question, options, anonymous, hideVotes)
+await meeting.polls.vote(pollId, optionIndex)
+```
+
+### `meeting.plugins` - Collaborative Apps
+```typescript
+meeting.plugins.all  // Array
+await meeting.plugins.activate(pluginId) / deactivate()
+```
+
+### `meeting.ai` - AI Features
+```typescript
+meeting.ai.transcripts  // Live transcriptions (when enabled in Preset)
+```
+
+### Core Methods
+```typescript
+await meeting.join()   // Emits 'roomJoined' on meeting.self
+await meeting.leave()
+```
+
+## REST API
+
+Base: `https://api.cloudflare.com/client/v4/accounts/{account_id}/realtime/kit/{app_id}`
+
+### Meetings
+```bash
+GET    /meetings                                    # List all
+GET    /meetings/{meeting_id}                       # Get details
+POST   /meetings                                    # Create: {"title": "..."}
+PATCH  /meetings/{meeting_id}                       # Update: {"title": "...", "record_on_start": true}
+```
+
+### Participants
+```bash
+GET    /meetings/{meeting_id}/participants                          # List all
+GET    /meetings/{meeting_id}/participants/{participant_id}         # Get details
+POST   /meetings/{meeting_id}/participants                          # Add: {"name": "...", "preset_name": "...", "custom_participant_id": "..."}
+PATCH  /meetings/{meeting_id}/participants/{participant_id}         # Update: {"name": "...", "preset_name": "..."}
+DELETE /meetings/{meeting_id}/participants/{participant_id}         # Delete
+POST   /meetings/{meeting_id}/participants/{participant_id}/token   # Refresh token
+```
+
+### Active Session
+```bash
+GET  /meetings/{meeting_id}/active-session               # Get active session
+POST /meetings/{meeting_id}/active-session/kick          # Kick users: {"user_ids": ["id1", "id2"]}
+POST /meetings/{meeting_id}/active-session/kick-all      # Kick all
+POST /meetings/{meeting_id}/active-session/poll          # Create poll: {"question": "...", "options": [...], "anonymous": false}
+```
+
+### Recording
+```bash
+GET  /recordings?meeting_id={meeting_id}                 # List recordings
+GET  /recordings/active-recording/{meeting_id}           # Get active recording
+POST /recordings                                         # Start: {"meeting_id": "...", "type": "composite"} (or "track")
+PUT  /recordings/{recording_id}                          # Control: {"action": "pause"} (or "resume", "stop")
+POST /recordings/track                                   # Track recording: {"meeting_id": "...", "layers": [...]}
+```
+
+### Livestreaming
+```bash
+GET  /livestreams?exclude_meetings=false                                # List all
+GET  /livestreams/{livestream_id}                                       # Get details
+POST /meetings/{meeting_id}/livestreams                                 # Start for meeting
+POST /meetings/{meeting_id}/active-livestream/stop                      # Stop
+POST /livestreams                                                       # Create independent: returns {ingest_server, stream_key, playback_url}
+```
+
+### Sessions & Analytics
+```bash
+GET  /sessions                                                          # List all
+GET  /sessions/{session_id}                                             # Get details
+GET  /sessions/{session_id}/participants                                # List participants
+GET  /sessions/{session_id}/participants/{participant_id}               # Call stats
+GET  /sessions/{session_id}/chat                                        # Download chat CSV
+GET  /sessions/{session_id}/transcript                                  # Download transcript CSV
+GET  /sessions/{session_id}/summary                                     # Get summary
+POST /sessions/{session_id}/summary                                     # Generate summary
+GET  /analytics/daywise?start_date=YYYY-MM-DD&end_date=YYYY-MM-DD      # Day-wise analytics
+GET  /analytics/livestreams/overall                                     # Livestream analytics
+```
+
+### Webhooks
+```bash
+GET    /webhooks                    # List all
+POST   /webhooks                    # Create: {"url": "https://...", "events": ["session.started", "session.ended"]}
+PATCH  /webhooks/{webhook_id}       # Update
+DELETE /webhooks/{webhook_id}       # Delete
+```
+
+## Session Lifecycle
+
+```
+Initialization → Join Intent → [Waitlist?] → Meeting Screen (Stage) → Ended
+                                   ↓ Approved
+                               [Rejected → Ended]
+```
+
+UI Kit handles state transitions automatically.
+
+## See Also
+
+- [Configuration](./configuration.md) - Setup and installation
+- [Patterns](./patterns.md) - Usage examples
+- [README](./README.md) - Overview and quick start

package/.codex/skills/cloudflare/references/realtimekit/configuration.md

@@ -0,0 +1,147 @@
+# RealtimeKit Configuration
+
+Configuration guide for RealtimeKit setup, client SDKs, and wrangler integration.
+
+## Installation
+
+### React
+```bash
+npm install @cloudflare/realtimekit @cloudflare/realtimekit-react-ui
+```
+
+### Angular
+```bash
+npm install @cloudflare/realtimekit @cloudflare/realtimekit-angular-ui
+```
+
+### Web Components/HTML
+```bash
+npm install @cloudflare/realtimekit @cloudflare/realtimekit-ui
+```
+
+## Client SDK Configuration
+
+### React UI Kit
+```tsx
+import { RtkMeeting } from '@cloudflare/realtimekit-react-ui';
+<RtkMeeting authToken="<token>" onLeave={() => {}} />
+```
+
+### Angular UI Kit
+```typescript
+@Component({ template: `<rtk-meeting [authToken]="authToken" (rtkLeave)="onLeave($event)"></rtk-meeting>` })
+export class AppComponent { authToken = '<token>'; onLeave() {} }
+```
+
+### Web Components
+```html
+<script type="module" src="https://cdn.jsdelivr.net/npm/@cloudflare/realtimekit-ui/dist/realtimekit-ui/realtimekit-ui.esm.js"></script>
+<rtk-meeting id="meeting"></rtk-meeting>
+<script>
+  document.getElementById('meeting').authToken = '<token>';
+</script>
+```
+
+### Core SDK Configuration
+```typescript
+import RealtimeKitClient from '@cloudflare/realtimekit';
+
+const meeting = new RealtimeKitClient({
+  authToken: '<token>',
+  video: true, audio: true, autoSwitchAudioDevice: true,
+  mediaConfiguration: {
+    video: { width: { ideal: 1280 }, height: { ideal: 720 }, frameRate: { ideal: 30 } },
+    audio: { echoCancellation: true, noiseSuppression: true, autoGainControl: true },
+    screenshare: { width: { max: 1920 }, height: { max: 1080 }, frameRate: { ideal: 15 } }
+  }
+});
+await meeting.join();
+```
+
+## Backend Setup
+
+### Create App & Credentials
+
+**Dashboard**: https://dash.cloudflare.com/?to=/:account/realtime/kit
+
+**API**:
+```bash
+curl -X POST 'https://api.cloudflare.com/client/v4/accounts/<account_id>/realtime/kit/apps' \
+  -H 'Content-Type: application/json' \
+  -H 'Authorization: Bearer <api_token>' \
+  -d '{"name": "My RealtimeKit App"}'
+```
+
+**Required Permissions**: API token with **Realtime / Realtime Admin** permissions
+
+### Create Presets
+
+```bash
+curl -X POST 'https://api.cloudflare.com/client/v4/accounts/<account_id>/realtime/kit/<app_id>/presets' \
+  -H 'Authorization: Bearer <api_token>' \
+  -d '{
+    "name": "host",
+    "permissions": {
+      "canShareAudio": true,
+      "canShareVideo": true,
+      "canRecord": true,
+      "canLivestream": true,
+      "canStartStopRecording": true
+    }
+  }'
+```
+
+## Wrangler Configuration
+
+### Basic Configuration
+```jsonc
+// wrangler.jsonc
+{
+  "name": "realtimekit-app",
+  "main": "src/index.ts",
+  "compatibility_date": "2025-01-01",  // Use current date
+  "vars": {
+    "CLOUDFLARE_ACCOUNT_ID": "abc123",
+    "REALTIMEKIT_APP_ID": "xyz789"
+  }
+  // Secrets: wrangler secret put CLOUDFLARE_API_TOKEN
+}
+```
+
+### With Database & Storage
+```jsonc
+{
+  "d1_databases": [{ "binding": "DB", "database_name": "meetings", "database_id": "d1-id" }],
+  "r2_buckets": [{ "binding": "RECORDINGS", "bucket_name": "recordings" }],
+  "kv_namespaces": [{ "binding": "SESSIONS", "id": "kv-id" }]
+}
+```
+
+### Multi-Environment
+```bash
+# Deploy to environments
+wrangler deploy --env staging
+wrangler deploy --env production
+```
+
+## TURN Service Configuration
+
+RealtimeKit can use Cloudflare's TURN service for connectivity through restrictive networks:
+
+```jsonc
+// wrangler.jsonc
+{
+  "vars": {
+    "TURN_SERVICE_ID": "your_turn_service_id"
+  }
+  // Set secret: wrangler secret put TURN_SERVICE_TOKEN
+}
+```
+
+TURN automatically configured when enabled in account - no client-side changes needed.
+
+## See Also
+
+- [API](./api.md) - Meeting APIs, REST endpoints
+- [Patterns](./patterns.md) - Backend integration examples
+- [README](./README.md) - Overview and quick start