diff --git a/README.md b/README.md
new file mode 100644
index 0000000..113e354
--- /dev/null
+++ b/README.md
@@ -0,0 +1,203 @@
+# Ragusa IT-Consulting
+
+[![React](https://img.shields.io/badge/React-19-61DAFB?logo=react)](https://react.dev)
+[![TypeScript](https://img.shields.io/badge/TypeScript-5.9-3178C6?logo=typescript)](https://www.typescriptlang.org)
+[![Vite](https://img.shields.io/badge/Vite-7.3-646CFF?logo=vite)](https://vitejs.dev)
+[![Vitest](https://img.shields.io/badge/Vitest-4.0-6E9F18?logo=vitest)](https://vitest.dev)
+
+A modern, performant website for Ragusa IT-Consulting built with React 19, TypeScript, and Vite. Features smooth animations, internationalization (i18n), and a sophisticated design system.
+
+## Features
+
+- **Modern React 19** - Latest React features with concurrent rendering
+- **TypeScript** - Strict type checking for robust code
+- **Motion** - Beautiful animations and transitions
+- **i18n** - Internationalization with English and German support
+- **Responsive Design** - Mobile-first, fully responsive layout
+- **Accessibility** - ARIA labels, semantic HTML, keyboard navigation
+- **Performance** - Code splitting, lazy loading, optimized assets
+- **Testing** - Vitest with React Testing Library for comprehensive test coverage
+- **Firebase Hosting** - Production-ready deployment setup
+
+## Tech Stack
+
+- **Framework**: React 19.2 with React Router 7
+- **Build Tool**: Vite 7.3
+- **Language**: TypeScript 5.9 (strict mode)
+- **Animation**: Motion (Framer Motion successor)
+- **Styling**: CSS Modules + Global CSS
+- **Testing**: Vitest + React Testing Library + jsdom
+- **Forms**: EmailJS for contact form
+- **Icons**: React Icons
+- **WebGL**: OGL for gradient effects
+- **Deployment**: Firebase Hosting
+
+## Getting Started
+
+### Prerequisites
+
+- Node.js 18+ recommended
+- pnpm (preferred) or npm
+
+### Installation
+
+```bash
+# Clone the repository
+git clone https://github.com/ragusa-it/ragusaitweb.git
+cd ragusaitweb
+
+# Install dependencies
+pnpm install
+
+# Copy environment variables
+cp .env.example .env
+```
+
+### Development
+
+```bash
+# Start development server (port 3000)
+pnpm dev
+```
+
+### Build
+
+```bash
+# Production build
+pnpm build
+
+# Preview production build
+pnpm preview
+```
+
+### Testing
+
+```bash
+# Run all tests
+pnpm exec vitest
+
+# Run tests in watch mode
+pnpm exec vitest --watch
+
+# Run tests with coverage
+pnpm exec vitest --coverage
+
+# Run a single test file
+pnpm exec vitest src/components/ui/__tests__/Button.test.tsx
+```
+
+### Type Checking
+
+```bash
+pnpm exec tsc --noEmit
+```
+
+## Project Structure
+
+```
+src/
+├── components/
+│   ├── effects/       # Visual effects (GradientBlinds)
+│   ├── layout/        # Layout components (Navbar, Footer, FancyCursor)
+│   ├── sections/      # Page sections (Hero, Services)
+│   └── ui/            # Reusable UI components (Button, Input, Card, Modal)
+├── hooks/             # Custom React hooks (useRateLimit, useTypingEffect)
+├── i18n/              # Internationalization (en, de translations)
+├── pages/             # Route components (Home, About, Contact)
+├── styles/            # Global styles and theme
+├── utils/             # Utility functions (debounce, security)
+├── App.tsx            # Main app component with routing
+├── config.ts          # App configuration
+└── main.tsx           # Entry point
+
+public/                # Static assets
+build/                 # Production build output
+```
+
+## Available Scripts
+
+| Command | Description |
+|---------|-------------|
+| `pnpm dev` | Start development server |
+| `pnpm build` | Type-check and build for production |
+| `pnpm preview` | Preview production build locally |
+
+## Key Features
+
+### Animation System
+
+- **FancyCursor**: Custom cursor with blend-mode effects
+- **GradientBlinds**: WebGL-powered animated gradient background
+- **PageLoader**: Smooth page transition loading state
+- **Motion**: All interactive elements use `motion` components for micro-interactions
+
+### Internationalization
+
+- Full i18n support with English and German
+- Language switching with context provider
+- RTL-ready architecture
+
+### Performance Optimizations
+
+- Code splitting with React.lazy() for routes
+- Preloaded critical fonts
+- Optimized build with Vite
+- Rate limiting hooks for form submissions
+
+### Testing Strategy
+
+- Unit tests for components
+- Hook tests for custom logic
+- Performance tests for heavy components
+- Security tests for utility functions
+
+## Design System
+
+- **Primary Font**: Sora (variable font, weights 100-800)
+- **Monospace**: JetBrains Mono
+- **Color Palette**: Dark theme with accent colors (defined in `.jules/palette.md`)
+- **Spacing**: CSS custom properties for consistent spacing
+- **Components**: Modular CSS with BEM-like naming in CSS Modules
+
+## Environment Variables
+
+Copy `.env.example` to `.env` and configure:
+
+```env
+VITE_EMAILJS_SERVICE_ID=your_service_id
+VITE_EMAILJS_TEMPLATE_ID=your_template_id
+VITE_EMAILJS_PUBLIC_KEY=your_public_key
+```
+
+## Deployment
+
+The site is configured for Firebase Hosting. Build output goes to `build/` directory.
+
+```bash
+# Build and deploy
+pnpm build
+firebase deploy
+```
+
+## Browser Support
+
+- Chrome 90+
+- Firefox 88+
+- Safari 14+
+- Edge 90+
+
+## Contributing
+
+1. Follow the existing code style (see AGENTS.md)
+2. Use TypeScript strict mode
+3. Write tests for new features
+4. Ensure all tests pass before committing
+5. Use conventional commit messages
+
+## License
+
+ISC License - See package.json for details
+
+---
+
+**Ragusa IT-Consulting** - Professional Web Development & IT Support