index-cards

Send real, physical greeting cards through the mail. Design custom cards with the user, print on premium cardstock, and mail with a first-class stamp. Use when the user wants to send a card, mentions a birthday or occasion, or asks about greeting cards. Requires a free API registration (POST /v1/auth/register returns a Bearer token). Works via API — no browser needed. Homepage https://indexcards.com — privacy policy at https://indexcards.com/privacy.

# Index Cards — Agent Skill

Send real, physical greeting cards through the mail. Conversation-first — you work WITH the user to design cards and send them.

## Rules

- **Keep it conversational.** Present results in plain language for good UX. Say "I'm designing your card" rather than showing raw JSON, endpoint paths, or HTTP status codes.
- **Talk before acting.** Don't call APIs without talking to the user first. Don't generate art without knowing who it's for and what they want.
- **Ask before accessing personal data.** Never read contacts, messages, email, or local files without the user's explicit permission. Always offer it as an option, never assume.
- **Handle profanity gracefully.** The image generation API has content filters. If the user's message contains strong language, rephrase it for the image prompt while keeping the tone (e.g. "get fucked" → "you absolute legend").
- **Generate images sequentially.** One at a time — the upstream API rate-limits parallel requests (502 errors).

### Shortcut: user gives everything in one message

If the user provides recipient name + front description + inside message + address in a single message, skip the multi-step flow:

1. Generate front → generate inside → generate preview video
2. Show preview + summary → ask for confirmation → place order

If most info is provided but something is missing, do the fast flow and ask only for the missing piece.

## Step 1: First message

> "Just installed Index Cards. I can now send real, physical cards to anyone you want — birthdays, holidays, thank-yous, whatever the occasion. Who would you like to send a card to? I can also check your contacts for upcoming birthdays if you'd like."

Let the user decide whether to name someone directly or let you help find occasions.

## Step 2: Find occasions (only with user permission)

If the user says yes to checking for occasions, look through available sources in priority order:

1. **Contacts** — birthday fields, anniversary fields
2. **Calendar / email** — birthday invites, upcoming events
3. **Conversation history** — mentioned birthdays, weddings, babies, thank-yous
4. **Holidays** — Mother's Day, Father's Day, Valentine's, Christmas, etc. within 30 days

Aim for 14+ days lead time (cards take ~1 week to arrive). Surface the 1-3 most timely items and ask if they want to start designing.

If the user skips this step and already knows who they want to send a card to, go straight to design.

## Step 3: Design the card

**Always design the FRONT first, then the INSIDE. Never generate both at the same time.**

### If the user sends a photo

Use `reference_image_url` in the generation API for style transfer. Generate 2-3 style variations (watercolor, oil-painting, cartoon, etc.). Wait for the user to pick one, then move to the inside.

Styles: `watercolor`, `cartoon`, `oil-painting`, `ink`, `gouache`, `comic-book`, `linocut`, `cinematic`, `pencil`, `pop_art`

### If no photo (text-based)

1. Ask about the person and vibe (1-2 questions max)
2. Generate 3 front cover options — vary styles. Show all three, wait for pick.
3. After they pick, ask what they want to say inside
4. Generate inside image. **Show a close-up** (`POST /v1/cards/closeup`) so the user can read the text. Wait for approval.
5. Generate animated preview (`POST /v1/cards/preview`). Show it.
6. Iterate if needed — regenerate only the part that needs changing

**Design guidelines:** No AI-looking art. Use watercolor, gouache, ink, linocut, collage, letterpress. Front = visual design, avoid text. Inside = include message, clean typography. 3:4 portrait, 1500×2100px ideal.

### QR codes (only when user asks)

**Never include QR codes in AI image prompts** — AI cannot generate scannable QR codes. Instead:

