# notify — Manual

## What it does
Pushes a notification to the user's device — application web push, a Synapse event, or both, depending on the user's notification settings. It exists to reach the user **when the turn is not enough**: a background task finished, something broke, or a decision is needed before work can continue.

It is not a progress log. A notification interrupts; each one should be something the user would want to know now.

## Parameters

| Parameter | Required | Description |
|-----------|----------|-------------|
| `message` | yes | One plain sentence or two. |
| `level` | no | `info` (default) \| `warning` \| `intervention`. |

```json
{"message": "Backup finished: 4.2 GB, no errors.", "level": "info"}
{"message": "Deploy failed at the migration step — the DB is still on the old schema.", "level": "warning"}
{"message": "Delete the 12 archived sessions on prod? Two of them are referenced by open tasks. Need an answer before I continue.", "level": "intervention"}
```

Levels map to delivery priority and to the push title:

| `level` | Meaning | Priority |
|---|---|---|
| `info` | FYI — the result is in, nothing needed | normal |
| `warning` | Something went wrong or degraded | high |
| `intervention` | The user's decision is needed now | critical |

The notification titles are localised by level ("Navi: уведомление" / "Navi: предупреждение" / "Navi: нужно ваше решение") — that is the app's wording, not yours; the `message` is what you write.

## Where it goes

Delivery follows the user's `push_target` setting, and the result says exactly what happened:

- **app** — web push to the running client. Skipped if push is not configured on this server.
- **app_synapse** — both legs.
- **synapse** — a `navi-notification` event through Synapse, with the level as the action and a dedup key derived from the message. Skipped if the Synapse source key is not configured.

A successful call returns `success: true` and a report such as `Delivered: app, synapse.` or `Skipped: synapse (source key not configured).` **A skipped leg is not a failure** — the notification went where it could. Do not retry to force the other leg; the configuration is a user choice.

The call fails only when there is genuinely nothing to send: no user context in the run (*No user context*), an empty `message`, or a `level` outside the three above.

## Rules

- **`intervention` must state the decision.** Say what you need decided and what happens next, so the user can answer from the notification without opening the session. "Please advise" is not a request.
- One notification per event. A background task that finished gets one note — not one when it starts, one at 50%, and one at the end.
- Do not notify for work the user is watching anyway, and do not notify to report your own progress. The push is for what they are *not* looking at.
- When a background task completes and the user is already in the session, a note in the reply is enough.