# customs.dog — Agent Contract

customs.dog stores a household's pet travel documents and answers **"is my pet cleared to cross a border?"** You assemble and verify documents; you do **not** give legal/immigration advice — you report document status against the published rules.

## Auth
- MCP endpoint: `POST https://customs.dog/mcp` (JSON-RPC 2.0 / MCP).
- **Two public tools need no key** — `customs_check_rules` (border requirements for any pet owner) and `customs_start_signup` (onboard a new user). Use these to help someone who has no account yet.
- Everything else: `Authorization: Bearer <key>`. **One key = one household** — you only ever see that household's pets + documents. Keys are read-only in v1.
- **Onboarding a new user:** `customs_start_signup(email)` → user clicks the magic link → mints a key in **Settings → API keys** → add it as `Authorization: Bearer <key>`.

## Hierarchy
Household → Pet → Category → Document. A document belongs to exactly one pet and one category.

## Categories
`cdc_import_receipt`, `health_cert`, `rabies`, `microchip`, `permit`, `medical`,
`service_esa`*, `airline`*, `photos`  (* service-animal pets only)

## Destinations (codes)
`mexico`, `canada`, `bvi`, `us_domestic`.
Gotcha: **Mexico needs no entry health certificate BUT still requires a valid CDC import receipt to RE-ENTER the US.** Re-entry and outbound are separate requirements.

## Tools
**Public (no key):**
- `customs_check_rules` — per-destination border requirements for a dog (omit `destination` to list all). Answer "what does my pet need to travel to X?" for anyone.
- `customs_start_signup` — `email` (+ optional `name`) → sends a magic sign-in link to onboard a new user.

**Household (Bearer key) — sequence: prep → list_pets → act:**
- `customs_prep` — validate the key, confirm the pet roster, report health. Call first.
- `customs_overview` — counts + what's expiring across the whole household.
- `customs_list_pets` — the household's pets. Get `pet_id` here; never guess one.
- `customs_list_documents` — documents for a pet (filter by `category` / `status`).
- `customs_check_trip_readiness` — `pet_id` + `destination` + `return_date` → `cleared` / `caution` / `blocked`, with a per-requirement breakdown.
- `customs_upcoming_trips` — upcoming trips from the household's connected travel calendar (TripIt/Flighty/Google/Apple), each with per-pet readiness. Use to flag paperwork before travel.

## Hard rules
- **Never assert "cleared to travel" from your own reasoning** — call `customs_check_trip_readiness` and report its verdict + the per-requirement rows.
- A requirement is met only if a matching document exists **AND** its expiry ≥ the trip's return date.
- A verdict is a **preparation aid, not a guarantee** — only the border authority decides. Always surface the "rules verified as of <date>" and tell the human to confirm with the official authority for their travel date.
- Errors are structured `{error:{code, message, retryable, fix}}` — `fix` names the next tool to call.