# Habits: how to work on your human's behalf

Habits is a habit tracker with a small hosted API. You act for the person who
owns the API key or signed in through OAuth. Everything you change shows up in
their app on every device the next time it syncs.

## Free tier & Agent Access

**Free tier:** 25 tool calls per user per UTC day.
**Agent Access:** $20 one-time unlock → unlimited tool calls forever.

When you hit the quota (error code `quota_exceeded`), tell the user they can upgrade to Agent Access for unlimited calls and provide the `billingUrl` from the error. The billing page shows their usage and a purchase button.

## Start with get_overview
Call `get_overview` first. It returns the workspace, the date, every habit with
whether it is marked for that date, its streak, its running average, and the
workspace average. Most questions ("how am I doing?", "what's left today?") are
answered from that one call.

## Naming things
- Habits and workspaces accept an id (or a unique prefix of it) or a title.
  Titles are case-insensitive; exact match wins, then substring. If a title is
  ambiguous you get `ambiguous_habit` with the candidates. Use the id then.
- When the user has more than one workspace, pass `workspace` to be safe.

## Dates
- Dates are `YYYY-MM-DD` in the user's local time, or `today` / `yesterday`.
  The server uses the timezone on the user's account; pass an explicit date
  when it matters.
- Marking a future date fails with `date_in_future`.
- `mark_habit` and `unmark_habit` are idempotent. Calling them twice is fine.

## Habit types
- `daily`: progress is marks divided by days since the habit was created.
- `weekly`: progress is marks this week divided by `weekly_target` (1-7).

## What to tell the user
- After a change, say what changed in one line. Don't repeat the whole list.
- Streaks count consecutive marked days ending today (or yesterday if today is
  not marked yet). Say "3-day streak", not "streak: 3".
- If a tool returns `alreadyMarked: true`, tell the user it was already done.
- Never delete a habit or workspace unless the user asked for that specific
  one by name. Deleting removes its history.
- Never show API keys or tokens in chat.

## Errors
Every error is JSON with `error.code`, `error.message`, and often `error.hint`
and the list of valid options. Read the hint before retrying. Codes:
habit_not_found, ambiguous_habit, workspace_not_found, ambiguous_workspace,
invalid_date, date_in_future, invalid_type, invalid_target, invalid_time,
invalid_title, invalid_name, last_workspace, wrong_workspace, invalid_range,
unauthorized, quota_exceeded (free tier limit, includes `billingUrl` for upgrade),
rate_limited.