From 648285766af7b72560bf09ec63b5883acff069da Mon Sep 17 00:00:00 2001
From: Brad Harris <bmharris@gmail.com>
Date: Sun, 19 Jul 2026 22:03:03 -0600
Subject: [PATCH] Correct focus suppression and document tips in Notifications
 docs
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Audited the in-app docs Notifications section against the (newly split)
notification settings components, focus-tracker.ts, use-agent-focus.ts,
notification-runtime.ts, and slack.ts.

- Focus suppression: blur/hide/agent-switch clears focus immediately, so
  notifications resume right away; the 30s TTL is the safety net for tabs
  that vanish without reporting. Heartbeat interval is 15s.
- Browser notifications: the enable toggle is disabled until permission is
  granted, the ack fallback window is ~3s, and there's a Send test button.
- Added a Tips & Guidance paragraph — the tips toggle and "Reset dismissed
  tips" live in the same settings pane and were undocumented.

Verified as still accurate: the three configurable events, sound cue
inventory (4 status cues + mobile tap), Slack fallback conditions, and every
dispatch_notify parameter/limit.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 .../app/docs-sections/notifications.tsx       | 36 +++++++++++++------
 1 file changed, 26 insertions(+), 10 deletions(-)

diff --git a/apps/web/src/components/app/docs-sections/notifications.tsx b/apps/web/src/components/app/docs-sections/notifications.tsx
index 34db400df..a0abc019d 100644
--- a/apps/web/src/components/app/docs-sections/notifications.tsx
+++ b/apps/web/src/components/app/docs-sections/notifications.tsx
@@ -34,11 +34,13 @@ export function NotificationsContent() {
         <H3>Browser notifications</H3>
         <P>
           Grant the browser permission, then toggle{" "}
-          <strong>Enable browser notifications</strong>. When the app is open in
-          at least one tab, matching events are delivered as native desktop or
-          mobile banners instead of Slack. If no tab is open to acknowledge the
-          notification within a few seconds, Dispatch falls back to Slack
-          automatically.
+          <strong>Enable browser notifications</strong> — the toggle stays
+          disabled until permission is granted. When the app is open in at least
+          one tab, matching events are delivered as native desktop or mobile
+          banners instead of Slack. If no tab acknowledges the notification
+          within about three seconds, Dispatch falls back to Slack
+          automatically. <strong>Send test</strong> fires a sample banner so you
+          can confirm the setup.
         </P>
         <P>
           On iOS and iPadOS, notifications only work after installing Dispatch
@@ -78,15 +80,29 @@ export function NotificationsContent() {
         </P>
       </Section>
 
+      <Section>
+        <H3>Tips &amp; guidance</H3>
+        <P>
+          The same settings pane hosts <strong>Tips &amp; Guidance</strong> —
+          short contextual hints that point out features and link into these
+          docs. They're per-device like sound cues. Untick{" "}
+          <strong>Show tips</strong> to turn them off, or use{" "}
+          <strong>Reset dismissed tips</strong> to bring back everything you've
+          already dismissed.
+        </P>
+      </Section>
+
       <Section>
         <H3>Focus-aware suppression</H3>
         <P>
           Dispatch suppresses browser and Slack notifications for an agent
-          you're already looking at. Tabs that have an agent selected send
-          periodic focus heartbeats while the tab is visible and focused;
-          notifications for that agent are dropped until the heartbeat lapses (a
-          ~30 second TTL after you switch tabs, change agents, or blur the
-          window). Sound cues are not filtered by focus.
+          you're already looking at. Tabs that have an agent selected send a
+          focus heartbeat every 15 seconds while the tab is visible and focused,
+          and notifications for that agent are dropped while it's live. Blurring
+          the window, hiding the tab, or switching agents clears focus
+          immediately, so notifications resume right away; the heartbeat also
+          expires on its own after 30 seconds if a tab goes away without
+          reporting. Sound cues are not filtered by focus.
         </P>
       </Section>