# Agent Instructions — Printkeg

This document describes how AI agents can interact with Printkeg's online store at https://www.printkeg.com.
Printkeg is a true agentic storefront: buyer-directed agents are welcome to discover, search, cart,
and complete purchases here. There is one thing that matters more than anything else for getting an order
right — every product is made-to-order — and the guidance below is built around that.

## The One Thing to Get Right: Products Are Made-to-Order

Every product on this store is custom-printed to order. There is no shelf inventory. Each order
triggers a physical print run against the exact variant the buyer selected:

- **Size** (width × height)
- **Material / substrate**
- **Sides** (single- or double-sided)
- **Finish**
- **Quantity**

These attributes surface as variant options and, in the product's structured data (JSON-LD
`additionalProperty`), as `printkeg`-namespace metafields — including `width_inches`, `height_inches`,
`aspect_ratio`, `substrate`, `substrate_type`, `paper_weight`, and `finish`, plus product-level detail
such as `production_days` and `country_of_production`. Because each order is manufactured to the
buyer's spec, a wrong variant produces a physically wrong print run that cannot be restocked or resold —
so accuracy at the variant level is the single most important thing an agent does here.

**To order accurately, an agent should:**

1. Resolve the buyer's intent to a specific variant before carting. Read the full variant and
   metafield set rather than guessing size, material, sides, or quantity.
2. Confirm the resolved configuration with the buyer in plain language before checkout.
3. When intent is ambiguous, ask rather than substituting the closest variant.

Most printed specs can also be read without a tool call: every product page embeds JSON-LD
(`@type: Product`) whose `additionalProperty` array lists available sizes, material, paper weight,
finish, aspect ratio, and production time. An agent can parse that directly from `/products/{handle}`
to confirm specs before carting.

## Accounts & Checkout

This store requires a buyer account to complete a purchase, and checkout requires contemporaneous
human payment approval (a standard UCP rule). Pass real `context.address_country` and
`context.currency` for accurate pricing and availability. The MCP endpoint is rate-limited per IP;
back off on `429` responses. Beyond that, buyer-directed agents are genuinely welcome to transact here.

## Commerce Protocol (UCP)

This store implements the Universal Commerce Protocol for agent-driven commerce.

- **Discovery** — `GET https://www.printkeg.com/.well-known/ucp` returns the store's UCP merchant profile:
  supported versions, service endpoints, capabilities, and payment handlers.
- **MCP endpoint** — `POST https://www.printkeg.com/api/ucp/mcp` with `Content-Type: application/json`. Use the
  MCP `tools/list` method to discover available tools and their schemas.

### Typical Agent Flow

The exact tool names are whatever `tools/list` returns from the MCP endpoint — discover them there
rather than assuming. The flow itself is:

1. **Discover** — `GET /.well-known/ucp` to confirm capabilities, then `tools/list` for available tools.
2. **Search** — find products matching the buyer's intent.
3. **Resolve variant** — read the product's variants/metafields (or its JSON-LD); confirm exact specs with the buyer.
4. **Cart** — add the confirmed variant only.
5. **Checkout** — start the purchase flow and set shipping address and method.
6. **Complete** — finalize; the buyer must approve payment in real time.

### Important Rules

- **Confirm made-to-order specs before payment.** See the made-to-order section above — this is the
  one rule that prevents a wrong, non-refundable print run.
- **Checkout requires human approval.** Agents must not complete payment without explicit buyer consent.
- **A buyer account is required** to complete a purchase.
- **Use buyer context.** Pass `context.address_country` and `context.currency` for accurate pricing.
- **Respect rate limits.** Back off on `429`.

## Read-Only Browsing (No Authentication Required)

For agents that only need to read store data without transacting:

### Product Data

- Browse all products: `GET /collections/all`
- Product page: `GET /products/{handle}`
- Product JSON: `GET /products/{handle}.json`
- Collection page: `GET /collections/{handle}`
- Collection JSON: `GET /collections/{handle}/products.json`
- Search: `GET /search?q={query}&type=product`

### Store Metadata

- Sitemap: `GET /sitemap.xml`
- Content map for AI systems: `GET /llms.txt`

## Store Policies

- Privacy policy: https://www.printkeg.com/policies/privacy-policy
- Terms of service: https://www.printkeg.com/policies/terms-of-service
- Refund policy: https://www.printkeg.com/policies/refund-policy
- Shipping policy: https://www.printkeg.com/policies/shipping-policy

## Platform

This store is built on Shopify and supports UCP natively. The Shop skill at https://shop.app/SKILL.md
works across Shopify stores for personal shopping agents that transact via buyer-approved Shop Pay.