From b60cd84f5056f65bad2da1a8cbae010adf1eea6e Mon Sep 17 00:00:00 2001
From: Francis Roberts <111994975+franrob-projects@users.noreply.github.com>
Date: Thu, 18 Dec 2025 15:15:02 +0100
Subject: [PATCH 01/10] Adds placeholder USP component
---
src/components/blocks/dividers/Aside.tsx | 8 ++++++++
src/components/blocks/dividers/dividers.module.css | 3 +++
2 files changed, 11 insertions(+)
diff --git a/src/components/blocks/dividers/Aside.tsx b/src/components/blocks/dividers/Aside.tsx
index 151a323bad..d0ea494fc0 100644
--- a/src/components/blocks/dividers/Aside.tsx
+++ b/src/components/blocks/dividers/Aside.tsx
@@ -44,6 +44,14 @@ const Aside = ({ children, attribs }: AsideProps) => {
Further Reading
+ ) : attribs && attribs[`data-type`] === `see-evidence` ? (
+ <>
+
+
+ π
+ See evidence
+
+
) : attribs && isVersioningInfo ? (
<>
Date: Thu, 18 Dec 2025 15:41:03 +0100
Subject: [PATCH 02/10] Adds PERFORMANCE USPs to Pub/Sub
---
src/pages/docs/pub-sub/advanced.mdx | 4 ++++
src/pages/docs/pub-sub/index.mdx | 4 ++++
2 files changed, 8 insertions(+)
diff --git a/src/pages/docs/pub-sub/advanced.mdx b/src/pages/docs/pub-sub/advanced.mdx
index 0bb1c6ad7a..91fce3a1c0 100644
--- a/src/pages/docs/pub-sub/advanced.mdx
+++ b/src/pages/docs/pub-sub/advanced.mdx
@@ -388,6 +388,10 @@ Subscribing to events server-side using the pub-sub pattern can be disadvantageo
[Message queues](/docs/platform/integrations/queues) are more appropriate to use in this instance, as multiple worker servers enable Ably to distribute the load of messages received. This ensures that each message is only processed once, by any one of your worker servers.
+
+Ably delivers messages globally with a median latency of 37ms, validated by over 6 million daily measurements across its infrastructure. [Click here for evidence π¬](https://ably.com/docs/platform/architecture/latency#latency)
+
+
### Subscription filters
+Ably delivers messages globally with a median latency of 37ms, validated by over 6 million daily measurements across its infrastructure. [Click here for evidence π¬](https://ably.com/docs/platform/architecture/latency#latency)
+
+
To get started with sending and receiving messages, all you need to do is:
* [Use a channel](#use)
From a8601498d469dc4a44882aedfdd8bc86fac1d92e Mon Sep 17 00:00:00 2001
From: Francis Roberts <111994975+franrob-projects@users.noreply.github.com>
Date: Thu, 18 Dec 2025 16:41:37 +0100
Subject: [PATCH 03/10] Adds RELIABILITY USPs to Pub/Sub
---
src/pages/docs/channels/index.mdx | 4 ++++
src/pages/docs/channels/options/deltas.mdx | 4 ++++
src/pages/docs/channels/options/rewind.mdx | 4 ++++
src/pages/docs/connect/index.mdx | 8 ++++++++
src/pages/docs/connect/states.mdx | 4 ++++
src/pages/docs/getting-started/index.mdx | 4 ++++
src/pages/docs/messages/index.mdx | 4 ++++
src/pages/docs/presence-occupancy/presence.mdx | 5 +++++
src/pages/docs/protocols/index.mdx | 4 ++++
src/pages/docs/protocols/mqtt.mdx | 4 ++++
src/pages/docs/protocols/pubnub.mdx | 4 ++++
src/pages/docs/protocols/pusher.mdx | 4 ++++
src/pages/docs/protocols/sse.mdx | 5 +++++
src/pages/docs/push/index.mdx | 4 ++++
src/pages/docs/push/publish.mdx | 4 ++++
src/pages/docs/storage-history/history.mdx | 4 ++++
src/pages/docs/storage-history/storage.mdx | 4 ++++
17 files changed, 74 insertions(+)
diff --git a/src/pages/docs/channels/index.mdx b/src/pages/docs/channels/index.mdx
index 72b2a7cb2e..3f2fb20b51 100644
--- a/src/pages/docs/channels/index.mdx
+++ b/src/pages/docs/channels/index.mdx
@@ -202,6 +202,10 @@ The channel rules related to enabling features are:
| Message conflation | If enabled, messages are aggregated over a set period of time and evaluated against a conflation key. All but the latest message for each conflation key value will be discarded, and the resulting message, or messages, will be delivered to subscribers as a single batch once the period of time elapses. [Message conflation](/docs/messages#conflation) reduces costs in high-throughput scenarios by removing redundant and outdated messages. |
| Message annotations, updates, deletes, and appends | If enabled, allows message "annotations":/docs/messages/annotations to be used, as well as updates, deletes, and appends to be published to messages. Note that these features are currently in public preview. When this feature is enabled, messages will be "persisted":/docs/storage-history/storage#all-message-persistence (necessary in order from them later be annotated or updated), and "continuous history":/docs/storage-history/history#continuous-history features will not work.
+
+Your messages are protected with 99.999999% (eight nines) survivability, ensuring virtually no message loss even during failures. [Click here for evidence π¬](https://ably.com/docs/platform/architecture/fault-tolerance)
+
+
To set a channel rule in the Ably dashboard:
1. Sign in to your Ably account.
diff --git a/src/pages/docs/channels/options/deltas.mdx b/src/pages/docs/channels/options/deltas.mdx
index 75bfb30734..a954b26c35 100644
--- a/src/pages/docs/channels/options/deltas.mdx
+++ b/src/pages/docs/channels/options/deltas.mdx
@@ -31,6 +31,10 @@ As delta compression is specified by a subscriber, the publisher has no control
There is no constraint on how many publishers or subscribers there are. If there are multiple publishers, then deltas can still be generated, and they will be determined based on the order of messages. Deltas are calculated strictly based on the message ordering in that channel, with the effectiveness being dependent on the level of similarity between successive payloads.
+
+Subscribers on that channel anywhere in the world will receive those messages in the same order they were originally published. [Click here for evidence π¬](https://ably.com/docs/platform/architecture/message-ordering)
+
+
If a delta is generated and it results in a difference that is not appreciably smaller than the original message, or is larger than the original message, for example if successive messages are completely different, then the delta will not be sent. Clients will receive the original, unprocessed message.
diff --git a/src/pages/docs/channels/options/rewind.mdx b/src/pages/docs/channels/options/rewind.mdx
index 91f4326318..42537dcb36 100644
--- a/src/pages/docs/channels/options/rewind.mdx
+++ b/src/pages/docs/channels/options/rewind.mdx
@@ -27,6 +27,10 @@ A `rewind` value that is a number, `N`, is a request to attach to the channel at
If the attachment is successful, and one or more messages exist on the channel prior to the present position, then those messages will be delivered to the subscriber immediately after the attachment has completed, and before any subsequent messages that arise in real time.
+
+Timeserials enable precise positioning within a message stream, allowing clients to resume connections from exactly where they left off. [Click here for evidence π¬](https://ably.com/docs/platform/architecture/message-ordering#timeserials-tracking-position-in-message-streams)
+
+
Any `rewind` value that cannot be parsed either as a number or a time specifier will cause the attachment request to fail and return an error.
diff --git a/src/pages/docs/connect/index.mdx b/src/pages/docs/connect/index.mdx
index 5e677d29ad..a266e74118 100644
--- a/src/pages/docs/connect/index.mdx
+++ b/src/pages/docs/connect/index.mdx
@@ -151,6 +151,10 @@ A connection ID is a unique identifier given to a connection, allowing for ident
An active connection ID is guaranteed to be unique in the Ably system whilst it is active, i.e. no other connection will share that connection ID. However, Ably reserves the right to generate a new connection ID later that may be the same as a previously discarded connection ID (once the connection is closed). Therefore customers are advised to not use the connection ID as a perpetual unique identifier as it is possible that a connection ID may be used many times.
+
+If a client reconnects within two minutes, full connection recovery with exactly-once delivery is guaranteed. [Click here for evidence π¬](https://ably.com/docs/platform/architecture/idempotency#connection-recovery-and-exactly-once-delivery)
+
+
### Connection metachannels
+Ably's SDKs automatically resolve edge network failures within 30 seconds, keeping your users connected even during infrastructure issues. [Click here for evidence π¬](https://ably.com/docs/platform/architecture/edge-network)
+
+
### Reliability considerations
The `beforeunload` event can be unreliable and is not guaranteed to fire under certain circumstances:
* The event may fire but the page is subsequently not disposed of (navigation can be cancelled).
diff --git a/src/pages/docs/connect/states.mdx b/src/pages/docs/connect/states.mdx
index 60f98e8638..0889dc831d 100644
--- a/src/pages/docs/connect/states.mdx
+++ b/src/pages/docs/connect/states.mdx
@@ -7,6 +7,10 @@ Connections to Ably will transition through multiple states throughout their lif
Although connection state is temporary, Ably provides continuity of message delivery between a client and the service provided that a dropped connection is re-established by the client within a limited interval (typically around two minutes). After that time the connection becomes stale and the system will not attempt to recover the connection state.
+
+Failed connections automatically try up to 6 alternative endpoints worldwide, maximizing reconnection success. [Click here for evidence π¬](https://ably.com/docs/platform/architecture/edge-network)
+
+
An Ably SDK is responsible for managing a connection. This includes:
* Selecting a transport, when multiple transports are available.
diff --git a/src/pages/docs/getting-started/index.mdx b/src/pages/docs/getting-started/index.mdx
index 3bfc41c640..86ff384e14 100644
--- a/src/pages/docs/getting-started/index.mdx
+++ b/src/pages/docs/getting-started/index.mdx
@@ -15,6 +15,10 @@ You'll learn the basics, such as how to connect to Ably, publish and subscribe t
These are your first steps towards building a realtime application that can effortlessly scale to serve millions of users.
+
+Ably delivers messages globally with a median latency of 37ms, validated by over 6 million daily measurements across its infrastructure. [Click here for evidence π¬](https://ably.com/docs/platform/architecture/latency#latency)
+
+
{[
{
diff --git a/src/pages/docs/messages/index.mdx b/src/pages/docs/messages/index.mdx
index f148ff6eee..686025794b 100644
--- a/src/pages/docs/messages/index.mdx
+++ b/src/pages/docs/messages/index.mdx
@@ -44,6 +44,10 @@ Ensure a message was successfully published by checking the [history](/docs/stor
Ably does not store per-message delivery logs, nor logs of who is subscribed to a channel at any point in time. This means it is not possible to check which users have received messages retroactively.
+
+Applications maintain their state during disruptions - all messages are received in correct order with zero message loss. [Click here for evidence π¬](https://ably.com/docs/platform/architecture/connection-recovery)
+
+
## Message conflation
+In catastrophic datacenter failures, Ably automatically reroutes all traffic in under 2 minutes, maintaining service continuity. [Click here for evidence π¬](https://ably.com/docs/platform/architecture/edge-network)
+
+
| Update | An already present member has updated their [member data](#member-data). Being notified of member data updates can be useful, for example, it can be used to update the status of a user when they are typing a message |
| Present | When subscribing to presence events on a channel that already has members present, this event is emitted for every member already present on the channel before the subscribe listener was registered |
diff --git a/src/pages/docs/protocols/index.mdx b/src/pages/docs/protocols/index.mdx
index 8f4c6a4a2a..366a7a0089 100644
--- a/src/pages/docs/protocols/index.mdx
+++ b/src/pages/docs/protocols/index.mdx
@@ -15,6 +15,10 @@ Ably helps customers migrate from other data streaming networks including PubNub
Protocol adapters ensure interoperability between different protocols. For example, you can publish sensor data from an MQTT device, subscribe to that data using a Pusher client library for dashboard display, support mobile apps using Ably SDKs, and process data using AMQP worker queues - all within the same system.
+
+Direct site-to-site distribution means that messages are delivered to all subscribers in the minimum time. [Click here for evidence π¬](https://ably.com/docs/platform/architecture/message-ordering#multi-region)
+
+
Migration times typically range from a few hours (using protocol adapters) to a week, depending on your migration strategy and whether you choose to adopt Ably's native SDKs immediately or transition gradually.
A full list of Ably SDKs can be found on the [SDK page](/docs/sdks).
diff --git a/src/pages/docs/protocols/mqtt.mdx b/src/pages/docs/protocols/mqtt.mdx
index 62779c03e9..33a888ad9b 100644
--- a/src/pages/docs/protocols/mqtt.mdx
+++ b/src/pages/docs/protocols/mqtt.mdx
@@ -26,6 +26,10 @@ Using the MQTT adapter will be a little slower than using an Ably SDK, as an ada
While the adapter can be useful for devices which need to use MQTT, there are many benefits to using an Ably SDK, such as continuity guarantees, fallback host support, history and presence. As a result, if an Ably SDK is available for your platform, it is recommended you consider using it instead of the protocol adapter.
+
+Users in the same region will have a consistent experience with all subscribers observing messages in the same order. [Click here for evidence π¬](https://ably.com/docs/platform/architecture/message-ordering#practical-implications-of-dual-ordering)
+
+
Our MQTT adapter only supports features supported by both the MQTT protocol and the Ably platform:
* Only supports MQTT 3.1.1 clients only, connection attempts using earlier protocol versions will be rejected
diff --git a/src/pages/docs/protocols/pubnub.mdx b/src/pages/docs/protocols/pubnub.mdx
index 96e0ccc928..85ee8ec3b3 100644
--- a/src/pages/docs/protocols/pubnub.mdx
+++ b/src/pages/docs/protocols/pubnub.mdx
@@ -10,6 +10,10 @@ Ably enables migration from PubNub to Ably using its PubNub Adapter. The protoco
Using an adapter introduces some latency and is slower than using an Ably SDK. The PubNub adapter can have more variable latency than other adapters because PubNub's protocol is inherently long-polling based, which creates an impedance mismatch with Ably's WebSocket-based architecture. Some operations are quick with PubNub, but slower or impossible with Ably, and vice versa.
+
+Ably delivers messages globally with a median latency of 37ms, validated by over 6 million daily measurements across its infrastructure. [Click here for evidence π¬](https://ably.com/docs/platform/architecture/latency#latency)
+
+
Many of the advantages associated with using Ably, such as the use of WebSockets rather than long polling, [continuity guarantees](https://ably.com/four-pillars-of-dependability), and fallback host support are only available when using an Ably SDK. If an [Ably SDK](/docs/sdks) is available in your chosen platform, it is recommended you use that, or plan to transition to it eventually.
You can use PuBNub and and an Ably SDK side-by-side as they are interoperable, with the exception of a few features.
diff --git a/src/pages/docs/protocols/pusher.mdx b/src/pages/docs/protocols/pusher.mdx
index f4661c728f..f39ef4d791 100644
--- a/src/pages/docs/protocols/pusher.mdx
+++ b/src/pages/docs/protocols/pusher.mdx
@@ -9,6 +9,10 @@ Ably enables migration from Pusher to Ably using its Pusher Adapter. The protoco
Using an adapter introduces some latency and is slower than using an Ably SDK, however the impact is typically 1-10ms. It will also be slightly slower than using Pusher natively, but only if you are close to whichever Pusher data center used. If you aren't close to the Pusher data center you've chosen, then the extra latency from using the adapter should be more than compensated for by being able to use a data center that is close to you. This is because Ably automatically connects clients to the data center closest to them.
+
+Ably delivers messages globally with a median latency of 37ms, validated by over 6 million daily measurements across its infrastructure. [Click here for evidence π¬](https://ably.com/docs/platform/architecture/latency#latency)
+
+
The Pusher Adapter provides some of the advantages of Ably, such as inter-regional message federation, however others, such as [continuity guarantees](https://ably.com/four-pillars-of-dependability), fallback host support, and [message history](/docs/storage-history/history) are only available when using an Ably SDK. If an [Ably SDK](/docs/sdks) is available in your chosen platform, it is recommended you use that, or plan to transition to it eventually.
## Supported features
+In catastrophic datacenter failures, Ably automatically reroutes all traffic in under 2 minutes, maintaining service continuity. [Click here for evidence π¬](https://ably.com/docs/platform/architecture/edge-network)
+
+
* Access to a comprehensive range of features including, but not limited to, [publishing](/docs/push/publish), [presence](/docs/presence-occupancy/presence), [history](/docs/storage-history/history), [push notifications](/docs/push), [automatic payload encoding](/docs/channels/options/encryption), and [symmetric encryption](/docs/channels/options/encryption).
* Optimal compatibility with browsers via the WebSocket protocol.
diff --git a/src/pages/docs/push/index.mdx b/src/pages/docs/push/index.mdx
index 9fbe5b7fe6..1eefc3872a 100644
--- a/src/pages/docs/push/index.mdx
+++ b/src/pages/docs/push/index.mdx
@@ -17,6 +17,10 @@ redirect_from:
Push notifications notify user devices or browsers regardless of whether an application is open and running. They deliver information, such as app updates, social media alerts, or promotional offers, directly to the user's screen. Ably sends push notifications to devices using [Firebase Cloud Messaging](https://firebase.google.com/docs/cloud-messaging) or [Apple Push Notification Service](https://developer.apple.com/notifications/), and to browsers using [Web Push](https://developer.mozilla.org/en-US/docs/Web/API/Push_API). Push notifications don't require a device or browser to stay connected to Ably. Instead, a device's or browser's operating system or web browser maintains its own battery-efficient transport to receive notifications.
+
+Trust 99.999% uptime with just 5 minutes of downtime per year, ensuring your realtime features are always available. [Click here for evidence π¬](https://ably.com/docs/platform/architecture/infrastructure-operations.mdx)
+
+
You can publish push notifications to user devices or browsers [directly](/docs/push/publish/#direct-publishing) or [via channels](#via-channels).
Publishing directly sends push notifications to specific devices or browsers identified by unique identifiers, such as a `deviceId` or a `clientId`. This approach is akin to sending a personal message or alerts directly to an individual user's device or browser, bypassing the need for channel subscriptions. It excels in targeted and personalized communications, such as alerts specific to a user's actions, account notifications, or customized updates.
diff --git a/src/pages/docs/push/publish.mdx b/src/pages/docs/push/publish.mdx
index 2765f08d1b..9a35bf60ec 100644
--- a/src/pages/docs/push/publish.mdx
+++ b/src/pages/docs/push/publish.mdx
@@ -14,6 +14,10 @@ redirect_from:
Publishing sends push notifications to all specified devices or browsers either directly or via channels. This process is facilitated by Ably's realtime messaging infrastructure, which ensures that messages and notifications are delivered instantaneously.
+
+Even if publications occur almost simultaneously in different regions, subscribers receive each message only once, providing true exactly-once semantics. [Click here for evidence π¬](https://ably.com/docs/platform/architecture/idempotency#ablys-approach-to-idempotent-publishing)
+
+
Publish push notifications directly or via channels:
diff --git a/src/pages/docs/storage-history/history.mdx b/src/pages/docs/storage-history/history.mdx
index 4ad96cf087..7b20f9f8de 100644
--- a/src/pages/docs/storage-history/history.mdx
+++ b/src/pages/docs/storage-history/history.mdx
@@ -18,6 +18,10 @@ Ably's message History feature doesnβt replace a long-term database, itβs fo
When a client disconnects, Ably automatically handles the reconnection. If the disconnection lasts less than 2 minutes, Ably's [connection-state recovery](/docs/platform/architecture/connection-recovery) feature streams any missed messages to the client. For longer outages, the client must use the [History API](/docs/api/realtime-sdk/history) to fetch the missed messages. The API works efficiently because it indexes all messages by channel, timestamp, and serial number, allowing retrieval from any point in time.
+
+Ably maintains message continuity for up to 2 minutes during disconnections. The SDKs automatically handle reconnection and deliver all missed messages. [Click here for evidence π¬](https://ably.com/docs/platform/architecture/connection-recovery)
+
+
It's important to understand that History is not a database. The feature is purely for time-based retrieval on a single channel. It simply cannot support the complex queries that modern applications require. For example, the History API does not index message content or publisher IDs, so you cannot:
* Search messages by their author (clientId).
diff --git a/src/pages/docs/storage-history/storage.mdx b/src/pages/docs/storage-history/storage.mdx
index d9b3346f01..706a8fb37f 100644
--- a/src/pages/docs/storage-history/storage.mdx
+++ b/src/pages/docs/storage-history/storage.mdx
@@ -9,6 +9,10 @@ Ably stores all messages for two minutes by default. This can be increased up to
The default message storage of two minutes enables clients that briefly disconnect from Ably to [automatically retrieve](/docs/connect/states) any messages they may have missed. These messages can also be retrieved using the [history](/docs/storage-history/history) feature, and this applies to both regular messages and [presence messages](/docs/presence-occupancy/presence).
+
+Every message is redundantly stored across multiple isolated datacenters within your region before acknowledgment, preventing data loss. [Click here for evidence π¬](https://ably.com/docs/platform/architecture/index.mdx)
+
+
The following diagram illustrates the default persistence of messages:
From 825838dace342e2c98b2be74fe81c5b5705e0891 Mon Sep 17 00:00:00 2001
From: Francis Roberts <111994975+franrob-projects@users.noreply.github.com>
Date: Thu, 18 Dec 2025 16:58:19 +0100
Subject: [PATCH 04/10] Adds SCALE USPs to Pub/Sub
---
src/pages/docs/channels/index.mdx | 2 +-
src/pages/docs/metadata-stats/stats.mdx | 4 ++++
src/pages/docs/presence-occupancy/index.mdx | 4 ++++
src/pages/docs/presence-occupancy/occupancy.mdx | 4 ++++
src/pages/docs/push/index.mdx | 4 ++++
5 files changed, 17 insertions(+), 1 deletion(-)
diff --git a/src/pages/docs/channels/index.mdx b/src/pages/docs/channels/index.mdx
index 3f2fb20b51..07a94d424d 100644
--- a/src/pages/docs/channels/index.mdx
+++ b/src/pages/docs/channels/index.mdx
@@ -203,7 +203,7 @@ The channel rules related to enabling features are:
| Message annotations, updates, deletes, and appends | If enabled, allows message "annotations":/docs/messages/annotations to be used, as well as updates, deletes, and appends to be published to messages. Note that these features are currently in public preview. When this feature is enabled, messages will be "persisted":/docs/storage-history/storage#all-message-persistence (necessary in order from them later be annotated or updated), and "continuous history":/docs/storage-history/history#continuous-history features will not work.
-Your messages are protected with 99.999999% (eight nines) survivability, ensuring virtually no message loss even during failures. [Click here for evidence π¬](https://ably.com/docs/platform/architecture/fault-tolerance)
+With 50% capacity headroom built in, Ably instantly absorbs traffic spikes without degradation or pre-provisioning. [Click here for evidence π¬](https://ably.com/docs/platform/architecture/infrastructure-operations.mdx)
To set a channel rule in the Ably dashboard:
diff --git a/src/pages/docs/metadata-stats/stats.mdx b/src/pages/docs/metadata-stats/stats.mdx
index 87df7857cb..a40f8f3a05 100644
--- a/src/pages/docs/metadata-stats/stats.mdx
+++ b/src/pages/docs/metadata-stats/stats.mdx
@@ -18,6 +18,10 @@ redirect_from:
Ably provides statistics at one minute intervals. They are aggregated by minute, hour, day and month. The most recent statistics can be delayed by up to six seconds.
+
+Ably delivers over 500 billion messages monthly, demonstrating massive throughput capability. [Click here for evidence π¬](https://ably.com/docs/platform/architecture/infrastructure-operations.mdx)
+
+
Statistics are available as:
* [Account statistics](#account) covering all applications in your account
diff --git a/src/pages/docs/presence-occupancy/index.mdx b/src/pages/docs/presence-occupancy/index.mdx
index 3cb17665d8..31b26b7267 100644
--- a/src/pages/docs/presence-occupancy/index.mdx
+++ b/src/pages/docs/presence-occupancy/index.mdx
@@ -14,3 +14,7 @@ Presence is a feature that tracks the membership of a presence set for a channel
Occupancy provides metrics for a channel. It is a feature that counts how many of a thing are attached to a channel, such as the number of connections. It does not provide any information that can identify individual connections or clients attached to the channel.
Take a chat application containing multiple chat rooms as an example. Occupancy would be a more lightweight method for displaying the popularity of rooms, by displaying the number of connections to each channel. Presence could be utilized in each channel to indicate which users are online, and to notify other members when someone leaves the room.
+
+
+Ably's tiered fanout architecture allows it to scale to handle millions of subscribers per channel. [Click here for evidence π¬](https://ably.com/docs/platform/architecture/platform-scalability#handling-high-scale-fanout)
+
diff --git a/src/pages/docs/presence-occupancy/occupancy.mdx b/src/pages/docs/presence-occupancy/occupancy.mdx
index 79e47a836d..3e1c4b1344 100644
--- a/src/pages/docs/presence-occupancy/occupancy.mdx
+++ b/src/pages/docs/presence-occupancy/occupancy.mdx
@@ -8,6 +8,10 @@ redirect_from:
Occupancy provides high level metrics about the clients attached to a channel. This includes the number of [connections](/docs/connect) currently attached to a channel, and the number of connections attached that are permitted to publish and subscribe to the channel.
+
+Whether there are many lightly-loaded channels or fewer heavily-loaded ones, scaling and placement strategies ensure capacity is added as required and load is effectively distributed. [Click here for evidence π¬](https://ably.com/docs/platform/architecture/platform-scalability#how-ably-achieves-scalability)
+
+
## Occupancy metric categories
+Ably's infrastructure serves billions of devices each month, handling enterprise-scale traffic reliably and quickly. [Click here for evidence π¬](https://ably.com/docs/platform/architecture/infrastructure-operations.mdx)
+
+
Push subscriptions do not count toward your connection limit since devices don't need to maintain an active connection to receive push notifications. However, publishing push notifications via channels does activate those channels, so your concurrent peak channel count will equal the number of channels you publish to simultaneously.
From 02ae86008ea7cc2380ed4a7f6afbcbd5a82c2a72 Mon Sep 17 00:00:00 2001
From: Francis Roberts <111994975+franrob-projects@users.noreply.github.com>
Date: Thu, 18 Dec 2025 17:26:03 +0100
Subject: [PATCH 05/10] Specifes URLs
---
src/pages/docs/auth/identified-clients.mdx | 4 ++++
src/pages/docs/channels/index.mdx | 2 +-
src/pages/docs/channels/states.mdx | 4 ++++
src/pages/docs/messages/batch.mdx | 4 ++++
src/pages/docs/metadata-stats/stats.mdx | 2 +-
src/pages/docs/push/index.mdx | 2 +-
src/pages/docs/storage-history/storage.mdx | 2 +-
7 files changed, 16 insertions(+), 4 deletions(-)
diff --git a/src/pages/docs/auth/identified-clients.mdx b/src/pages/docs/auth/identified-clients.mdx
index 6420260ee7..4761b9309c 100644
--- a/src/pages/docs/auth/identified-clients.mdx
+++ b/src/pages/docs/auth/identified-clients.mdx
@@ -9,6 +9,10 @@ When a client is assigned a trusted identity, that is, a `clientId`, then they a
For example, assume you are building a chat application and want to allow clients to publish messages and be present on a channel. If each client is assigned a trusted identity by your server, such as a unique email address or UUID, then all other subscribed clients can trust any messages or presence events they receive in the channel as being from that client. No other clients are permitted to assume a `clientId` that they are not assigned in their Ably-compatible token. They are unable to masquerade as another `clientId`.
+
+Message processing is designed to be transactional - messages are either fully processed or not processed at all, preventing data corruption. [Click here for evidence π¬](https://ably.com/docs/platform/architecture/fault-tolerance#core-layer)
+
+
## ClientId immutability
-With 50% capacity headroom built in, Ably instantly absorbs traffic spikes without degradation or pre-provisioning. [Click here for evidence π¬](https://ably.com/docs/platform/architecture/infrastructure-operations.mdx)
+With 50% capacity headroom built in, Ably instantly absorbs traffic spikes without degradation or pre-provisioning. [Click here for evidence π¬](https://ably.com/docs/platform/architecture/infrastructure-operations#resource-implications)
To set a channel rule in the Ably dashboard:
diff --git a/src/pages/docs/channels/states.mdx b/src/pages/docs/channels/states.mdx
index 32dfca1ff7..ba6db6e000 100644
--- a/src/pages/docs/channels/states.mdx
+++ b/src/pages/docs/channels/states.mdx
@@ -220,6 +220,10 @@ channel.on('attached', (stateChange) => {
});
```
+
+Messages are persisted in multiple locations before acknowledgment, ensuring zero message loss even during node failures. [Click here for evidence π¬](https://ably.com/docs/platform/architecture/fault-tolerance#core-layer)
+
+
```realtime_nodejs
channel.on('attached', (stateChange) => {
console.log('channel ' + channel.name + ' is now attached');
diff --git a/src/pages/docs/messages/batch.mdx b/src/pages/docs/messages/batch.mdx
index b54dcdc5e0..87fdf8eb55 100644
--- a/src/pages/docs/messages/batch.mdx
+++ b/src/pages/docs/messages/batch.mdx
@@ -158,6 +158,10 @@ For each channel, the messages grouped into a single `BatchSpec` are published a
* The [max message size](/docs/platform/pricing/limits#message) limit applies to the total size of all messages in in a `BatchSpec`
* Each `BatchSpec` will only count as a single message for the purpose of the [per-channel rate limit](/docs/platform/pricing/limits#message)
+
+Build with confidence on industry-leading quality of service guarantees that ensure message integrity, ordering, and delivery. [Click here for evidence π¬](https://ably.com/docs/platform/architecture/message-ordering)
+
+
So if you do not need the atomicity guarantee and might be in danger of exceeding the max message size limit, you can put each message into its own `BatchSpec` (relative ordering will still be preserved). Conversely, if you are publishing many hundreds of small messages and are in danger of exceeding the max per-channel message rate, you group them into a fewer `BatchSpecs`.
The batch request as a whole is subject to the following limits:
diff --git a/src/pages/docs/metadata-stats/stats.mdx b/src/pages/docs/metadata-stats/stats.mdx
index a40f8f3a05..f0f630e877 100644
--- a/src/pages/docs/metadata-stats/stats.mdx
+++ b/src/pages/docs/metadata-stats/stats.mdx
@@ -19,7 +19,7 @@ redirect_from:
Ably provides statistics at one minute intervals. They are aggregated by minute, hour, day and month. The most recent statistics can be delayed by up to six seconds.
-Ably delivers over 500 billion messages monthly, demonstrating massive throughput capability. [Click here for evidence π¬](https://ably.com/docs/platform/architecture/infrastructure-operations.mdx)
+Ably delivers over 500 billion messages monthly, demonstrating massive throughput capability. [Click here for evidence π¬](https://ably.com/docs/platform/architecture/scalability)
Statistics are available as:
diff --git a/src/pages/docs/push/index.mdx b/src/pages/docs/push/index.mdx
index 87b05d683f..c3e4d4ba9b 100644
--- a/src/pages/docs/push/index.mdx
+++ b/src/pages/docs/push/index.mdx
@@ -28,7 +28,7 @@ Publishing directly sends push notifications to specific devices or browsers ide
Publishing via channels uses a [Pub/Sub](/docs/messages) model. Messages are sent to channels to which multiple devices or browsers can subscribe. When a message is published to a channel, all devices or browsers subscribed to that channel receive the notification. This approach is particularly powerful for simultaneously publishing messages to multiple users.
-Ably's infrastructure serves billions of devices each month, handling enterprise-scale traffic reliably and quickly. [Click here for evidence π¬](https://ably.com/docs/platform/architecture/infrastructure-operations.mdx)
+Ably's infrastructure serves billions of devices each month, handling enterprise-scale traffic reliably and quickly. [Click here for evidence π¬](https://ably.com/docs/platform/architecture/scalability)
diff --git a/src/pages/docs/storage-history/storage.mdx b/src/pages/docs/storage-history/storage.mdx
index 706a8fb37f..162f91623b 100644
--- a/src/pages/docs/storage-history/storage.mdx
+++ b/src/pages/docs/storage-history/storage.mdx
@@ -10,7 +10,7 @@ Ably stores all messages for two minutes by default. This can be increased up to
The default message storage of two minutes enables clients that briefly disconnect from Ably to [automatically retrieve](/docs/connect/states) any messages they may have missed. These messages can also be retrieved using the [history](/docs/storage-history/history) feature, and this applies to both regular messages and [presence messages](/docs/presence-occupancy/presence).
-Every message is redundantly stored across multiple isolated datacenters within your region before acknowledgment, preventing data loss. [Click here for evidence π¬](https://ably.com/docs/platform/architecture/index.mdx)
+Every message is redundantly stored across multiple isolated datacenters within your region before acknowledgment, preventing data loss. [Click here for evidence π¬](https://ably.com/docs/platform/architecture/fault-tolerance#core-layer)
The following diagram illustrates the default persistence of messages:
From a01e4e12026244371822182f6c3d93c42ee002d4 Mon Sep 17 00:00:00 2001
From: Francis Roberts <111994975+franrob-projects@users.noreply.github.com>
Date: Thu, 18 Dec 2025 17:51:42 +0100
Subject: [PATCH 06/10] Adds INFRA USPs to Pub/Sub
---
src/pages/docs/auth/identified-clients.mdx | 2 +-
src/pages/docs/auth/revocation.mdx | 4 ++++
src/pages/docs/channels/options/index.mdx | 4 ++++
src/pages/docs/metadata-stats/metadata/subscribe.mdx | 4 ++++
4 files changed, 13 insertions(+), 1 deletion(-)
diff --git a/src/pages/docs/auth/identified-clients.mdx b/src/pages/docs/auth/identified-clients.mdx
index 4761b9309c..2b3a9dd5a0 100644
--- a/src/pages/docs/auth/identified-clients.mdx
+++ b/src/pages/docs/auth/identified-clients.mdx
@@ -10,7 +10,7 @@ When a client is assigned a trusted identity, that is, a `clientId`, then they a
For example, assume you are building a chat application and want to allow clients to publish messages and be present on a channel. If each client is assigned a trusted identity by your server, such as a unique email address or UUID, then all other subscribed clients can trust any messages or presence events they receive in the channel as being from that client. No other clients are permitted to assume a `clientId` that they are not assigned in their Ably-compatible token. They are unable to masquerade as another `clientId`.
-Message processing is designed to be transactional - messages are either fully processed or not processed at all, preventing data corruption. [Click here for evidence π¬](https://ably.com/docs/platform/architecture/fault-tolerance#core-layer)
+Message processing is designed to be transactional, therefore messages are either fully processed or not processed at all, preventing data corruption. [Click here for evidence π¬](https://ably.com/docs/platform/architecture/fault-tolerance#core-layer)
## ClientId immutability
+By tracking changes over time, Ably can identify gradual degradations before they become critical issues. [Click here for evidence π¬](https://ably.com/docs/platform/architecture/infrastructure-operations#metrics-collection)
+
+
Note that revocation does not permanently forbid a client, connection, `clientId` or channel. It invalidates token credentials issued before a certain point in time. Ultimately, the app that issues tokens is responsible for whether or not a client is able to continue to interact with the Ably service.
## Revocation targets
+Metrics are collected from the host instance and from each of the containers on every instance, providing comprehensive visibility into system performance and resource utilization. [Click here for evidence π¬](https://ably.com/docs/platform/architecture/infrastructure-operations#metrics-collection)
+
+
As `occupancy` requires a channel subscription, it is only available when using the realtime interface of an Ably SDK.
diff --git a/src/pages/docs/metadata-stats/metadata/subscribe.mdx b/src/pages/docs/metadata-stats/metadata/subscribe.mdx
index ea3184f7c7..ee39962356 100644
--- a/src/pages/docs/metadata-stats/metadata/subscribe.mdx
+++ b/src/pages/docs/metadata-stats/metadata/subscribe.mdx
@@ -62,6 +62,10 @@ Seeing `channel.region.inactive` events in your [Dev Console](/docs/platform/acc
A `channel.region.inactive` event indicates that a channel no longer has any clients in that specific region, or that the channel is shutting down altogether. This is part of Ably's normal operation to efficiently manage resources across its global infrastructure.
+
+With 50% capacity headroom built in, Ably instantly absorbs traffic spikes without degradation or pre-provisioning. [Click here for evidence π¬](https://ably.com/docs/platform/architecture/infrastructure-operations#resource-implications)
+
+
The following is an example of subscribing to all `[meta]channel.lifecycle` events:
From 4b5b43cf45113755fdf68a7f6700e0b9704e9ad7 Mon Sep 17 00:00:00 2001
From: Francis Roberts <111994975+franrob-projects@users.noreply.github.com>
Date: Mon, 22 Dec 2025 16:01:28 +0100
Subject: [PATCH 07/10] Addresses feedback
---
src/pages/docs/auth/identified-clients.mdx | 4 ----
src/pages/docs/auth/revocation.mdx | 4 ----
src/pages/docs/channels/index.mdx | 4 ----
src/pages/docs/channels/options/deltas.mdx | 2 +-
src/pages/docs/channels/options/index.mdx | 4 ----
src/pages/docs/channels/options/rewind.mdx | 4 ----
src/pages/docs/channels/states.mdx | 4 ----
src/pages/docs/connect/states.mdx | 2 +-
src/pages/docs/getting-started/index.mdx | 4 ----
src/pages/docs/messages/batch.mdx | 4 ----
src/pages/docs/presence-occupancy/presence.mdx | 2 +-
src/pages/docs/push/index.mdx | 4 ----
12 files changed, 3 insertions(+), 39 deletions(-)
diff --git a/src/pages/docs/auth/identified-clients.mdx b/src/pages/docs/auth/identified-clients.mdx
index 2b3a9dd5a0..6420260ee7 100644
--- a/src/pages/docs/auth/identified-clients.mdx
+++ b/src/pages/docs/auth/identified-clients.mdx
@@ -9,10 +9,6 @@ When a client is assigned a trusted identity, that is, a `clientId`, then they a
For example, assume you are building a chat application and want to allow clients to publish messages and be present on a channel. If each client is assigned a trusted identity by your server, such as a unique email address or UUID, then all other subscribed clients can trust any messages or presence events they receive in the channel as being from that client. No other clients are permitted to assume a `clientId` that they are not assigned in their Ably-compatible token. They are unable to masquerade as another `clientId`.
-
-Message processing is designed to be transactional, therefore messages are either fully processed or not processed at all, preventing data corruption. [Click here for evidence π¬](https://ably.com/docs/platform/architecture/fault-tolerance#core-layer)
-
-
## ClientId immutability
-By tracking changes over time, Ably can identify gradual degradations before they become critical issues. [Click here for evidence π¬](https://ably.com/docs/platform/architecture/infrastructure-operations#metrics-collection)
-
-
Note that revocation does not permanently forbid a client, connection, `clientId` or channel. It invalidates token credentials issued before a certain point in time. Ultimately, the app that issues tokens is responsible for whether or not a client is able to continue to interact with the Ably service.
## Revocation targets
-With 50% capacity headroom built in, Ably instantly absorbs traffic spikes without degradation or pre-provisioning. [Click here for evidence π¬](https://ably.com/docs/platform/architecture/infrastructure-operations#resource-implications)
-
-
To set a channel rule in the Ably dashboard:
1. Sign in to your Ably account.
diff --git a/src/pages/docs/channels/options/deltas.mdx b/src/pages/docs/channels/options/deltas.mdx
index a954b26c35..d68972eba9 100644
--- a/src/pages/docs/channels/options/deltas.mdx
+++ b/src/pages/docs/channels/options/deltas.mdx
@@ -32,7 +32,7 @@ As delta compression is specified by a subscriber, the publisher has no control
There is no constraint on how many publishers or subscribers there are. If there are multiple publishers, then deltas can still be generated, and they will be determined based on the order of messages. Deltas are calculated strictly based on the message ordering in that channel, with the effectiveness being dependent on the level of similarity between successive payloads.
-Subscribers on that channel anywhere in the world will receive those messages in the same order they were originally published. [Click here for evidence π¬](https://ably.com/docs/platform/architecture/message-ordering)
+Messages published using Realtime have consistent ordering for all subscribers, with each message assigned a unique serial number to preserve its place. [Click here for evidence π¬](https://ably.com/docs/platform/architecture/message-ordering)
If a delta is generated and it results in a difference that is not appreciably smaller than the original message, or is larger than the original message, for example if successive messages are completely different, then the delta will not be sent. Clients will receive the original, unprocessed message.
diff --git a/src/pages/docs/channels/options/index.mdx b/src/pages/docs/channels/options/index.mdx
index a55276fc36..a6e2f99999 100644
--- a/src/pages/docs/channels/options/index.mdx
+++ b/src/pages/docs/channels/options/index.mdx
@@ -262,10 +262,6 @@ const channel = realtime.channels.get('{{RANDOM_CHANNEL_NAME}}', channelOpts);
[Occupancy](/docs/presence-occupancy/occupancy) provides metrics about the clients attached to a channel, such as the number of connections and the number of clients subscribed to the channel. `occupancy` can be specified in the `params` property in order to subscribe a client to occupancy metrics for the channel. The metrics will be received by a client as events on the channel.
-
-Metrics are collected from the host instance and from each of the containers on every instance, providing comprehensive visibility into system performance and resource utilization. [Click here for evidence π¬](https://ably.com/docs/platform/architecture/infrastructure-operations#metrics-collection)
-
-
As `occupancy` requires a channel subscription, it is only available when using the realtime interface of an Ably SDK.
diff --git a/src/pages/docs/channels/options/rewind.mdx b/src/pages/docs/channels/options/rewind.mdx
index 42537dcb36..91f4326318 100644
--- a/src/pages/docs/channels/options/rewind.mdx
+++ b/src/pages/docs/channels/options/rewind.mdx
@@ -27,10 +27,6 @@ A `rewind` value that is a number, `N`, is a request to attach to the channel at
If the attachment is successful, and one or more messages exist on the channel prior to the present position, then those messages will be delivered to the subscriber immediately after the attachment has completed, and before any subsequent messages that arise in real time.
-
-Timeserials enable precise positioning within a message stream, allowing clients to resume connections from exactly where they left off. [Click here for evidence π¬](https://ably.com/docs/platform/architecture/message-ordering#timeserials-tracking-position-in-message-streams)
-
-
Any `rewind` value that cannot be parsed either as a number or a time specifier will cause the attachment request to fail and return an error.
diff --git a/src/pages/docs/channels/states.mdx b/src/pages/docs/channels/states.mdx
index ba6db6e000..32dfca1ff7 100644
--- a/src/pages/docs/channels/states.mdx
+++ b/src/pages/docs/channels/states.mdx
@@ -220,10 +220,6 @@ channel.on('attached', (stateChange) => {
});
```
-
-Messages are persisted in multiple locations before acknowledgment, ensuring zero message loss even during node failures. [Click here for evidence π¬](https://ably.com/docs/platform/architecture/fault-tolerance#core-layer)
-
-
```realtime_nodejs
channel.on('attached', (stateChange) => {
console.log('channel ' + channel.name + ' is now attached');
diff --git a/src/pages/docs/connect/states.mdx b/src/pages/docs/connect/states.mdx
index 0889dc831d..04ef09c5b1 100644
--- a/src/pages/docs/connect/states.mdx
+++ b/src/pages/docs/connect/states.mdx
@@ -8,7 +8,7 @@ Connections to Ably will transition through multiple states throughout their lif
Although connection state is temporary, Ably provides continuity of message delivery between a client and the service provided that a dropped connection is re-established by the client within a limited interval (typically around two minutes). After that time the connection becomes stale and the system will not attempt to recover the connection state.
-Failed connections automatically try up to 6 alternative endpoints worldwide, maximizing reconnection success. [Click here for evidence π¬](https://ably.com/docs/platform/architecture/edge-network)
+Failed connections automatically try up to 5 alternative endpoints worldwide, maximizing reconnection success. [Click here for evidence π¬](https://ably.com/docs/platform/architecture/edge-network)
An Ably SDK is responsible for managing a connection. This includes:
diff --git a/src/pages/docs/getting-started/index.mdx b/src/pages/docs/getting-started/index.mdx
index 86ff384e14..3bfc41c640 100644
--- a/src/pages/docs/getting-started/index.mdx
+++ b/src/pages/docs/getting-started/index.mdx
@@ -15,10 +15,6 @@ You'll learn the basics, such as how to connect to Ably, publish and subscribe t
These are your first steps towards building a realtime application that can effortlessly scale to serve millions of users.
-
-Ably delivers messages globally with a median latency of 37ms, validated by over 6 million daily measurements across its infrastructure. [Click here for evidence π¬](https://ably.com/docs/platform/architecture/latency#latency)
-
-
{[
{
diff --git a/src/pages/docs/messages/batch.mdx b/src/pages/docs/messages/batch.mdx
index 87fdf8eb55..b54dcdc5e0 100644
--- a/src/pages/docs/messages/batch.mdx
+++ b/src/pages/docs/messages/batch.mdx
@@ -158,10 +158,6 @@ For each channel, the messages grouped into a single `BatchSpec` are published a
* The [max message size](/docs/platform/pricing/limits#message) limit applies to the total size of all messages in in a `BatchSpec`
* Each `BatchSpec` will only count as a single message for the purpose of the [per-channel rate limit](/docs/platform/pricing/limits#message)
-
-Build with confidence on industry-leading quality of service guarantees that ensure message integrity, ordering, and delivery. [Click here for evidence π¬](https://ably.com/docs/platform/architecture/message-ordering)
-
-
So if you do not need the atomicity guarantee and might be in danger of exceeding the max message size limit, you can put each message into its own `BatchSpec` (relative ordering will still be preserved). Conversely, if you are publishing many hundreds of small messages and are in danger of exceeding the max per-channel message rate, you group them into a fewer `BatchSpecs`.
The batch request as a whole is subject to the following limits:
diff --git a/src/pages/docs/presence-occupancy/presence.mdx b/src/pages/docs/presence-occupancy/presence.mdx
index 0c39fa0225..592653cd32 100644
--- a/src/pages/docs/presence-occupancy/presence.mdx
+++ b/src/pages/docs/presence-occupancy/presence.mdx
@@ -34,7 +34,7 @@ The following presence events are emitted:
| Leave | A member who was present has now left the channel. This may be a result of an explicit request to leave or implicitly when detaching from the channel. Alternatively, if a member's connection is abruptly disconnected and they do not resume their connection within a minute, Ably treats this as a leave event as the client is no longer present |
-In catastrophic datacenter failures, Ably automatically reroutes all traffic in under 2 minutes, maintaining service continuity. [Click here for evidence π¬](https://ably.com/docs/platform/architecture/edge-network)
+Ably's edge network bypasses DNS entirely when clients can't reach primary endpoints. SDKs automatically reconnect to backup endpoints instead of waiting several minutes for DNS to make changes. [Click here for evidence π¬](https://ably.com/docs/platform/architecture/edge-network)
| Update | An already present member has updated their [member data](#member-data). Being notified of member data updates can be useful, for example, it can be used to update the status of a user when they are typing a message |
diff --git a/src/pages/docs/push/index.mdx b/src/pages/docs/push/index.mdx
index c3e4d4ba9b..cf7603391b 100644
--- a/src/pages/docs/push/index.mdx
+++ b/src/pages/docs/push/index.mdx
@@ -17,10 +17,6 @@ redirect_from:
Push notifications notify user devices or browsers regardless of whether an application is open and running. They deliver information, such as app updates, social media alerts, or promotional offers, directly to the user's screen. Ably sends push notifications to devices using [Firebase Cloud Messaging](https://firebase.google.com/docs/cloud-messaging) or [Apple Push Notification Service](https://developer.apple.com/notifications/), and to browsers using [Web Push](https://developer.mozilla.org/en-US/docs/Web/API/Push_API). Push notifications don't require a device or browser to stay connected to Ably. Instead, a device's or browser's operating system or web browser maintains its own battery-efficient transport to receive notifications.
-
-Trust 99.999% uptime with just 5 minutes of downtime per year, ensuring your realtime features are always available. [Click here for evidence π¬](https://ably.com/docs/platform/architecture/infrastructure-operations.mdx)
-
-
You can publish push notifications to user devices or browsers [directly](/docs/push/publish/#direct-publishing) or [via channels](#via-channels).
Publishing directly sends push notifications to specific devices or browsers identified by unique identifiers, such as a `deviceId` or a `clientId`. This approach is akin to sending a personal message or alerts directly to an individual user's device or browser, bypassing the need for channel subscriptions. It excels in targeted and personalized communications, such as alerts specific to a user's actions, account notifications, or customized updates.
From d683362f95f8c0999434dfdafe513fe5ba17a3cb Mon Sep 17 00:00:00 2001
From: Francis Roberts <111994975+franrob-projects@users.noreply.github.com>
Date: Mon, 5 Jan 2026 15:45:40 +0100
Subject: [PATCH 08/10] Revised version of pub/sub usp callouts
---
src/pages/docs/channels/options/deltas.mdx | 6 +++---
src/pages/docs/connect/index.mdx | 4 ++--
src/pages/docs/connect/states.mdx | 8 ++++----
src/pages/docs/messages/index.mdx | 2 +-
src/pages/docs/metadata-stats/metadata/subscribe.mdx | 8 ++++----
src/pages/docs/metadata-stats/stats.mdx | 8 ++++----
src/pages/docs/presence-occupancy/index.mdx | 2 +-
src/pages/docs/presence-occupancy/occupancy.mdx | 2 +-
src/pages/docs/presence-occupancy/presence.mdx | 7 +++----
src/pages/docs/protocols/index.mdx | 8 ++++----
src/pages/docs/protocols/mqtt.mdx | 8 ++++----
src/pages/docs/protocols/pubnub.mdx | 8 ++++----
src/pages/docs/protocols/pusher.mdx | 6 +++---
src/pages/docs/protocols/sse.mdx | 9 ++++-----
src/pages/docs/pub-sub/advanced.mdx | 2 +-
src/pages/docs/pub-sub/index.mdx | 8 ++++----
src/pages/docs/push/index.mdx | 6 +++---
src/pages/docs/push/publish.mdx | 10 +++++-----
src/pages/docs/storage-history/history.mdx | 7 +++----
src/pages/docs/storage-history/storage.mdx | 8 ++++----
20 files changed, 62 insertions(+), 65 deletions(-)
diff --git a/src/pages/docs/channels/options/deltas.mdx b/src/pages/docs/channels/options/deltas.mdx
index d68972eba9..3994589c67 100644
--- a/src/pages/docs/channels/options/deltas.mdx
+++ b/src/pages/docs/channels/options/deltas.mdx
@@ -31,12 +31,12 @@ As delta compression is specified by a subscriber, the publisher has no control
There is no constraint on how many publishers or subscribers there are. If there are multiple publishers, then deltas can still be generated, and they will be determined based on the order of messages. Deltas are calculated strictly based on the message ordering in that channel, with the effectiveness being dependent on the level of similarity between successive payloads.
+If a delta is generated and it results in a difference that is not appreciably smaller than the original message, or is larger than the original message, for example if successive messages are completely different, then the delta will not be sent. Clients will receive the original, unprocessed message.
+
-Messages published using Realtime have consistent ordering for all subscribers, with each message assigned a unique serial number to preserve its place. [Click here for evidence π¬](https://ably.com/docs/platform/architecture/message-ordering)
+Deltas rely on consistent message ordering. Messages published using Realtime from a single publisher are delivered to all subscribers in the same order, with each message assigned a unique serial number. [See evidence here π΅οΈ](/docs/platform/architecture/message-ordering#message-ordering-guarantees).
-If a delta is generated and it results in a difference that is not appreciably smaller than the original message, or is larger than the original message, for example if successive messages are completely different, then the delta will not be sent. Clients will receive the original, unprocessed message.
-
## Install vcdiff decoder
-If a client reconnects within two minutes, full connection recovery with exactly-once delivery is guaranteed. [Click here for evidence π¬](https://ably.com/docs/platform/architecture/idempotency#connection-recovery-and-exactly-once-delivery)
+Ably automatically recovers connections and prevents message loss or duplication when clients reconnect within two minutes. [See evidence here π΅οΈ](/docs/platform/architecture/idempotency#connection-recovery-and-exactly-once-delivery)
### Connection metachannels
-Ably's SDKs automatically resolve edge network failures within 30 seconds, keeping your users connected even during infrastructure issues. [Click here for evidence π¬](https://ably.com/docs/platform/architecture/edge-network)
+Ably's SDKs automatically resolve edge network failures within 30 seconds, keeping your users connected even during infrastructure issues. [See evidence here π΅οΈ](/docs/platform/architecture/edge-network)
### Reliability considerations
diff --git a/src/pages/docs/connect/states.mdx b/src/pages/docs/connect/states.mdx
index 04ef09c5b1..f6a5cd554d 100644
--- a/src/pages/docs/connect/states.mdx
+++ b/src/pages/docs/connect/states.mdx
@@ -7,10 +7,6 @@ Connections to Ably will transition through multiple states throughout their lif
Although connection state is temporary, Ably provides continuity of message delivery between a client and the service provided that a dropped connection is re-established by the client within a limited interval (typically around two minutes). After that time the connection becomes stale and the system will not attempt to recover the connection state.
-
-Failed connections automatically try up to 5 alternative endpoints worldwide, maximizing reconnection success. [Click here for evidence π¬](https://ably.com/docs/platform/architecture/edge-network)
-
-
An Ably SDK is responsible for managing a connection. This includes:
* Selecting a transport, when multiple transports are available.
@@ -19,6 +15,10 @@ An Ably SDK is responsible for managing a connection. This includes:
When an SDK is instantiated it will establish a connection immediately, and if the connection drops at any time it will attempt to re-establish it by making repeated connection attempts every 15 seconds for up to two minutes.
+
+Failed connections automatically try up to 5 alternative endpoints worldwide, maximizing reconnection success. [See evidence here π΅οΈ](/docs/platform/architecture/edge-network#protocol-level-resilience)
+
+
## Available connection states
-Applications maintain their state during disruptions - all messages are received in correct order with zero message loss. [Click here for evidence π¬](https://ably.com/docs/platform/architecture/connection-recovery)
+Applications maintain their state during disruptions. All messages are received in correct order with no message loss. [See evidence here π΅οΈ](/docs/platform/architecture/connection-recovery#message-identification-with-timeserial)
## Message conflation
-With 50% capacity headroom built in, Ably instantly absorbs traffic spikes without degradation or pre-provisioning. [Click here for evidence π¬](https://ably.com/docs/platform/architecture/infrastructure-operations#resource-implications)
-
-
The following is an example of subscribing to all `[meta]channel.lifecycle` events:
@@ -153,6 +149,10 @@ channel.subscribe("channel.closed", new Channel.MessageListener() {
```
+
+Auto Scaling Groups in each region scale independently according to demand, automatically maintaining sufficient capacity to handle traffic peaks. [See evidence here π΅οΈ](/docs/platform/architecture/infrastructure-operations#multi-region-deployment)
+
+
## Log events
-Ably delivers over 500 billion messages monthly, demonstrating massive throughput capability. [Click here for evidence π¬](https://ably.com/docs/platform/architecture/scalability)
-
-
Statistics are available as:
* [Account statistics](#account) covering all applications in your account
* [App statistics](#app) for each individual application
+
+Ably delivers over 500 billion messages monthly, demonstrating large throughput capability. [See evidence here π΅οΈ](/docs/platform/architecture/platform-scalability#monitoring-and-auto-scaling)
+
+
## Account statistics
-Ably's tiered fanout architecture allows it to scale to handle millions of subscribers per channel. [Click here for evidence π¬](https://ably.com/docs/platform/architecture/platform-scalability#handling-high-scale-fanout)
+Ably monitors resource headroom and triggers automatic scaling when load approaches capacity, absorbing traffic spikes without degradation. [See evidence here π΅οΈ](/docs/platform/architecture/platform-scalability#monitoring-and-auto-scaling)
diff --git a/src/pages/docs/presence-occupancy/occupancy.mdx b/src/pages/docs/presence-occupancy/occupancy.mdx
index 3e1c4b1344..d4ff6410a8 100644
--- a/src/pages/docs/presence-occupancy/occupancy.mdx
+++ b/src/pages/docs/presence-occupancy/occupancy.mdx
@@ -9,7 +9,7 @@ redirect_from:
Occupancy provides high level metrics about the clients attached to a channel. This includes the number of [connections](/docs/connect) currently attached to a channel, and the number of connections attached that are permitted to publish and subscribe to the channel.
-Whether there are many lightly-loaded channels or fewer heavily-loaded ones, scaling and placement strategies ensure capacity is added as required and load is effectively distributed. [Click here for evidence π¬](https://ably.com/docs/platform/architecture/platform-scalability#how-ably-achieves-scalability)
+Whether there are many lightly-loaded channels or fewer heavily-loaded ones, scaling and placement strategies ensure capacity is added as required and load is effectively distributed. [See evidence here π΅οΈ](/docs/platform/architecture/platform-scalability#how-ably-achieves-scalability)
## Occupancy metric categories
-Ably's edge network bypasses DNS entirely when clients can't reach primary endpoints. SDKs automatically reconnect to backup endpoints instead of waiting several minutes for DNS to make changes. [Click here for evidence π¬](https://ably.com/docs/platform/architecture/edge-network)
+If clients can't connect to primary endpoints, Ably SDKs automatically attempt alternative fallback endpoints, including a completely segregated secondary domain with a different DNS provider. [See evidence here π΅οΈ](/docs/platform/architecture/edge-network#fallback-endpoints-and-secondary-domains)
-| Update | An already present member has updated their [member data](#member-data). Being notified of member data updates can be useful, for example, it can be used to update the status of a user when they are typing a message |
-| Present | When subscribing to presence events on a channel that already has members present, this event is emitted for every member already present on the channel before the subscribe listener was registered |
-
### Member data
-Direct site-to-site distribution means that messages are delivered to all subscribers in the minimum time. [Click here for evidence π¬](https://ably.com/docs/platform/architecture/message-ordering#multi-region)
-
-
Migration times typically range from a few hours (using protocol adapters) to a week, depending on your migration strategy and whether you choose to adopt Ably's native SDKs immediately or transition gradually.
A full list of Ably SDKs can be found on the [SDK page](/docs/sdks).
+
+Direct site-to-site distribution means that messages are delivered to all subscribers in the minimum time. [See evidence here π΅οΈ](/docs/platform/architecture/message-ordering#multi-region-message-distribution)
+
+
## Available Protocol Adapters
-Users in the same region will have a consistent experience with all subscribers observing messages in the same order. [Click here for evidence π¬](https://ably.com/docs/platform/architecture/message-ordering#practical-implications-of-dual-ordering)
-
-
Our MQTT adapter only supports features supported by both the MQTT protocol and the Ably platform:
* Only supports MQTT 3.1.1 clients only, connection attempts using earlier protocol versions will be rejected
@@ -39,6 +35,10 @@ Our MQTT adapter only supports features supported by both the MQTT protocol and
* Doesn't support any MQTT features that aren't normally supported by Ably, such as `WILL` messages, the `RETAIN` flag or [wildcard channel subscriptions](/docs/channels)
* Doesn't support Ably features that aren't supported by the MQTT protocol, such as presence, history and push notifications, though you can use the Ably REST API in conjunction with the adapter to access features available over REST
+
+Within a single region, all MQTT subscribers will observe messages in the same order, ensuring consistent experiences for users in that region. [See evidence here π΅οΈ](/docs/platform/architecture/message-ordering#practical-implications-of-dual-ordering)
+
+
## Configuration
-Ably delivers messages globally with a median latency of 37ms, validated by over 6 million daily measurements across its infrastructure. [Click here for evidence π¬](https://ably.com/docs/platform/architecture/latency#latency)
-
-
Many of the advantages associated with using Ably, such as the use of WebSockets rather than long polling, [continuity guarantees](https://ably.com/four-pillars-of-dependability), and fallback host support are only available when using an Ably SDK. If an [Ably SDK](/docs/sdks) is available in your chosen platform, it is recommended you use that, or plan to transition to it eventually.
You can use PuBNub and and an Ably SDK side-by-side as they are interoperable, with the exception of a few features.
For a detailed comparison of Ably and PubNub features, see [Ably vs PubNub](https://ably.com/compare/ably-vs-pubnub).
+
+Ably achieves a global median message delivery latency of 37ms, continuously monitored through over 6 million measurements daily across all regions. [See evidence here π΅οΈ](/docs/platform/architecture/latency#how-latency-is-measured)
+
+
## Migration process
-Ably delivers messages globally with a median latency of 37ms, validated by over 6 million daily measurements across its infrastructure. [Click here for evidence π¬](https://ably.com/docs/platform/architecture/latency#latency)
+Ably achieves a global median message delivery latency of 37ms, continuously monitored through over 6 million measurements daily across all regions. [See evidence here π΅οΈ](/docs/platform/architecture/latency#how-latency-is-measured)
-The Pusher Adapter provides some of the advantages of Ably, such as inter-regional message federation, however others, such as [continuity guarantees](https://ably.com/four-pillars-of-dependability), fallback host support, and [message history](/docs/storage-history/history) are only available when using an Ably SDK. If an [Ably SDK](/docs/sdks) is available in your chosen platform, it is recommended you use that, or plan to transition to it eventually.
-
## Supported features
-In catastrophic datacenter failures, Ably automatically reroutes all traffic in under 2 minutes, maintaining service continuity. [Click here for evidence π¬](https://ably.com/docs/platform/architecture/edge-network)
-
-
* Access to a comprehensive range of features including, but not limited to, [publishing](/docs/push/publish), [presence](/docs/presence-occupancy/presence), [history](/docs/storage-history/history), [push notifications](/docs/push), [automatic payload encoding](/docs/channels/options/encryption), and [symmetric encryption](/docs/channels/options/encryption).
* Optimal compatibility with browsers via the WebSocket protocol.
@@ -47,6 +42,10 @@ In catastrophic datacenter failures, Ably automatically reroutes all traffic in
If you are streaming LLM responses to users, [AI Transport](/docs/ai-transport) provides purpose-built token streaming with resumable sessions and multi-device continuity, addressing the limitations of HTTP-based streaming.
+
+Ably's DNS uses a 60-second TTL, allowing traffic to be rerouted away from unhealthy datacenters within minutes when issues are detected. [See evidence here π΅οΈ](/docs/platform/architecture/edge-network#dns-organization-and-latency-based-routing)
+
+
## Configuration
-Ably delivers messages globally with a median latency of 37ms, validated by over 6 million daily measurements across its infrastructure. [Click here for evidence π¬](https://ably.com/docs/platform/architecture/latency#latency)
+Ably's message queues use consistent hashing to distribute messages across worker servers, ensuring even load distribution and exactly-once processing. [See evidence here π΅οΈ](/docs/platform/architecture/scalability#consistent-hashing-for-workload-distribution)
### Subscription filters
-Ably delivers messages globally with a median latency of 37ms, validated by over 6 million daily measurements across its infrastructure. [Click here for evidence π¬](https://ably.com/docs/platform/architecture/latency#latency)
-
-
To get started with sending and receiving messages, all you need to do is:
* [Use a channel](#use)
* [Subscribe to the channel](#subscribe)
* [Publish messages to the channel](#publish)
+
+Channels are lightweight and stateful internally, enabling applications to maintain millions simultaneously while optimizing message processing with minimal overhead. [See evidence here π΅οΈ](/docs/platform/architecture/performance#channels-as-the-foundation-of-performance)
+
+
## Use a channel
-Ably's infrastructure serves billions of devices each month, handling enterprise-scale traffic reliably and quickly. [Click here for evidence π¬](https://ably.com/docs/platform/architecture/scalability)
+Ably's infrastructure serves billions of devices each month, handling enterprise-scale traffic reliably and quickly. [See evidence here π΅οΈ](/docs/platform/architecture/platform-scalability)
@@ -41,7 +41,7 @@ The following diagram demonstrates the push notification process:
### Configure
-Configuring push notifications sets your [device's](/docs/push/configure/device) or [browser's](/docs/push/configure/web) push notification service to operate with the Ably [platform](https://ably.com/docs/). This process includes inputting the necessary credentials into your Ably [dashboard](https://ably.com/accounts).
+Configuring push notifications sets your [device's](/docs/push/configure/device) or [browser's](/docs/push/configure/web) push notification service to operate with the Ably [platform](/docs/). This process includes inputting the necessary credentials into your Ably [dashboard](https://ably.com/accounts).
### Activate
@@ -101,7 +101,7 @@ Each push target device or browser is associated with a unique `deviceId` and au
* By employing a standard [Ably key](/docs/auth/basic) or [Token](/docs/auth/token), with a `deviceIdentityToken`, a credential generated during registration to assert the device's or browser's identity, included in the request header.
-The service credential management is handled by the [Ably SDK](https://ably.com/docs/sdks), removing the need for the client application to manage device credentials unless accessing the [push admin API](/docs/api/realtime-sdk/push-admin) directly via HTTP.
+The service credential management is handled by the [Ably SDK](/docs/sdks), removing the need for the client application to manage device credentials unless accessing the [push admin API](/docs/api/realtime-sdk/push-admin) directly via HTTP.
#### Error handling
-Even if publications occur almost simultaneously in different regions, subscribers receive each message only once, providing true exactly-once semantics. [Click here for evidence π¬](https://ably.com/docs/platform/architecture/idempotency#ablys-approach-to-idempotent-publishing)
-
-
Publish push notifications directly or via channels:
@@ -30,6 +26,10 @@ Publish push notifications directly or via channels:
- **Description:** Messages are sent to multiple devices or browsers through specified channels.
- **Requirement:** Devices or browsers must be [subscribed](#sub-channels) to these channels to receive notifications.
+
+Proactive capacity management with headroom maintenance ensures performance isn't degraded by capacity limitations, regardless of demand levels. [See evidence here π΅οΈ](/docs/platform/architecture/performance#capacity-management-and-quality-of-service)
+
+
## Push notification payload structure
-Ably maintains message continuity for up to 2 minutes during disconnections. The SDKs automatically handle reconnection and deliver all missed messages. [Click here for evidence π¬](https://ably.com/docs/platform/architecture/connection-recovery)
-
-
It's important to understand that History is not a database. The feature is purely for time-based retrieval on a single channel. It simply cannot support the complex queries that modern applications require. For example, the History API does not index message content or publisher IDs, so you cannot:
* Search messages by their author (clientId).
@@ -32,6 +28,9 @@ For any application needing complex queries or long-term data persistence, you m
You can also learn more about [connection states](/docs/connect/states) and the broader [platform architecture](/docs/platform/architecture).
+
+Ably maintains message continuity for up to 2 minutes during disconnections. The SDKs automatically handle reconnection and deliver all missed messages. [See evidence here π΅οΈ](/docs/platform/architecture/connection-recovery)
+
## History versus rewind
-Every message is redundantly stored across multiple isolated datacenters within your region before acknowledgment, preventing data loss. [Click here for evidence π¬](https://ably.com/docs/platform/architecture/fault-tolerance#core-layer)
-
-
The following diagram illustrates the default persistence of messages:
@@ -31,6 +27,10 @@ The time that messages will be stored for depends on your account package:
There is a cost associated with storing messages for longer than the minimum time period. [Contact us](https://ably.com/support) to discuss enabling long term storage.
+
+Every message is redundantly stored across multiple isolated datacenters within your region before acknowledgment, preventing data loss. [See evidence here π΅οΈ](/docs/platform/architecture/fault-tolerance#core-layer)
+
+
### Message deletion
---
src/components/blocks/dividers/Aside.tsx | 8 --------
src/components/blocks/dividers/dividers.module.css | 3 ---
2 files changed, 11 deletions(-)
diff --git a/src/components/blocks/dividers/Aside.tsx b/src/components/blocks/dividers/Aside.tsx
index d0ea494fc0..151a323bad 100644
--- a/src/components/blocks/dividers/Aside.tsx
+++ b/src/components/blocks/dividers/Aside.tsx
@@ -44,14 +44,6 @@ const Aside = ({ children, attribs }: AsideProps) => {
Further Reading
- ) : attribs && attribs[`data-type`] === `see-evidence` ? (
- <>
-
-
- π
- See evidence
-
-
) : attribs && isVersioningInfo ? (
<>
Date: Thu, 29 Jan 2026 15:18:47 +0100
Subject: [PATCH 10/10] Rebases to pull new usp asides formmting
---
src/pages/docs/channels/options/deltas.mdx | 6 ++++--
src/pages/docs/connect/index.mdx | 10 ++++------
src/pages/docs/connect/states.mdx | 6 ++++--
src/pages/docs/messages/index.mdx | 6 ++++--
src/pages/docs/metadata-stats/metadata/subscribe.mdx | 6 ++++--
src/pages/docs/metadata-stats/stats.mdx | 6 ++++--
src/pages/docs/presence-occupancy/index.mdx | 4 ----
src/pages/docs/presence-occupancy/occupancy.mdx | 4 ----
src/pages/docs/presence-occupancy/presence.mdx | 6 ++++--
src/pages/docs/protocols/index.mdx | 4 ----
src/pages/docs/protocols/mqtt.mdx | 6 ++++--
src/pages/docs/protocols/pubnub.mdx | 6 ++++--
src/pages/docs/protocols/pusher.mdx | 6 ++++--
src/pages/docs/protocols/sse.mdx | 6 ++++--
src/pages/docs/pub-sub/advanced.mdx | 6 ++++--
src/pages/docs/pub-sub/index.mdx | 4 ----
src/pages/docs/push/index.mdx | 10 ++++++----
src/pages/docs/push/publish.mdx | 6 ++++--
src/pages/docs/storage-history/history.mdx | 6 ++++--
src/pages/docs/storage-history/storage.mdx | 6 ++++--
20 files changed, 66 insertions(+), 54 deletions(-)
diff --git a/src/pages/docs/channels/options/deltas.mdx b/src/pages/docs/channels/options/deltas.mdx
index 3994589c67..1aac702e9a 100644
--- a/src/pages/docs/channels/options/deltas.mdx
+++ b/src/pages/docs/channels/options/deltas.mdx
@@ -33,8 +33,10 @@ There is no constraint on how many publishers or subscribers there are. If there
If a delta is generated and it results in a difference that is not appreciably smaller than the original message, or is larger than the original message, for example if successive messages are completely different, then the delta will not be sent. Clients will receive the original, unprocessed message.
-
-Deltas rely on consistent message ordering. Messages published using Realtime from a single publisher are delivered to all subscribers in the same order, with each message assigned a unique serial number. [See evidence here π΅οΈ](/docs/platform/architecture/message-ordering#message-ordering-guarantees).
+
+Consistent message ordering for deltas.
+
+Deltas rely on consistent message ordering. Messages published using Realtime from a single publisher are delivered to all subscribers in the [same order](/docs/platform/architecture/message-ordering#message-ordering-guarantees), with each message assigned a unique serial number.
diff --git a/src/pages/docs/connect/index.mdx b/src/pages/docs/connect/index.mdx
index 3728919efa..6cf03fca0f 100644
--- a/src/pages/docs/connect/index.mdx
+++ b/src/pages/docs/connect/index.mdx
@@ -151,10 +151,6 @@ A connection ID is a unique identifier given to a connection, allowing for ident
An active connection ID is guaranteed to be unique in the Ably system whilst it is active, i.e. no other connection will share that connection ID. However, Ably reserves the right to generate a new connection ID later that may be the same as a previously discarded connection ID (once the connection is closed). Therefore customers are advised to not use the connection ID as a perpetual unique identifier as it is possible that a connection ID may be used many times.
-
-Ably automatically recovers connections and prevents message loss or duplication when clients reconnect within two minutes. [See evidence here π΅οΈ](/docs/platform/architecture/idempotency#connection-recovery-and-exactly-once-delivery)
-
-
### Connection metachannels
-Ably's SDKs automatically resolve edge network failures within 30 seconds, keeping your users connected even during infrastructure issues. [See evidence here π΅οΈ](/docs/platform/architecture/edge-network)
+
+Transparent edge network failover.
+
+Ably's SDKs automatically resolve [edge network failures](/docs/platform/architecture/edge-network) within 30 seconds, keeping your users connected even during datacenter outages.
### Reliability considerations
diff --git a/src/pages/docs/connect/states.mdx b/src/pages/docs/connect/states.mdx
index f6a5cd554d..232b4dbb2a 100644
--- a/src/pages/docs/connect/states.mdx
+++ b/src/pages/docs/connect/states.mdx
@@ -15,8 +15,10 @@ An Ably SDK is responsible for managing a connection. This includes:
When an SDK is instantiated it will establish a connection immediately, and if the connection drops at any time it will attempt to re-establish it by making repeated connection attempts every 15 seconds for up to two minutes.
-
-Failed connections automatically try up to 5 alternative endpoints worldwide, maximizing reconnection success. [See evidence here π΅οΈ](/docs/platform/architecture/edge-network#protocol-level-resilience)
+
+Automatic fallback to alternative endpoints.
+
+Failed connections automatically try up to 5 [alternative endpoints](/docs/platform/architecture/edge-network#protocol-level-resilience) worldwide, maximizing reconnection success.
## Available connection states
-Applications maintain their state during disruptions. All messages are received in correct order with no message loss. [See evidence here π΅οΈ](/docs/platform/architecture/connection-recovery#message-identification-with-timeserial)
+
+Message continuity during disruptions.
+
+Applications maintain their state during brief disruptions. If a client reconnects within two minutes, all messages are received in the correct order with [no message loss](/docs/platform/architecture/connection-recovery#message-identification-with-timeserial).
## Message conflation
-
-Auto Scaling Groups in each region scale independently according to demand, automatically maintaining sufficient capacity to handle traffic peaks. [See evidence here π΅οΈ](/docs/platform/architecture/infrastructure-operations#multi-region-deployment)
+
+Metadata events scale with your traffic.
+
+Auto Scaling Groups in each region [scale independently](/docs/platform/architecture/infrastructure-operations#multi-region-deployment) according to demand, ensuring metachannels remain responsive and deliver operational insights reliably during traffic peaks.
## Log events
-Ably delivers over 500 billion messages monthly, demonstrating large throughput capability. [See evidence here π΅οΈ](/docs/platform/architecture/platform-scalability#monitoring-and-auto-scaling)
+
+Over 500 billion messages delivered monthly.
+
+Ably delivers over 500 billion messages monthly, demonstrating [large-scale throughput capability](/docs/platform/architecture/platform-scalability#monitoring-and-auto-scaling).
## Account statistics
-Ably monitors resource headroom and triggers automatic scaling when load approaches capacity, absorbing traffic spikes without degradation. [See evidence here π΅οΈ](/docs/platform/architecture/platform-scalability#monitoring-and-auto-scaling)
-
diff --git a/src/pages/docs/presence-occupancy/occupancy.mdx b/src/pages/docs/presence-occupancy/occupancy.mdx
index d4ff6410a8..79e47a836d 100644
--- a/src/pages/docs/presence-occupancy/occupancy.mdx
+++ b/src/pages/docs/presence-occupancy/occupancy.mdx
@@ -8,10 +8,6 @@ redirect_from:
Occupancy provides high level metrics about the clients attached to a channel. This includes the number of [connections](/docs/connect) currently attached to a channel, and the number of connections attached that are permitted to publish and subscribe to the channel.
-
-Whether there are many lightly-loaded channels or fewer heavily-loaded ones, scaling and placement strategies ensure capacity is added as required and load is effectively distributed. [See evidence here π΅οΈ](/docs/platform/architecture/platform-scalability#how-ably-achieves-scalability)
-
-
## Occupancy metric categories
-If clients can't connect to primary endpoints, Ably SDKs automatically attempt alternative fallback endpoints, including a completely segregated secondary domain with a different DNS provider. [See evidence here π΅οΈ](/docs/platform/architecture/edge-network#fallback-endpoints-and-secondary-domains)
+
+Presence state preserved during disconnections.
+
+When a client briefly disconnects, Ably [preserves their connection state](/docs/platform/architecture/connection-recovery), including presence membership, for up to two minutes. This prevents false leave and re-enter events during temporary network issues.
### Member data
-Direct site-to-site distribution means that messages are delivered to all subscribers in the minimum time. [See evidence here π΅οΈ](/docs/platform/architecture/message-ordering#multi-region-message-distribution)
-
-
## Available Protocol Adapters
-Within a single region, all MQTT subscribers will observe messages in the same order, ensuring consistent experiences for users in that region. [See evidence here π΅οΈ](/docs/platform/architecture/message-ordering#practical-implications-of-dual-ordering)
+
+Consistent regional message ordering.
+
+Within a single region, all MQTT subscribers will observe messages in the [same order](/docs/platform/architecture/message-ordering#practical-implications-of-dual-ordering), ensuring consistent experiences for users in that region.
## Configuration
-Ably achieves a global median message delivery latency of 37ms, continuously monitored through over 6 million measurements daily across all regions. [See evidence here π΅οΈ](/docs/platform/architecture/latency#how-latency-is-measured)
+
+Automatic connection recovery and message continuity.
+
+Ably automatically [recovers connections](/docs/platform/architecture/connection-recovery) and delivers all missed messages when clients reconnect within two minutes, ensuring no data is lost during brief disconnections.
## Migration process
-Ably achieves a global median message delivery latency of 37ms, continuously monitored through over 6 million measurements daily across all regions. [See evidence here π΅οΈ](/docs/platform/architecture/latency#how-latency-is-measured)
+
+Automatic routing to the closest datacenter.
+
+Ably automatically connects clients to the closest datacenter using [latency-based DNS routing](/docs/platform/architecture/edge-network#dns-organization-and-latency-based-routing), compensating for any protocol adapter overhead with optimal network proximity.
## Supported features
-
-Ably's DNS uses a 60-second TTL, allowing traffic to be rerouted away from unhealthy datacenters within minutes when issues are detected. [See evidence here π΅οΈ](/docs/platform/architecture/edge-network#dns-organization-and-latency-based-routing)
+
+Resilient connections with DNS failover.
+
+Ably's DNS uses a [60-second TTL](/docs/platform/architecture/edge-network#dns-organization-and-latency-based-routing), allowing traffic to be rerouted away from unhealthy datacenters within minutes when issues are detected.
## Configuration
-Ably's message queues use consistent hashing to distribute messages across worker servers, ensuring even load distribution and exactly-once processing. [See evidence here π΅οΈ](/docs/platform/architecture/scalability#consistent-hashing-for-workload-distribution)
+
+Even load distribution with consistent hashing.
+
+Ably's message queues use [consistent hashing](/docs/platform/architecture/platform-scalability#consistent-hashing-for-workload-distribution) to distribute messages across worker servers, ensuring even load distribution and exactly-once processing.
### Subscription filters
-Channels are lightweight and stateful internally, enabling applications to maintain millions simultaneously while optimizing message processing with minimal overhead. [See evidence here π΅οΈ](/docs/platform/architecture/performance#channels-as-the-foundation-of-performance)
-
-
## Use a channel
+Enterprise-scale push notification delivery.
+
+Ably's infrastructure serves billions of devices each month, handling [enterprise-scale traffic](/docs/platform/architecture/platform-scalability) reliably and quickly.
+
+
You can publish push notifications to user devices or browsers [directly](/docs/push/publish/#direct-publishing) or [via channels](#via-channels).
Publishing directly sends push notifications to specific devices or browsers identified by unique identifiers, such as a `deviceId` or a `clientId`. This approach is akin to sending a personal message or alerts directly to an individual user's device or browser, bypassing the need for channel subscriptions. It excels in targeted and personalized communications, such as alerts specific to a user's actions, account notifications, or customized updates.
Publishing via channels uses a [Pub/Sub](/docs/messages) model. Messages are sent to channels to which multiple devices or browsers can subscribe. When a message is published to a channel, all devices or browsers subscribed to that channel receive the notification. This approach is particularly powerful for simultaneously publishing messages to multiple users.
-
-Ably's infrastructure serves billions of devices each month, handling enterprise-scale traffic reliably and quickly. [See evidence here π΅οΈ](/docs/platform/architecture/platform-scalability)
-
-
Push subscriptions do not count toward your connection limit since devices don't need to maintain an active connection to receive push notifications. However, publishing push notifications via channels does activate those channels, so your concurrent peak channel count will equal the number of channels you publish to simultaneously.
diff --git a/src/pages/docs/push/publish.mdx b/src/pages/docs/push/publish.mdx
index 5069469408..5e75aac480 100644
--- a/src/pages/docs/push/publish.mdx
+++ b/src/pages/docs/push/publish.mdx
@@ -26,8 +26,10 @@ Publish push notifications directly or via channels:
- **Description:** Messages are sent to multiple devices or browsers through specified channels.
- **Requirement:** Devices or browsers must be [subscribed](#sub-channels) to these channels to receive notifications.
-
-Proactive capacity management with headroom maintenance ensures performance isn't degraded by capacity limitations, regardless of demand levels. [See evidence here π΅οΈ](/docs/platform/architecture/performance#capacity-management-and-quality-of-service)
+
+Proactive capacity management.
+
+Proactive [capacity management](/docs/platform/architecture/performance#capacity-management-and-quality-of-service) with headroom maintenance ensures performance isn't degraded by capacity limitations, regardless of demand levels.
## Push notification payload structure
-Ably maintains message continuity for up to 2 minutes during disconnections. The SDKs automatically handle reconnection and deliver all missed messages. [See evidence here π΅οΈ](/docs/platform/architecture/connection-recovery)
+
+Two-minute message continuity.
+
+Ably maintains message continuity for up to 2 minutes during disconnections. The SDKs automatically handle [reconnection](/docs/platform/architecture/connection-recovery) and deliver all missed messages.
## History versus rewind
-Every message is redundantly stored across multiple isolated datacenters within your region before acknowledgment, preventing data loss. [See evidence here π΅οΈ](/docs/platform/architecture/fault-tolerance#core-layer)
+
+Redundant multi-datacenter storage.
+
+Every message is redundantly stored across [multiple isolated datacenters](/docs/platform/architecture/fault-tolerance#core-layer) within your region before acknowledgment, preventing data loss.
### Message deletion