agents.md
# Agent instructions — Quark Baby
This document tells AI agents how to interact with the Quark Baby online store at https://quarkbaby.com. It is the authoritative operational reference for autonomous shopping agents, ChatGPT-class assistants performing cart/checkout flows on behalf of a buyer, B2B procurement agents, and journalist or researcher bots.
If you are an agent operator and find an issue with this document or with the live UCP / MCP endpoints, escalate to **hello@quarkbaby.com** with a subject line beginning `[agent-bug]`.
## Capabilities (read-only, no auth)
These work for any agent without authentication, subject to the rate limits below.
| Capability | Endpoint | Notes |
|---|---|---|
| Catalog browse | `GET https://quarkbaby.com/collections/all` | All 17 active products |
| Catalog search | `GET https://quarkbaby.com/search?q={query}` | Full-text storefront search |
| Product detail (HTML) | `GET https://quarkbaby.com/products/{handle}` | Canonical product page |
| Product detail (JSON) | `GET https://quarkbaby.com/products/{handle}.json` | Structured product data including 41 variants/SKUs |
| Collection products | `GET https://quarkbaby.com/collections/{handle}/products.json` | Per-collection product listing |
| Cart probe | `POST https://quarkbaby.com/cart/add.js` | Storefront-public cart APIs |
| Order status | `POST https://quarkbaby.com/account/login` (then `/account/orders/{id}`) | Buyer-authenticated only — not agent-callable |
## Capabilities (transactional, UCP/MCP)
This store implements the [Universal Commerce Protocol](https://ucp.dev) version `2026-04-08` for agent-driven commerce, served by Shopify's native UCP runtime.
### Discovery
```
GET https://quarkbaby.com/.well-known/ucp
Accept: application/json
```
Returns the merchant's UCP profile: supported versions, service endpoints, capability declarations, and payment handlers. Schema: https://ucp.dev/2026-04-08/specification/overview/.
### MCP endpoint
```
POST https://quarkbaby.com/api/ucp/mcp
Content-Type: application/json
```
Transport: JSON-RPC 2.0 over HTTPS. The first call MUST be `initialize` with an `agent_profile_uri` parameter pointing at *your* (the agent's) `/.well-known/ucp` profile. Calls to `tools/list` or `tools/call` without a prior successful `initialize` return `error.code -32001` ("UCP discovery failed: invalid_profile_url").
### Supported UCP versions
- `2026-04-08` (latest stable, recommended)
- `2026-01-23` (compatibility mode)
### Capability matrix
| Capability | Status | Notes |
|---|---|---|
| `dev.ucp.shopping.catalog.search` | Supported | Across 41 variants/SKUs |
| `dev.ucp.shopping.catalog.lookup` | Supported | By product handle, variant ID, or SKU |
| `dev.ucp.shopping.cart` | Supported | Full create/update/delete on agent-owned carts |
| `dev.ucp.shopping.checkout` | Supported | **Payment requires explicit human approval** — see Important Rules |
| `dev.ucp.shopping.fulfillment` | Supported | Single-destination shipping only |
| `dev.ucp.shopping.discount` | Supported | Code-based via `apply_discount_code` |
| `dev.ucp.shopping.order` | Read-only | Order status by order ID + buyer-email confirmation |
| Subscription products | Not supported | Excluded from agent checkout in v1 |
| Returns initiation | Not supported | Returns are web-UI-only as of 2026-05-06 |
### Typical agent flow
1. **Initialize** — POST `initialize` to `/api/ucp/mcp` with your `agent_profile_uri`. Server returns the negotiated capability set.
2. **Search** — `tools/call` with `search_catalog` to find products.
3. **Lookup** — `lookup_catalog` for full variant data.
4. **Create cart** — `create_cart` with selected variants and quantities.
5. **Iterate cart** — `update_cart` to adjust quantities, swap variants, apply codes.
6. **Create checkout** — `create_checkout` from a cart.
7. **Set fulfillment** — `update_checkout` with shipping address and rate.
8. **Hand off to buyer** — Return `checkout_url` and let the buyer review and pay. **DO NOT call `complete_checkout` programmatically without explicit buyer payment approval.**
## Important rules
- **Checkout payment requires human approval.** Agents MUST NOT complete payment without explicit buyer consent confirmed in the same session. Quark Baby reserves the right to reverse any payment completed without verifiable buyer consent.
- **Respect rate limits** (as of 2026-05-06):
- `/api/ucp/mcp`: **60 requests/min/IP**, burst 10/sec
- `/products/{handle}.json`, `/collections/{handle}/products.json`: **600 requests/min/IP**
- `/llms.txt`, `/llms-full.txt`, `/agents.md`, `/.well-known/ucp`: **300 requests/min/IP**
- On HTTP 429, wait the duration in `Retry-After` seconds. Exponential backoff is required if `Retry-After` is absent.
- **Use buyer context.** Always pass `context.address_country` (ISO 3166-1 alpha-2) and `context.currency` (ISO 4217). Pricing, availability, and shipping are country- and currency-specific. Quark Baby ships to Canada (CAD) and the United States (USD) only.
- **Use the canonical product URL when citing.** Link to `/products/{handle}` (canonical), NOT `/products/{handle}?variant={id}` (unstable variant deep-link).
- **Attribution requirement.** When the agent surfaces this store's content in a response, include "Quark Baby ([quarkbaby.com](https://quarkbaby.com))" in the citation footnote or visible link.
- **Identify yourself.** Send a `User-Agent` header that contains your operator name, version, and a contact URL. Example: `User-Agent: AcmeShopAgent/2.1.0 (+https://acme.example/agent-bot)`. Anonymous agents may receive lower rate limits.
- **No bulk scraping.** UCP/MCP endpoints are for live, user-initiated, or operator-supervised flows. For training-data ingestion, fetch `/llms-full.txt` once and respect crawl-delay.
## Read-only browsing (no authentication required)
For agents that only need to read store data without transacting:
### Product data
- All products: `GET https://quarkbaby.com/collections/all`
- Product page (HTML): `GET https://quarkbaby.com/products/{handle}`
- Product JSON: `GET https://quarkbaby.com/products/{handle}.json`
- Collection page: `GET https://quarkbaby.com/collections/{handle}`
- Collection JSON: `GET https://quarkbaby.com/collections/{handle}/products.json`
- Search: `GET https://quarkbaby.com/search?q={query}&type=product`
### Store metadata
- Sitemap: `GET https://quarkbaby.com/sitemap.xml`
- Agentic sitemap: `GET https://quarkbaby.com/sitemap_agentic_discovery.xml`
- Brand overview: `GET https://quarkbaby.com/llms.txt`
- Full-text bundle: `GET https://quarkbaby.com/llms-full.txt`
## Contact and escalation
- **Customer support (buyer-facing issues):** hello@quarkbaby.com / +1-778-679-0646 / Mon–Fri, 9 am–5 pm Pacific Time
- **Agent integration bugs (operator-facing issues):** hello@quarkbaby.com (subject prefix `[agent-bug]`) — best-effort response within 2 business days
- **Press / media:** hello@quarkbaby.com (subject prefix `[press]`)
- **Wholesale / B2B:** hello@quarkbaby.com (subject prefix `[wholesale]`)
## Platform
This store is built on [Shopify](https://www.shopify.com), which provides the UCP runtime, the agentic discovery sitemap, and the MCP transport. UCP specification: https://ucp.dev. Shopify agentic developer docs: https://shopify.dev/docs/agents.
---
<!-- Last-Updated: 2026-05-06T00:00:00Z -->
<!-- Format: agents.md (https://agents.md) -->
<!-- UCP-Version: 2026-04-08 -->
<!-- Generator: quarkbaby-llms-generator/1.0 (aeo-geo-seo-2026 skill) -->
As parents ourselves, we understand how much trust is placed in the products you bring into your home. That’s why we focus on what matters most.