Eric-Zhang-Developer · Eric-Zhang-Developer · Jan 25, 2026 · Jan 25, 2026
diff --git a/README.md b/README.md
@@ -1,36 +1,177 @@
-This is a [Next.js](https://nextjs.org) project bootstrapped with [`create-next-app`](https://nextjs.org/docs/app/api-reference/cli/create-next-app).
+<!-- Badges -->
+<p align="center">
+  <a href="https://nextjs.org/"><img src="https://img.shields.io/badge/Next.js-000000?style=for-the-badge&logo=nextdotjs&logoColor=white" alt="Next.js" /></a>
+  <a href="https://react.dev/"><img src="https://img.shields.io/badge/react-%2320232a.svg?style=for-the-badge&logo=react&logoColor=%2361DAFB" alt="React" /></a>
+  <a href="https://www.typescriptlang.org/"><img src="https://img.shields.io/badge/typescript-%23007ACC.svg?style=for-the-badge&logo=typescript&logoColor=white" alt="TypeScript" /></a>
+  <a href="https://tailwindcss.com/"><img src="https://img.shields.io/badge/Tailwind_CSS-38B2AC?style=for-the-badge&logo=tailwind-css&logoColor=white" alt="Tailwind CSS" /></a>
+  <a href="https://openrouter.ai/"><img src="https://img.shields.io/badge/OpenRouter-6366F1?style=for-the-badge&logo=openai&logoColor=white" alt="OpenRouter" /></a>
+  <a href="https://gemini.google.com/"><img src="https://img.shields.io/badge/Gemini-8E75B2?style=for-the-badge&logo=google%20gemini&logoColor=white" alt="Google Gemini" /></a>
+  <a href="https://vercel.com/"><img src="https://img.shields.io/badge/Vercel-000000?style=for-the-badge&logo=vercel&logoColor=white" alt="Vercel" /></a>
+</p>
+
+<p align="center">
+  <a href="https://vitest.dev/"><img src="https://img.shields.io/badge/Vitest-%236E9F18.svg?style=for-the-badge&logo=vitest&logoColor=white" alt="Vitest" /></a>
+  <a href="https://testing-library.com/"><img src="https://img.shields.io/badge/RTL-%23E33332.svg?style=for-the-badge&logo=testing-library&logoColor=white" alt="React Testing Library" /></a>
+  <a href="https://playwright.dev/"><img src="https://img.shields.io/badge/Playwright-45ba4b?style=for-the-badge&logo=playwright&logoColor=white" alt="Playwright" /></a>
+  <a href="https://eslint.org/"><img src="https://img.shields.io/badge/eslint-4B32C3?style=for-the-badge&logo=eslint&logoColor=white" alt="ESLint" /></a>
+</p>
+
+---
+
+<h1 align="center">MealCraft</h1>
+
+<p align="center">
+  <strong>Craft meals from what you have.</strong>
+</p>
+
+<p align="center">
+  A Minecraft-themed AI-powered recipe generator that turns photos of your fridge into delicious meal ideas.
+  <br />
+  Built at <strong>SwampHacks 2026</strong>.
+</p>
+
+<p align="center">
+  <a href="https://mealcraftai.vercel.app"><img src="https://img.shields.io/badge/-🍳%20Try%20It%20Now!-brightgreen?style=for-the-badge" alt="Try It Now" /></a>
+</p>
+
+<!-- TODO: Add screenshot or demo GIF here -->
+<!-- <p align="center">
+  <img src="./demo.gif" alt="MealCraft Demo" width="600" />
+</p> -->
+
+## Overview
+
+**MealCraft** helps you answer the age-old question: _"What should I cook with what I have?"_
+
+Simply snap a photo of your fridge, pantry, or grocery haul, and our AI-powered chef will analyze your ingredients and generate five personalized recipes complete with step-by-step instructions and nutritional information. No more food waste, no more decision fatigue -just delicious meals crafted from what you already own.
+
+The app features a playful Minecraft-inspired UI with pixel art styling, authentic sound effects, and that nostalgic blocky aesthetic we all love.
+
+## How It Works
+
+1. **Upload Your Photo** - Take a picture of your fridge, pantry, or ingredients and upload it to MealCraft.
+2. **AI Analyzes Ingredients** - Google Gemini's vision model identifies all the ingredients it can see in your image.
+3. **Recipes Are Crafted** - The AI generates 5 diverse, practical recipes using your available ingredients.
+4. **Get Cooking** - Each recipe includes ingredients with amounts, step-by-step instructions, and macro nutrition info (calories, protein, carbs, fat).
+5. **Expand for Detail** - Need more guidance? Expand any recipe's instructions for detailed cooking steps.
+
+## Key Features
+
+- **AI-Powered Ingredient Detection** - Upload any image and let Gemini identify your ingredients automatically.
+- **Smart Recipe Generation** - Get 5 diverse, practical recipes tailored to what you have on hand.
+- **Nutritional Information** - Every recipe includes calorie and macro breakdowns.
+- **Expandable Instructions** - One-click detailed cooking instructions for any recipe.
+- **Minecraft-Themed UI** - Nostalgic pixel art design with authentic sound effects and animations.
+- **Responsive Design** - Works seamlessly on desktop and mobile devices.
+- **Image Compression** - Client-side image optimization for faster uploads.
+
+## Tech Stack
+
+### Frontend
+
+- **Next.js 16** - React framework with App Router
+- **React 19** - UI library with latest features
+- **TypeScript** - Type-safe development
+- **Tailwind CSS 4** - Utility-first styling
+- **Lucide React** - Beautiful icons
+
+### Backend
+
+- **Next.js API Routes** - Serverless API endpoints
+- **OpenRouter** - AI model routing and management
+- **Google Gemini 3 Flash** - Multimodal AI for image analysis and recipe generation
+
+### Testing
+
+- **Vitest** - Fast unit testing
+- **React Testing Library** - Component testing
+- **Playwright** - End-to-end testing
+- **jsdom** - DOM environment for tests
 
 ## Getting Started
 
-First, run the development server:
+### Prerequisites
+
+- Node.js 18+
+- npm, yarn, pnpm, or bun
+
+### Installation
+
+1. Clone the repository:
+
+   ```bash
+   git clone https://github.com/YOUR_USERNAME/swamphacks-2026.git
+   cd swamphacks-2026
+   ```
+
+2. Install dependencies:
+
+   ```bash
+   npm install
+   ```
+
+3. Set up environment variables:
+
+   ```bash
+   cp .env.example .env.local
+   ```
+
+   Add your OpenRouter API key:
+
+   ```
+   OPENROUTER_API_KEY=your_api_key_here
+   ```
+
+4. Run the development server:
+
+   ```bash
+   npm run dev
+   ```
+
+5. Open [http://localhost:3000](http://localhost:3000) in your browser.
 
-```bash
-npm run dev
-# or
-yarn dev
-# or
-pnpm dev
-# or
-bun dev
-```
+### Scripts
 
-Open [http://localhost:3000](http://localhost:3000) with your browser to see the result.
+| Command                 | Description              |
+| ----------------------- | ------------------------ |
+| `npm run dev`           | Start development server |
+| `npm run build`         | Build for production     |
+| `npm run start`         | Start production server  |
+| `npm run test`          | Run tests in watch mode  |
+| `npm run test:run`      | Run tests once           |
+| `npm run test:coverage` | Run tests with coverage  |
+| `npm run lint`          | Run ESLint               |
 
-You can start editing the page by modifying `app/page.tsx`. The page auto-updates as you edit the file.
+## Team
 
-This project uses [`next/font`](https://nextjs.org/docs/app/building-your-application/optimizing/fonts) to automatically optimize and load [Geist](https://vercel.com/font), a new font family for Vercel.
+Built with love at **SwampHacks 2026** by:
 
-## Learn More
+- **Eric Zhang** - [GitHub](https://github.com/Eric-Zhang-Developer)
+- **Nate Flores** - [GitHub](https://github.com/nflow24)
+- **Johan Diaz** - [GitHub](https://github.com/JDiaz824)
+- **Patrick Ouano** - [GitHub](https://github.com/patrick-ouano)
 
-To learn more about Next.js, take a look at the following resources:
+## Credits
 
-- [Next.js Documentation](https://nextjs.org/docs) - learn about Next.js features and API.
-- [Learn Next.js](https://nextjs.org/learn) - an interactive Next.js tutorial.
+- **[VT323](https://fonts.google.com/specimen/VT323)** - Pixel-style font by Peter Hull via Google Fonts
+- **[Lucide](https://lucide.dev/)** - Beautiful open-source icons
+- **[Google Gemini](https://deepmind.google/technologies/gemini/)** - Multimodal AI for image analysis
+- **[OpenRouter](https://openrouter.ai/)** - AI model routing
+- **Minecraft** - UI inspiration and aesthetic (Mojang/Microsoft)
+- **Cursor** - AI IDE
+- **Claude Code** - Anthropic's agentic coding tool
 
-You can check out [the Next.js GitHub repository](https://github.com/vercel/next.js) - your feedback and contributions are welcome!
+## Future Roadmap
 
-## Deploy on Vercel
+- User accounts and saved recipes
+- Dietary preference filters (vegetarian, vegan, gluten-free)
+- Shopping list generation for missing ingredients
+- Recipe sharing and social features
+- Voice-guided cooking mode
+- Meal planning calendar
 
-The easiest way to deploy your Next.js app is to use the [Vercel Platform](https://vercel.com/new?utm_medium=default-template&filter=next.js&utm_source=create-next-app&utm_campaign=create-next-app-readme) from the creators of Next.js.
+---
 
-Check out our [Next.js deployment documentation](https://nextjs.org/docs/app/building-your-application/deploying) for more details.
+<p align="center">
+  Made with pixels and passion at SwampHacks 2026
+</p>