From dd53c9e4975476e3d27ec9023d3e51cd7629b5b0 Mon Sep 17 00:00:00 2001
From: Steve Cliff <steve@devcloud.guru>
Date: Mon, 4 May 2026 22:25:35 +0000
Subject: [PATCH] ui(alerts): clarify Acknowledge vs Resolve (#9)

Co-authored-by: Steve Cliff <steve@devcloud.guru>
Co-committed-by: Steve Cliff <steve@devcloud.guru>
---
 web/templates/pages/alerts.html       | 9 ++++++++-
 web/templates/partials/alert_row.html | 9 ++++++---
 2 files changed, 14 insertions(+), 4 deletions(-)

diff --git a/web/templates/pages/alerts.html b/web/templates/pages/alerts.html
index f7475fd..c059e24 100644
--- a/web/templates/pages/alerts.html
+++ b/web/templates/pages/alerts.html
@@ -28,6 +28,13 @@
     </div>
   </div>
 
+  {{/* triage legend — Acknowledge vs Resolve looks identical on screen
+       (both leave the Open tab) so the difference needs spelling out. */}}
+  <div class="text-ink-mute mt-2 leading-[1.55]" style="font-size: 11.5px; max-width: 760px;">
+    <span class="text-ink-mid">Acknowledge</span> silences fan-out while the underlying problem is still happening — the alert moves to the Acknowledged tab.
+    <span class="text-ink-mid">Resolve</span> closes the alert; the next failure raises a fresh one with a new notification.
+  </div>
+
   {{/* filter strip */}}
   <div class="panel mt-4 px-4 py-3 rounded-[7px]"
        style="display: grid; grid-template-columns: auto auto auto 1fr; gap: 14px; align-items: center;">
@@ -89,7 +96,7 @@
     {{/* header row */}}
     <div class="alert-row head">
       <div></div>
-      <div>Severity / kind</div>
+      <div>Kind</div>
       <div>Host</div>
       <div>Message</div>
       <div>Raised</div>
diff --git a/web/templates/partials/alert_row.html b/web/templates/partials/alert_row.html
index b194386..7cabdc1 100644
--- a/web/templates/partials/alert_row.html
+++ b/web/templates/partials/alert_row.html
@@ -69,13 +69,15 @@
         {{if $qs}}<input type="hidden" name="qs" value="{{$qs}}">{{end}}
         <button type="submit" class="btn"
                 hx-post="/alerts/{{$a.ID}}/acknowledge{{if $qs}}?{{$qs}}{{end}}"
-                hx-swap="none">Acknowledge</button>
+                hx-swap="none"
+                title="I've seen this — silence further fan-out, but the alert is still open until the condition clears or you Resolve it.">Acknowledge</button>
       </form>
       <form method="post" action="/alerts/{{$a.ID}}/resolve">
         {{if $qs}}<input type="hidden" name="qs" value="{{$qs}}">{{end}}
         <button type="submit" class="btn"
                 hx-post="/alerts/{{$a.ID}}/resolve{{if $qs}}?{{$qs}}{{end}}"
-                hx-swap="none">Resolve</button>
+                hx-swap="none"
+                title="The underlying issue is fixed. Closes the alert. If the condition fires again a fresh alert will be raised with a new fan-out.">Resolve</button>
       </form>
     {{else if eq $status "acknowledged"}}
       <span class="text-ink-fade" style="font-size: 11px;">
@@ -85,7 +87,8 @@
         {{if $qs}}<input type="hidden" name="qs" value="{{$qs}}">{{end}}
         <button type="submit" class="btn"
                 hx-post="/alerts/{{$a.ID}}/resolve{{if $qs}}?{{$qs}}{{end}}"
-                hx-swap="none">Resolve</button>
+                hx-swap="none"
+                title="The underlying issue is fixed. Closes the alert.">Resolve</button>
       </form>
     {{else}}
       <span class="text-ink-fade" style="font-size: 11px;">resolved · {{relTime $a.ResolvedAt}}</span>