---
name: briefkin
description: Report meaningful results, blockers, and requests for human action to the user's Briefkin dashboard. Use when you finish a task, open a PR, get blocked, need the user to do something, or produce a scheduled metric or research finding. Do not report routine tool calls.
---

# Reporting to Briefkin

Briefkin is the user's dashboard for agent work. Send one update when something meaningful happens:

- Work finished (with links: PR, deploy, report).
- You are blocked or failed.
- The user must do something (review, approve, run a command, decide).
- A scheduled job produced a metric or finding.

Do not report routine progress, individual tool calls, or anything the user already saw in this session.

## Sending an update

The token is in `BRIEFKIN_TOKEN`. The API base is `BRIEFKIN_URL` (default `https://briefkin.dev`).

```bash
curl -sS -X POST "${BRIEFKIN_URL:-https://briefkin.dev}/v1/events" \
  -H "authorization: Bearer $BRIEFKIN_TOKEN" \
  -H "content-type: application/json" \
  -d @- <<'JSON'
{
  "v": 1,
  "event_id": "<unique id for this update, e.g. a UUID>",
  "item_key": "<stable key for the task, e.g. repo/feature-name>",
  "project": "<project name>",
  "kind": "action",
  "title": "Feature F finished",
  "summary": "PR #44 opened.",
  "work_state": "done",
  "action": { "request": "Review PR #44", "why": "Merging unblocks the release." },
  "links": [{ "label": "Review PR", "url": "https://github.com/org/repo/pull/44" }]
}
JSON
```

## Fields

- `item_key`: the same key for every update about the same task or metric. A later update replaces the card; it does not add a duplicate.
- `event_id`: unique per update. Resending the same `event_id` is safe and changes nothing.
- `kind`:
  - `update`: a result or milestone. No human action needed.
  - `action`: the user must do something. Requires `action.request`. Stays in "Needs you" until the user resolves it.
  - `metric`: a number for a period. Requires `metric` with `label`, `value`, `period_start`, `period_end` (ISO 8601), optional `unit`.
- `work_state`: `in_progress`, `done`, `blocked`, or `failed`.
- `urgency`: `low`, `normal` (default), or `high`. A suggestion only; the user's rules decide notifications.
- `links`: up to 10 `{label, url}` evidence links.

## Rules

- Say what you verified. "PR opened" is a fact; "migration ran" needs evidence.
- One update per milestone. Keep `title` short and put detail in `summary`.
- If the request fails, tell the user in your normal reply. Do not retry in a loop.