# Notifications

OS notifications fire on **state transitions only** — never on every check, never on every log line. The transition detector compares the previous health snapshot to the new one and emits one event per check that crossed the `error` threshold.

## Layered policy

1. **Global default** — `notifications:` block in `cockpit.yaml`:

   ```yaml
   notifications:
     enabled: true
     onTransitionTo:
       - error
       - recovered
   ```

2. **Per-item override** — a `notify:` field on any process or health check:

   ```yaml
   processes:
     - id: lint
       command: npx eslint . --watch
       notify: false                     # mute this item

   health:
     - id: api-up
       type: http-ok
       url: http://localhost:3000/health
       notify:
         onTransitionTo: [error]         # only on going-down, not on recovery
   ```

3. **Session toggle** — press `n` in the cockpit to mute *all* notifications for the current session (overrides config). The Health pane shows the current session state at the bottom.

## Events

- `health-failed` / `health-recovered` — emitted by the health framework on state transitions.
- Profiles can emit their own event names (`build-failed`, `db-disconnect`, anything domain-specific) via the exported `emitEvent` helper; they flow through the same `enabled` + `onTransitionTo` + `exclude` policy.

The `appName` configured in `cockpit.yaml` is used as the title prefix on every notification (e.g. `my-app — API responds`).
