# AGENTS.md — Auto-parts storefront template

If you are an AI agent working on this storefront, **start here.**

## TL;DR for rebranding

1. **Edit `lib/brand.ts`** — every visible string, plus the `fitments` make/model/year tree.
2. **Edit `app/globals.css`** — `@theme { … }` block for palette + radius + font references.
3. **Edit `.env.local`** — `NEXT_PUBLIC_CIMPLIFY_*` env vars.

## Aesthetic

- **Inter + JetBrains Mono** — clean modern sans, mono-spaced labels for spec-feel.
- **Carbon-black foreground + sport-red accent.**
- **Sharp corners**: `0.5rem` — workshop-modern.
- **`AutoPartsStore`** is the Schema.org `@type` (set in `brand.schemaType`).

## Page surface

```
app/
  page.tsx                       AutoHero + FitmentFinder + TrustBar + Most ordered
                                  grid + ServiceBrief + Newsletter
  shop/page.tsx                  SDK <CataloguePage/>. Reads `?fits=<tag>` to
                                  filter by fitment tag.
  search/page.tsx                Search
  collections/[slug]/page.tsx    Collection landing
  categories/[slug]/page.tsx     Category landing
  products/[slug]/page.tsx       Full product detail page (Product JSON-LD)
  cart/page.tsx, checkout/page.tsx, orders/[id]/page.tsx  SDK
  account/* + login/signup
  contact/, track-order/, about, faq, terms, privacy, shipping, returns,
  accessibility/, sitemap-page/  Brand-driven content pages
```

## File ↔ brand-field map

| File | Reads from `brand` |
|---|---|
| `app/layout.tsx` | identity, contact, socials, schemaType (AutoPartsStore JSON-LD) |
| `app/page.tsx` | `brand.hero`, `brand.fitments`, `brand.serviceBrief`, `brand.newsletter` |
| `app/about/page.tsx` | `brand.about` |
| `app/faq/page.tsx` | `brand.faq` |
| `app/terms/page.tsx` | `brand.terms` |
| `app/privacy/page.tsx` | `brand.privacy` |
| `app/shipping/page.tsx` | `brand.shipping` |
| `app/returns/page.tsx` | `brand.returns` |
| `app/accessibility/page.tsx` | `brand.accessibility` |
| `app/contact/page.tsx` | `brand.contactPage`, `brand.contact` |
| `app/track-order/page.tsx` | `brand.trackOrder` |
| `app/products/[slug]/page.tsx` | `brand.name`, `brand.currency` |
| `app/llms.txt/route.ts` | `brand.llms`, contact, currency |
| `components/auto-hero.tsx` | `brand.hero`, hard-coded trust-chip labels |
| `components/fitment-finder.tsx` | `brand.fitments` (makes/models/years tree) |
| `components/service-brief.tsx` | `brand.serviceBrief` (3 cards) |
| `components/header.tsx`, `components/footer.tsx` | `brand.shortName`, `brand.header.nav`, `brand.footer`, `brand.contact`, `brand.socials` |
| `components/trust-bar.tsx` | `brand.trustItems` |
| `components/newsletter.tsx` | `brand.newsletter` |

## Auto-specific notes

- **Fitment is tag-based, not a custom_attribute.** Each product carries `tags: ["fits:toyota", "fits:toyota:corolla"]` etc. or `["fits:universal"]`. The shop page reads `?fits=<tag>` and filters by tag prefix match. Universal-fit products bypass the filter.
- **Adding a vehicle**: edit `brand.fitments.makes` in `lib/brand.ts`. Add `{ slug, name, models: [...] }`. Slug becomes the URL fragment.
- **Adding a part with new fitment**: tag the product `fits:<make>` and (optionally) `fits:<make>:<model>`. No schema change needed.
- **Partner-workshop fitting**: the mock doesn't model this; the storefront copy describes it. To wire it, eject the cart drawer and add a "Add fitting (GH₵80)" toggle that adds a service line.

## Known TODOs

- Contact form + newsletter signup currently fake their submit. Wire to a real provider.
- The fitment finder uses `useRouter().push` to a query-string URL; the catalogue page-side filter is left as an exercise for the merchant (read the `fits` param and pass it as a SDK `getProducts({ tags: [...] })` filter).

## Mock seed

Wired to `--seed auto` (Driveline Auto Parts). Edit `dev:mock` in `package.json` to preview another seed.

## 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, fitment-tag filtering, services with scheduling) — the SDK already gets price math, axis matching, tag filtering, and cart payload contracts right. Default to ejecting and restyling:

```bash
cimplify add cart-drawer
cimplify add variant-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>.
