# AGENTS.md — Grocery storefront template

If you are an AI agent (Claude, Cursor, Aider, devin, …) working on this storefront, **start here.**

## TL;DR for rebranding

1. **Edit `lib/brand.ts`** — every visible string lives here.
2. **Edit `app/globals.css`** — `@theme { … }` for palette + radius.
3. **Edit `.env.local`** — set `NEXT_PUBLIC_CIMPLIFY_PUBLIC_KEY` (the only required var).
## Aesthetic

- **Inter sans only** (no serif) — friendly, readable for dense product grids.
- **Fresh green + cream** — vibrant green primary, warm cream background.
- **Generous radius**: `0.875rem` — softer than retail.
- **Bold, slightly heavy** headings.
- Schema.org `@type` is `GroceryStore`.

## Page surface

```
app/
  page.tsx                       Home — hero ("Free delivery over GH₵150"),
                                  collection strips, category grid, newsletter
  shop/page.tsx                  Aisle (SDK <CataloguePage/>)
  search/page.tsx                Search
  collections/[slug]/page.tsx    Collection landing (e.g. weekly box, deals)
  categories/[slug]/page.tsx     Category landing

  cart/page.tsx, checkout/page.tsx, orders/[id]/page.tsx

  account/page.tsx               <AccountDashboardPage /> (native, Server Component)
  account/orders/page.tsx        <AccountOrdersPage /> (native)
  account/addresses/page.tsx     Native list + Server Actions for CRUD
  account/wallets/page.tsx       Native list + Server Actions for CRUD
  login/page.tsx, signup/page.tsx  redirects → /account

  contact/page.tsx, track-order/page.tsx

  about/page.tsx, faq/page.tsx
  shipping/page.tsx (delivery + slots), returns/page.tsx (quality guarantee),
  accessibility/page.tsx, terms/page.tsx, privacy/page.tsx

  sitemap-page/page.tsx, sitemap.ts, robots.ts, llms.txt/route.ts, opensearch.xml/route.ts
  error.tsx, not-found.tsx
```

## File ↔ brand-field map

| File | Reads from `brand` |
|---|---|
| `app/layout.tsx` | identity, contact, socials, GroceryStore JSON-LD |
| `app/page.tsx` | `brand.hero` (free-delivery badge) |
| `app/about/page.tsx` | `brand.about` |
| `app/faq/page.tsx` | `brand.faq` (delivery slots, sourcing, subscription boxes) |
| `app/shipping/page.tsx` | `brand.shipping` (delivery slots + free-over threshold) |
| `app/returns/page.tsx` | `brand.returns` (quality guarantee) |
| `app/accessibility/page.tsx` | `brand.accessibility` |
| `app/terms/page.tsx`, `app/privacy/page.tsx` | `brand.terms`, `brand.privacy` |
| `app/contact/page.tsx` | `brand.contactPage`, `brand.contact` |
| `app/track-order/page.tsx` | `brand.trackOrder` |
| `app/account/*/page.tsx` | `brand.account` (iframe owns UI) |
| `app/llms.txt/route.ts` | `brand.llms`, contact, currency |
| `components/header.tsx`, `footer.tsx` | `brand.header`, `brand.footer`, `brand.contact`, `brand.socials` |

## Grocery-specific notes

- **Subscription boxes** are modelled as products with `billing_plans` (renders the SubscriptionCard variant). The basket-box landing lives at `/categories/baskets`.
- **Weight-based pricing**: SDK supports `quantity_pricing` tiers per product, but most grocery products are sold by unit/kg. Real weight-at-pack pricing happens on the backend pricing rule.
- Mock seed: `--seed grocery` (FreshMart).

## Known TODOs

- Contact + newsletter fake submits.
- Hero / category / product imagery is Unsplash placeholder — replace with merchant photography.

## Customizing SDK components

For anything beyond `lib/brand.ts` + `app/globals.css`, lean on the SDK's prebuilt components rather than reinvent. **Especially for product customization** (variants, add-ons, bundles, composites) — the SDK already gets price math, axis matching, and cart payload contracts right. Default to ejecting and restyling:

```bash
cimplify add cart-drawer
cimplify add add-on-selector
cimplify add product-page
```

Then edit the local copy. **Don't change the cart payload shape** unless you're also touching the SDK mock + backend lens. Full ejection rules and the customizer contract are in the SDK-level [`AGENTS.md`](../../AGENTS.md) → "Don't reinvent product customization".

## Quick start

```bash
bun install
bun dev
```

Open <http://localhost:3000>.
