# Tasks (/docs/notifications/tasks)



"Tasks" in Layers today are onboarding milestones with credit rewards.
The system is deliberately generic (`category` field with values like
`onboarding`, `milestone`, `challenge`, `activation`) — the initial
roster is all onboarding tasks.

## Where tasks live [#where-tasks-live]

* An onboarding-task widget on the dashboard lists outstanding tasks
  with their credit reward amount and a CTA (for example, a link to
  the layer install page).
* Completion is tracked on `user_task_progress` rows
  (`pending` → `completed` | `skipped`).
* Credit grants write to `organization_credit_events` with
  `event_type: 'grant'` and `source: 'onboarding_task'` so they show
  up alongside billing history.

## Task definition fields [#task-definition-fields]

Every task is a row in `task_definitions` with:

* `task_key` — stable identifier (e.g. `connect_instagram`).
* `title`, `description`, `icon`.
* `category` (`onboarding`, `milestone`, `challenge`, `activation`),
  plus optional `subcategory` (`social`, `ads`, `sdk`, `content`).
* `credit_reward` — how many credits to grant on completion.
* `scope` — `organization` (credits awarded once per org) or `user`
  (credits awarded per user).
* `lifecycle` — `one_time`, `recurring`, or `time_boxed`.
* `completion_type` — how the task gets marked complete:
  * `event` — frontend-emitted event.
  * `backend_event` — server-emitted event.
  * `backend_validation` — server explicitly validates (e.g., SDK
    began receiving events).
  * `manual` — user dismisses or explicitly marks done.
* `completion_event` — the event key that triggers completion (for
  event-based tasks).
* `cta_label`, `cta_url` — the nudge action shown on the widget.
* `velocity_eligible` — feeds an internal "velocity credits" promo.
* `is_active`, `display_order` — roster management.

## Anti-gaming [#anti-gaming]

* `scope: organization` + `lifecycle: one_time` means credits only
  land once per org no matter how many members trigger the event.
* Disconnect-and-reconnect flows don't re-grant — completion is
  permanent on the progress row.
* The event-to-task matcher runs server-side via
  `complete_onboarding_task_by_event` RPC, so client tampering can't
  mint credits.

## What tasks are NOT [#what-tasks-are-not]

Tasks are not a human taskboard — there is no "snooze," no "assign to
a teammate," no SLA escalation, no Linear / Jira sync, no "in
progress" state, and no "reassign." It's strictly a
complete-milestone-to-earn-credits flow today.