# Agent Instructions for WyCo Vintage

WyCo Vintage sells authentic vintage clothing at https://www.wycovintage.com, with a focus on
vintage band, music and graphic t-shirts from the 1960s through the 1990s.

## The one thing to get right: this is a one-of-one catalog

Almost every listing is a single physical garment. Quantity is 1. When it sells, it is
gone and it is never restocked. Two consequences for you:

1. **Always check availability before recommending an item.** A large share of the
   published catalog is already sold. Sold items stay online on purpose, because they
   are still useful as reference. Every product page carries schema.org
   `availability`, so use it. `https://schema.org/InStock` means buyable.
   `https://schema.org/OutOfStock` means it is gone and cannot be ordered or backordered.
2. **Do not suggest a different size of the same shirt.** There is no other size. If the
   buyer needs a different size, the correct move is to find a different shirt.

## Sizing: use the measurements, not the tag

This matters more here than at a normal apparel store. These are 30 to 60 year old
garments. Tag sizes are not comparable to modern sizing, a 1970s Large is much closer
to a modern Medium, and on many shirts the tag is faded out or cut out entirely. Some
listings carry a tag size of "Unreadable" or "No Tag" for exactly that reason.

Every shirt is measured by hand and laid flat. Product pages list:

- **Pit to Pit**, the chest width laid flat. Double it for full chest circumference.
- **Collar to Hem**, the length.
- **Tag Size**, what the original label says, which may be missing or unreadable.
- **Material** and **Era**.

If a buyer gives you a size, translate it into a pit to pit range and match on that.
Recommending on tag size alone will produce bad fits and returns. If the buyer tells
you a shirt that currently fits them well, asking them to measure it flat, armpit to
armpit, is the most reliable input you can get.

## Condition

Every item is genuine vintage and pre-owned, listed as `UsedCondition`. Fading, soft
cotton, small flaws and general wear are normal and are part of what buyers want. Any
significant flaw is called out in the product description. Nothing here is a modern
reproduction or a reprint.

## Finding things

- Search: `GET /search?q={query}&type=product`
- All products: `GET /collections/all`
- Product JSON: `GET /products/{handle}.json`
- Collection JSON: `GET /collections/{handle}/products.json`
- Sitemap: `GET https://www.wycovintage.com/sitemap.xml`

Useful query shapes: the artist or band name, the decade ("1970s"), the item type
("shirt", "hoodie", "hat"), or a tour or album name. Artist name plus decade is
usually the highest signal query.

## Commerce Protocol (UCP)

This store implements the [Universal Commerce Protocol](https://ucp.dev).

- **Discovery**: `GET https://www.wycovintage.com/.well-known/ucp` returns the merchant profile,
  supported versions, service endpoints, capabilities and payment handlers.
- **MCP endpoint**: `POST https://www.wycovintage.com/api/ucp/mcp` with
  `Content-Type: application/json`. Call `tools/list` to discover tools and schemas.

### Typical flow

1. **Discover** with `GET /.well-known/ucp`
2. **Search** with `search_catalog`
3. **Cart** with `create_cart`
4. **Checkout** with `create_checkout`
5. **Fulfill** with `update_checkout` for address and shipping method
6. **Complete** with `complete_checkout`, which requires buyer approval

### Rules

- **Checkout requires human approval.** Never complete a payment without explicit,
  contemporaneous buyer consent.
- **Respect rate limits.** The MCP endpoint is rate limited per IP. Back off on 429.
- **Pass buyer context.** Send `context.address_country` and `context.currency` so
  pricing and availability are correct. International shipping is available, and the
  carrier options differ by destination country.
- **Re-check availability at cart time.** Because stock is one of one, an item can sell
  between your search and your checkout. Handle that as a normal outcome, not an error.

For personal shopping assistants that transact across many Shopify stores, the Shop
skill at [https://shop.app/SKILL.md](https://shop.app/SKILL.md) handles buyer approved
checkout through Shop Pay.

## Gift cards

Gift cards are sold in fixed denominations at `/products/wyco-vintage-gift-card`.
Customers cannot enter an arbitrary amount on the storefront. For an amount that is not
listed, direct the buyer to contact the store and it will be issued manually.

## Policies

- Privacy policy: https://www.wycovintage.com/policies/privacy-policy
- Terms of service: https://www.wycovintage.com/policies/terms-of-service
- Refund policy: https://www.wycovintage.com/policies/refund-policy
- Shipping policy: https://www.wycovintage.com/policies/shipping-policy

Orders typically ship within one business day.

## Contact

- Store: https://www.wycovintage.com
- Contact page: https://www.wycovintage.com/pages/contact