diff --git a/spec/supabase_js_v2_legacy.yml b/spec/supabase_js_v2_legacy.yml
index 284a35b1e4e..ee7779ad29e 100644
--- a/spec/supabase_js_v2_legacy.yml
+++ b/spec/supabase_js_v2_legacy.yml
@@ -1153,15 +1153,17 @@ pages:
     $ref: '@supabase/realtime-js.RealtimeChannel.on'
     notes: |
       - Realtime is disabled by default for new Projects for better database performance and security. You can turn it on by [managing replication](/docs/guides/api#managing-realtime).
+      - Row level security is not applied to delete statements.
       - If you want to receive the "previous" data for updates and deletes, you will need to set `REPLICA IDENTITY` to `FULL`, like this: `ALTER TABLE your_table REPLICA IDENTITY FULL;`
+      - When a delete occurs, the contents of old_record will be broadcast to all subscribers to that table so ensure that each table's replica identity only contains information that is safe to expose publicly.
     examples:
       - name: Listen to all database changes
         isSpotlight: true
         js: |
           ```js
-          const mySubscription = supabase
-            .from('*')
-            .on('*', payload => {
+          const myChannel = supabase
+            .channel('*')
+            .on('postgres_changes', { event: '*', schema: '*' }, payload => {
               console.log('Change received!', payload)
             })
             .subscribe()
@@ -1169,9 +1171,9 @@ pages:
       - name: Listening to a specific table
         js: |
           ```js
-          const mySubscription = supabase
-            .from('countries')
-            .on('*', payload => {
+          const myChannel = supabase
+            .channel('public:countries')
+            .on('postgres_changes', { event: '*', schema: 'public', table: 'countries' }, payload => {
               console.log('Change received!', payload)
             })
             .subscribe()
@@ -1179,9 +1181,9 @@ pages:
       - name: Listening to inserts
         js: |
           ```js
-          const mySubscription = supabase
-            .from('countries')
-            .on('INSERT', payload => {
+          const myChannel = supabase
+            .channel('public:countries')
+            .on('postgres_changes', { event: 'INSERT', schema: 'public', table: 'countries' }, payload => {
               console.log('Change received!', payload)
             })
             .subscribe()
@@ -1189,16 +1191,16 @@ pages:
       - name: Listening to updates
         description: |
           By default, Supabase will send only the updated record. If you want to receive the previous values as well you can
-          enable full replication for the table you are listening too:
+          enable full replication for the table you are listening to:
 
           ```sql
           alter table "your_table" replica identity full;
           ```
         js: |
           ```js
-          const mySubscription = supabase
-            .from('countries')
-            .on('UPDATE', payload => {
+          const myChannel = supabase
+            .channel('public:countries')
+            .on('postgres_changes', { event: 'UPDATE', schema: 'public', table: 'countries' }, payload => {
               console.log('Change received!', payload)
             })
             .subscribe()
@@ -1213,9 +1215,9 @@ pages:
           ```
         js: |
           ```js
-          const mySubscription = supabase
-            .from('countries')
-            .on('DELETE', payload => {
+          const myChannel = supabase
+            .channel('public:countries')
+            .on('postgres_changes', { event: 'DELETE', schema: 'public', table: 'countries' }, payload => {
               console.log('Change received!', payload)
             })
             .subscribe()
@@ -1224,10 +1226,10 @@ pages:
         description: You can chain listeners if you want to listen to multiple events for each table.
         js: |
           ```js
-          const mySubscription = supabase
-            .from('countries')
-            .on('INSERT', handleRecordInserted)
-            .on('DELETE', handleRecordDeleted)
+          const myChannel = supabase
+            .channel('public:countries')
+            .on('postgres_changes', { event: 'INSERT', schema: 'public', table: 'countries' }, handleRecordInserted)
+            .on('postgres_changes', { event: 'DELETE', schema: 'public', table: 'countries' }, handleRecordDeleted)
             .subscribe()
           ```
       - name: Listening to row level changes
@@ -1236,9 +1238,9 @@ pages:
           - ``eq`` filter works with all database types as under the hood, it's casting both the filter value and the database value to the correct type and then comparing them.
         js: |
           ```js
-          const mySubscription = supabase
-            .from('countries:id=eq.200')
-            .on('UPDATE', handleRecordUpdated)
+          const myChannel = supabase
+            .channel('public:countries:id=eq.200')
+            .on('postgres_changes', { event: 'UPDATE', schema: 'public', table: 'countries', filter: 'id=eq.200' }, handleRecordUpdated)
             .subscribe()
           ```
 
@@ -1246,22 +1248,22 @@ pages:
     title: 'removeChannel()'
     $ref: '@supabase/supabase-js.index.SupabaseClient.removeChannel'
     notes: |
-      - Removing subscriptions is a great way to maintain the performance of your project's database. Supabase will automatically handle cleanup 30 seconds after a user is disconnected, but unused subscriptions may cause degradation as more users are simultaneously subscribed.
+      - Removing a channel is a great way to maintain the performance of your project's Realtime service as well as your database if you're listening to Postgres changes. Supabase will automatically handle cleanup 30 seconds after a client is disconnected, but unused channels may cause degradation as more clients are simultaneously subscribed.
     examples:
-      - name: Remove a subscription
+      - name: Remove a channel
         isSpotlight: true
         js: |
           ```js
-          supabase.removeChannel(mySubscription)
+          supabase.removeChannel(myChannel)
           ```
 
   removeAllChannels():
-    title: 'removeAllSubscriptions()'
+    title: 'removeAllChannels()'
     $ref: '@supabase/supabase-js.index.SupabaseClient.removeAllChannels'
     notes: |
-      - Removing subscriptions is a great way to maintain the performance of your project's database. Supabase will automatically handle cleanup 30 seconds after a user is disconnected, but unused subscriptions may cause degradation as more users are simultaneously subscribed.
+      - Removing channels is a great way to maintain the performance of your project's Realtime service as well as your database if you're listening to Postgres changes. Supabase will automatically handle cleanup 30 seconds after a client is disconnected, but unused channels may cause degradation as more clients are simultaneously subscribed.
     examples:
-      - name: Removes all subscriptions
+      - name: Removes all channels
         isSpotlight: true
         js: |
           ```js
@@ -1269,14 +1271,14 @@ pages:
           ```
 
   getChannels():
-    title: 'getSubscriptions()'
+    title: 'getChannels()'
     $ref: '@supabase/supabase-js.index.SupabaseClient.getChannels'
     examples:
-      - name: Get all subscriptions
+      - name: Get all channels
         isSpotlight: true
         js: |
           ```js
-          const subscriptions = supabase.getChannels()
+          const channels = supabase.getChannels()
           ```
 
   storage.listBuckets():