# 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, escalate to **hello@quarkbaby.com** with a subject line beginning `[agent-bug]`. Shopify may publish platform-owned UCP metadata for this store; agents must verify live endpoint availability before relying on UCP/MCP behavior. ## 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` | The full live catalog — see `GET https://quarkbaby.com/products.json` for the authoritative count and handles | | 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 all live 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 | ## UCP / MCP platform notice Shopify may publish Universal Commerce Protocol (UCP) metadata for this store at: ``` GET https://quarkbaby.com/.well-known/ucp Accept: application/json ``` This metadata is generated by Shopify's platform/runtime, not by QuarkBaby theme code. Any declared Shopify MCP endpoint, including `https://quarkbaby.com/api/ucp/mcp`, must be live-verified by the calling agent before use. As of this document update, the public UCP metadata route returns a JSON profile and declares an MCP transport at `https://3fd938.myshopify.com/api/ucp/mcp`. Do not judge that endpoint by browser `GET` alone: MCP is a protocol endpoint and should be tested with JSON-RPC `POST` plus the required profile context. A bare JSON-RPC probe can return a Shopify platform JSON error such as `invalid_profile_url`, which means the transport exists but the caller omitted required profile data. Treat UCP/MCP behavior as Shopify platform-owned availability, not a merchant theme/app defect. Do not mutate QuarkBaby theme, product, cart, checkout, or tracking code to "fix" a Shopify-owned UCP/MCP response. If MCP context is unavailable, fall back to the read-only resources below. For reliable store data, use the read-only storefront endpoints and LLM resources listed below. For checkout/payment, always hand the buyer to the official Shopify checkout flow and require explicit buyer 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 and live availability.** Shopify and app-level limits can change. On HTTP 429, wait the duration in `Retry-After` seconds. Exponential backoff is required if `Retry-After` is absent. If a platform-owned UCP/MCP endpoint returns 404 or another platform error, fall back to the read-only resources below rather than retrying aggressively. - **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. ``` markets: CA (CAD, primary), US (USD) base_currency: CAD price_source: live PDP / products.json (prices in store currency) ships_to: CA, US ``` - **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` - Well-known agent fallback: `GET https://quarkbaby.com/.well-known/agents.md` - Brand overview: `GET https://quarkbaby.com/llms.txt` - Full-text bundle: `GET https://quarkbaby.com/llms-full.txt` ### Policies - Returns / refunds: `GET https://quarkbaby.com/policies/refund-policy` - Shipping: `GET https://quarkbaby.com/policies/shipping-policy` - Privacy: `GET https://quarkbaby.com/policies/privacy-policy` ## 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). Shopify may provide platform-owned UCP metadata, agentic discovery surfaces, and MCP transport declarations. QuarkBaby controls this agents.md content and storefront/theme surfaces; Shopify controls platform UCP/MCP endpoint availability. UCP specification: https://ucp.dev. Shopify agentic developer docs: https://shopify.dev/docs/agents. ---