Guide › Modules
Training
A library of tasks with rewards, penalties, deadlines and photo verification. Assign one or roll random; complete with proof; overdue training fails on its own.
📋 Training is the work. A task library you curate, assignments with deadlines, rewards that take time off the clock, penalties that add it, and — for tasks that require it — a verification photo that lands in your gallery.
The library
Every task has:
| Field | Meaning |
|---|---|
| Title, description | what to do |
| Tags | free words; a verification photo inherits them |
| Reward (minutes) | taken off the clock when verified (only if a lock is active) |
| Penalty (minutes) | added to the clock when failed (only if a lock is active) |
| XP | earned on completion |
| Requires verification | completion needs a photo — no photo, no completion |
| Default deadline (hours) | how long an assignment has; falls back to tasks.default_due_hours (24) |
| Enabled | disabled tasks stay in the library but cannot be assigned |
The library editor is on Settings → 📋 Training. The seeded five:
| Task | Reward | Penalty | XP | Photo | Due |
|---|---|---|---|---|---|
| Verification photo — show the lock | 10 min | 30 min | 10 | yes | 12 h |
| Journal check-in — three honest sentences | 15 min | 15 min | 10 | 24 h | |
| 20 minutes of movement | 30 min | 30 min | 15 | 24 h | |
| Drink a full glass of water | 5 min | 0 | 5 | 6 h | |
| Tidy one surface | 20 min | 15 min | 10 | 24 h |
Assigning
On the Training page: pick a task and an optional deadline in hours, or choose random — a random enabled task that is not already open. The wheel's Random task segment does the same. An assignment records its source (you, the wheel, the API).
Open assignments show on the Training page and on the dashboard card, ordered by deadline, with overdue lit on the button once one has passed its time.
Completing
Tap Complete. If the task requires verification, choose a photo — the form will not accept completion without one. Add a note, or a when if you finished earlier. Then:
The photo can be one you already took
The verification field opens your normal picker, so a shot taken minutes ago with the phone's own Camera app is fine — it does not have to be taken inside Handlr. Once you pick one you get a thumbnail of it, with ↻ replace if it was the wrong shot. Pair it with did it earlier? set the time to log a task you finished before you got to your phone.
- the assignment is marked verified,
- the reward is removed from the clock of the lock that was active at that time,
- the task's XP is earned,
- the photo (if any) is stored with the task's title and tags and shows in the gallery.
A completion backdated into a lock that has since ended applies its reward to nothing — that clock is history — but the completion, the photo and the XP still count.
Failing
Tap Fail with a reason. The penalty goes on the active clock; the assignment is closed as failed. And every 30 seconds the scheduler sweeps: any open assignment past its deadline is failed by the system with reason overdue, stamped at the deadline — not at the moment the sweep happened to run. If the app was down when the deadline passed, the event is marked logged later, which is the truth.
Orders
A task can name a habit (the habit and min columns in the library editor). That makes it an order: ride the bike, 30 minutes. Log that habit inside the assignment's window — one tap, the timer, a Shortcut or a calendar feed — and the order completes itself, stamped when the log that met it ended. Two 15-minute rides meet a 30-minute order; min 0 (or an untimed habit) means any one log. An order that needs a photo still waits for you.
An order can name a distance too (the distance column): ride 8 miles. A bare number is
miles; type 13 km or 5000 m for anything else. Only the distance a bout measured counts —
the watch's, or what you typed in the log form — so a ride logged with no distance brings no
miles. With minutes as well, both must be reached. Only a habit timed by its own logs can carry a
distance (a ride, a walk; not a sit). See Workouts.
Let an order run out and it fails like any training. Let it run out while you logged a different habit in its window and it is off-script — the log says what you did instead, and Mischief marks it 🌀 Zoomies rather than 👻 Ghosted. An order for a workout is judged by the credit table instead: a walk for a ride, or a ride cut short, can earn full or half credit, depending on your Handler.
An order can also name a trance sit, and one score — sit Descent, 45 minutes (the sit column): a sit of that score completes it.
Orders come from three places:
- Your library — the wheel and random can draw one like any task.
- Standing days on a habit — bike on Mon, Wed, Fri (Habits): the first tick of each of those days issues one, due at midnight, and a ride you logged before the tick still counts.
- Today's workout — when you let your Handler pick it, proposed or ordered each morning.
- Your AI Handler, under Assign training: reward 0, penalty 0, like all its training. Only your own habits can be ordered — never a playset's, never one your health data feeds — and a pack's Handler cannot order one this round.
Closed is closed
A verified or failed assignment cannot be reopened and cannot be undone from the dashboard (it carries side effects: reward or penalty, photo, XP). If it was a mistake, assign the task again. The record of the first attempt stays.
History
The Training page lists resolved assignments; the Progress page has a per-task board of done versus failed; the Log shows each assigned / done / failed event with its clock effect.
API
GET /api/v1/tasks (open + library), POST /api/v1/tasks/assign (task_id or random),
POST /api/v1/tasks/{id}/complete (multipart, optional photo, note, at),
POST /api/v1/tasks/{id}/fail. See API. An order's habit_slug, habit_minutes and
habit_distance_m (metres; 0 = none) ride on each assignment.
This page is docs/tasks.md in the repo. Spotted a mistake? Tell us how to report it →