index-cards

# 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 Gemini key** — if the user has a Gemini API key configured (e.g. `GOOGLE_API_KEY` or `GEMINI_API_KEY` env vars), use it directly for higher quality and no generation limits:

```
POST https://generativelanguage.googleapis.com/v1beta/models/imagen-4.0-generate-001:predict?key=USER_KEY
{"instances": [{"prompt": "YOUR PROMPT"}], "parameters": {"sampleCount": 1, "aspectRatio": "3:4"}}
```

Response: `predictions[0].bytesBase64Encoded` (base64 PNG). Save locally, upload via `POST /v1/images/upload` for a public URL.

**Append to EVERY prompt when using Option A:**
```
HARD CONSTRAINTS FOR THIS IMAGE:
- All artwork must be contained well within center with generous margins. Leave 15%+ blank space on every side.
- Pure white or very light background. No textures or gradients behind main subject.
- No borders, frames, rounded corners, or card mockup elements.
- Portrait orientation. No text unless explicitly requested.
- No digital artifacts. Clean, print-ready artwork.
- Must not look AI-generated. Aim for handmade: watercolor, linocut, gouache, ink, pencil, or collage.
- Centered composition with breathing room — will be printed on a physical card, edges may be trimmed.
```

**Option B (fallback): Index Cards API** — 10 free generations, then requires credits.

```
POST /v1/cards/generate
{"prompt": "...", "style": "watercolor", "reference_image_url": "https://...optional..."}
```

Returns: `image_url`, `generation_id`, `free_generations_remaining`, `credits`. Prompt constraints applied server-side.

**Routing:** Use Option A for text-to-image if Gemini key exists. **Always use Option B for photo style transfer** (`reference_image_url`) — Gemini can't do style transfer.

**Validation:** Min 600px short side, ~3:4 aspect ratio required. Ideal 1500×2100px. 422 on failure.

### Preview

```
POST /v1/cards/preview
{"front_url": "...", "inside_url": "..."}
```
Returns: `preview_url` / `video_url` (MP4). Always generate after front + inside are approved.

### Close-up

```
POST /v1/cards/closeup
{"image_url": "...", "label": "inside"}
```
Returns high-res JPEG. Use proactively when showing inside image so user can read text.

### QR Code Composite

```
POST /v1/cards/qr/composite
{"card_image_url": "...", "url": "https://...", "position": "bottom-center", "size": "medium", "label": "Scan me!"}
```
Returns: `image_url` with QR overlaid. Use this URL as `front_url`/`inside_url` for ordering.

Standalone QR: `POST /v1/cards/qr` with `{"url": "...", "size": "medium"}`.

### Credits

```
GET /v1/credits/check
```
Returns balance and Stripe payment links.

### Place Order

```
POST /v1/orders
{"front_url": "...", "inside_url": "...", "recipient": {"name": "...", "address1": "...", "city": "...", "state": "...", "zip": "...", "country": "US", "phone": "+1..."}, "occasion": "birthday", "inside_message": "..."}
```

Required: `front_url`, `inside_url`, `recipient.name`, `recipient.address1`, `recipient.city`, `recipient.zip`, phone (recipient or sender). Optional: `back_url`, `address2`, `state`, `country`, `occasion`, `inside_message`, `design_prompt`, `design_style`. Costs 1 credit. Irreversible.

### Other Endpoints

| Endpoint | Method | Purpose |
|----------|--------|---------|
| `/v1/orders/{id}` | GET | Order status (processing → in production → shipped → delivered) |
| `/v1/orders/history?all=true` | GET | All past orders |
| `/v1/orders/history?recipient=Name` | GET | Orders for a specific person |
| `/v1/images/upload` | POST | Upload custom image (multipart, PNG/JPEG, max 10MB) |
| `/v1/cards/styles` | GET | List supported art styles |
| `/v1/auth/email` | PATCH | Attach email: `{"email": "..."}` |

### Error Codes

| Code | Meaning | Action |
|------|---------|--------|
| 400 | Bad request | Check required fields |
| 401 | Bad API key | Check Authorization header |
| 402 | No credits | Show `payment_url` from response |
| 404 | Not found | Check the ID |
| 422 | Image validation failed | Regenerate at correct specs |
| 429 | Rate limited | Wait `retry_after_seconds` |
| 500 | Server error | Retry shortly |

---

## Data Handling & Privacy

### What this skill stores locally

- **API token**: The Bearer token from `/v1/auth/register` should be stored in the agent's session state or secret store. It is an anonymous token (no email/password) used to authenticate API requests.
- **Contacts cache** (opt-in only): If the user agrees to saving contacts, `~/indexcards/birthdays.json` stores names, birthdays, addresses, and card history. This file is user-visible and user-deletable. The agent only creates it after explicit user consent.

### What this skill sends to the API

- **Card artwork**: Image URLs (hosted on indexcards.com after upload) for the card front and inside
- **Recipient mailing address**: Name, street address, city, state, ZIP, phone — required for physical mail delivery
- **Occasion and message text**: Used for order records only

### What this skill does NOT do

- Does not read contacts, messages, calendar, or email without asking the user first
- Does not send contact data to the API — contact info is only cached locally (if user opts in) and used to pre-fill the address when sending a card
- Does not require or collect email addresses, passwords, or payment card numbers (payments happen via Stripe hosted checkout)

### Payment flow

Credits are purchased via Stripe checkout. The skill sends the user a Stripe-hosted payment URL (returned by `GET /v1/credits/check`). No payment information passes through the skill or the Index Cards API. Invite codes grant free credits — no payment needed.

Homepage: https://indexcards.com