diff --git a/README.md b/README.md
index 13e8c25..38aba65 100644
--- a/README.md
+++ b/README.md
@@ -1,20 +1,160 @@
-<div align="center">
-<img width="1200" height="475" alt="GHBanner" src="https://github.com/user-attachments/assets/0aa67016-6eaf-458a-adb2-6e31a0763ed6" />
-</div>
+# Kyoo - Media Discovery Platform
 
-# Run and deploy your AI Studio app
+A modern web application for browsing, managing, and discovering media across multiple categories. Kyoo provides a unified interface for your media library with support for importing from external sources like Playnite, StashAPP, and XBVR.
 
-This contains everything you need to run your app locally.
+## Features
 
-View your app in AI Studio: https://ai.studio/apps/e9b611d4-7585-400f-9a12-81904b28ce1c
+- **Multi-Category Media Management**: Browse and organize Anime, Movies, TV Series, Music, Books, Consoles, Games, and Adult content
+- **Detailed Media Views**: Rich information display including descriptions, genres, studios, cast, and ratings
+- **Cast & Staff Directory**: Explore actors, directors, and other staff across your media library
+- **Search & Filter**: Quickly find media by title, year, genre, or studio
+- **Custom Media**: Add your own media entries manually
+- **External Importers**: Import libraries from popular media managers:
+  - **Playnite**: Import your game library with playtime, achievements, and metadata
+  - **StashAPP**: Import adult content with scene and performer details
+  - **XBVR**: Import VR content with scene information
+- **Category Toggles**: Enable/disable categories to customize your view
+- **Responsive Design**: Beautiful UI built with Tailwind CSS and shadcn/ui components
 
-## Run Locally
+## Tech Stack
 
-**Prerequisites:**  Node.js
+- **Frontend Framework**: React 19 with TypeScript
+- **Build Tool**: Vite 6
+- **Styling**: Tailwind CSS 4
+- **UI Components**: shadcn/ui, Base UI
+- **Icons**: Lucide React
+- **Animations**: Motion (Framer Motion)
+- **Fonts**: Geist Variable Font
 
+## Prerequisites
 
-1. Install dependencies:
-   `npm install`
-2. Set the `GEMINI_API_KEY` in [.env.local](.env.local) to your Gemini API key
-3. Run the app:
-   `npm run dev`
+- Node.js (v18 or higher)
+- npm or yarn
+- Backend API server (configured via environment variables)
+
+## Installation
+
+1. Clone the repository:
+```bash
+git clone <repository-url>
+cd frontend
+```
+
+2. Install dependencies:
+```bash
+npm install
+```
+
+3. Configure environment variables:
+```bash
+cp .env.example .env
+```
+
+Edit `.env` and configure your settings (see [Configuration](#configuration) below).
+
+4. Start the development server:
+```bash
+npm run dev
+```
+
+The app will be available at `http://localhost:3000`
+
+## Configuration
+
+Create a `.env` file based on `.env.example`:
+
+```env
+# App URL (auto-injected by AI Studio in production)
+APP_URL="http://localhost:3000"
+
+# XBVR Importer
+VITE_XBVR_URL="http://localhost:9999"
+
+# StashAPP Importer
+VITE_STASHAPP_URL="http://localhost:9999"
+VITE_STASHAPP_API_KEY="your-api-key"
+
+# Playnite Importer
+VITE_PLAYNITE_IP="localhost"
+VITE_PLAYNITE_PORT="19821"
+VITE_PLAYNITE_API_TOKEN="your-api-token"
+```
+
+### Importer Configuration
+
+#### Playnite
+1. Install the [Playnite Bridge extension](https://github.com/JosefNemec/PlayniteExtensions) in Playnite
+2. Enable the HTTP API server in Playnite settings
+3. Generate an API token in the Playnite Bridge settings
+4. Configure the IP, port, and token in your `.env` file
+5. See [playnite_skill.md](playnite_skill.md) for detailed API documentation
+
+#### StashAPP
+1. Ensure StashAPP is running and accessible
+2. Generate an API key in StashAPP settings
+3. Configure the URL and API key in your `.env` file
+
+#### XBVR
+1. Ensure XBVR is running and accessible
+2. Configure the URL in your `.env` file
+
+## Usage
+
+### Browsing Media
+- Navigate between categories using the header navigation
+- Toggle categories on/off using the category buttons
+- Search for media using the search bar
+- Click on any media item to view detailed information
+
+### Managing Media
+- **Add Media**: Click the "+" button to add custom media entries
+- **Import**: Use the import feature to bring in libraries from Playnite, StashAPP, or XBVR
+- **View Cast**: Browse the cast directory to see all staff across your library
+
+### Importing from External Sources
+1. Click the import button in the header
+2. Select the importer you want to use
+3. Follow the on-screen instructions to configure and run the import
+4. Progress will be displayed in real-time
+
+## Available Scripts
+
+- `npm run dev` - Start development server
+- `npm run build` - Build for production
+- `npm run preview` - Preview production build
+- `npm run lint` - Run TypeScript type checking
+- `npm run clean` - Remove build artifacts
+
+## Project Structure
+
+```
+src/
+├── components/          # React components
+│   ├── ui/             # shadcn/ui components
+│   ├── AddMediaView.tsx
+│   ├── BrowseView.tsx
+│   ├── CastDetailView.tsx
+│   ├── CastView.tsx
+│   ├── DetailView.tsx
+│   └── ImporterView.tsx
+├── lib/                # Utility functions
+│   ├── playniteImporter.ts
+│   ├── stashappImporter.ts
+│   └── utils.ts
+├── App.tsx             # Main application component
+├── api.ts              # API client functions
+├── data.ts             # Mock data
+└── types.ts            # TypeScript type definitions
+```
+
+## API Documentation
+
+For detailed API documentation, see [api.md](api.md).
+
+## License
+
+SPDX-License-Identifier: Apache-2.0
+
+## Support
+
+For issues, questions, or contributions, please refer to the project repository.