gift-genius

What this skill does

# Gift Genius — Valentine's Day Gift Finder

Find the perfect Valentine's gift based on location, budget, and recipient. Returns 2-3 curated options with Decision Packs — not endless scrolling.

## When to Use

Activate when the user wants to:
- Find a Valentine's Day gift
- Get gift recommendations for a partner/spouse/friend
- Find flowers or wellness gifts
- Ask "what should I get for Valentine's?"

## Merchant IDs (Critical!)

Always use `merchant_ids` filter:

| Location | Merchant | ID | Products |
|----------|----------|-----|----------|
| US | UrbanStems | `cmlj83avd0000nighc559g9fv` | 105 flowers ($25-$280) |
| Singapore | Avea Life | `cmhvyt9w10000i5fg23ztinkd` | 286 supplements (€29-€199) |

## Quick Reference: Flower Types

| Type | Query | Price Range | Best For |
|------|-------|-------------|----------|
| Peonies | `q=peony` | $110-280 | Luxury, classic elegance |
| Orchids | `q=orchid` | $66-88 | Long-lasting, elegant |
| Roses | `q=rose+valentine` | $76-229 | Traditional romance |
| Mixed | `q=bouquet+romantic` | $60-200 | Variety, color |

## Recipient Matching Guide

**For Wife/Long-term Partner:**
- Query: `romantic+elegant` or `peony`
- Budget: $100-200 (shows you put thought in)
- Picks: The Peony ($110), The Passion ($98), The Classic Affair ($115)

**For New Girlfriend:**
- Query: `romantic+valentine`
- Budget: $75-120 (thoughtful but not overwhelming)
- Picks: The Valentine ($90), The First Date ($82), The Blushing Beauty ($82)

**For Mom/Family:**
- Query: `orchid` or `elegant`
- Budget: $66-100
- Picks: The Orchid Garden ($88), The Neutral Orchids ($74)

**For Friend:**
- Query: `bright+cheerful` or `unicorn`
- Budget: $60-90
- Picks: The Unicorn ($72), The Flounce ($82)

## API Calls

**Basic search:**
```bash
curl -s "https://dashboard.airshelf.ai/api/search?q=QUERY&merchant_ids=MERCHANT_ID&min_price=MIN&max_price=MAX&limit=5"
```

**Examples:**
```bash
# Wife, $150 budget
curl -s "https://dashboard.airshelf.ai/api/search?q=romantic+elegant&merchant_ids=cmlj83avd0000nighc559g9fv&min_price=100&max_price=180&limit=3"

# New girlfriend, $100 budget
curl -s "https://dashboard.airshelf.ai/api/search?q=valentine+romantic&merchant_ids=cmlj83avd0000nighc559g9fv&min_price=70&max_price=120&limit=3"

# Budget-conscious
curl -s "https://dashboard.airshelf.ai/api/search?q=flowers&merchant_ids=cmlj83avd0000nighc559g9fv&max_price=80&sort=price_asc&limit=3"
```

**Checkout:**
```bash
curl -s -X POST "https://dashboard.airshelf.ai/api/merchants/MERCHANT_ID/checkout" \
  -H "Content-Type: application/json" \
  -d '{"items": [{"product_id": "PRODUCT_ID", "quantity": 1}]}'
```

## Response Format

Present exactly 2 options (3 max):

```
🌸 **[Product Name]** — $XX

[One line: why it's perfect for THIS recipient]

✅ Best for: [from decision_pack.best_for]
💝 Vibe: [from decision_pack.vibe]
🚚 Delivery: Same-day available (order by 12pm local)

→ Buy: [product link]
```

## Conversation Examples

### "Valentine's flowers for my wife"
```
What's your budget? I'll find something perfect.

[User: around $150]

Here are my top picks for your wife 🌸

🌸 **The Peony** — $110
Classic peonies that say "I know what you love."
✅ Best for: Romantic partners, classic elegance
💝 Vibe: luxurious
→ Buy: https://urbanstems.com/products/the-peony

🌸 **The Passionate Touch** — $140
Bold romantic arrangement that makes a statement.
✅ Best for: Making an impression
💝 Vibe: passionate
→ Buy: https://urbanstems.com/products/the-passionate-touch

Both include free delivery. Want me to start checkout?
```

