feat: realtime agent reference

skills/supabase/AGENTS.md

@@ -62,6 +62,17 @@ Reference files are named `{prefix}-{topic}.md` (e.g., `query-missing-indexes.md
 - `references/db-security-functions.md`
 - `references/db-security-service-role.md`
 
+**Realtime** (`realtime-`):
+- `references/realtime-broadcast-basics.md`
+- `references/realtime-broadcast-database.md`
+- `references/realtime-patterns-cleanup.md`
+- `references/realtime-patterns-debugging.md`
+- `references/realtime-patterns-errors.md`
+- `references/realtime-postgres-changes.md`
+- `references/realtime-presence-tracking.md`
+- `references/realtime-setup-auth.md`
+- `references/realtime-setup-channels.md`
+
 ---
 
-*18 reference files across 11 categories*
+*27 reference files across 11 categories*

skills/supabase/SKILL.md

@@ -4,7 +4,7 @@ description: Guides and best practices for working with Supabase. Covers getting
 license: MIT
 metadata:
   author: supabase
-  version: "1.0.0"
+  version: '1.0.0'
   organization: Supabase
   date: January 2026
   abstract: Comprehensive Supabase development guide for building applications with Supabase services. Contains guides covering Auth, Database, Storage, Edge Functions, Realtime, client libraries, CLI, and tooling. Each reference includes setup instructions, code examples, common mistakes, and integration patterns.
@@ -33,13 +33,23 @@ Reference the appropriate resource file based on the user's needs:
 
 ### Database
 
-| Area               | Resource                         | When to Use                                    |
-| ------------------ | -------------------------------- | ---------------------------------------------- |
-| RLS Security       | `references/db-rls-*.md`         | Row Level Security policies, common mistakes   |
-| Connection Pooling | `references/db-conn-pooling.md`  | Transaction vs Session mode, port 6543 vs 5432 |
-| Schema Design      | `references/db-schema-*.md`      | auth.users FKs, timestamps, JSONB, extensions  |
-| Migrations         | `references/db-migrations-*.md`  | CLI workflows, idempotent patterns, db diff    |
-| Performance        | `references/db-perf-*.md`        | Indexes (BRIN, GIN), query optimization        |
-| Security           | `references/db-security-*.md`    | Service role key, security_definer functions   |
+| Area               | Resource                        | When to Use                                    |
+| ------------------ | ------------------------------- | ---------------------------------------------- |
+| RLS Security       | `references/db-rls-*.md`        | Row Level Security policies, common mistakes   |
+| Connection Pooling | `references/db-conn-pooling.md` | Transaction vs Session mode, port 6543 vs 5432 |
+| Schema Design      | `references/db-schema-*.md`     | auth.users FKs, timestamps, JSONB, extensions  |
+| Migrations         | `references/db-migrations-*.md` | CLI workflows, idempotent patterns, db diff    |
+| Performance        | `references/db-perf-*.md`       | Indexes (BRIN, GIN), query optimization        |
+| Security           | `references/db-security-*.md`   | Service role key, security_definer functions   |
+
+### Realtime
+
+| Area             | Resource                             | When to Use                                     |
+| ---------------- | ------------------------------------ | ----------------------------------------------- |
+| Channel Setup    | `references/realtime-setup-*.md`     | Creating channels, naming conventions, auth     |
+| Broadcast        | `references/realtime-broadcast-*.md` | Client messaging, database-triggered broadcasts |
+| Presence         | `references/realtime-presence-*.md`  | User online status, shared state tracking       |
+| Postgres Changes | `references/realtime-postgres-*.md`  | Database change listeners (prefer Broadcast)    |
+| Patterns         | `references/realtime-patterns-*.md`  | Cleanup, error handling, React integration      |
 
 **CLI Usage:** Always use `npx supabase` instead of `supabase` for version consistency across team members.

skills/supabase/references/realtime-broadcast-basics.md

@@ -0,0 +1,94 @@
+---
+title: Send and Receive Broadcast Messages
+impact: HIGH
+impactDescription: Core pattern for real-time client-to-client messaging
+tags: realtime, broadcast, send, receive, subscribe
+---
+
+## Send and Receive Broadcast Messages
+
+Broadcast enables low-latency pub/sub messaging between clients. Prefer Broadcast over Postgres Changes for applications that require more concurrent connections.
+
+## Subscribe to Broadcast Events
+
+```javascript
+const channel = supabase.channel('room:123:messages', {
+  config: { private: true },
+})
+
+channel
+  .on('broadcast', { event: 'message_created' }, (payload) => {
+    console.log('New message:', payload.payload)
+  })
+  .on('broadcast', { event: '*' }, (payload) => {
+    // Listen to all events on this channel
+  })
+  .subscribe((status) => {
+    if (status === 'SUBSCRIBED') {
+      console.log('Connected!')
+    }
+  })
+```
+
+## Send Messages
+
+**After subscribing (WebSocket - lower latency):**
+
+```javascript
+channel.send({
+  type: 'broadcast',
+  event: 'message_created',
+  payload: { text: 'Hello!', user_id: '123' },
+})
+```
+
+**Before subscribing or one-off (HTTP):**
+
+```javascript
+await channel.httpSend('message_created', { text: 'Hello!' })
+```
+
+## Receive Own Messages
+
+By default, senders don't receive their own broadcasts.
+
+**Incorrect:**
+
+```javascript
+// Won't receive own messages
+const channel = supabase.channel('room:123')
+```
+
+**Correct:**
+
+```javascript
+// Enable self-receive when needed (e.g., optimistic UI confirmation)
+const channel = supabase.channel('room:123', {
+  config: {
+    broadcast: { self: true },
+  },
+})
+```
+
+## Get Server Acknowledgment
+
+```javascript
+const channel = supabase.channel('room:123', {
+  config: {
+    broadcast: { ack: true },
+  },
+})
+
+// Returns 'ok' when server confirms receipt
+const status = await channel.send({
+  type: 'broadcast',
+  event: 'message_created',
+  payload: { text: 'Hello!' },
+})
+```
+
+## Related
+
+- [broadcast-database.md](broadcast-database.md)
+- [patterns-cleanup.md](patterns-cleanup.md)
+- [Docs](https://supabase.com/docs/guides/realtime/broadcast)

skills/supabase/references/realtime-broadcast-database.md

@@ -0,0 +1,95 @@
+---
+title: Broadcast from Database Triggers
+impact: CRITICAL
+impactDescription: Scalable pattern for notifying clients of database changes
+tags: realtime, broadcast, database, triggers, realtime.send, realtime.broadcast_changes
+---
+
+## Broadcast from Database Triggers
+
+Use database triggers with `realtime.broadcast_changes()` instead of `postgres_changes` for better scalability. This avoids per-subscriber RLS checks.
+
+## realtime.broadcast_changes()
+
+Broadcasts database changes in a standard format.
+
+```sql
+create or replace function room_messages_broadcast()
+returns trigger
+security definer
+language plpgsql
+as $$
+begin
+  perform realtime.broadcast_changes(
+    'room:' || coalesce(new.room_id, old.room_id)::text,  -- topic
+    tg_op,                                                 -- event (INSERT/UPDATE/DELETE)
+    tg_op,                                                 -- operation
+    tg_table_name,                                         -- table
+    tg_table_schema,                                       -- schema
+    new,                                                   -- new record
+    old                                                    -- old record
+  );
+  return coalesce(new, old);
+end;
+$$;
+
+create trigger messages_broadcast_trigger
+  after insert or update or delete on messages
+  for each row execute function room_messages_broadcast();
+```
+
+**Client subscription:**
+
+```javascript
+const channel = supabase
+  .channel('room:123', { config: { private: true } })
+  .on('broadcast', { event: 'INSERT' }, (payload) => console.log('Insert:', payload))
+  .on('broadcast', { event: 'UPDATE' }, (payload) => console.log('Update:', payload))
+  .on('broadcast', { event: 'DELETE' }, (payload) => console.log('Delete:', payload))
+  .subscribe()
+```
+
+## realtime.send()
+
+Sends custom payloads without table binding.
+
+```sql
+select realtime.send(
+  jsonb_build_object('message', 'Custom notification'),  -- payload
+  'notification_sent',                                   -- event
+  'user:456:notifications',                              -- topic
+  true                                                   -- private (true = requires auth)
+);
+```
+
+## Public vs Private Mismatch
+
+**Incorrect:**
+
+```sql
+-- Database sends to public channel
+select realtime.send('{}', 'event', 'topic', false);  -- private = false
+```
+
+```javascript
+// Client expects private channel - won't receive message
+const channel = supabase.channel('topic', { config: { private: true } })
+```
+
+**Correct:**
+
+```sql
+-- Database sends to private channel
+select realtime.send('{}', 'event', 'topic', true);  -- private = true
+```
+
+```javascript
+// Client matches
+const channel = supabase.channel('topic', { config: { private: true } })
+```
+
+## Related
+
+- [setup-auth.md](setup-auth.md)
+- [broadcast-basics.md](broadcast-basics.md)
+- [Docs](https://supabase.com/docs/guides/realtime/broadcast)

skills/supabase/references/realtime-patterns-cleanup.md

@@ -0,0 +1,92 @@
+---
+title: Clean Up Channels to Prevent Memory Leaks
+impact: CRITICAL
+impactDescription: Prevents memory leaks and connection quota exhaustion
+tags: realtime, cleanup, react, lifecycle, removeChannel
+---
+
+## Clean Up Channels to Prevent Memory Leaks
+
+Always remove channels when components unmount or subscriptions are no longer needed.
+
+## React Pattern
+
+**Incorrect:**
+
+```javascript
+function ChatRoom({ roomId }) {
+  useEffect(() => {
+    const channel = supabase.channel(`room:${roomId}`)
+    channel.on('broadcast', { event: 'message' }, handleMessage).subscribe()
+    // Missing cleanup - channel persists after unmount
+  }, [roomId])
+}
+```
+
+**Correct:**
+
+```javascript
+function ChatRoom({ roomId }) {
+  const channelRef = useRef(null)
+
+  useEffect(() => {
+    // Prevent duplicate subscriptions
+    if (channelRef.current?.state === 'subscribed') return
+
+    const channel = supabase.channel(`room:${roomId}:messages`, {
+      config: { private: true },
+    })
+    channelRef.current = channel
+
+    channel
+      .on('broadcast', { event: 'message_created' }, handleMessage)
+      .subscribe()
+
+    return () => {
+      if (channelRef.current) {
+        supabase.removeChannel(channelRef.current)
+        channelRef.current = null
+      }
+    }
+  }, [roomId])
+}
+```
+
+## Channel Lifecycle Methods
+
+```javascript
+// Remove specific channel
+supabase.removeChannel(channel)
+
+// Remove all channels (e.g., on logout)
+supabase.removeAllChannels()
+
+// Get active channels
+const channels = supabase.getChannels()
+```
+
+## Check Channel State Before Subscribing
+
+```javascript
+// Prevent duplicate subscriptions
+if (channel.state === 'subscribed') {
+  return
+}
+channel.subscribe()
+```
+
+## Connection Quotas
+
+| Plan | Max Connections | Channels per Connection |
+|------|-----------------|------------------------|
+| Free | 200 | 100 |
+| Pro | 500 | 100 |
+| Team | 10,000 | 100 |
+
+Leaked channels count against quotas even when inactive.
+For Pay as you go customers you can edit these limits on [Realtime Settings](https://supabase.com/dashboard/project/_/realtime/settings)
+## Related
+
+- [patterns-errors.md](patterns-errors.md)
+- [setup-channels.md](setup-channels.md)
+- [Docs](https://supabase.com/docs/guides/realtime/quotas)