docs: update README and add AGENTS.md for agent guidance

AGENTS.md

@@ -0,0 +1,127 @@
+# EuchreCamp - Agent Guide
+
+This document provides guidance for AI agents working on the EuchreCamp project.
+
+## Project Overview
+
+EuchreCamp is a Next.js 14+ application for managing Euchre tournaments and tracking partnership analytics.
+
+### Key Technologies
+- **Next.js 14+** (App Router)
+- **TypeScript**
+- **Prisma ORM** (SQLite)
+- **Tailwind CSS**
+- **Better Auth** (Authentication)
+- **Vitest** (Unit Testing)
+- **Playwright** (Acceptance Testing)
+
+## Architecture Patterns
+
+### Authentication & Authorization
+- **Session Management**: Better Auth with cookie-based sessions
+- **Role-Based Access Control**: Three roles (player, tournament_admin, club_admin)
+- **Permission Functions**: Located in `src/lib/permissions.ts`
+- **Session Cache**: Disabled to avoid stale role data
+
+### Database Schema
+- **Players**: `id`, `name`, `currentElo`, `gamesPlayed`, `wins`, `losses`
+- **Users**: `id`, `email`, `role`, `playerId` (foreign key to players)
+- **Events**: Tournaments with `ownerId` for ownership tracking
+- **Matches**: Individual match results with `createdById` for tracking
+
+### Data Flow
+1. User authentication via Better Auth
+2. Session stored in HTTP-only cookies
+3. Permission checks read directly from database
+4. API routes enforce authorization
+
+## Common Tasks
+
+### Fixing Authentication Issues
+If users are redirected incorrectly or permissions aren't working:
+1. Check if cookie cache is disabled in `src/lib/auth.ts`
+2. Verify permission functions read from database, not session
+3. Ensure `getSession()` uses `disableCookieCache=true`
+
+### Adding New Features
+1. Create API route in `src/app/api/`
+2. Add permission checks using functions from `src/lib/permissions.ts`
+3. Create UI component in `src/app/` or `src/components/`
+4. Add tests in `src/__tests__/`
+5. Run tests: `npm run test` and `npm run test:acceptance`
+
+### Database Changes
+1. Edit `prisma/schema.prisma`
+2. Run `npx prisma migrate dev --name <migration-name>`
+3. Run `npx prisma generate`
+4. Update affected API routes and components
+
+### Running Tests
+- **Unit tests**: `npm run test`
+- **Acceptance tests**: `npm run test:acceptance`
+- **Specific test**: `npm run test:acceptance -- --grep "test name"`
+
+## Key Files
+
+### Configuration
+- `src/lib/auth.ts` - Better Auth configuration
+- `src/lib/permissions.ts` - Authorization functions
+- `src/lib/elo-utils.ts` - Elo calculation logic
+
+### API Routes
+- `src/app/api/auth/[[...all]]/route.ts` - Better Auth API
+- `src/app/api/tournaments/route.ts` - Tournament management
+- `src/app/api/matches/upload/route.ts` - CSV upload processing
+
+### UI Components
+- `src/components/Navigation.tsx` - Navigation with role-based links
+- `src/app/page.tsx` - Home page with top players, recent tournament, club president
+- `src/app/players/[id]/profile/page.tsx` - Player profile with stats
+
+### Tests
+- `src/__tests__/unit/permissions.test.ts` - Permission function tests
+- `src/__tests__/unit/elo.test.ts` - Elo calculation tests
+- `src/__tests__/e2e/global.setup.ts` - Test setup with admin user creation
+- `src/__tests__/e2e/home-page.test.ts` - Home page tests
+
+## Troubleshooting
+
+### Session Cache Issues
+**Problem**: Updated user roles don't reflect in session
+**Solution**: Ensure cookie cache is disabled and permission functions read from database
+
+### Test Failures
+**Problem**: Tests timing out or failing unexpectedly
+**Solution**:
+- Check if dev server is running
+- Verify database is accessible
+- Run tests with `--headed` to see browser
+
+### Database Conflicts
+**Problem**: Tests interfering with each other
+**Solution**: Tests run sequentially with `fullyParallel: false` and `workers: 1`
+
+## Conventions
+
+### Commit Messages
+- Use conventional commit format: `<type>: <description>`
+- Types: `feat`, `fix`, `docs`, `style`, `refactor`, `test`, `chore`, `ci`
+
+### Code Style
+- Use TypeScript for type safety
+- Prefer React Server Components for data fetching
+- Keep business logic in `src/lib/` directory
+- Write tests for new features
+
+### File Naming
+- Components: PascalCase (e.g., `Navigation.tsx`)
+- Utilities: camelCase (e.g., `elo-utils.ts`)
+- Tests: `.test.ts` or `.test.tsx` suffix
+
+## Resources
+
+- **Better Auth Docs**: https://better-auth.com/docs
+- **Next.js Docs**: https://nextjs.org/docs
+- **Prisma Docs**: https://www.prisma.io/docs
+- **Playwright Docs**: https://playwright.dev
+- **Vitest Docs**: https://vitest.dev/

README.md

@@ -1,27 +1,29 @@
 # EuchreCamp
 
-A comprehensive tournament management and partnership analytics system for the card game Euchre, built with Next.js, TypeScript, and Prisma.
+A comprehensive tournament management and partnership analytics system for the card game Euchre.
 
 ## Overview
 
