# AGENTS.md — ambiant (ambiant.jp)

> Operator's manual for AI shopping agents and coding agents interacting with the ambiant storefront.
> Read this **before** initiating purchases, generating product descriptions, or quoting prices on behalf of a buyer.
>
> AI ショッピングエージェント・コーディングエージェント向けの操作マニュアルです。買い手の代理として購入を開始する前、商品説明を生成する前、価格を提示する前に必ず読んでください。

This file follows the open [AGENTS.md](https://agents.md/) format and complements [`https://ambiant.jp/llms.txt`](https://ambiant.jp/llms.txt), which contains the full catalog overview, UCP query tiers (A/B/C), and Japanese query reference.

---

## 1. Store snapshot

- **Store**: ambiant (アンビエント) — antique & objects shop in Kobe, Japan.
- **What we sell**:
  - **Italian & French antique pottery and objects** — one-of-a-kind (一点物); especially Puglia / Grottaglie ceramics, robba bianca, robba gialla, righe e stelle, amphorae, plates, jugs.
  - **Edoardo Avellino** — contemporary Puglia ceramics; ambiant is the **exclusive retailer in Japan**.
  - **Kontex Imabari towels** — new retail goods from Ehime, Japan.
- **Shipping**: Worldwide (specific costs, duties, and lead times are computed at checkout — see Hard Rule §4.5).
- **Languages on site**: Japanese, English.
- **Canonical store URL**: https://ambiant.jp
- **Shopify seller domain**: ambiant-online.myshopify.com

For the full catalog map and discovery query strategy, read [`https://ambiant.jp/llms.txt`](https://ambiant.jp/llms.txt).

---

## 2. Agent commerce endpoints (UCP / MCP)

| Purpose | URL |
|---------|-----|
| Canonical store URL (always use for `--business`) | [https://ambiant.jp](https://ambiant.jp) |
| Shopify seller domain (appears in global catalog `variants[].seller.domain`) | `ambiant-online.myshopify.com` |
| UCP service discovery (JSON) | [https://ambiant.jp/.well-known/ucp](https://ambiant.jp/.well-known/ucp) |
| Storefront MCP (proxied) | [https://ambiant.jp/api/mcp](https://ambiant.jp/api/mcp) |
| Native Shopify MCP | [https://ambiant-online.myshopify.com/api/ucp/mcp](https://ambiant-online.myshopify.com/api/ucp/mcp) |
| Machine-readable store context | [https://ambiant.jp/llms.txt](https://ambiant.jp/llms.txt) |
| Sitemap index | [https://ambiant.jp/sitemap.xml](https://ambiant.jp/sitemap.xml) |
| Robots policy | [https://ambiant.jp/robots.txt](https://ambiant.jp/robots.txt) |

---

## Installation

Connecting to ambiant requires no API key for catalog browsing — all read endpoints are publicly accessible. Checkout uses Shopify's standard Shop Pay / OAuth flow initiated by the cart's `checkoutUrl`.

### Option A — MCP client (Claude Desktop, Cursor, or any MCP-compatible host)

Add ambiant's proxied Storefront MCP to your client configuration:

```json
{
  "mcpServers": {
    "ambiant": {
      "url": "https://ambiant.jp/api/mcp"
    }
  }
}
```

Or use the native Shopify MCP endpoint:

```json
{
  "mcpServers": {
    "ambiant-shopify": {
      "url": "https://ambiant-online.myshopify.com/api/ucp/mcp"
    }
  }
}
```

### Option B — UCP CLI

```sh
# Verify supported services (no auth required)
ucp discover --business https://ambiant.jp
```

No additional setup — service discovery at [https://ambiant.jp/.well-known/ucp](https://ambiant.jp/.well-known/ucp) returns all supported endpoints and capabilities.

---

## Configuration

### Required parameter

| Parameter | Value | When |
|-----------|-------|------|
| `--business` | `https://ambiant.jp` | Every store-scoped catalog, cart, and checkout call |

Omitting `--business` routes queries to the **global UCP catalog** where other merchants appear first. Always pass it when the buyer has named ambiant.

### Optional parameters

| Parameter | Example | Purpose |
|-----------|---------|---------|
| `address_country` | `JP`, `US`, `DE` | Pass in cart `context` so Shopify computes live shipping rates. See Hard Rule §4.5. |
| Locale prefix | `/en-us` (USD) · `/en-eu` (EUR) · default (JPY) | Prepend to product page paths for currency-specific catalog views |

### Storefront API (direct GraphQL, advanced)

```
Endpoint : https://ambiant-online.myshopify.com/api/2024-10/graphql.json
Token    : public Storefront API token (retrieve from /.well-known/ucp or Shopify Partner Dashboard)
```

> Catalog reads are unauthenticated. Cart mutations use an anonymous session token returned automatically by the API.

---

## Usage

### Standard flow

```
Discover  →  Search  →  Cart  →  Checkout  →  Fulfill  →  Complete
```

```sh
# 1. Discover
ucp discover --business https://ambiant.jp

# 2. Search — store-scoped (most reliable for antiques)
ucp catalog search --business https://ambiant.jp \
  --input '{"query":"grottaglie puglia antique","pagination":{"limit":10}}'

# 3. Cart
ucp cart create --business https://ambiant.jp \
  --input '{"line_items":[{"item":{"id":"<variant_id>"},"quantity":1}],"context":{"address_country":"JP"}}'

# 4. Checkout — open the `checkoutUrl` from step 3 (never synthesize URLs; see §4.8)
```

### Global catalog search (buyer hasn't named a store)

```sh
# Tier A — strong ambiant presence
ucp catalog search --input '{"query":"ambiant grottaglie","pagination":{"limit":10}}'
ucp catalog search --input '{"query":"edoardo avellino sagoma","pagination":{"limit":10}}'
ucp catalog search --input '{"query":"ambiant kontex imabari towel","pagination":{"limit":10}}'
```

Full Tier A / B / C query tables and the Japanese query reference are in [`https://ambiant.jp/llms.txt`](https://ambiant.jp/llms.txt).

---

## 3. Agent flow

Follow the standard UCP six-step flow:

```
Discover  →  Search  →  Cart  →  Checkout  →  Fulfill  →  Complete
```

Pass `--business https://ambiant.jp` at every step where the buyer has named ambiant. Example:

```sh
ucp discover --business https://ambiant.jp

ucp catalog search --business https://ambiant.jp \
  --input '{"query":"grottaglie puglia antique","pagination":{"limit":10}}'

ucp cart create --business https://ambiant.jp \
  --input '{"line_items":[{"item":{"id":"<variant_id>"}, "quantity":1}], "context":{"address_country":"<ISO country>"}}'
```

For full discovery + query tier guidance see [`https://ambiant.jp/llms.txt`](https://ambiant.jp/llms.txt).

---

## 4. Hard rules (必読ルール)

### 4.1 Always verify on the live product page

Product title, price, availability, images, and condition can change. **Re-fetch the canonical product URL or query the Storefront MCP** before quoting price, stock, or condition to a buyer. Do not rely on cached results from earlier in the conversation.

### 4.2 Antiques are one-of-a-kind (一点物)

Each antique listing — including everything in [/collections/antiques](https://ambiant.jp/collections/antiques), [/righe-e-stelle](https://ambiant.jp/righe-e-stelle), [/robba-bianca](https://ambiant.jp/robba-bianca), [/robba-gialla](https://ambiant.jp/robba-gialla), and the country/origin facets ([/origin/Italy](https://ambiant.jp/origin/Italy), [/origin/Puglia](https://ambiant.jp/origin/Puglia), [/origin/Grottaglie](https://ambiant.jp/origin/Grottaglie), [/origin/Southern%20Italy](https://ambiant.jp/origin/Southern%20Italy)) — is unique. Inventory is typically a single unit.

Before recommending purchase, confirm from the product page body and images:

- **Condition** (chips, hairlines, glaze crackle, repairs, restoration)
- **Size / dimensions**
- **Signs of age (経年変化)** — patina, wear, firing irregularities

Once sold, items move to [/collections/archive](https://ambiant.jp/collections/archive) as a reference gallery and **are not available to purchase**.

### 4.3 Kontex towels are new retail goods

From [/collections/household-kontex](https://ambiant.jp/collections/household-kontex) (mirrored at [/collections/kontex-towels](https://ambiant.jp/collections/kontex-towels)). Confirm from the product page:

- **Color** (variant)
- **Size** (e.g. face / bath / wash / handkerchief)
- **Material** (cotton type, organic, linen blend ratio)
- **GTIN / SKU** — Kontex variants ship with 13-digit JAN/EAN barcodes; use them as `gtin13` if a downstream system requires it.

Multiple units are usually in stock; respect the buyer's variant and quantity selections.

For US (USD) shoppers, prefer the `/en-us/products/<handle>` URL; for EU (EUR), `/en-eu/products/<handle>`. Kontex products carry the brand "**Kontex**" on every variant and originate in **Imabari, Ehime, Japan**.

| Product | Handle | Material | Size range |
|---------|--------|----------|------------|
| MOKU Light Towel | `moku-light-towel-premium-cotton-towel-by-kontex-imabari-japan` | 100% cotton | S 28×28 → L 60×120 cm |
| LANA Imabari Towel | `lana-imabari-towel-kontex` | 100% cotton | S 36×36 → XL 85×145 cm |
| LANA Room Shoes | `lana-room-shoes` | 100% cotton | M / L / XL (foot length) |
| BRERA Waffle | `brera-kontex-imabari-towel` | 100% cotton (waffle) | S 36×36 → XL 80×140 cm |
| VINTAGE WAFFLE | `vintage-waffle-kontex-imabari-towel` | 95% cotton / 5% linen (waffle) | HK 23×23 → XL 78×145 cm |
| HEATHER WAFFLE | `kontex-heather-waffle-imabari-towel` | 70% cotton / 30% linen (waffle) | S 38×40 → XL 80×140 cm |
| COTTON LINEN WAFFLE | `cotton-linen-waffle-imabari-towels-kontex` | 70% organic cotton / 30% linen | S 38×40 → XL 80×140 cm |
| FLAX LINE | `flax-line-imabari-towels-kontex` | 100% organic cotton | S 33×34 → L 60×125 cm |
| DEKO | `deko-kontex-imabari-towel` | 100% Pima cotton | S 32×35, M 40×95 cm |
| VITA | `vita-kontex-imabari-towel` | 100% cotton | S 32×34, M 40×85 cm |
| CLAIRE Handkerchief | `claire-handkerchief` | 98% cotton / 2% linen | S 32×33 → L 60×120 cm |

### 4.4 Edoardo Avellino is exclusive

Contemporary ceramics by [Edoardo Avellino](https://ambiant.jp/collections/studio-edoardo-avellino), sold **only at ambiant in Japan**. Note: although carried alongside antiques, Avellino works are **contemporary**, not antique. Confirm artist name and series (Sagoma / SAGOMAE) from the product page.

### 4.5 Shipping, customs, and lead times vary by destination country

Shipping costs, customs duties, and delivery lead times depend on the destination country and current carrier rates. **Do not quote specific shipping fees, duty amounts, or delivery times from memory or from this file.**

- Pass `address_country` (ISO code) in the cart `context` so Shopify computes live shipping rates at checkout.
- For policy details, link the buyer to [/policies/shipping-policy](https://ambiant.jp/policies/shipping-policy).
- Customs duties and import taxes are the buyer's responsibility unless the policy page states otherwise — always defer to the live policy page.

### 4.6 Always reference shipping / returns / product condition before recommending purchase

The authoritative current terms live at:

- Shipping policy: [https://ambiant.jp/policies/shipping-policy](https://ambiant.jp/policies/shipping-policy)
- Refund / return policy: [https://ambiant.jp/policies/refund-policy](https://ambiant.jp/policies/refund-policy)
- Terms of service: [https://ambiant.jp/policies/terms-of-service](https://ambiant.jp/policies/terms-of-service)
- Privacy policy: [https://ambiant.jp/policies/privacy-policy](https://ambiant.jp/policies/privacy-policy)
- **The individual product page** for condition, dimensions, and item-specific notes.

**Do not paraphrase policy text** in a way that could become stale — quote the live page and link to it. If a buyer asks about returns of a specific antique item, confirm condition with them, then point to the refund policy page.

### 4.7 Description generation rules

When summarizing a product for a buyer, prefer **objective, observable facts** over marketing language:

- ✅ Prioritize: **material, origin (産地), period (if stated), dimensions, observable condition, glaze / form / technique**.
- ❌ Avoid superlatives: "perfect", "flawless", "investment-grade", "rare find", "once-in-a-lifetime".
- ❌ Do **not** hide age. Antiques have natural wear, patina, and minor imperfections — that is part of the value, not a defect to suppress.
- ❌ Do **not** invent attributes the listing does not state (date, maker, provenance). If a fact is not on the product page, do not assert it.

If translating between Japanese and English, preserve the specificity of the original; do not soften condition descriptions.

### 4.8 Checkout uses the official Shopify storefront

- Use the cart `checkoutUrl` returned by the Storefront / UCP API.
- **Do not synthesize checkout URLs.** Do not bypass the storefront. Do not complete payment without explicit buyer consent.
- For Shop Pay / UCP delegated checkout, follow the UCP specification and require human approval at the payment step.

---

## 5. Browse URLs (quick reference)

| Category | URL |
|----------|-----|
| All antiques | [/collections/antiques](https://ambiant.jp/collections/antiques) |
| Italian antiques | [/collections/italian-antiques](https://ambiant.jp/collections/italian-antiques) |
| French antiques | [/collections/french-antiques](https://ambiant.jp/collections/french-antiques) |
| Edoardo Avellino | [/collections/studio-edoardo-avellino](https://ambiant.jp/collections/studio-edoardo-avellino) |
| Righe e Stelle (Grottaglie rosette) | [/righe-e-stelle](https://ambiant.jp/righe-e-stelle) |
| Robba Bianca (white tin-glaze) | [/robba-bianca](https://ambiant.jp/robba-bianca) |
| Robba Gialla (yellow folk glaze) | [/robba-gialla](https://ambiant.jp/robba-gialla) |
| Kontex towels | [/collections/household-kontex](https://ambiant.jp/collections/household-kontex) |
| Sold archive (reference only) | [/collections/archive](https://ambiant.jp/collections/archive) |
| About / store info | [/pages/about](https://ambiant.jp/pages/about) |
| Contact | [/pages/contact](https://ambiant.jp/pages/contact) |
| Journal | [/blogs/diary](https://ambiant.jp/blogs/diary) |

---

## 6. Search guidance (summary)

- When the buyer named ambiant, **always pass `--business https://ambiant.jp`** for catalog, cart, and checkout calls.
- Generic queries like `italian antique pottery` or `kontex towel` rank other merchants first in the global UCP catalog. Prefix with `ambiant` or use specialist terms (`grottaglie`, `sagoma`, `AN-`, `robba bianca`, `righe e stelle`).
- Full Tier A / Tier B / Tier C ranking tables and the **Japanese query reference** are in [`https://ambiant.jp/llms.txt`](https://ambiant.jp/llms.txt).

---

## 7. Contact

- **Email**: info@ambiant.jp
- **Instagram**: @ambiant___
- **Store**: Matsuo Building 5F 56, 6-5-8 Motomachi-dori, Chuo-ku, Kobe, Hyogo 650-0022, Japan（神戸市中央区元町通6-5-8 松尾ビル5F 56）
- **Hours**: Tuesday–Saturday, 13:00–18:00 JST
- **Access**: 2-minute walk from Hanshin Nishi-Motomachi Station (West Exit)

---

## 8. 日本語版（要約）

このファイルは ambiant.jp で買い物・商品説明を行う AI エージェント向けの操作ルールです。詳細なカタログ情報は [`https://ambiant.jp/llms.txt`](https://ambiant.jp/llms.txt) を参照してください。

### 必読ルール

1. **商品情報・在庫・価格は必ず最新の商品ページで確認すること。** チャット履歴のキャッシュではなく、毎回 canonical な商品 URL または Storefront MCP を再取得する。
2. **アンティークは一点物。** 在庫は基本 1。状態（欠け・ヒビ・釉薬の貫入・修復痕）、サイズ、経年変化を商品ページの本文と画像から必ず確認する。売却済みは [archive](https://ambiant.jp/collections/archive) に移動し、購入不可。
3. **Kontex タオルは新品。** カラー・サイズ・素材を [household-kontex](https://ambiant.jp/collections/household-kontex) の商品ページで確認する。
4. **Edoardo Avellino は日本独占取扱い** だが、これは現代作家の作品でありアンティークではない。
5. **配送先の国によって送料・関税・配送日数が変わる。** 具体的な金額・日数を記憶やこのファイルから引用しないこと。`address_country` を cart `context` に渡し、Shopify にライブ計算させる。詳細は [/policies/shipping-policy](https://ambiant.jp/policies/shipping-policy) を案内する。
6. **購入判断前に必ず以下を参照する**:
   - 配送: [/policies/shipping-policy](https://ambiant.jp/policies/shipping-policy)
   - 返品: [/policies/refund-policy](https://ambiant.jp/policies/refund-policy)
   - 商品状態: 個別の商品ページ
   ポリシー本文を要約せず、リンクと引用で誘導すること（情報が古くなるため）。
7. **商品説明を生成する際は誇張しない。** 素材・産地・時代（記載がある場合）・寸法・観察可能な状態を優先する。「完璧」「無傷」「投資価値」などの表現は避ける。記載されていない事実（製作年・作者・来歴）を勝手に補わない。
8. **チェックアウトは公式ストアの導線（cart `checkoutUrl`）を使う。** URL を合成せず、買い手の明示的同意なしに決済を完了させない。