feat(notifications): add guided notification setup #3216

Problem

People coming from Slack expect Buzz to notify them when someone needs them. They should have one clear way to enable notifications and check that they work.

In a macOS walkthrough of Buzz 1.0.0, Desktop alerts was switched on while the same Settings page said Allow notifications to receive alerts. The permission warning and repair button already exist, but users must find them and reconcile the enabled preference with missing system permission. No notification delivery test was performed during that read-only walkthrough.

Proposal: “Set up your Buzz notifications”

Add a non-blocking entry point in Messages or Activity that walks the user from notification preferences to a confirmed test. Keep it available in Settings → Notifications afterward.

Suggested flow:

1. Choose what matters. Show the existing notification preferences. For new setups, offer a recommended selection of direct messages, mentions, and replies to followed threads, subject to the existing thread-notification semantics. Preserve existing choices; apply changes only when the user confirms them.
2. Enable notifications on this device. Read the current system permission state. If permission can be requested, request it after an explicit click. If permission was denied, offer Open notification settings with instructions. If permission is already granted, continue without another prompt. Explain unknown or system-managed states without pretending they are confirmed.
3. Try a notification. Offer Send test notification, using a clearly labeled local notification through Buzz’s normal desktop delivery mechanism. Explain whether Buzz must be in the background for the test. Ask Did you see it? with Yes and No actions. A successful API call alone must not mark setup complete.
4. Finish or troubleshoot. After the user confirms seeing the test, say You’re all set on this device. If they did not see it, show the next relevant step and a retry. State any limits on what Buzz can determine about OS settings or notification presentation.

Use Finish notification setup when the flow is incomplete. Let people dismiss the entry point and resume later. Completion and dismissal should be tracked per device, so a working setup on one computer does not certify another.

Acceptance criteria

• Users can start setup from the main messaging experience and reopen it from Settings → Notifications.
• Existing notification preferences are shown and preserved unless the user explicitly changes them.
• The flow distinguishes Buzz’s enabled preference from effective system permission; an enabled toggle alone is not presented as successful setup.
• Granted, not-yet-requested, denied, and unknown/system-managed permission states each have an accurate next action.
• The test is explicitly requested, clearly labeled, and does not post a chat message, contact another person, or invoke an agent.
• The test exercises the normal native delivery mechanism. Any special handling of foreground or category rules is explained, so a successful test does not imply every message will alert.
• Setup completes only after the user confirms seeing the test. Failure, cancellation, or dismissal preserves a resumable state.
• Setup and completion states work with keyboard navigation and screen-reader labels.
• Native macOS validation covers first permission request, existing permission, denied permission, a visible test, and an unsuccessful test. Browser mocks alone are insufficient for delivery acceptance.

Scope and decisions to settle before implementation

This proposal connects existing notification controls into a guided setup. Initial delivery validation targets macOS, where the gap was observed. The implementation plan should identify how the same entry point behaves on other supported platforms.

Before a PR, settle the entry-point placement, the recommended category wording, and how the test behaves while Buzz is foregrounded. Keep the flow short and avoid repeatedly prompting people who dismiss it.

Message-level Why wasn’t I notified? explanations can be a later enhancement. This issue does not require a notification audit log or changes to per-channel alert policy.

Related work

• fix(notifications): show loading for permission checks #1386 added feedback while permission checks run; the underlying permission-check controls already exist.
• feat(activity): count unread conversations on the sidebar Activity row #3175 proposes an Activity unread count, and feat(notifications): show unread attention count on the Dock badge #2693 proposes a Dock attention count. Those improve attention signals but do not guide notification setup.
• feat(notifications): choose All new posts, Just mentions or Mute per channel #2918 and feat(notifications): notify on all activity in chosen channels #2956 concern per-channel notification choices. Reuse the existing preference model rather than creating a competing one.
• feat(doctor): consolidate background failures and recovery #3000 proposed a consolidated background-read recovery panel and was closed unmerged. This proposal is limited to notification setup and verification.