-EuchreCamp is a full-stack web application that provides:
+EuchreCamp is a full-stack web application built with Next.js 14+ and TypeScript that provides:
 
 - **Tournament Management**: Create and manage round-robin, single elimination, double elimination, and Swiss-style tournaments
 - **Partnership Analytics**: Track partnership performance, win rates, and Elo changes between players
 - **Player Profiles**: Display individual player statistics and partnership breakdowns
 - **Admin Dashboard**: Centralized management interface for tournaments, players, and matches
-- **CSV Import**: Batch import match results from CSV files
 - **Authentication & Authorization**: Role-based access control with player, tournament_admin, and club_admin roles
+- **Home Page**: Public-facing landing page showing top players, recent tournaments, and club information
 
 ## Tech Stack
 
-- **Framework**: Next.js 16 (App Router)
+- **Framework**: Next.js 14+ (App Router)
 - **Language**: TypeScript
 - **Database**: Prisma ORM with SQLite
 - **Styling**: Tailwind CSS
-- **Authentication**: NextAuth.js
+- **Authentication**: Better Auth
 - **Form Handling**: React Hook Form + Zod validation
 - **CSV Parsing**: PapaParse
+- **Unit Testing**: Vitest
+- **Acceptance Testing**: Playwright
 
 ## Project Structure
 
@@ -33,11 +35,17 @@ euchre_camp/
 │   │   ├── auth/         # Authentication pages
 │   │   ├── admin/        # Admin pages
 │   │   ├── players/      # Player pages
-│   │   ├── components/   # Shared components
+│   │   ├── rankings/     # Rankings page
-│   │   └── lib/          # Utilities and configuration
+│   │   └── components/   # Shared components
-│   └── types/            # TypeScript type definitions
+│   ├── lib/              # Utilities and configuration
+│   │   ├── auth.ts       # Better Auth configuration
+│   │   ├── prisma.ts     # Prisma client
+│   │   ├── permissions.ts # Authorization functions
+│   │   └── elo-utils.ts  # Elo calculation utilities
+│   └── __tests__/        # Vitest and Playwright tests
 ├── prisma/               # Prisma schema and migrations
 ├── docs/                 # Documentation
+├── scripts/              # Utility scripts
 └── public/               # Static assets
 ```
 
@@ -47,18 +55,20 @@ euchre_camp/
 - [x] User registration with email confirmation
 - [x] Login with credentials
 - [x] Password reset flow
-- [x] Session management with JWT
+- [x] Session management with Better Auth
-- [x] Role-based access control
+- [x] Role-based access control (player, tournament_admin, club_admin)
 
 ### Epic 2: Player Profile & Analytics
 - [x] Player profile page with statistics
 - [x] Partnership performance table
 - [x] Win rate and Elo display
+- [x] Direct player stats (gamesPlayed, wins, losses)
 
 ### Epic 3: Rankings & Public Data
 - [x] Player rankings page
 - [x] Sortable rankings table
 - [x] Public player profiles
+- [x] Home page with top 10 players, recent tournament, club president
 
 ### Epic 4: Tournament Management
 - [x] Create tournaments
@@ -76,8 +86,9 @@ euchre_camp/
 
 ### Prerequisites
 
-- Node.js 22+
+- Node.js 20+
 - npm or yarn
+- SQLite3
 
 ### Installation
 
@@ -94,7 +105,8 @@ euchre_camp/
 
 3. **Set up the database**
     ```bash
-   npx prisma db push
+    npx prisma migrate deploy
+    npx prisma generate
     ```
 
 4. **Start the development server**
@@ -108,8 +120,8 @@ Create a `.env` file:
 
 ```env
 DATABASE_URL="file:./dev.db"
-NEXTAUTH_SECRET="your-secret-key-here"
+BETTER_AUTH_SECRET="your-secret-key-here"
-NEXTAUTH_URL="http://localhost:3000"
+BETTER_AUTH_URL="http://localhost:3000"
 ```
 
 ## Usage
@@ -127,18 +139,30 @@ NEXTAUTH_URL="http://localhost:3000"
 ### Viewing Player Profiles
 Navigate to `/players/[id]/profile` to see statistics, partnerships, and recent games.
 
+### Home Page
+Visit `/` to see:
+- Top 10 players by Elo rating
+- Most recent tournament with full match list
+- Club president information
+
 ## API Endpoints
 
 ### Tournaments
 - `GET /api/tournaments` - List all tournaments
 - `POST /api/tournaments` - Create new tournament
-- `GET /api/tournaments/[id]` - Get tournament details
 
 ### Matches
 - `GET /api/matches` - List matches
-- `POST /api/matches` - Create match result
 - `POST /api/matches/upload` - Upload CSV with match results
 
+### Authentication
+- `POST /api/auth/sign-up/email` - Register new account
+- `POST /api/auth/sign-in/email` - Login with email/password
+- `POST /api/auth/sign-out` - Logout
+
+### Users
+- `GET /api/users/[id]/role` - Get user role
+
 ## Development
 
 ```bash
@@ -148,6 +172,12 @@ npm run dev
 # Production build
 npm run build
 npm start
+
+# Run unit tests
+npm run test
+
+# Run acceptance tests
+npm run test:acceptance
 ```
 
 ## User Stories