SKILL.md

---
name: sangria-shopping
description: Buy real products with Sangria's prepaid credits. Use when the user wants to buy, order, or find a physical product ("buy me X", "order Y", "find Z under $30", or an Amazon product link), or asks about their Sangria balance or order status. Do not use for account setup, adding credits, payment methods, or shipping details — those happen on Sangria's dashboard, not in chat.
---

# Shopping with Sangria

Sangria buys real products on the user's behalf using their prepaid USD
credit balance. Every purchase is quoted first and nothing is bought until
the user approves a specific product at a specific price.

## Workflow

1. **Quote first.** Call `discover` to mint a short-lived, price-locked quote:
   - The user described what they want → pass `intent` (a short product
     description) and `reasoning` (why it fits their need). Add
     `min_price_usd`/`max_price_usd` when they gave a budget.
   - The user pasted an Amazon product link → pass `url` instead.
   - Never pass both. If the request is too vague to search well
     ("get me a gift"), ask one or two clarifying questions first.
2. **Present the matches.** Show name, price (convert `price_microunits` to
   dollars: 1 USD = 1,000,000 microunits), rating, and product link. Let the
   user pick. Prices are locked only until the quote's `expires_at`.
3. **Get explicit approval.** Never call `buy` until the user has approved a
   specific match at its quoted price in this conversation. "Find me X" is
   not approval to buy X.
4. **Buy.** Call `buy` with the quote's `discovery_id` and the approved
   match's `sku`. Report the returned `status`:
   - `confirmed` — order placed; share the order id.
   - `running` — checkout is in progress; the user can check later with `orders`.
   - `failed` — explain `failure_code`/`failure_message` and the next step.
5. **Follow up.** Use `balance` for remaining credit and `orders` for order
   history and statuses (paginate with `next_cursor` when `has_more` is true).

## Boundaries

- **Never collect sensitive data in chat** — no payment cards, authorization
  codes, credentials, government IDs, health data, phone numbers, or shipping
  addresses. Purchases ship to the address already saved in the user's
  Sangria dashboard.
- **Setup lives on the dashboard.** Adding credits, payment methods, shipping
  address, or phone all happen at https://getsangria.com/client/settings —
  send the user there instead of asking for details.
- **Restricted categories are not purchasable** (tobacco, weapons, drugs,
  gambling, adult, counterfeit). Decline these without calling tools.
- Spending is bounded by the user's prepaid balance and their spend caps;
  `buy` is idempotent per (discovery_id, sku), so retrying a timed-out buy
  with the same pair is safe and cannot double-charge.

## On error

| Error | What to do |
| --- | --- |
| `profile_setup_required` | Ask the user to finish delivery/contact setup at https://getsangria.com/client/settings, then retry. |
| `dashboard_action_required` | Ask the user to add credits or a payment method at https://getsangria.com/client/settings, then retry. |
| `restricted_data` | Remove the flagged sensitive detail from the request and retry with product terms only. |
| `prohibited_goods` | Tell the user this category isn't supported; offer a different product. |
| Expired or unknown `discovery_id` on `buy` | Quotes are short-lived — call `discover` again, reconfirm the price with the user, then buy with the fresh quote. |
| `unauthorized` / `authenticated: false` | Ask the user to reconnect the Sangria connector and approve access. |