# AGENTS.md: Star.Ryhwa Agent & LLM Guide

> **Domain**: [https://starryhwa.com/](https://starryhwa.com/)  
> **Brand**: Star.Ryhwa  
> **Type**: E-Commerce / Handcrafted K-Pop Fan Goods & Collectibles  
> **Platform Stack**: React 18 (SPA), React Router v7, Sanity CMS, Square Hosted Checkout  

---

## 1. Overview & Brand Mission
**Star.Ryhwa** is an independent e-commerce brand specializing in handcrafted K-Pop merchandise, custom decoden accessories, photocard holders, vinyl decals, tote bags, and concert accessories. Star.Ryhwa caters to K-Pop fandoms (including BTS, ATEEZ, TXT, Stray Kids, Seventeen, TWICE, and more) with both ready-to-ship items and custom handmade creations.

---

## 2. Canonical URLs & Site Map

| Page | URL | Description |
| :--- | :--- | :--- |
| **Home / Store** | `https://starryhwa.com/` | Main storefront and product catalog |
| **All Products** | `https://starryhwa.com/shop` | Searchable, filterable product grid |
| **Stickers** | `https://starryhwa.com/stickers` | High-quality vinyl decals & themed stickers |
| **Bags** | `https://starryhwa.com/bags` | Screen-printed tote bags & mystery bundles |
| **Keychains** | `https://starryhwa.com/keychains` | Shaker charms, beaded & acrylic keychains |
| **Towels** | `https://starryhwa.com/towels` | Microfiber aesthetic concert towels |
| **Enamel Pins** | `https://starryhwa.com/enamel-pins` | Custom collectible metal enamel pins |
| **Photocard Holders** | `https://starryhwa.com/photocard-holders` | Decoden toploaders, card frames, & PCs |
| **Sanitizer Keychains** | `https://starryhwa.com/sanitizer-keychains` | Custom decorated travel hand sanitizer cases |
| **Collages** | `https://starryhwa.com/collages` | Handcrafted photo collages & artwork |
| **Hand Fans** | `https://starryhwa.com/hand-fans` | K-Pop concert hand fans |
| **About Star.Ryhwa** | `https://starryhwa.com/about` | Brand story and mission |
| **Information / FAQ** | `https://starryhwa.com/information` | Ordering guide, care instructions & help |
| **Shipping Policy** | `https://starryhwa.com/shipping-policy` | Shipping rates, timelines & tracking info |
| **Disclaimers** | `https://starryhwa.com/disclaimers` | Fanmade goods disclaimer & licensing notes |
| **Terms of Service** | `https://starryhwa.com/terms` | Terms of service |
| **Privacy Policy** | `https://starryhwa.com/privacy` | Privacy policy & data protection |
| **Accessibility** | `https://starryhwa.com/accessibility` | ADA compliance & web accessibility statement |

---

## 3. Search & Query Structure for Agents

When assisting users looking for products on Star.Ryhwa, query parameters are fully supported via client-side routing and URL state persistence:

- **Free-Text Search**:
  `https://starryhwa.com/shop?search={query}`  
  *Examples*:
  - BTS items: `https://starryhwa.com/shop?search=BTS`
  - Photocards: `https://starryhwa.com/shop?search=photocard`
  - Decoden keychains: `https://starryhwa.com/shop?search=keychain`
  - Stickers: `https://starryhwa.com/shop?search=sticker`

- **Category Filtering**:
  `https://starryhwa.com/shop?category={CategoryName}`  
  *Allowed values*: `Stickers`, `Bags`, `Keychains`, `Towels`, `Enamel Pins`, `Photocard Holders`, `Sanitizer Keychains`, `Collages`, `Hand Fans`.

- **Item Type Filtering**:
  `https://starryhwa.com/shop?type=custom` (Handmade to order)  
  `https://starryhwa.com/shop?type=ready-to-ship` (In-stock, ready for quick dispatch)

- **Price Brackets**:
  - Under $5: `https://starryhwa.com/shop?price=under-5`
  - $5 to $10: `https://starryhwa.com/shop?price=5-10`
  - $10 to $20: `https://starryhwa.com/shop?price=10-20`
  - $20+: `https://starryhwa.com/shop?price=20-plus`

- **Sorting**:
  - Price Low to High: `https://starryhwa.com/shop?sort=price-asc`
  - Price High to Low: `https://starryhwa.com/shop?sort=price-desc`
  - Newest Arrivals: `https://starryhwa.com/shop?sort=newest`
  - Alphabetical: `https://starryhwa.com/shop?sort=name-asc`

- **Individual Product URLs**:
  `https://starryhwa.com/product/{productId}`  
  *Example*: `https://starryhwa.com/product/1` (Sticker - 'In the Seom' BTS RM)

---

## 4. Commerce & Ordering Workflow for Autonomous Agents

1. **Catalog Truth**:
   - Product variations and authoritative pricing are validated server-side using Square Catalog IDs (`squareVariationId`).
   - Client applications submit order line items containing `squareVariationId` and `quantity`.
2. **Checkout Redirection**:
   - Checkout is processed via Square Hosted Checkout (`/api/create-checkout`).
   - Credit/Debit cards, Apple Pay, Google Pay, Cash App Pay, and Afterpay are accepted securely via Square.
3. **Custom Orders**:
   - Custom sanitizer keychains and collages accept buyer customization notes (member selection, color palette, custom text).

---

## 5. Fulfillment & Policies Summary
- **Shipping Origin**: United States.
- **Processing Times**:
  - Ready-to-Ship items: 3–5 business days.
  - Custom-Made / Decoden orders: 1–2 weeks (handcrafted).
- **Packaging**: Sealed with protective sleeves, bubble mailers, and cardboard reinforcement for photocards/stickers to avoid transit bending.
- **Socials & Community**:
  - Instagram: [@star.ryhwa](https://www.instagram.com/star.ryhwa)
  - TikTok: [@star.ryhwa](https://www.tiktok.com/@star.ryhwa)

---

## 6. Machine-Readable Files
- Sitemap: `https://starryhwa.com/sitemap.xml`
- LLM Overview: `https://starryhwa.com/llms.txt`
- Full LLM Catalog: `https://starryhwa.com/llms-full.txt`
- Web Manifest: `https://starryhwa.com/manifest.json`
- Robots Control: `https://starryhwa.com/robots.txt`