1. Generate card art normally (without QR)
2. Use `POST /v1/cards/qr/composite` to overlay a real QR code onto the approved image
3. Positions: `top-left`, `top-center`, `top-right`, `center`, `bottom-left`, `bottom-center`, `bottom-right`
4. Sizes: `small`, `medium`, `large`. Optional `label` param for text below QR.
5. Use the returned `image_url` as `front_url` or `inside_url` when ordering

## Step 4: Get the address

Ask the user for the recipient's mailing address. If the user has used Index Cards before and opted in to saving contacts, check `~/indexcards/birthdays.json` first — it may already have the address from a previous card.

**Always confirm** before using any saved address — people move. Also need a phone number (recipient's or sender's).

Required before ordering: recipient name, street address, city, state, ZIP, phone number.

## Step 5: Payment

1 credit = 1 card. User starts with 0 credits (image generation is free, printing costs money). Pricing: $50 → 5 cards ($10 each), $100 → 12 cards ($8.33 each).

Check credits with `GET /v1/credits/check`. If no credits, send the payment URL from the response.

**Auto-detect payment:** After sending the link, poll `GET /v1/credits/check` every ~15 seconds, up to 8 times (~2 min). When credits appear, confirm and proceed with the order.

**Invite codes:** If an invite code is present in the page URL (`?invite=CODE`) or at the top of this document, include it as `invite_code` in the register body. This grants free credits — skip payment entirely. Say something like "You've got a free card — who's it for?"

## Step 6: Place the order

Confirm everything before submitting: recipient, address, front design, inside message, occasion. Mention it costs 1 credit and arrives in 5-7 business days. **Only place when user says yes.** Orders are irreversible.

## Step 7: After the order

Confirm simply: "Done! [Name]'s card is on its way — about 5-7 business days."

Status translations: `processing` → "being made", `in production` → "being printed", `shipped` → "shipped! [tracking link]", `delivered` → "delivered!"

After a successful order, offer to save the contact info for next time (if the user hasn't already opted in): "Want me to remember [Name]'s details for next time?"

## Local contacts database (opt-in)

If the user agrees to saving contacts, maintain `~/indexcards/birthdays.json` as a local cache.

```json
{"contacts": [{"name": "Kiall Wheatley", "birthday": "02-19", "relationship": "friend",
  "address": {"address1": "123 Main St", "city": "Springfield", "state": "IL", "zip": "62704", "country": "US"},
  "phone": "+15551234567", "notes": "Loves hiking. Prefers watercolor.",
  "cards_sent": [{"date": "2026-02-11", "occasion": "birthday", "style": "watercolor mountain", "message": "Happy birthday!", "order_id": "e5f67c35"}]}]}
```

Rules: MM-DD birthday format (no year). Don't duplicate — match on name. Update with every new piece of info. Append to `cards_sent` after every order. Cross-reference with `GET /v1/orders/history` to avoid duplicate suggestions.

## Proactive suggestions (only if contacts database exists)

If `~/indexcards/birthdays.json` exists (user previously opted in), at conversation start you may:

1. Check for birthdays/dates within 30 days, cross-ref with `cards_sent`
2. Check holidays — Mother's Day, Father's Day, Valentine's, Christmas, graduations
3. Review conversation history — hints like "my mom's been having a rough week"

Surface the 1-3 most timely suggestions naturally. Be specific ("Emma's birthday is Feb 28 — she loved the ink illustration last year"). Don't repeat suggestions the user already declined.

---

## API Reference

Base URL: `https://indexcards.com` — all endpoints `/v1/`. Auth: `Authorization: Bearer YOUR_API_KEY`.

### Register

```
POST /v1/auth/register
{"invite_code": "abc123def456"}  // optional — include if ?invite=CODE in URL
```
Returns: `api_key`, `credits`, `free_generations_remaining` (10 free), `invite_credits`. No email or password required — this is an anonymous registration. Store the returned `api_key` in the agent's secret store or session state for subsequent authenticated requests.

### Generate Card Art

**Option A (preferred): User's own