---
name: zona
description: >
Send inbox notifications through Zona and operate the Zona MCP.
Use when the user wants a Zona ping, phone alert, /notify send, agent
notification, source token, attachments on a Zona send, or runs /zona.
---
# Zona
Zona is a private notification inbox. Agents send an HTTPS request with a
source token. Keep copy short and never include secrets.
## Secrets
- Token file: `~/.zona/token` (one `zona_live_...` line). Windows:
`%USERPROFILE%\.zona\token`.
- Optional override: env `ZONA_SOURCE_TOKEN`.
- Never print, log, commit, or put the token in URLs, README, or tool args.
- If the file is missing or `/notify` returns `INVALID_TOKEN`, ask the owner to
create a new source key in the app and replace the file. Do not search the
workspace for tokens.
## Prefer the MCP
When the `zona` MCP server is connected, use its tools instead of curling:
| Tool | When |
| --- | --- |
| `zona_status` | Check a token is configured (it does not return the token). |
| `zona_notify` | Real send: title, body, optional category, severity, a `todo` checklist (up to 20 short items the owner ticks off on the phone), a small `data` object, up to five image paths. |
| `zona_done` | End of a long task: a one-line summary, optional details, and the files worth reviewing (they become the checklist). Once per task, not per step. |
| `zona_curl` | The owner wants the alert as a command for a script or cron job. Returns curl and PowerShell text with no token in it; sends nothing. |
| `zona_checkin` | A scheduled job reports in: the check-in `name` the owner set up in the app, and `status` `ok` (default), `start` or `fail`. `CHECKIN_NOT_FOUND` means the owner has not added that check-in yet; say so, do not retry. |
| `zona_ping` | Connectivity check; optional category. |
Call the host's MCP tool with the `zona__…` qualified name it exposes. Do not
invent a token argument.
A rejected send returns `error` with `path`, `reason` and `limit`: fix that
field and send again. `retryAfterSeconds` means wait that long; do not loop.
If Zona did not answer in time, retry once with the `idempotencyKey` the error
names, so the owner gets one alert, not two.
If the owner set up agent updates (`zona hooks install <agent>`, or
`zona agent` in the agent's own hook settings), the session's state already
goes out by itself: "needs you" and "finished"
alerts, and "running" updates that feed the Agent board on Zona Plus. Do not
also send a `zona_notify` for the same thing. Use `zona_done` when there is
something specific to review. Nothing comes back from Zona: there is no way
to answer or approve an agent from the phone.
## Direct HTTP (MCP unavailable)
```
POST https://gerncrjtrdjtjvybvseb.supabase.co/functions/v1/notify
Authorization: Bearer <token from the file, never logged>
Idempotency-Key: <required unique key>
```
JSON body: `title` (1–120), `body` (1–2000), optional `category` (≤80),
`severity` (`low|medium|high|critical`), `todo` array (≤20 items of 1–200
characters), `data` object ≤4 KiB.
Images: `multipart/form-data`, repeat the `attachment` part once per PNG/JPEG/WebP
file, max five.
Check-ins use the same address and token, JSON only, with nothing else in the
body: `{"checkin": {"name": "backup", "status": "ok"}}` (`status` optional:
`ok`, `start` or `fail`). No `Idempotency-Key` is needed. A plain `ok` writes
no alert; Zona alerts when a check-in is missed, fails or starts and never
finishes. From a shell: `zona checkin <name> [--start|--fail]`.
Quiet hours still save the alert in the inbox; only the phone banner is skipped.
## When to send
Send after a user-asked Zona alert or a completed long job the owner asked to
be notified about. Keep copy short and non-secret.