From 7ede9e3fb857c5c6aea23241d3a898e3800007a0 Mon Sep 17 00:00:00 2001
From: spaced4ndy <spaced4ndy@users.noreply.github.com>
Date: Tue, 12 May 2026 12:38:22 +0000
Subject: [PATCH] deploy: 24859e128133bd7c0eb789d33f04b7a27de07dff

---
 docs/protocol/channels-protocol.html | 23 +++++++++++++++++++++++
 1 file changed, 23 insertions(+)

diff --git a/docs/protocol/channels-protocol.html b/docs/protocol/channels-protocol.html
index f900f7c593..492f6dc573 100644
--- a/docs/protocol/channels-protocol.html
+++ b/docs/protocol/channels-protocol.html
@@ -796,6 +796,7 @@ window.addEventListener('click',(e)=>{
 <ul>
 <li><a href="#channel-creation">Channel creation</a></li>
 <li><a href="#relay-acceptance">Relay acceptance</a></li>
+<li><a href="#relay-addition">Relay addition</a></li>
 <li><a href="#subscriber-connection">Subscriber connection</a></li>
 <li><a href="#message-signing">Message signing</a></li>
 <li><a href="#message-forwarding">Message forwarding</a></li>
@@ -854,6 +855,23 @@ window.addEventListener('click',(e)=>{
 </li>
 </ol>
 <p>TODO: Periodic monitoring where the relay retrieves channel link data to verify its relay link is still listed is planned but not yet implemented.</p>
+<h3 id="relay-addition" tabindex="-1">Relay addition</h3>
+<p>When the owner adds a relay to an existing channel:</p>
+<ol>
+<li>
+<p><strong>Acceptance.</strong> The new relay accepts the invitation following the <a href="#relay-acceptance">Relay acceptance</a> flow. The owner promotes the relay to active when the channel link's updated relay list is confirmed.</p>
+</li>
+<li>
+<p><strong>Announce.</strong> If the channel has at least one subscriber, the owner sends <code>x.grp.relay.new</code> (carrying the new relay's short link) to every other currently-connected relay of the channel.</p>
+</li>
+<li>
+<p><strong>Forward.</strong> Each relay forwards <code>x.grp.relay.new</code> to its subscribers. The relay does not create a member record for the announced relay — relays do not connect to other relays of the same channel.</p>
+</li>
+<li>
+<p><strong>Connect.</strong> On receipt, the subscriber resolves the announced short link and connects to the new relay asynchronously.</p>
+</li>
+</ol>
+<p>The announce is an optimisation. When it does not reach a subscriber — because the channel had no subscribers at announce time, because an older client or relay sits in the path, or because of a transient network failure — the subscriber reaches the same end state on the next channel open via its relay sync against the channel's link data.</p>
 <h3 id="subscriber-connection" tabindex="-1">Subscriber connection</h3>
 <p>A subscriber joins a channel through the following flow:</p>
 <ol>
@@ -920,6 +938,11 @@ window.addEventListener('click',(e)=>{
 <td>Required</td>
 </tr>
 <tr>
+<td><code>x.grp.relay.new</code></td>
+<td>Announce new relay to subscribers</td>
+<td>Required</td>
+</tr>
+<tr>
 <td><code>x.grp.leave</code></td>
 <td>Leave channel</td>
 <td>Required (unverified allowed between subscribers)</td>