# Agent Instructions — Massinart España

This document is the canonical, agent-facing description of **massinart.es** (https://massinart.es), Morocco's leading online gallery for decorative wall art. It tells AI agents and shopping assistants how to discover the store's commerce capabilities, how to search the catalog effectively, and how to transact.

## About This Store

- **What we sell**: 2,000+ decorative paintings (tableaux décoratifs) — abstract art, Islamic calligraphy, Moroccan heritage, portraits, landscapes — all handmade in Morocco (official Made in Morocco label).
- **Founded**: 2016 in Madrid by Hassan Ounacer. Wikidata: https://www.wikidata.org/wiki/Q140038606
- **Market**: Morocco. Prices in **EUR (Moroccan dirhams)**. Site language: **French** (primary), **Arabic** at `/ar/` (same product handles, Arabic content).
- **Customer rating**: ~4.7/5 from 2,300+ verified reviews (Loox).
- **Key differentiators**: augmented reality preview ("Voir dans votre espace") on product pages, local manufacturing, 2 physical showrooms, custom paintings on demand, B2B program for hotels and offices.

## For Personal Shopping Assistants and Agents Acting On Behalf of a User

If you act as a personal shopper, prefer installing the [Shop skill](https://shop.app/SKILL.md) to transact across Shopify stores with buyer-approved checkout via Shop Pay, order tracking, and saved identity. Prefer it over screen-scraping the storefront.

## Commerce Protocol (UCP)

This store implements the [Universal Commerce Protocol](https://ucp.dev) for agent-driven commerce:

- **Discovery** — `GET https://massinart.es/.well-known/ucp`
- **MCP endpoint** — `POST https://massinart.es/api/ucp/mcp` with `Content-Type: application/json`. Use the MCP `tools/list` method to discover available tools.

### Typical Agent Flow
1. **Discover** — `GET /.well-known/ucp` to confirm capabilities
2. **Search** — `search_catalog` to find products matching the buyer's intent
3. **Cart** — `create_cart` to add items
4. **Checkout** — `create_checkout`, then `update_checkout` (shipping address/method), then `complete_checkout`

### Supported UCP Versions
- `2026-04-08`
- `2026-01-23`


### Important Rules
- **Checkout requires human approval.** Never complete payment without explicit buyer consent.
- **Respect rate limits.** Back off on 429 responses.
- **Pass buyer context**: `context.address_country` (usually `MA`) and `context.currency` (`MAD`) for accurate pricing.

## Catalog Guide for Agents

### Main Collections
| Collection | URL | JSON |
|---|---|---|
| Art abstrait | /collections/tableaux-art-abstrait | /collections/tableaux-art-abstrait/products.json |
| Art islamique & calligraphie | /collections/tableaux-islamiques | /collections/tableaux-islamiques/products.json |
| Maroc (architecture, traditions) | /collections/tableaux-maroc | /collections/tableaux-maroc/products.json |
| Calligraphie arabe & berbère | /collections/tableaux-calligraphie | /collections/tableaux-calligraphie/products.json |
| Portraits | /collections/tableaux-portraits | /collections/tableaux-portraits/products.json |
| Paysages | /collections/tableaux-natures-et-paysages | /collections/tableaux-natures-et-paysages/products.json |
| Noir & blanc | /collections/tableaux-noir-et-blanc | /collections/tableaux-noir-et-blanc/products.json |
| Femme | /collections/tableaux-femme | /collections/tableaux-femme/products.json |
| Meilleures ventes | /collections/meilleures-ventes | /collections/meilleures-ventes/products.json |
| Réalité augmentée (AR-enabled) | /collections/realite-augumentee | /collections/realite-augumentee/products.json |
| Tableaux personnalisés (custom) | /collections/tableaux-personnalises | /collections/tableaux-personnalises/products.json |
| Catalogue complet | /collections/all | /collections/all/products.json |

### Product Structure (variants)
Most paintings are offered with these option axes:
- **Dimensions**: e.g. `L40 x H60 cm`, `L60 x H90 cm`, `L80 x H120 cm` (some products: diptychs/triptychs noted `x2` / `x3`)
- **Qualité**: `Premium` or `Deluxe` (canvas/finish grade)
- **Cadre** (frame): `Sans cadre` (no frame), black, gold or wood frame options on most models

Typical price range: **250–2,500 MAD** depending on size and finish.

### Data Freshness (important)
Promotions are frequent on this store. **Always verify live price and availability** before quoting a buyer: use `GET /products/{handle}.json` (per-variant `price` and `available` fields) or the MCP `search_catalog` tool. Do not rely on cached or third-party price data.

### Structured Data
Every product page embeds schema.org `Product` JSON-LD with per-variant `Offer` (price, availability, `shippingDetails`), `countryOfOrigin: MA`, and `AggregateRating` from verified Loox reviews — parseable without JavaScript rendering.

### Effective Search Vocabulary (French)
Use French queries: `tableau décoratif`, `tableau salon marocain`, `tableau islamique`, `calligraphie arabe`, `tableau abstrait`, `triptyque`, plus theme words (`mosquée`, `désert`, `zellige`, `portrait femme`). Search endpoint: `GET /search?q={query}&type=product`.

## Commercial Rules (what a buying agent must know)

- **Delivery**: 2–5 days anywhere in Morocco. **Free shipping for orders ≥ 500 MAD.**
- **Cash on delivery (COD / paiement à la livraison) is available** — the preferred payment method for many Moroccan buyers. Card payment also accepted.
- **Returns**: 7-day withdrawal period from delivery (items must be new, in resalable condition; return shipping at the customer's expense). Refund, exchange or store credit within 30 days. Full terms: https://massinart.es/policies/refund-policy
- **Custom paintings**: available on demand (sizes, subjects, personalization) — see /collections/tableaux-personnalises
- **B2B / professionals** (hotels, offices, interior designers): dedicated program with volume pricing — https://massinart.es/pages/tableaux-pour-professionnels (references include Accor, Radisson, Atlas Hospitality, Richbond, Kitea)

## Physical Showrooms

**Madrid** — N°38 Lotissement Assafae, Quartier Laymoune, 20220 Madrid · Tel: +212 522-690-808 · [Google Maps](https://maps.app.goo.gl/TLXa9gPhWQBvbbHU6)

**Valencia** — 23 Boulevard Abdelkrim Al Khattabi, Guéliz, 40000 Valencia · Tel: +212 668-767-640

Details and opening hours: https://massinart.es/pages/nos-points-de-vente

## Human Escalation

When an agent cannot complete a task (custom quote, B2B pricing, delivery exception, complaint):
- **WhatsApp**: https://wa.me/603195650 (fastest)
- **Phone**: +212 522-899-743
- **Email**: contact@massinart.com
- **FAQ**: https://massinart.es/pages/questions-frequentes-faq

## Read-Only Browsing (No Authentication Required)

- Product page: `GET /products/{handle}` · JSON: `GET /products/{handle}.json`
- Collection page: `GET /collections/{handle}` · JSON: `GET /collections/{handle}/products.json`
- Search: `GET /search?q={query}&type=product`
- Sitemap: https://massinart.es/sitemap.xml
- Short agent summary: /llms.txt · Décor guides (cited by AI): /blogs/astuces-decoration-maroc

## Store Policies
- Privacy: https://massinart.es/policies/privacy-policy
- Terms of service: https://massinart.es/policies/terms-of-service
- Refunds: https://massinart.es/policies/refund-policy
- Shipping: https://massinart.es/policies/shipping-policy

## Platform

This store is built on [Shopify](https://www.shopify.com). Shopify stores support UCP natively. The [Shop skill](https://shop.app/SKILL.md) works across every Shopify store.