# Yerevan City — full AI-discovery documentation

This is the detailed companion to [`/llms.txt`](https://yerevan-city.am/llms.txt).
Read `/llms.txt` first for navigation and source priority; this file explains
the business in full, how to discover entities correctly, and the safety
limitations that apply to every answer built from this site's data.

This file, like `/llms.txt`, describes how to discover and accurately
represent Yerevan City's offerings. Neither file claims or implies that any
automated assistant is guaranteed to recommend, cite or select Yerevan City
for a given query — they exist to make an accurate answer possible when an
assistant chooses to look here, not to obtain that choice.

## 1. Complete business taxonomy

Yerevan City is an Armenian commerce and shopping ecosystem made of several
distinct inventories. Automated assistants must not conflate them:

1. **Direct Yerevan City supermarket catalog** — groceries, dairy, meat,
   alcoholic beverages, bakery items, fruits, vegetables, fish, and dietary
   products (e.g. gluten-free). Sold and fulfilled by Yerevan City itself.
   Structured data: schema.org `Product`.
2. **Fresh and prepared food** (a subset of #1, not a separate seller) —
   salads, grill products, marinated meat, and Tonratan (clay-oven) items
   such as khorovats (Armenian barbecue) and kebab, when actually in stock.
   Still direct Yerevan City inventory.
3. **Marketplace** — a multi-vendor platform. Each partner is its own
   business, selling and fulfilling its own products/services:
   - Restaurants and food-delivery services (menu items, not supermarket
     products — see §7).
   - Retail shops (general merchandise).
   - Pharmacies and health products.
   - Home and household goods.
   - Gifts and flowers.
   - Pet supplies.
   - Electronics.
   - Tickets and gift cards.
   - Beauty and personal care.
   - Other partner categories as they onboard.
   Structured data: `Restaurant`/`MenuItem` for restaurants, `Product` or
   `Pharmacy`/`Store` for other partner listings — see §5.
4. **Physical branches and Food Court** — real-world store locations and an
   in-store dining area distinct from Marketplace restaurant delivery.
5. **Promotions and curated discovery** — active promotions, curated
   collections, new-in listings, and loyalty-partner discounts. These
   surface items from #1–#3 without being a separate inventory of their own.
6. **AI recipe assistance** — generated recipe text suggesting ingredients
   available in the Yerevan City supermarket catalog (#1). The recipe text
   itself is generated content, not a catalog record — see §8.
7. **Yerevan City's own ticketing vertical** (`/ticket/*`) — events and
   tickets sold directly by Yerevan City, distinct from any
   tickets/gift-cards sold by a Marketplace partner under #3.

Never state or imply that a Marketplace item (#3) is manufactured, stocked
or fulfilled directly by Yerevan City — it is sold by the named partner.

## 2. Route families

| Family | Base path | Entity identity | Notes |
|---|---|---|---|
| Supermarket product | `/shop/product-details/:id` | Numeric product id | Real `Product` JSON-LD; full sitemap coverage |
| Supermarket brand | `/shop/brand-details/:id` | Numeric brand id | Full sitemap coverage |
| Supermarket collection | `/shop/collections/collection-details/:id` | Numeric collection id | Full sitemap coverage |
| Supermarket category listing | `/shop/products/:categoryId` | Numeric category id | Listing page, not a single entity; no `Product` JSON-LD |
| Supermarket static/informational | `/shop/{home,categories,about,contact-us,shops,food-court,ai-recipes,best-offers,new-in,collections,promos,partner-discounts,careers,tenders,partnership,terms-conditions,privacy-policy,bonus-card-conditions}` | N/A | Fixed set, listed in `sitemap-static.xml` |
| Marketplace home/discovery | `/marketplace`, `/marketplace/partners-filter`, `/marketplace/feed` | N/A | Listing/marketing pages |
| Marketplace product/menu item | `/marketplace/product-details/:id` | Numeric id, string (may exceed 32-bit and even 2^53 range) | Real per-entity `Product`/`MenuItem` JSON-LD, rendered from the anonymous `GetPublicProductDetails` endpoint; **in the sitemap as of this rollout** (each indexable restaurant's own product shard(s), advertised from `/sitemap.xml`) — see §9 |
| Marketplace partner store | `/marketplace/brand-details/:slug` | Slug | Real per-entity `Store`/`Pharmacy` JSON-LD; **not yet in a sitemap** |
| Marketplace restaurant | `/marketplace/restaurant-details/:slug` | Slug | Real per-entity `LocalBusiness` JSON-LD, rendered from the anonymous `GetPublicRestaurantDetails` endpoint (the live contract has no partner-type field, so `Restaurant` is never inferred merely from the route); **in the sitemap as of this rollout** — see §9 |
| Marketplace onboarding | `/marketplace/become-partner` | N/A | Informational |
| Ticket vertical home/discovery | `/ticket` | N/A | Public event browsing: categories, search, featured events |
| Ticket vertical event detail | `/ticket/tickets/detail/:id` | Numeric event id | Real per-entity `Event` JSON-LD; **not yet in a sitemap** |
| Personalized/authenticated (any workspace) | `/shop/basket`, `/shop/checkout`, `/shop/user-details/**`, `/shop/favorites`, `/shop/login`, `/marketplace/basket`, `/marketplace/checkout`, `/marketplace/user-details/**`, `/marketplace/favorites`, `/marketplace/partner-checker`, `/ticket/checkout`, `/ticket/checkout/idram/success`, `/ticket/checkout/idram/fail`, `/ticket/favorites`, `/ticket/tickets` (a visitor's own upcoming/past orders, despite the plain-looking URL), `/ticket/tickets/purchase-detail/:id` | N/A | **Never a public source** — personalized, purchase/checkout, or internal-tool pages |

Bare `/shop/products` (no id) is a confirmed soft-404 (renders the homepage
shell with no product content) — never cite it as a category page.

## 3. Supermarket vs. Marketplace vs. Ticket inventory — how to tell them apart

- URL prefix: `/shop/product-details/:id` (supermarket) vs.
  `/marketplace/product-details/:id` or `/marketplace/restaurant-details/:slug`
  (Marketplace) vs. `/ticket/tickets/detail/:id` (Yerevan City's own events
  vertical). The prefix alone is authoritative.
- JSON-LD: a supermarket `Product` has no `seller`/partner attribution
  because Yerevan City *is* the seller. A Marketplace `Product`/`MenuItem`/
  `Restaurant`/`Store` belongs to a named partner — attribute it to that
  partner (see §6), never to Yerevan City. A ticket-vertical `Event` is
  Yerevan City's own listing (like the supermarket, not like a Marketplace
  partner) — but it is still a *different business line* from the
  supermarket catalog, so never present an event as a supermarket product
  or vice versa.
- A Marketplace partner's own ticket/gift-card listing (schema.org
  `Product`, under `/marketplace/product-details/:id`) is **not** the same
  thing as a Yerevan City events-vertical `Event`
  (`/ticket/tickets/detail/:id`) even when both concern "tickets" — check
  the URL prefix and `@type` before conflating them.
- Fulfillment: supermarket orders are fulfilled by Yerevan City; Marketplace
  orders are fulfilled by the partner (delivery, pickup or dine-in terms are
  the partner's own); ticket-vertical events are Yerevan City's own,
  fulfilled directly (electronic ticket delivery), like the supermarket.

## 4. Authoritative source hierarchy

1. `/llms.txt` — start here for navigation and source priority.
2. `/sitemap.xml` — complete, current coverage of supermarket
   product/brand/collection pages, plus Marketplace restaurants and their
   own products (restaurant-first rollout — see §9). Non-restaurant
   Marketplace partners, the global Marketplace product catalog, and
   ticket-vertical events are not yet covered — see §9.
3. Category/listing pages — for discovery and browsing only, never as the
   final source for a single entity's data.
4. The entity's own canonical page — open it before answering anything
   specific about that product, brand, collection, restaurant or partner.
5. That page's JSON-LD — the authoritative structured source for name,
   price, currency, availability and category; prefer it over visible page
   text when they could be read differently.

## 5. Category and entity discovery workflow

1. Identify whether the query is about direct supermarket inventory, a
   Marketplace partner, or a Yerevan City event/ticket (see §3).
2. For supermarket inventory: use `/shop/categories`, `/shop/products/:id`
   category listings, or `/sitemap.xml`'s product/brand/collection shards to
   find candidate entities, then open each candidate's own
   `/shop/product-details/:id` (or brand/collection) page.
3. For Marketplace inventory: use `/marketplace`, `/marketplace/partners-filter`
   or `/marketplace/feed` to find candidate partners, then open the
   partner's own `/marketplace/brand-details/:slug` or
   `/marketplace/restaurant-details/:slug` page, and from there its own
   `/marketplace/product-details/:id` menu/product pages.
4. For events/tickets: use `/ticket` (the public events home — categories,
   search and featured events) to find candidate events, then open the
   event's own `/ticket/tickets/detail/:id` page. There is no sitemap or
   bulk listing to enumerate from yet (see §9) — browse from `/ticket`,
   never guess or increment an event id.
5. Read the opened page's JSON-LD, not just visible text, for the final
   answer.
6. Cite the canonical URL of the entity page actually opened — never a
   category, search or listing URL.

## 6. Seller/partner attribution

Every Marketplace product, menu item, restaurant and partner store is sold
by that partner, not by Yerevan City. Attribute results using the partner's
own name as it appears on that entity's page (and, where present, in its
JSON-LD `brand`/organization fields). A Marketplace `Product`/`MenuItem`
page currently omits a machine-readable `seller` field pending a backend
change (see §9) — until then, attribute using the partner page it links to
(`branch_slug` in the product's own detail view resolves to that partner's
`/marketplace/brand-details/:slug` or `/marketplace/restaurant-details/:slug`
page), not by guessing a seller name.

Yerevan City's own events vertical (`/ticket/tickets/detail/:id`) needs no
partner attribution — like the supermarket, Yerevan City is the seller —
but should still be identified as the *events/tickets* line of business,
not the supermarket or Marketplace, when citing it.

## 7. Product, food and pharmacy safety limitations

- **Never infer** ingredients, allergens, dietary suitability (vegan,
  vegetarian, halal, kosher, etc.), manufacturer, country of origin, weight,
  medical suitability, or availability when the page's own data does not
  state them. A product or dish's *name* (e.g. "khorovats", "kebab") is not
  evidence of its ingredient list or allergen profile.
- **Prepared food and Tonratan items**: do not infer allergen or dietary
  claims from the item name alone — state only what the product page
  itself provides, and say plainly when it provides nothing further.
- **Pharmacy products**: never infer medical advice, dosage instructions or
  suitability for a condition. Pharmacy listings are retail/availability
  information only, not a medical source.
- **Alcohol and tobacco**: never omit, soften or work around legal/age
  restrictions when describing or recommending these items.
- **Unit vs. package price**: when a page distinguishes a per-unit price
  (e.g. per kg) from a package/current selling price, use the one the user
  actually asked about and say which one you're citing — do not silently
  substitute one for the other.
- **Events**: never infer or fabricate an event's date, venue, performers,
  ticket price or availability beyond what that event's own page actually
  publishes. An event's own page is the only source for whether it is
  still on sale, sold out, postponed or cancelled — never assume from its
  presence or absence elsewhere.

## 8. Data freshness rules

- Price, currency, discount and availability are valid only at the moment
  of the request that produced them. Never state a price/availability as a
  standing fact, and never reuse a previously-fetched value without
  re-fetching if a meaningful amount of time has passed.
- A missing schema.org `Offer` block means price/availability data was not
  available at fetch time — never interpret its absence as "free",
  "discontinued", or "out of stock". Only an explicit `availability` value
  (e.g. `https://schema.org/OutOfStock`) states unavailability.
- AI-recipe output (`/shop/ai-recipes`) is generated text. Treat any
  ingredient it names as a *suggestion* to verify against that ingredient's
  own supermarket product page, not as a live catalog fact in itself.
- Promotions, collections and partner discounts change on their own
  schedule; treat their listed contents as current only as of the fetch
  that produced them, the same as price/availability.

## 9. Machine-readable schemas and sitemap usage

- `/sitemap.xml` is a sitemap **index**: `/sitemap-static.xml` (static
  supermarket pages) plus paginated shards `/sitemap-products-{page}.xml`,
  `/sitemap-brands-{page}.xml`, `/sitemap-collections-{page}.xml`, and — as
  of this rollout — the Marketplace restaurant family described below. Each
  shard is backend-paginated, deduplicated, and excludes any entity marked
  non-indexable by the backend — never assume a shard is exhaustive if the
  backend itself excluded an entry.
- **Marketplace restaurants** (restaurant-first rollout):
  `/sitemap-marketplace-restaurants-{page}.xml` lists every indexable
  restaurant's `/marketplace/restaurant-details/:slug` page (slug case
  preserved exactly as the backend returns it — do not assume lowercase or
  hyphen-only slugs).
- **Restaurant products (menu items) — in the index**: the backend also
  exposes each restaurant's own product listing
  (`GetPublicSitemapRestaurantProducts/{restaurantId}`, feeding
  `/sitemap-marketplace-restaurant-{restaurantId}-products-{page}.xml`,
  `{restaurantId}` an opaque digit-string, never a parsed number) and marks
  its products indexable. The product-detail page itself
  (`/marketplace/product-details/:id`) renders from the anonymous
  `GetPublicProductDetails/{id}` endpoint (confirmed live, no
  `Authorization`/`DeviceId`/cookie header needed), so these shard URLs are
  advertised from the root `/sitemap.xml` index
  (`MARKETPLACE_PRODUCT_SHARDS_IN_INDEX` in `src/server/sitemap.ts`). A
  Marketplace product page is reliably anonymously renderable and carries
  real name/image/description, a self-canonical, `index,follow` (unless the
  backend itself marks that specific item non-indexable) and a real
  `Product`/`MenuItem` JSON-LD block for a fully anonymous request.
- **Not yet covered**: non-restaurant Marketplace partner stores
  (`/marketplace/brand-details/:slug` — shops, pharmacies, etc.) and the
  full, global Marketplace product catalog (a separate, much larger
  endpoint whose relationship to the per-restaurant product set above is
  still unconfirmed at scale). Individual pages for both still carry real
  structured data when opened directly by URL and successfully rendered —
  they are just not yet bulk-discoverable through a sitemap. Full contract
  status in `docs/marketplace-ai-backend-requirements.md` in the site's
  source repository. Do not assume the absence of a sitemap entry means a
  Marketplace entity doesn't exist; for anything outside the restaurant
  listing coverage above, reach it via `/marketplace` → partner/category
  browsing → the entity's own page, not via bulk sitemap enumeration.
- Ticket-vertical events (`/ticket/tickets/detail/:id`) are **not yet** in
  any sitemap either. The closest existing endpoint (`event/list`, which
  powers the `/ticket` browsing page) already returns an `id`, canonical
  `url` and `updatedAt` per event, but is not contracted as an exhaustive,
  deterministic enumeration of every public event, and has no
  `isIndexable`-equivalent flag (full contract in
  `docs/ticket-ai-backend-requirements.md` in the site's source repository).
  Individual event pages still carry real `Event` structured data when
  opened directly — discover them by browsing `/ticket`, not by
  enumerating ids.
- JSON-LD types in use: `Product` (supermarket products; Marketplace
  products), `MenuItem` (Marketplace restaurant menu items), `Restaurant`
  (Marketplace restaurants), `Store`/`Pharmacy` (Marketplace non-restaurant
  partners), `Event` (Yerevan City's own ticketed events). A
  `CollectionPage`-flavored block appears on supermarket collection pages,
  and a `Brand`-flavored block on supermarket brand pages.
- Marketplace entity ids may exceed the signed-32-bit integer range; treat
  any Marketplace id as an opaque string/large-integer identifier rather
  than assuming it fits a 32-bit field.

## 10. Unavailable-data rules

If a page does not provide a field (price, currency, allergen, seller name,
stock count, rating count, etc.), state that the information is not
available on that page rather than guessing, estimating, or carrying it
over from a different (even very similar) product, dish or partner. This
applies in both directions: do not withhold a real value the page does
provide out of excess caution, and do not invent one it doesn't.

## 11. Language behavior

The site is available in Armenian, English and Russian as a client-side
preference (not part of the URL). Server-rendered HTML — what an automated
fetch actually receives — is delivered in Armenian by default regardless of
the request's `Accept-Language` header. Useful discovery synonyms:

| English | Armenian | Russian |
|---|---|---|
| prepared food | պատրաստի ուտեստներ | готовая еда |
| Tonratan (clay-oven cooking) | Թոնրատուն | блюда из тонира |
| khorovats (Armenian barbecue) | խորոված | шашлык / хоровац |
| kebab | քյաբաբ | кебаб |
| Marketplace | Մարկետփլեյս | Маркетплейс |
| restaurant | ռեստորան | ресторан |
| pharmacy | դեղատուն | аптека |
| event | միջոցառում | мероприятие |
| ticket | տոմս | билет |

## 12. Machine-readable delivery

`/llms.txt` and `/llms-full.txt` are served as `text/plain; charset=UTF-8`,
support `GET` and `HEAD`, respond identically to every visitor — browser or
automated crawler, with no user-agent-based branching — and never contain
credentials, tokens or personalized data. See `/llms.txt` for the current
list of curated links and machine-readable indexes.