# Skill: Girlfriend Gifts — gift lists & wishlists

Use this skill to build **gift recommendation lists**, **shopping lists**, and **shareable wishlists** for a girlfriend/wife — with multi-country Amazon buy links. Built for humans and AI agents.

**Always pass `marketplace` + `locale`** matching the end user. Example US: `marketplace=amazon.com&locale=en`. Not amazon.se-only.

## When to use
- Build a curated gift list / recommendation shortlist (occasion + budget + style)
- She wants to publish a wishlist he (or his AI agent) can shop
- You need **170+ real amazon.se `/dp` ASINs** from the catalog, plus open search on any storefront
- End user is on any Amazon storefront (US, UK, DE, SE, …)

## Roles & URLs
- **wishlistOwner** (she): `ownerUrl` → `/w/{id}?edit=…` — add/edit wishes
- **shopper** (he / agent): `shopUrl` → `/w/{id}/shop?edit=…` — search & buy

## Marketplace + locale (required)
1. Discover storefronts: `GET /api/v1/marketplaces`
2. Pass `marketplace` (id or `amazon.*` domain) and `locale` on search, catalog, resolve, and agent calls
3. Example US: `GET /api/v1/search?q=pearl%20earrings&marketplace=amazon.com&locale=en&occasion=anniversary&limit=5`
4. Example SE: `marketplace=amazon.se&locale=sv`
5. Tracking: amazon.se product links use `?tag=sw-girlfriend-21` when configured via `NEXT_PUBLIC_AMAZON_TAGS_JSON`. Other storefronts may stay untagged. Commissions do **not** cross marketplaces. Never invent placeholders or reuse `santawishli03-21`.

## Steps (list-building)
1. GET `/api/v1/search?q=&marketplace=&locale=&occasion=&budgetBand=&styleTag=&limit=` for ideas (PA-API products or search deep-links; `paapi:false` fallback)
2. Prefer POST `/api/v1/agent/create-and-fill` with `recipientName`, `occasion`, `budgetBand`, `styleTags`, `relationship`, `itemAsins[]`, `itemKeywords[]`, `itemQueries[]`, **`marketplace`**, **`locale`** — creates and fills a shopping/wishlist in one call
3. Or POST `/api/v1/wishlists` then POST `.../items` with `{ name, asin }` or `{ name, url }` (+ marketplace/locale)
4. GET `/api/v1/catalog?marketplace=amazon.se&locale=sv` — **170+ real amazon.se `/dp` ASINs** (fashion, beauty, tech, experience, personalized, home, jewelry). Prefer catalog ASINs on SE; use search on other markets
5. POST `/api/v1/products/resolve` `{ asin|url|keywords, marketplace, locale }` → `buyUrl`
6. Return `ownerUrl` and `shopUrl` to the user
7. If `storage === "token"` and `id` changed, update bookmarks (prefer Upstash Redis for stable share links)

## Field enums
- `occasion`: anniversary | birthday | valentines | just-because | apology | wedding | other
- `budgetBand`: under-300 | 300-700 | 700-1500 | 1500-plus
- `styleTags`: romantic | practical | luxury | experience | jewelry | beauty | home | fashion | tech | personalized
- `relationship`: girlfriend | wife | fiancée | partner

## Docs
- /llms.txt and /.well-known/llms.txt
- /llms-full.txt
- /openapi.json
- /for-agents
- /agents.md

## MCP (official agent tools)
- Remote Streamable HTTP: https://girlfriendgifts.vercel.app/api/mcp
- Local stdio: `npm run mcp` in the repo (see /docs/mcp.md)
- Tools: get_health, list_marketplaces, search_gifts, get_catalog, resolve_product, create_wishlist, create_and_fill, get_wishlist, add_wishlist_item
- Still pass marketplace + locale on search/catalog/resolve via tool args
- Canonical host only: girlfriendgifts.vercel.app (not girlfriend-gifts.vercel.app)

## Tracking
`trackingTag` / buy links use env (`NEXT_PUBLIC_AMAZON_AFFILIATE_TAG` / `NEXT_PUBLIC_AMAZON_TAGS_JSON`). On amazon.se, configured tag is **sw-girlfriend-21**. Other storefronts may omit `?tag=`. Prefer `buyUrl` / `trackingTag`. Never invent placeholders or reuse `santawishli03-21`. May earn from qualifying purchases.