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

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
-│   │   └── lib/          # Utilities and configuration
-│   └── types/            # TypeScript type definitions
+│   │   ├── rankings/     # Rankings page
+│   │   └── components/   # Shared components
+│   ├── 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] Role-based access control
+- [x] Session management with Better Auth
+- [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,31 +86,33 @@ euchre_camp/
 
 ### Prerequisites
 
-- Node.js 22+
+- Node.js 20+
 - npm or yarn
+- SQLite3
 
 ### Installation
 
 1. **Clone the repository**
-   ```bash
-   git clone <repository-url>
-   cd euchre_camp
-   ```
+    ```bash
+    git clone <repository-url>
+    cd euchre_camp
+    ```
 
 2. **Install dependencies**
-   ```bash
-   npm install
-   ```
+    ```bash
+    npm install
+    ```
 
 3. **Set up the database**
-   ```bash
-   npx prisma db push
-   ```
+    ```bash
+    npx prisma migrate deploy
+    npx prisma generate
+    ```
 
 4. **Start the development server**
-   ```bash
-   npm run dev
-   ```
+    ```bash
+    npm run dev
+    ```
 
 ### Environment Variables
 
@@ -108,8 +120,8 @@ Create a `.env` file:
 
 ```env
 DATABASE_URL="file:./dev.db"
-NEXTAUTH_SECRET="your-secret-key-here"
-NEXTAUTH_URL="http://localhost:3000"
+BETTER_AUTH_SECRET="your-secret-key-here"
+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