diff --git a/.eslintrc.json b/.eslintrc.json
new file mode 100644
index 0000000..09b042e
--- /dev/null
+++ b/.eslintrc.json
@@ -0,0 +1,7 @@
+{
+ "extends": "next/core-web-vitals",
+ "rules": {
+ "@typescript-eslint/no-unused-vars": "warn",
+ "@typescript-eslint/no-explicit-any": "warn"
+ }
+}
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
new file mode 100644
index 0000000..4431d31
--- /dev/null
+++ b/.github/workflows/ci.yml
@@ -0,0 +1,101 @@
+name: CI
+
+on:
+ push:
+ branches: [main, develop]
+ pull_request:
+ branches: [main, develop]
+
+jobs:
+ lint:
+ name: Lint
+ runs-on: ubuntu-latest
+ steps:
+ - uses: actions/checkout@v4
+ - uses: actions/setup-node@v4
+ with:
+ node-version: "20"
+ cache: "npm"
+ - run: npm ci
+ - run: npm run lint
+
+ test:
+ name: Unit Tests
+ runs-on: ubuntu-latest
+ steps:
+ - uses: actions/checkout@v4
+ - uses: actions/setup-node@v4
+ with:
+ node-version: "20"
+ cache: "npm"
+ - run: npm ci
+ - run: npm test -- --coverage
+ - uses: codecov/codecov-action@v3
+ with:
+ fail_ci_if_error: false
+
+ e2e:
+ name: E2E Tests
+ runs-on: ubuntu-latest
+ steps:
+ - uses: actions/checkout@v4
+ - uses: actions/setup-node@v4
+ with:
+ node-version: "20"
+ cache: "npm"
+ - run: npm ci
+ - run: npx playwright install --with-deps
+ - run: npm run build
+ - run: npm run test:e2e
+ - uses: actions/upload-artifact@v4
+ if: failure()
+ with:
+ name: playwright-report
+ path: playwright-report/
+ retention-days: 7
+
+ build:
+ name: Build
+ runs-on: ubuntu-latest
+ needs: [lint, test]
+ steps:
+ - uses: actions/checkout@v4
+ - uses: actions/setup-node@v4
+ with:
+ node-version: "20"
+ cache: "npm"
+ - run: npm ci
+ - run: npm run build
+ - uses: actions/upload-artifact@v4
+ with:
+ name: build
+ path: .next/
+ retention-days: 1
+
+ deploy-preview:
+ name: Deploy Preview
+ runs-on: ubuntu-latest
+ needs: build
+ if: github.event_name == 'pull_request'
+ steps:
+ - uses: actions/checkout@v4
+ - uses: amondnet/vercel-action@v25
+ with:
+ vercel-token: ${{ secrets.VERCEL_TOKEN }}
+ vercel-org-id: ${{ secrets.VERCEL_ORG_ID }}
+ vercel-project-id: ${{ secrets.VERCEL_PROJECT_ID }}
+
+ deploy-production:
+ name: Deploy Production
+ runs-on: ubuntu-latest
+ needs: [build, e2e]
+ if: github.ref == 'refs/heads/main' && github.event_name == 'push'
+ environment: production
+ steps:
+ - uses: actions/checkout@v4
+ - uses: amondnet/vercel-action@v25
+ with:
+ vercel-token: ${{ secrets.VERCEL_TOKEN }}
+ vercel-org-id: ${{ secrets.VERCEL_ORG_ID }}
+ vercel-project-id: ${{ secrets.VERCEL_PROJECT_ID }}
+ vercel-args: "--prod"
diff --git a/.log b/.log
new file mode 100644
index 0000000..0bf7010
--- /dev/null
+++ b/.log
@@ -0,0 +1,15 @@
+# Execution Log
+
+## 2024-12-23 fix: Plan name shows as undefined on upgrade page
+
+- **Root cause:** Components passed undefined planId directly to getPlanById(), which returns undefined. This undefined value was rendered as text "undefined" in the UI when users had no subscription.
+- **Solution:** Added two new helper functions:
+ - `getDisplayPlanName(planId)` - Returns "Free" for undefined/null/unknown planIds
+ - `getPlanOrDefault(planId)` - Returns Free plan object for undefined/null/unknown planIds
+ - Updated UpgradePage.tsx and BillingOverview.tsx to use getPlanOrDefault()
+- **Files changed:**
+ - src/lib/plans.ts (added helper functions)
+ - src/components/UpgradePage.tsx (use getPlanOrDefault)
+ - src/components/BillingOverview.tsx (use getPlanOrDefault)
+ - tests/plan-display.test.ts (added verification tests)
+- **Tests:** 19 passing
diff --git a/.tasks b/.tasks
index 617cfac..b852cd5 100644
--- a/.tasks
+++ b/.tasks
@@ -2,13 +2,13 @@
## Format
# [ ] Not started
-# [~] In progress
+# [~] In progress
# [x] Done (YYYY-MM-DD)
# [!] Stuck - needs help
# [REVIEW] tag = Claude stops for approval
## Tasks
-[ ] First feature to build
-[ ] Second feature
-[ ] Payment integration [REVIEW]
+[x] Add aria-label to upgrade button in UpgradePage (2024-12-23)
+[x] Add TypeScript strict null check to tsconfig (2024-12-23)
+[x] Update package.json description (2024-12-23)
diff --git a/DESIGN-SYSTEM.md b/DESIGN-SYSTEM.md
new file mode 100644
index 0000000..fe04add
--- /dev/null
+++ b/DESIGN-SYSTEM.md
@@ -0,0 +1,149 @@
+# Design System: Billing Dashboard
+
+> Generated by Claude Code V7.7 on 2024-12-23
+
+## Color Palette
+
+### Semantic Tokens
+
+```css
+:root {
+ /* Primary */
+ --color-primary: #3b82f6;
+ --color-primary-hover: #2563eb;
+
+ /* Feedback */
+ --color-success: #22c55e;
+ --color-warning: #f59e0b;
+ --color-error: #ef4444;
+
+ /* Neutral */
+ --color-background: #ffffff;
+ --color-surface: #f9fafb;
+ --color-text: #111827;
+ --color-text-muted: #6b7280;
+ --color-border: #e5e7eb;
+}
+
+/* Dark mode */
+[data-theme="dark"] {
+ --color-background: #111827;
+ --color-surface: #1f2937;
+ --color-text: #f9fafb;
+}
+```
+
+## Typography
+
+| Role | Font | Size | Weight |
+| --------- | ----- | -------- | ------ |
+| Heading 1 | Inter | 2rem | 700 |
+| Heading 2 | Inter | 1.5rem | 600 |
+| Body | Inter | 1rem | 400 |
+| Caption | Inter | 0.875rem | 400 |
+
+## Spacing Scale
+
+```
+4px - xs
+8px - sm
+12px - md
+16px - lg
+24px - xl
+32px - 2xl
+48px - 3xl
+```
+
+## Component Library
+
+**Choice:** Custom components with Tailwind CSS
+
+**Installed Components:**
+
+- [x] Button
+- [x] Card
+- [x] BillingOverview
+- [x] UpgradePage
+- [x] UsageMetrics _(new)_
+
+## Components
+
+### UsageMetricsCard
+
+**Purpose:** Display current usage metrics (API calls, storage, team members) with progress bars.
+
+**File:** `src/components/UsageMetrics.tsx`
+
+**Props:**
+
+```typescript
+interface UsageMetricsProps {
+ metrics: UsageMetrics | null;
+ planLimits: { apiCalls: number; storageUsed: number; teamMembers: number };
+ isLoading?: boolean;
+ error?: string | null;
+}
+```
+
+**States:**
+
+| State | Component | Description |
+| ------- | ----------------- | ---------------------------------------------- |
+| Loading | `LoadingSkeleton` | Skeleton placeholders with aria-busy |
+| Empty | `EmptyState` | Guidance: "Start using the API to see metrics" |
+| Error | `ErrorState` | Error message + "Try Again" button |
+| Success | `SuccessState` | Three metric cards with progress bars |
+
+**Metrics Displayed:**
+
+- API Calls (count / limit)
+- Storage (GB / limit)
+- Team Members (seats / limit)
+
+**Visual Indicators:**
+
+- Green bar: < 80% usage
+- Yellow bar: 80-99% usage
+- Red bar: 100%+ usage (over limit)
+
+**Accessibility:**
+
+- `aria-busy="true"` on loading state
+- `role="alert"` on error state
+- `aria-label` on retry button
+- `aria-hidden` on decorative icons
+
+**Usage:**
+
+```tsx
+
+```
+
+---
+
+### BillingOverview
+
+**Purpose:** Display current plan with upgrade CTA.
+
+**File:** `src/components/BillingOverview.tsx`
+
+**States:** Loading, Success only (simple component)
+
+---
+
+### UpgradePage
+
+**Purpose:** Show plan options and allow upgrades.
+
+**File:** `src/components/UpgradePage.tsx`
+
+**States:** Loading, Success
+
+---
+
+_Last updated: 2024-12-23_
diff --git a/README.md b/README.md
index e9b3e75..92003c4 100644
--- a/README.md
+++ b/README.md
@@ -1,154 +1,158 @@
-# Claude Code V7.7
+# Billing Dashboard
-**From Coding Assistant to Production App Builder**
+> A SaaS billing dashboard built with Next.js, Stripe, and React Native companion app.
-Claude Code V7.7 transforms from a coding assistant into a production app builder by adding domain expertise, progressive documentation, and minimal subagents.
+## Quick Start
-## What's New in V7.7
+```bash
+# Clone the repository
+git clone https://github.com/example/billing-dashboard.git
+cd billing-dashboard
-### Domain Skills (11 NEW)
+# Install dependencies
+npm install
-Skills provide domain expertise without agent overhead (~500 tokens vs ~15x for agents):
+# Copy environment variables
+cp .env.example .env.local
-| Skill | Purpose | Auto-generates |
-|-------|---------|----------------|
-| `ui-design` | Visual design, design systems | DESIGN-SYSTEM.md |
-| `frontend` | React, state management | - |
-| `backend` | APIs, business logic | docs/API-CONTRACTS.md |
-| `database` | Schema, queries, Supabase | docs/DATA-MODELS.md |
-| `testing` | Jest, Playwright, E2E | - |
-| `performance` | Core Web Vitals, optimization | - |
-| `accessibility` | WCAG compliance | - |
-| `devops` | CI/CD, deployment | docs/DEPLOYMENT.md, RUNBOOK.md, MONITORING.md |
-| `integration` | Stripe, Auth0, third-party | Appends to API-CONTRACTS.md |
-| `mobile` | React Native, Expo | - |
-| `documentation` | README, guides | README.md |
+# Run development server
+npm run dev
-### New Agents (2)
+# Open http://localhost:3000
+```
-| Agent | Purpose |
-|-------|---------|
-| `initializer` | Project setup (Anthropic two-agent pattern) |
-| `researcher` | External API verification with web access |
+## Tech Stack
-### Enhanced Agents (2)
+| Layer | Technology |
+| ------------- | ----------------------- |
+| **Framework** | Next.js 14 (App Router) |
+| **Language** | TypeScript |
+| **Styling** | Tailwind CSS |
+| **Payments** | Stripe |
+| **Analytics** | Plausible |
+| **Testing** | Jest + Playwright |
+| **Mobile** | React Native + Expo |
-- **explorer** - Now returns structured output, max 2000 tokens
-- **reviewer** - Now checks if documentation was updated
+## Project Structure
-### New Command
+```
+billing-dashboard/
+├── src/
+│ ├── app/ # Next.js App Router pages
+│ ├── components/ # React components
+│ │ ├── BillingOverview.tsx
+│ │ ├── Dashboard.tsx
+│ │ ├── UpgradePage.tsx
+│ │ └── UsageMetrics.tsx
+│ ├── lib/ # Utilities
+│ │ ├── plans.ts # Plan data and helpers
+│ │ └── subscription.ts
+│ ├── hooks/ # Custom React hooks
+│ └── types/ # TypeScript types
+├── tests/ # Jest unit tests
+├── e2e/ # Playwright E2E tests
+├── mobile/ # React Native companion app
+├── docs/ # Documentation
+│ ├── DEPLOYMENT.md
+│ ├── RUNBOOK.md
+│ └── MONITORING.md
+└── .github/workflows/ # CI/CD
+```
-- `/launch` - Production readiness checklist
+## Environment Variables
+
+| Variable | Required | Description |
+| ------------------------ | -------- | ----------------------------- |
+| `DATABASE_URL` | Yes | PostgreSQL connection string |
+| `NEXTAUTH_SECRET` | Yes | Auth encryption key |
+| `NEXTAUTH_URL` | Yes | App base URL |
+| `STRIPE_SECRET_KEY` | Yes | Stripe secret key |
+| `STRIPE_PUBLISHABLE_KEY` | Yes | Stripe publishable key |
+| `STRIPE_WEBHOOK_SECRET` | Yes | Stripe webhook signing secret |
+| `PLAUSIBLE_DOMAIN` | No | Plausible analytics domain |
+
+## Available Scripts
+
+```bash
+npm run dev # Start development server
+npm run build # Production build
+npm run start # Start production server
+npm run lint # Run ESLint
+npm test # Run unit tests
+npm run test:e2e # Run Playwright E2E tests
+npm run test:e2e:ui # Run Playwright with UI
+```
-### Document Templates (10)
+## Features
-Pre-built templates ensure consistent documentation:
-- ARCHITECTURE.template.md
-- DESIGN-SYSTEM.template.md
-- API-CONTRACTS.template.md
-- DATA-MODELS.template.md
-- AUTH-FLOWS.template.md
-- DEPLOYMENT.template.md
-- RUNBOOK.template.md
-- MONITORING.template.md
-- SECURITY.template.md
-- PRODUCTION-CHECKLIST.template.md
+### Billing Dashboard
-## Quick Start
+- View current subscription plan
+- Display usage metrics (API calls, storage, team members)
+- Upgrade/downgrade plans
+- Access Stripe Customer Portal
-1. Copy `.claude/` folder to your project root
-2. Copy `CLAUDE.md` to your project root
-3. Start coding: `/build "add user authentication"`
+### Usage Analytics
-## Architecture
+- Real-time usage tracking
+- Progress bars with limit warnings
+- Color-coded status (green/yellow/red)
-```
-┌─────────────────────────────────────────────────────────────────┐
-│ MAIN AGENT (Coding Agent) │
-│ │
-│ - Receives user commands (/build, /fix, /quick, /launch) │
-│ - Loads skills on-demand (20 skills) │
-│ - Follows Iron Laws (TDD, Verification, Debugging) │
-│ - Skills auto-generate documentation as they work │
-│ │
-└─────────────────────────────────────────────────────────────────┘
- │ │ │ │
- ▼ ▼ ▼ ▼
- ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐
- │initializer│ │ explorer │ │ reviewer │ │researcher│
- │ │ │ │ │ │ │ │
- │ Project │ │ Read-only│ │ Code │ │ API/docs │
- │ setup │ │ explore │ │ review │ │ verify │
- └──────────┘ └──────────┘ └──────────┘ └──────────┘
-```
+### Mobile App
+
+- React Native companion app
+- View plan details on the go
+- Same features as web dashboard
-## Key Decisions
+## Testing
-### Skills > Agents for Domain Expertise
+### Unit Tests (Jest)
-Each subagent spawns with a fresh 200K context window, adding ~15x token overhead. Skills load into the main context (~500 tokens each) and share context with the workflow.
+```bash
+npm test
+```
-### Progressive Documentation
+### E2E Tests (Playwright)
-Documents aren't generated upfront. Skills append to docs as they work:
-- Create API endpoint → Append to API-CONTRACTS.md
-- Create UI component → Append to DESIGN-SYSTEM.md
-- Create table → Append to DATA-MODELS.md
+```bash
+npm run test:e2e
+```
-### Four Agents Only
+### Test Coverage Targets
-1. **initializer** - Project setup
-2. **explorer** - Read-only codebase investigation
-3. **reviewer** - Code review before commit
-4. **researcher** - External API verification
+- Unit tests: 80%+ coverage
+- E2E tests: Critical user journeys
-## Version History
+## Deployment
-| Version | Key Changes |
-|---------|-------------|
-| V7.7 | Domain skills, progressive docs, 4 agents, /launch |
-| V7.6 | Skills-based, softer guidance, 9/10 stress test |
-| V7.4 | Iron Laws, rationalization tables |
-| V7.0 | Skills architecture |
+See [docs/DEPLOYMENT.md](docs/DEPLOYMENT.md) for complete deployment guide.
-## Files
+Quick deploy to Vercel:
-```
-project/
-├── CLAUDE.md # Project instructions
-├── ARCHITECTURE.md # Generated on first /build
-├── DESIGN-SYSTEM.md # Generated by ui-design skill
-├── SCRATCHPAD.md # Session continuity
-├── .tasks # Task queue
-├── .log # Execution history
-│
-├── docs/
-│ ├── API-CONTRACTS.md # Generated by backend skill
-│ ├── DATA-MODELS.md # Generated by database skill
-│ ├── AUTH-FLOWS.md # Generated by security skill
-│ ├── DEPLOYMENT.md # Generated by devops skill
-│ ├── RUNBOOK.md # Generated by devops skill
-│ ├── MONITORING.md # Generated by devops skill
-│ └── PRODUCTION-CHECKLIST.md # Generated by /launch
-│
-└── .claude/
- ├── settings.json # Hook configuration
- ├── skills/ # 20 skills
- ├── agents/ # 4 agents
- ├── commands/ # 8 commands
- ├── templates/ # 10 doc templates
- ├── hooks/ # 6 hooks
- └── state/ # Workflow state
+```bash
+vercel --prod
```
-## Iron Laws (Preserved)
+## Documentation
-```
-1. NO PRODUCTION CODE WITHOUT A FAILING TEST FIRST
-2. NO FIXES WITHOUT ROOT CAUSE INVESTIGATION FIRST
-3. NO COMPLETION CLAIMS WITHOUT FRESH VERIFICATION EVIDENCE
-```
+| Document | Description |
+| ------------------------------------ | --------------------- |
+| [DESIGN-SYSTEM.md](DESIGN-SYSTEM.md) | Component library |
+| [DEPLOYMENT.md](docs/DEPLOYMENT.md) | Deployment procedures |
+| [RUNBOOK.md](docs/RUNBOOK.md) | Incident response |
+| [MONITORING.md](docs/MONITORING.md) | Metrics and alerts |
+
+## Contributing
+
+1. Create a feature branch
+2. Write tests first (TDD)
+3. Submit PR for review
+4. CI must pass before merge
## License
MIT
+
+---
+
+_Built with Claude Code V7.7_
diff --git a/SCRATCHPAD.md b/SCRATCHPAD.md
new file mode 100644
index 0000000..3a53497
--- /dev/null
+++ b/SCRATCHPAD.md
@@ -0,0 +1,150 @@
+# Scratchpad
+
+## Session Continuity
+
+This file tracks the current session state, API verifications, and investigation notes.
+
+## Current Status
+
+- Project: Billing Dashboard
+- Phase: Part 2 Testing
+- Last Updated: 2024-12-23
+
+## API Verifications
+
+### Plausible Analytics (via Researcher Agent + WebSearch/WebFetch)
+
+**Verified:** 2024-12-23
+**Documentation:** https://plausible.io/docs
+
+| Method | Status | Notes |
+| ------------------ | ----------- | -------------------------------------------------------------------------- |
+| JavaScript Snippet | ✅ Verified | `