Prod Release: SEO + V3 Transitivity + GBP + Card Pioneers (flagged)

.cursorrules

@@ -10,6 +10,7 @@
 - **Do not generate .md files** unless explicity told to do so.
 - **Comments** should always be made in all lowercase and simple english
 - **Error messages**, any error being shown in the ui should be user friendly and easy to understand, and any error being logged in consoles and sentry should be descriptive for developers to help with debugging
+- **Never add AI co-author to commits** - do not add "Co-Authored-By" lines for AI assistants in git commits
 
 ## 💻 Code Quality
 
@@ -78,6 +79,57 @@
 - **Service Worker cache version** - only bump `NEXT_PUBLIC_API_VERSION` for breaking API changes (see JSDoc in `src/app/sw.ts`). Users auto-migrate.
 - **Gate heavy features in dev** - prefetching, precompiling, or eager loading of routes can add 5-10s to dev cold starts. wrap with `process.env.NODE_ENV !== 'development'` (e.g. `<link rel="prefetch" href="/qr-pay" />` in layout.tsx).
 
+## 🎨 Design System
+
+- **Live showcase**: visit `/dev/components` to see all components rendered with all variants and copy-paste code
+- **Three layers**: Bruddle primitives (`src/components/0_Bruddle/`), Global shared components (`src/components/Global/`), and Tailwind custom classes (`tailwind.config.js`)
+
+### Bruddle Primitives (`0_Bruddle/`)
+- Button, Card (named export), BaseInput, BaseSelect, Checkbox, Divider, Title, Toast, PageContainer, CloudsBackground
+
+### Global Shared Components (`Global/`)
+- **Navigation**: NavHeader (back button + title), TopNavbar, Footer
+- **Modals**: Modal (base @headlessui Dialog), ActionModal (with buttons/checkboxes/icons), Drawer (vaul bottom sheet)
+- **Loading**: Loading (spinner), PeanutLoading (branded), PeanutFactsLoading (with fun facts)
+- **Cards**: Card (with position prop for stacked lists), InfoCard, PeanutActionCard
+- **Status**: StatusPill, StatusBadge, ErrorAlert, ProgressBar
+- **Icons**: Icon component with 50+ icons — `<Icon name="check" size={20} />`
+- **Inputs**: AmountInput, ValidatedInput, CopyField, GeneralRecipientInput, TokenSelector
+- **Utilities**: CopyToClipboard, AddressLink, ExternalWalletButton, ShareButton, Banner, MarqueeWrapper
+
+### Color Names (misleading!)
+- `purple-1` / `primary-1` = `#FF90E8` (pink, not purple)
+- `primary-3` = `#EFE4FF` (lavender)
+- `yellow-1` / `secondary-1` = `#FFC900`
+- `green-1` = `#98E9AB`
+
+### Key Rules
+- **Button sizing trap**: `size="large"` is `h-10` (40px) — SHORTER than default `h-13` (52px). never use for primary CTAs
+- **Primary CTA**: `<Button variant="purple" shadowSize="4" className="w-full">` — no size prop
+- **Secondary CTA**: `<Button variant="stroke" className="w-full">`
+- **Shadows**: always black `#000000`. use `shadowSize="4"` for action buttons
+- **Border radius**: always `rounded-sm` (not rounded-lg or rounded-md)
+- **Border stroke**: `border border-n-1` (1px black)
+- **Links**: `text-black underline` — never `text-purple-1` (pink)
+- **Text hierarchy**: `text-n-1` primary, `text-grey-1` secondary
+- **Two Card components**: `0_Bruddle/Card` (standalone containers, named export) vs `Global/Card` (stacked list items, default export)
+- **Backgrounds**: `bg-peanut-repeat-normal` for waving peanut pattern
+- **Messaging**: use "starter balance" for card deposits — never "card balance" or "Peanut rewards"
+
+### Page Layouts
+
+- **Outer shell**: `flex min-h-[inherit] flex-col gap-8` — NavHeader is first child
+- **Centered content + CTA** (default): wrap content AND CTA in `<div className="my-auto flex flex-col gap-6">`. CTA must be INSIDE this div, never a sibling
+- **Pinned footer CTA**: add `justify-between` to outer div, CTA as last child outside content
+- **Never** use `space-y-*` on the outer flex div (conflicts with centering) — use `gap-*` instead
+
+## ✅ Before Pushing
+
+- **Format**: `pnpm prettier --write <changed-files>` then verify with `pnpm prettier --check .`
+- **Typecheck**: `npm run typecheck` — catches type errors that tests miss (tests don't run tsc)
+- **Test**: `npm test` (fast, ~5s) — all 17 suites must pass
+- **Build** (if touching imports/types): `npm run build` to catch compile errors
+
 ## 📝 Commits
 
 - **Be descriptive**

.github/workflows/preview.yaml

@@ -12,6 +12,7 @@ jobs:
             - uses: actions/checkout@v4
               with:
                   submodules: true
+                  token: ${{ secrets.SUBMODULE_TOKEN }}
             - uses: pnpm/action-setup@v4
               with:
                   version: 9
@@ -24,4 +25,4 @@ jobs:
             - name: Build Project Artifacts
               run: vercel build --target=preview --token=${{ secrets.VERCEL_TOKEN }}
             - name: Deploy Project Artifacts to Vercel
-              run: vercel deploy --prebuilt --target=preview --token=${{ secrets.VERCEL_TOKEN }}
+              run: vercel deploy --prebuilt --archive=tgz --target=preview --token=${{ secrets.VERCEL_TOKEN }}

.github/workflows/tests.yml

@@ -9,6 +9,9 @@ jobs:
         runs-on: ubuntu-latest
         steps:
             - uses: actions/checkout@v4
+              with:
+                  submodules: true
+                  token: ${{ secrets.SUBMODULE_TOKEN }}
 
             - uses: actions/setup-node@v4
               with:
@@ -24,11 +27,24 @@ jobs:
             - name: Check formatting
               run: pnpm prettier --check .
 
-            - name: Run Tests
+            - name: Run Unit Tests
               run: pnpm test
 
+            - name: Install Playwright Browsers
+              run: npx playwright install --with-deps chromium
+
+            - name: Run E2E Tests
+              run: pnpm test:e2e
+
             - name: Upload Coverage
               uses: actions/upload-artifact@v4
               with:
                   name: coverage
                   path: coverage/
+
+            - name: Upload Playwright Report
+              if: always()
+              uses: actions/upload-artifact@v4
+              with:
+                  name: playwright-report
+                  path: playwright-report/

.gitignore

@@ -16,6 +16,9 @@ PR.md
 
 # testing
 /coverage
+/test-results/
+/playwright-report/
+/playwright/.cache/
 
 # next.js
 /.next/
@@ -70,3 +73,7 @@ public/sw*
 public/swe-worker*
 
 .idea
+
+# mobile POC
+android/
+.claude/

.gitmodules

@@ -1,3 +1,6 @@
 [submodule "src/assets/animations"]
 	path = src/assets/animations
 	url = https://github.com/peanutprotocol/peanut-animations.git
+[submodule "src/content"]
+	path = src/content
+	url = https://github.com/peanutprotocol/peanut-content.git

README.md

@@ -1,3 +1,15 @@
+# Peanut UI
+
+[![Tests](https://github.com/peanutprotocol/peanut-ui/actions/workflows/tests.yml/badge.svg)](https://github.com/peanutprotocol/peanut-ui/actions/workflows/tests.yml)
+[![Code Formatting](https://github.com/peanutprotocol/peanut-ui/actions/workflows/prettier.yml/badge.svg)](https://github.com/peanutprotocol/peanut-ui/actions/workflows/prettier.yml)
+[![CodeQL](https://github.com/peanutprotocol/peanut-ui/actions/workflows/codeql.yml/badge.svg)](https://github.com/peanutprotocol/peanut-ui/actions/workflows/codeql.yml)
+[![Next.js](https://img.shields.io/badge/Next.js-16-black?logo=next.js)](https://nextjs.org/)
+[![React](https://img.shields.io/badge/React-19-61DAFB?logo=react)](https://react.dev/)
+[![TypeScript](https://img.shields.io/badge/TypeScript-5.6-3178C6?logo=typescript&logoColor=white)](https://www.typescriptlang.org/)
+[![Tailwind CSS](https://img.shields.io/badge/Tailwind-4-06B6D4?logo=tailwindcss&logoColor=white)](https://tailwindcss.com/)
+[![i18n](https://img.shields.io/badge/i18n-5_locales-blue)](https://peanut.me)
+[![PWA Ready](https://img.shields.io/badge/PWA-ready-5A0FC8?logo=pwa)](https://peanut.me)
+
 Live at: [peanut.me](https://peanut.me) | [staging.peanut.me](https://staging.peanut.me)
 
 ## Getting Started

docs/TESTING.md

@@ -0,0 +1,170 @@
+# Testing Philosophy
+
+## Overview
+
+peanut-ui uses a focused testing strategy that prioritizes **high-value tests** over coverage theater. We test critical paths that catch real bugs, not to hit arbitrary coverage percentages.
+
+## Test Types
+
+### 1. Unit Tests (Jest)
+
+**Location**: Tests live with the code they test (e.g. `src/utils/foo.test.ts`)
+
+**What we test**:
+- Pure business logic (calculations, validations, transformations)
+- Complex utility functions
+- Critical algorithms (e.g. point calculations, country eligibility)
+
+**What we DON'T test**:
+- React components (brittle, low ROI)
+- API service wrappers (thin fetch calls)
+- Hooks that just wrap react-query (already tested upstream)
+- JSX/UI layout (visual QA better)
+
+**Run tests**:
+- `npm test` - Run all unit tests
+- `npm run test:watch` - Run tests in watch mode
+
+### 2. E2E Tests (Playwright)
+
+**Location**: Tests live with features they test (e.g. `src/features/card-pioneer/card-pioneer.e2e.test.ts`)
+
+**What we test**:
+- ✅ Multi-step navigation flows
+- ✅ Form validation and error states
+- ✅ URL state management (nuqs integration)
+- ✅ Auth flows (signup, login, logout)
+- ✅ UI interactions without external dependencies
+
+**What we DON'T test**:
+- ❌ Payment flows (require real transactions)
+- ❌ KYC flows (external API dependencies)
+- ❌ Bank transfers (real money, manual QA required)
+- ❌ Wallet connections (MetaMask/WalletConnect popups)
+
+**Why this split?**
+External dependencies (payments, KYC, banks) are better tested manually because:
+1. They require real credentials and real money
+2. They have complex state (KYC approval status, bank account verification)
+3. They involve third-party UIs (wallet popups, bank OAuth)
+4. Manual QA catches edge cases E2E can't simulate
+
+**Run tests**:
+- `npm run test:e2e` - Run all E2E tests (headless)
+- `npm run test:e2e:headed` - Run with browser visible
+- `npm run test:e2e:ui` - Run in interactive UI mode
+- `npx playwright test --grep "Card Pioneer"` - Run specific test suite
+- `npx playwright test --list` - List all tests without running
+
+## Testing Principles
+
+### 1. Test Critical Paths Only
+
+Focus on code that:
+- Has financial impact (payment calculations, point multipliers)
+- Has legal requirements (sanctions compliance, geo restrictions)
+- Has security implications (reference parsing, user ID extraction)
+- Is complex or hard to verify manually (date logic, ISO code mappings)
+
+### 2. Fast Tests
+
+- Unit tests run in ~5s
+- E2E tests focus on minimal, high-value flows
+- No unnecessary setup/teardown
+- Mock external APIs but keep mocks simple
+
+### 3. Tests Live With Code
+
+Per .cursorrules: tests live where the code they test is, not in a separate folder.
+
+```
+src/
+  utils/
+    geo.ts
+    geo.test.ts          ← unit test
+  features/
+    card-pioneer/
+      card-pioneer.tsx
+      card-pioneer.e2e.test.ts  ← e2e test
+```
+
+### 4. DRY in Tests
+
+Reuse test utilities, shared fixtures, and helper functions. Less code is better code.
+
+## Example Test Scenarios
+
+### Unit Test Example
+
+```typescript
+// src/utils/country-codes.test.ts
+describe('convertIso3ToIso2', () => {
+  it('should convert USA to US', () => {
+    expect(convertIso3ToIso2('USA')).toBe('US')
+  })
+
+  it('should handle sanctioned countries', () => {
+    expect(convertIso3ToIso2('CUB')).toBe('CU') // Cuba
+    expect(convertIso3ToIso2('VEN')).toBe('VE') // Venezuela
+  })
+})
+```
+
+### E2E Test Example
+
+```typescript
+// src/features/card-pioneer/card-pioneer.e2e.test.ts
+test('user can navigate card pioneer flow', async ({ page }) => {
+  await page.goto('/card-pioneer')
+
+  // step 1: info screen
+  await expect(page.getByRole('heading', { name: /card pioneer/i })).toBeVisible()
+  await page.getByRole('button', { name: /get started/i }).click()
+
+  // step 2: details screen (check URL state)
+  await expect(page).toHaveURL(/step=details/)
+  await page.getByRole('button', { name: /continue/i }).click()
+
+  // step 3: geo check
+  await expect(page).toHaveURL(/step=geo/)
+})
+```
+
+## When to Add Tests
+
+Add tests when:
+1. Implementing new financial logic
+2. Handling compliance requirements
+3. Complex algorithms or data transformations
+4. Bug fixes (regression tests)
+
+Skip tests when:
+1. Just rendering JSX
+2. Thin wrappers around libraries
+3. Purely visual changes
+4. Code that's easier to verify manually
+
+## CI Integration
+
+- Unit tests run on every PR
+- E2E tests run on PR to main
+- Fail fast: first failure stops the build
+
+## Maintenance
+
+Keep tests:
+- **Concise** - no verbose setup or comments
+- **Focused** - one concern per test
+- **Stable** - avoid flaky selectors or timing issues
+- **Up-to-date** - delete tests for removed features
+
+When tests fail:
+1. Fix the bug (if test caught a real issue)
+2. Update the test (if behavior intentionally changed)
+3. Delete the test (if feature was removed)
+
+## Resources
+
+- Jest: https://jestjs.io/
+- Playwright: https://playwright.dev/
+- Testing Library: https://testing-library.com/ (for React unit tests if needed)

package.json

@@ -15,10 +15,15 @@
         "knip": "knip",
         "format": "prettier --write .",
         "analyze": "ANALYZE=true next build",
+        "typecheck": "tsc --noEmit",
         "test": "jest",
         "test:watch": "jest --watch",
         "test:coverage": "jest --coverage",
-        "script": "NODE_OPTIONS=\"--experimental-json-modules\" tsx"
+        "test:e2e": "playwright test",
+        "test:e2e:ui": "playwright test --ui",
+        "test:e2e:headed": "playwright test --headed",
+        "script": "NODE_OPTIONS=\"--experimental-json-modules\" tsx",
+        "validate-content": "tsx scripts/validate-content.ts"
     },
     "dependencies": {
         "@dicebear/collection": "^9.2.2",
@@ -48,19 +53,22 @@
         "@vercel/analytics": "^1.4.1",
         "@wagmi/core": "2.19.0",
         "@zerodev/passkey-validator": "^5.6.0",
-        "@zerodev/sdk": "5.5.0",
+        "@zerodev/sdk": "5.5.7",
         "autoprefixer": "^10.4.20",
         "canvas-confetti": "^1.9.3",
         "classnames": "^2.5.1",
         "d3-force": "^3.0.0",
         "embla-carousel-react": "^8.6.0",
         "ethers": "5.7.2",
         "framer-motion": "^11.11.17",
+        "gray-matter": "^4.0.3",
         "i18n-iso-countries": "^7.13.0",
         "iban-to-bic": "^1.4.0",
         "js-cookie": "^3.0.5",
         "jsqr": "^1.4.0",
+        "marked": "^17.0.2",
         "next": "16.0.10",
+        "next-mdx-remote": "^6.0.0",
         "nuqs": "^2.8.6",
         "pix-utils": "^2.8.2",
         "pulltorefreshjs": "^0.1.22",
@@ -75,6 +83,8 @@
         "react-redux": "^9.2.0",
         "react-tooltip": "^5.28.0",
         "redux": "^5.0.1",
+        "remark-gfm": "^4.0.1",
+        "shiki": "^3.22.0",
         "siwe": "^2.3.2",
         "tailwind-merge": "^1.14.0",
         "tailwind-scrollbar": "^3.1.0",
@@ -86,6 +96,7 @@
     },
     "devDependencies": {
         "@next/bundle-analyzer": "^16.1.1",
+        "@playwright/test": "^1.58.0",
         "@serwist/build": "^9.0.10",
         "@size-limit/preset-app": "^11.2.0",
         "@testing-library/jest-dom": "^6.4.2",
@@ -147,6 +158,10 @@
             "**/__tests__/**/*.test.[jt]s?(x)",
             "**/?(*.)+(spec|test).[jt]s?(x)"
         ],
+        "testPathIgnorePatterns": [
+            "/node_modules/",
+            "\\.e2e\\.test\\.(ts|tsx)$"
+        ],
         "extensionsToTreatAsEsm": [
             ".ts",
             ".tsx"