adom-desktop notify_user '{"title":"Build complete","body":"hd_build_rust finished — exit 0","level":"info"}'

{
  "title": "...",
  "body":  "...",
  "level": "info | warning | error | emergency",   // default: info
  "actions": ["Open log", "Dismiss"]                 // optional buttons
}

# via the control API (or adom-cli hydrogen api, or the API Explorer "Try it")
POST /ui/toast { "message": "Build finished ✅", "type": "success", "duration": 5000 }

adom-desktop browser_alert_window '{"sessionId":"default"}'

---
name: hd-notifications
description: >
  How Hydrogen Desktop reaches the user OUTSIDE the window — native Windows toast
  notifications + taskbar attention — so the AI can proactively tell the user a
  long job finished or that it needs them (great for hands-free / away-from-keyboard
  work). Covers HD's notify handler (levels info|warning|error|emergency, optional
  <actions> buttons; emergency = a persistent orange taskbar flash via
  request_user_attention(Critical) until the user looks), how toasts route via a
  PowerShell AUMID so they may show an "Adom" title, and how to fire one with the
  `notify` desktop command / `adom-desktop notify_user`. Also Pup's
  browser_alert_window taskbar flash. Windows-only. Trigger words — notify the
  user, send a notification, desktop notification, toast, windows toast, taskbar
  flash, get the user's attention, alert the user, notify_user, emergency
  notification, urgent alert, notification actions, action buttons, ping the user,
  job done notification, tell me when it's done, flash the taskbar, request
  attention, browser_alert_window, in-app toast, ui toast, /ui/toast, show a toast
  in HD, toast inside the window.
---

# Hydrogen Desktop — Notifications (reaching the user outside the window)

When the user isn't looking at HD — a long build is running, you've finished a job,
or you're **blocked and need them** — you can reach them on the OS level: a native
Windows **toast**, and for urgent cases a **persistent taskbar flash**. This is what
makes hands-free / away-from-keyboard work usable: don't just print a message into a
panel nobody's watching — fire a notification.

> **Windows-only** for the full experience (WinRT toasts + taskbar attention).
> macOS has a limited `osascript` fallback; Linux has no toast path.

## Firing a notification

Source: `src-tauri/crates/hd-app/src/notifications.rs` (`handle_notify` → `show_toast`).
Dispatched via the `notify` message; from the workspace use the AD CLI:

```bash
adom-desktop notify_user '{"title":"Build complete","body":"hd_build_rust finished — exit 0","level":"info"}'
```

Payload shape (`NotifyPayload`):

```json
{
  "title": "...",
  "body":  "...",
  "level": "info | warning | error | emergency",   // default: info
  "actions": ["Open log", "Dismiss"]                 // optional buttons
}
```

| Field | Notes |
|---|---|
| `title` | Toast heading. If it doesn't already start with "Adom", HD prefixes it → `"Adom: <title>"`. |
| `body` | The message. |
| `level` | `info` / `warning` / `error` / `emergency`. `warning`/`error`/`emergency` render as **long-duration** toasts; `info` is short. |
| `actions` | Optional array of button labels rendered as `<actions>` in the toast template. Empty/omitted = no buttons. |

### Levels — and the `emergency` taskbar flash

- `info` / `warning` / `error` — a standard toast (warnings and errors stay up
  longer).
- **`emergency`** — in addition to the toast, HD calls
  **`request_user_attention(Critical)`** on the main window and shows/unminimizes
  it. This produces a **persistent orange taskbar flash that keeps flashing until
  the user actually clicks the taskbar icon themselves** — it is *not* cleared by a
  programmatic focus. Reserve `emergency` for "I genuinely cannot proceed without
  you" — it's intentionally hard to ignore.

### The "Adom" title quirk (AUMID routing)

On Windows, HD's toasts route through a **PowerShell AUMID**. A side effect: toasts
may surface under an **"Adom"** identity/title rather than a per-app one. That's
expected — don't treat an "Adom"-labeled toast as a bug.

## In-app toast — `POST /ui/toast` (inside the HD window)

The notifications above reach the user **outside** the window (OS toast / taskbar).
For a lightweight message **inside** the HD window — the same toast UI the app uses
for its own success/error messages — fire a control-API toast:

```bash
# via the control API (or adom-cli hydrogen api, or the API Explorer "Try it")
POST /ui/toast { "message": "Build finished ✅", "type": "success", "duration": 5000 }
```

| Field | Notes |
|---|---|
| `message` | Required. The toast text. |
| `type` | `info` (default) / `success` / `warning` / `error` — sets icon + color. |
| `duration` | ms before auto-dismiss (default 5000). **0 = persistent** until the user dismisses. |
| `groupId` + `detail` | Optional: coalesce related toasts into one expandable group. |

It emits the `hd-toast` Tauri event, which the main window renders via the global
`toastStore` (bottom-stacked toasts). **OS toast vs in-app toast:** use a `notify`
OS toast when the user may be **away from / not looking at** HD; use `/ui/toast` for
an in-window status cue while they're working in HD. (HD's native recording uses this
for its auto-stop notice — see [hd-recording](../hd-recording/SKILL.md).)

## Pup's taskbar flash (`browser_alert_window`)

For AI-driven browser work, Pup has its own attention nudge:

```bash
adom-desktop browser_alert_window '{"sessionId":"default"}'
```

It **flashes the taskbar** for that browser window (and brings the page to front
within Chrome) **without stealing foreground focus** — a gentle "look here." (Use
`browser_focus_window` if you actually want to raise the window.)

## When you (the AI) should notify proactively

- **Long-job completion** — a build, a batch, a render, a deploy finished. Fire an
  `info` toast so the user can wander off and get pulled back.
- **You need the user** — an approval, a decision, a credential. Use `warning`, or
  `emergency` if you're fully blocked.
- **Hands-free / driving** — pair a notification with audio (TTS) so the user gets
  both a glance-able toast and the spoken answer.

Don't spam: one notification per meaningful event. Verify the bridge first
(`adom-desktop ping`) before claiming you notified them.

## Related skills
- [hd-adom-desktop](../hd-adom-desktop/SKILL.md) — AD is what carries `notify_user` to the host; `ping`/`status` to verify the bridge and the `notify` capability
- [hd-bridges](../hd-bridges/SKILL.md) — the full AD capability list (`notify`, …) and Pup's `browser_alert_window`