huskies: merge 599_story_cross_project_status_notifications_in_chat

website/docs/configuration.html

@@ -247,6 +247,61 @@ Run `cargo clippy -- -D warnings` before committing. Zero warnings allowed.</cod
           <tr><td>history_size</td><td>Optional. Maximum conversation turns to remember per room/user (default: 20).</td></tr>
         </tbody>
       </table>
+
+      <h2 id="gateway-aggregated-stream">Gateway: aggregated chat stream</h2>
+      <p>When running <code>huskies --gateway</code>, you can configure a single bot that receives pipeline notifications from <strong>all</strong> registered projects. Events are prefixed with <code>[project-name]</code> so you can tell them apart in one shared room.</p>
+
+      <p>The aggregated stream is configured entirely in the <strong>gateway's</strong> <code>.huskies/bot.toml</code> — no per-project bot config is required and no per-project files need to change when you add a new project to <code>projects.toml</code>.</p>
+
+      <h3>Enabling the aggregated stream</h3>
+      <p>Add or edit <code>&lt;gateway-config-dir&gt;/.huskies/bot.toml</code> and set <code>enabled = true</code>. The gateway bot will automatically poll every project listed in <code>projects.toml</code> and forward events to the configured rooms.</p>
+<pre><code># &lt;gateway-config-dir&gt;/.huskies/bot.toml
+enabled = true
+transport = "matrix"
+homeserver = "https://matrix.example.com"
+username = "@gateway-bot:example.com"
+password = "secret"
+room_ids = ["!gateway-room:example.com"]
+allowed_users = ["@you:example.com"]
+
+# Gateway-specific: poll interval and on/off switch
+aggregated_notifications_poll_interval_secs = 5   # default
+aggregated_notifications_enabled = true            # default</code></pre>
+
+      <h3>Aggregated stream settings</h3>
+      <table>
+        <thead>
+          <tr><th>Key</th><th>Type</th><th>Default</th><th>Description</th></tr>
+        </thead>
+        <tbody>
+          <tr>
+            <td>aggregated_notifications_enabled</td>
+            <td>bool</td>
+            <td><code>true</code></td>
+            <td>Set to <code>false</code> to disable the aggregated stream without disabling the gateway bot entirely. Per-project configs are never consulted.</td>
+          </tr>
+          <tr>
+            <td>aggregated_notifications_poll_interval_secs</td>
+            <td>integer</td>
+            <td><code>5</code></td>
+            <td>How often (in seconds) the gateway polls each project's <code>/api/events</code> endpoint. Lower values reduce notification latency.</td>
+          </tr>
+        </tbody>
+      </table>
+
+      <h3>No-duplicate guarantee</h3>
+      <p>Per-project bots and the gateway aggregated stream send to different rooms — they are independent. Events from a per-project bot go to that project's rooms; events from the gateway stream go to the gateway rooms. The same event will never appear twice in either room.</p>
+
+      <h3>Unreachable projects</h3>
+      <p>If a per-project server is temporarily unreachable, the gateway logs a warning and skips that project for the current poll cycle. All other projects continue to deliver notifications normally. No configuration change is required — the poller retries on the next interval.</p>
+
+      <h3>Supported event types</h3>
+      <p>The aggregated stream delivers the following event types, each prefixed with the project name:</p>
+      <ul>
+        <li><strong>Stage transitions</strong> — story created, agent started, QA requested, QA approved/rejected, merge succeeded (all pipeline stage moves)</li>
+        <li><strong>Merge failures</strong> — merge failed with a reason</li>
+        <li><strong>Story blocked</strong> — story blocked after exceeding retry limit</li>
+      </ul>
     </main>
   </div>
 

website/docs/transports.html

@@ -200,6 +200,13 @@
           <tr><td>discord_allowed_users</td><td>Optional. Discord user IDs allowed to interact. When absent, all users in configured channels can interact.</td></tr>
         </tbody>
       </table>
+
+      <h2 id="gateway-aggregated">Gateway: aggregated notifications</h2>
+      <p>When using <code>huskies --gateway</code>, you can configure the gateway bot to receive notifications from <strong>all</strong> registered projects in a single room. Events are prefixed with <code>[project-name]</code>.</p>
+      <p>No additional transport is required — the gateway aggregated stream works with any of the transports above. Configure the gateway's <code>.huskies/bot.toml</code> with your transport credentials and set <code>aggregated_notifications_enabled = true</code> (the default). See <a href="configuration.html#gateway-aggregated-stream">Configuration → Gateway aggregated stream</a> for the full reference.</p>
+      <div class="note">
+        <strong>No per-project changes needed:</strong> Adding a new project to <code>projects.toml</code> does not require editing per-project bot configs — the gateway picks it up automatically.
+      </div>
     </main>
   </div>