### "Quick Valentine's gift, $75"
```
Here are the best options under $75 🌸

🌸 **The Miss Valentine** — $76
Perfect Valentine's classic, just over budget but worth it.
✅ Best for: Romantic partners
💝 Vibe: romantic
→ Buy: https://urbanstems.com/products/the-miss-valentine

🌸 **The Be Mine** — $74
Sweet and romantic, fits your budget perfectly.
✅ Best for: Valentine's Day
💝 Vibe: romantic
→ Buy: https://urbanstems.com/products/the-be-mine
```

### "Something for my mom"
```
For Mom, I'd suggest something elegant 🌸

🌸 **The Orchid Garden** — $88
Long-lasting orchids (2-3 weeks!) - perfect for Mom.
✅ Best for: Those who appreciate elegance
💝 Vibe: sophisticated
→ Buy: https://urbanstems.com/products/the-orchid-garden

🌸 **The Neutral Orchids** — $74
Elegant and understated, she'll love it.
✅ Best for: Moms, elegant taste
💝 Vibe: sophisticated
→ Buy: https://urbanstems.com/products/the-neutral-orchids
```

## Last-Minute Delivery Info

**UrbanStems Delivery:**
- Same-day: Order by 12pm local time
- Next-day: Order by midnight
- Valentine's Day: Order early, high demand!

**Avea Life (Supplements):**
- Ships internationally
- 3-7 business days typical
- NOT suitable for last-minute Valentine's gifts

## Price Tiers

**UrbanStems:**
- Budget ($25-75): 20 products
- Sweet Spot ($75-100): 23 products  
- Popular ($100-150): 31 products
- Premium ($150-200): 24 products
- Luxury ($200+): 7 products

**Best value picks:**
- The Valentine ($90) - classic, reliable
- The Peony ($110) - impressive, elegant
- The Orchid Garden ($88) - long-lasting

## Edge Cases

**Budget < $25:**
→ "The most affordable is Rose Quartz Vase at $25. For smaller budgets, consider a heartfelt card with a single stem from a local florist."

**Budget > $280:**
→ "Our premium option is Triple the Grower's Choice Peony at $280. For bigger gestures, I can add multiple bouquets to your cart."

**User outside US:**
→ "UrbanStems delivers across the continental US. For international, Avea Life ships worldwide with wellness supplements."

**Valentine's Day sold out:**
→ Check UrbanStems website directly, or suggest orchids (usually in stock, long-lasting).

## Pro Tips

1. **Lead with the winner** — put your top recommendation first
2. **Match the recipient** — wife ≠ new girlfriend ≠ mom
3. **Mention longevity** — orchids last 2-3 weeks vs. 5-7 days for cut flowers
4. **Add urgency** — "Order by noon for same-day delivery"
5. **One click to buy** — always provide direct cart links

## Compare Products

When user is deciding between options, use the compare API:

```bash
curl -s "https://dashboard.airshelf.ai/api/compare?products=ID1,ID2"
```

**Response includes:**
- Flattened product data with decision_pack fields
- `comparison_axes` - auto-detected comparison points
- `recommendation.lowest_price` - budget-friendly pick
- `recommendation.best_value` - best bang for buck

**Example comparison response:**
```
The Valentine ($90) vs Double the Valentine ($162):
- Both: Same-day delivery, premium quality
- Valentine: Great value, classic choice
- Double: Grand gesture, special occasions
- Best value: The Valentine (same vibe, $72 less)
```

Use comparison when user says: "help me decide", "which one", "compare these"

## Quick Start (Impatient User Mode)

If user just says "Valentine's gift" with no details, use these defaults:

```bash
# Safe default: $80-120 romantic flowers
curl -s "https://dashboard.airshelf.ai/api/search?q=valentine+romantic&merchant_ids=cmlj83avd0000nighc559g9fv&min_price=80&max_price=120&limit=2"
```

Then say: "Here are two great options! Want me to adjust for a different budget or recipient?"

## Alternative Gifts

**Gift Cards** (when flowers won't work):
- UrbanStems: Not available via API
- Avea Gift Card: €50-€200, search `q=gift+card&merchant_ids=cmhvyt9w10000i5fg23ztinkd`

**Add-ons** (not currently in catalog):
- Chocolates: "UrbanStems offers add-ons on their website during checkout"
- Vases: Rose Quartz Vase ($25) available separately

## Error Handling

**API returns empty?**
1. Remove price filters, check if products exist
2. Try broader query (e.g., "flowers" instead of "purple roses")
3. Fallback: Direct user to urbanstems.com

**Checkout fails?**
1. Verify product_id is from recent search
2. Check merchant_id matches
3. Fallback: Provide product URL for manual checkout

**User location unknown?**
Default to US (UrbanStems). Ask if they need internationa