---
name: yerevan-city
description: Order groceries from yerevan-city.am — search products, manage delivery addresses, build a cart. Use when the user asks to order groceries, buy food in Yerevan, add products to their yerevan-city cart, or mentions yerevan-city.am / City Supermarket.
allowed-tools: [Bash, Read]
---

# Yerevan City Grocery Skill

Build a grocery cart on [yerevan-city.am](https://yerevan-city.am) from conversation.

**Safe by design**: never places an order or pays — only builds the cart.
Checkout and payment always stay with the user, in their own browser or app.

## When to Use

- "Order milk and bread" / "добавь молоко в корзину"
- "What's in my yerevan-city cart?"
- "Find tomatoes on yerevan-city"
- Any grocery shopping request for Yerevan City / City Supermarket

## Setup

All commands run through one script (Python 3 stdlib only, no install needed):

```bash
SCRIPT="$CLAUDE_PROJECT_DIR/scripts/yerevan_city.py"   # or path where this skill is installed
python3 "$SCRIPT" --help
```

If the skill is installed under `~/.claude/skills/yerevan-city/`, use
`python3 ~/.claude/skills/yerevan-city/scripts/yerevan_city.py`.

## Login Flow (one-time)

Session persists in `~/.yerevan-city-skill/session.json`; an existing
`yerevan-city-mcp` session is reused automatically. Only log in when a
command fails with "No active yerevan-city.am session".

1. Ask the user for their Armenian phone number.
2. `python3 "$SCRIPT" login-request --phone +37441234567`
3. Ask the user for the SMS code they received.
4. `python3 "$SCRIPT" login-confirm --phone +37441234567 --code 1234`

Never guess the code. Never trigger login-request repeatedly — each call sends a real SMS.

## Commands

```bash
python3 "$SCRIPT" search --query "milk" [--page 1]        # free-text catalogue search
python3 "$SCRIPT" account                                  # profile: name, bonus card, default address
python3 "$SCRIPT" addresses                                # saved delivery addresses
python3 "$SCRIPT" address-add --city Yerevan --street Tumanyan --building 1 \
    --apartment 1 --floor 1 --lat 40.1811 --lng 44.5136    # create address (become session default)
python3 "$SCRIPT" address-update --id 45 ...               # same flags as address-add, plus --id
python3 "$SCRIPT" add --product-id 123 --count 2 --address-id 45     # piece-counted product
python3 "$SCRIPT" add --product-id 456 --grams 500 --address-id 45   # weight-based product
python3 "$SCRIPT" remove --product-id 123 --address-id 45
python3 "$SCRIPT" cart --address-id 45
python3 "$SCRIPT" logout
```

## Rules to Follow

1. **Address first.** The cart is scoped to a delivery address. Login stores the
   account's default address in the session automatically; run `addresses` to
   check. If the list is empty, ask the user for their address (city, street,
   building, apartment, floor) and create it with `address-add` — geocode
   lat/lng first (e.g. Nominatim: `https://nominatim.openstreetmap.org/search?q=<street>+<building>,+Yerevan&format=json`).
   Pass the address `id` as `--address-id` to add/remove/cart calls (or rely
   on the session default).
2. **Count vs grams.** Products with `isKilogram: false` are added with
   `--count` (pieces). Products with `isKilogram: true` are added with
   `--grams`; respect `minimumWeight` and `weightStep` from search results
   (both in grams) — fresh meat is typically 1000g minimum, loose produce
   300–800g. If the user asks for less than the minimum, tell them the
   forced minimum and get their OK before adding.
3. **Check `isMissing` after every add.** The API accepts adds for
   out-of-stock products and only reports it via `isMissing` on the returned
   `addedItem`. If `isMissing` is true, the product will NOT be delivered:
   immediately `remove` it, tell the user it's unavailable (mention
   `availableCount`/`availableWeight` if partial stock exists), and suggest an
   alternative from search results if there's an obvious one. Never leave an
   out-of-stock item in the cart silently.
4. **Always report totals.** After adding items or showing the cart, state
   `totalPrice` and `deliveryFee` together as the full amount to pay (prices
   are in Armenian drams, AMD).
5. **Before declaring the cart ready**, run `cart` and clean up any item with
   `isMissing: true` via `remove`.
6. **Never place an order.** The script cannot check out, and you must not try
   to via the website. Tell the user to finish checkout in their own
   browser or app.

## Example Session

```
User: order 2 bottles of milk and half a kilo of cheese

1. python3 "$SCRIPT" addresses                 → default address id 45
2. python3 "$SCRIPT" search --query "milk"     → pick product, isKilogram false
3. python3 "$SCRIPT" add --product-id 111 --count 2 --address-id 45
   → check addedItem.isMissing, note totalPrice
4. python3 "$SCRIPT" search --query "cheese"   → pick product, isKilogram true
5. python3 "$SCRIPT" add --product-id 222 --grams 500 --address-id 45
6. python3 "$SCRIPT" cart --address-id 45      → verify, report total + delivery fee
```

## Notes

- Product names come in three languages (`nameEn`, `nameRu`, `nameArm`) — match
  against whichever language the user used. English queries sometimes miss items
  that Russian ones find (e.g. "стейк", "чеснок", "вырезка") — retry in another
  language before concluding a product doesn't exist.
- The shop API misspells two address fields: `buliding` and `appartment`. The
  script's `--building`/`--apartment` flags map to them — don't "fix" the
  spelling in the API payloads.
- The user's bonus card lives on the account profile (`account` command,
  `bonusCardNumber`) and applies at checkout automatically — no cart action
  needed.
- Unofficial, educational project; not affiliated with Yerevan City / City
  Supermarket. Non-commercial license — see LICENSE.