# Todoist

The Todoist integration turns labeled Todoist tasks into real, money-staked
TaskRatchet commitments. A Todoist task that has **both** a trigger label
(default `ratchet`) **and** a due date becomes a TaskRatchet task, staked at the
default amount you configure. Todoist stays the place you work; TaskRatchet adds
the deadline and the stake.

The sync is **one-way** (Todoist → TaskRatchet) and runs every few minutes.

## Enable the Todoist integration

1. Navigate to your settings page and find the Todoist section.
2. Click the connect button. You'll be redirected to Todoist to grant
   TaskRatchet read access to your tasks.
3. After you approve, you'll be returned to your settings page, now showing
   **"Your Todoist account is connected."**
4. Set two things and click **Save**:
   - **Trigger label** — the label that opts a task in (default `ratchet`; you
     can enter it with or without the leading `@`).
   - **Default stake (\$)** — the amount staked on each imported commitment (at
     least \$1.00).

To stop syncing, click **Disconnect Todoist**. This clears your Todoist
credentials from TaskRatchet; your Todoist account itself is unaffected, and you
can reconnect at any time.

## Stake a Todoist task

Give a Todoist task **both** the trigger label **and** a due date. On the next
sync it's imported as a TaskRatchet commitment staked at your default amount:

- A **date-only** due (e.g. "today") becomes **end of day** in your Todoist
  account's timezone.
- A **timed** due is taken at that clock time in your Todoist timezone (or the
  due's own timezone, if you set one) — unless it already carries an explicit
  UTC offset, in which case that exact instant is used.

(Your **Todoist** timezone is read fresh on each sync and is what converts a due
date into a TaskRatchet deadline — both when a task is first staked and when a
later edit pulls its due earlier.)

You'll also receive emails from TaskRatchet about the integration: an immediate
notice if labeled tasks **can't** be staked (no saved card, no default stake, or
you've hit your monthly stake limit) or if the connection needs reauthorizing,
plus a **daily digest** of what was staked.

## Important: how Todoist commitments behave

These rules are what make the integration safe to trust with money — read them
before you stake anything.

- **Both the label and a due date are required.** A labeled task with no due
  date is not staked; neither is a dated task without the label.
- **Give yourself lead time.** Because syncing runs on a roughly 5-minute cycle,
  set deadlines at least **10–15 minutes out**. A task due sooner than that may
  not be staked in time.
- **Once staked, a commitment is firm.** Removing the label or even deleting the
  task in Todoist does **not** cancel it. The only ways it resolves are an
  on-time completion or the charge.
- **TaskRatchet owns the deadline once staked.** Moving the Todoist due date
  **earlier** pulls your TaskRatchet deadline in to match. Moving it **later**
  (or removing it) does **not** extend your deadline — so the Todoist and
  TaskRatchet due dates can diverge.
- **Late completion does not prevent the charge.** Deadlines are firm: a task
  completed after its deadline still charges.
- **Completion is one-way and terminal.** Completing the task in Todoist on time
  marks the TaskRatchet commitment complete. **Reopening** it in Todoist is
  ignored — to un-complete a commitment, do it in TaskRatchet.
- **A stake needs a card and limit headroom.** Imported commitments use your
  configured default stake and require a saved payment method plus room under
  your monthly stake limit. Without those, the task is skipped (and you're
  emailed) rather than staked. Once you fix the blocker — add a card, set a
  default stake, or free up limit headroom (including at the start of a new
  month) — the task is imported automatically within a few hours; you don't
  need to re-touch it in Todoist.
- **Recurring tasks aren't supported yet.** Recurring Todoist tasks are skipped.
- **Disconnecting stops syncing but doesn't cancel live commitments.** Any
  commitments already staked stay active — complete them in TaskRatchet.