huskies: merge 760

website/docs/cli.html

@@ -146,6 +146,57 @@ HUSKIES_PORT=3002 huskies</code></pre>
         </tbody>
       </table>
 
+      <h2>Gateway event-push protocol</h2>
+      <p>Project nodes can push pipeline status events to the gateway in real time over a WebSocket connection. The gateway fans each event out to all connected local subscribers.</p>
+
+      <h3>Connecting</h3>
+      <ol>
+        <li>Obtain a one-time join token: <code>POST /gateway/tokens</code> → <code>{"token":"…"}</code></li>
+        <li>Open a WebSocket upgrade to <code>GET /gateway/events/push?token=TOKEN&amp;project=PROJECT_NAME</code></li>
+        <li>The token is consumed on upgrade. The project name is attached to every event the server broadcasts downstream.</li>
+      </ol>
+
+      <h3>Sending events</h3>
+      <p>Each message must be a JSON-encoded <code>StoredEvent</code> frame:</p>
+<pre><code>// Stage transition
+{"type":"stage_transition","story_id":"42_story_login","from_stage":"2_current","to_stage":"3_qa","timestamp_ms":1700000000000}
+
+// Merge failure
+{"type":"merge_failure","story_id":"42_story_login","reason":"conflict in src/main.rs","timestamp_ms":1700000001000}
+
+// Story blocked
+{"type":"story_blocked","story_id":"42_story_login","reason":"retry limit exceeded","timestamp_ms":1700000002000}</code></pre>
+      <p>The server does not send frames back. Any other frames received by the project node indicate an error or server restart — treat them as a disconnect signal.</p>
+
+      <h3>Reconnect with exponential back-off</h3>
+      <p>Project nodes <strong>must</strong> reconnect on any disconnect. Use the following policy to avoid thundering herds after a gateway restart:</p>
+      <table>
+        <thead><tr><th>Parameter</th><th>Value</th></tr></thead>
+        <tbody>
+          <tr><td>Initial delay</td><td>1 s</td></tr>
+          <tr><td>Back-off multiplier</td><td>2× per attempt</td></tr>
+          <tr><td>Maximum delay</td><td>60 s</td></tr>
+          <tr><td>Jitter</td><td>±10 % of the computed delay</td></tr>
+        </tbody>
+      </table>
+      <p>Pseudocode:</p>
+<pre><code>delay = 1.0          // seconds
+max_delay = 60.0
+
+loop:
+    token = POST /gateway/tokens
+    connect ws:/gateway/events/push?token=TOKEN&amp;project=NAME
+    while connected:
+        send StoredEvent frames
+    // disconnected — wait and retry
+    jitter = delay * (random(0.9, 1.1))
+    sleep(min(jitter, max_delay))
+    delay = min(delay * 2, max_delay)</code></pre>
+
+      <div class="note">
+        <strong>New token per connection:</strong> Each WebSocket upgrade consumes the join token. Request a fresh token for every reconnect attempt.
+      </div>
+
       <h2>Building from source</h2>
       <h3>Standard release build</h3>
 <pre><code>cargo build --release