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

{"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:

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.