diff --git a/README.md b/README.md
index 0d10b6f..b20d8d9 100644
--- a/README.md
+++ b/README.md
@@ -1,2 +1,340 @@
-# Homepage
+# Services Homepage
+A lightweight, self-hosted dashboard for quick access to your Docker services with a modern holographic UI design.
+
+
+
+
+## Features
+
+- 🎨 **Holographic Glass Design** - Modern liquid glass buttons with animated shimmer effects
+- 🎯 **Dynamic Service Loading** - Services configured via simple XML file
+- 🔍 **Smart URL Resolution** - Automatic handling of ports, protocols, and hostnames
+- 🎭 **Icon Integration** - Includes Simple Icons pack (3000+ brand logos)
+- 📱 **Responsive Layout** - Works seamlessly on desktop and mobile
+- 🐳 **Docker-Ready** - Single-container deployment with nginx
+- ⚡ **Lightweight** - Minimal resources, fast loading
+
+## Quick Start
+
+### 1. Deploy with Docker Compose
+
+```bash
+docker-compose up -d
+```
+
+The homepage will be available at `http://localhost:8088`
+
+### 2. Configure Your Services
+
+Edit `services.xml` to add your services:
+
+```xml
+
+
+
+
+
+```
+
+### 3. Restart to Apply Changes
+
+```bash
+docker-compose restart
+```
+
+## Configuration Guide
+
+### Service Attributes
+
+| Attribute | Required | Description | Example |
+|-----------|----------|-------------|---------|
+| `name` | Yes | Display name for the service | `"Nextcloud"` |
+| `proto` | No | Protocol (http/https) | `"https"` (default: `"http"`) |
+| `port` | No | Port number | `"8080"` |
+| `host` | No | Custom hostname or full URL | `"nextcloud.example.com"` |
+| `logo` | No | Icon filename in `/logos/` | `"nextcloud.svg"` |
+
+### URL Resolution Logic
+
+The service URL is built using this priority:
+
+1. **Full URL** - If `host` starts with `http://` or `https://`, use as-is
+2. **Hostname with Port** - If `host` contains `:port`, use `proto://host:port`
+3. **Hostname Only** - If `host` is set (no port), use `https://host` (ignores `proto` and `port`)
+4. **Fallback** - Use current page hostname with specified `proto` and `port`
+
+### Examples
+
+```xml
+
+
+
+
+
+
+
+
+
+
+
+```
+
+## Icon Management
+
+### Using Included Icons
+
+The repository includes Simple Icons (3000+ brand logos). Available icons are in:
+```
+logos/simple-icons/icons/
+```
+
+### Adding Custom Icons
+
+1. Add your SVG file to the `logos/` directory
+2. Reference it in `services.xml`:
+```xml
+
+```
+
+### Icon Styling
+
+All icons are automatically styled white using CSS filters. To customize:
+
+Edit `styles.css` and modify the `.card .logo` rule:
+```css
+.card .logo {
+ filter: brightness(0) invert(1); /* White icons */
+ /* OR */
+ filter: hue-rotate(180deg); /* Color shift */
+}
+```
+
+## Customization
+
+### Theme Colors
+
+Edit CSS variables in `styles.css`:
+
+```css
+:root {
+ --bg: #0f1720; /* Background color */
+ --card: #0b1220; /* Card background */
+ --accent: #4f46e5; /* Accent color (purple) */
+ --muted: #94a3b8; /* Muted text */
+}
+```
+
+### Holographic Effects
+
+The holographic button effects include:
+- **Shimmer Animation** - Continuous light sweep (8s loop, 3s on hover)
+- **Gradient Background** - Purple/pink gradient blend
+- **Glowing Border** - Animated gradient border on hover
+- **Backdrop Blur** - Glass-like frosted effect
+
+To adjust shimmer speed, modify the `@keyframes shimmer` animation:
+```css
+.card::before {
+ animation: shimmer 8s infinite linear; /* Change 8s to adjust speed */
+}
+```
+
+### Layout
+
+Change grid responsiveness in `styles.css`:
+```css
+.grid {
+ grid-template-columns: repeat(auto-fit, minmax(180px, 1fr));
+ /* Adjust minmax() to change card width */
+}
+```
+
+## File Structure
+
+```
+services-homepage/
+├── docker-compose.yml # Docker deployment config
+├── Dockerfile # Custom nginx build (if needed)
+├── index.html # Main HTML page
+├── styles.css # Holographic UI styles
+├── services.xml # Service definitions
+├── README.md # This file
+├── LICENSE # License information
+└── logos/ # Icon directory
+ ├── simple-icons/ # Simple Icons pack (3000+ logos)
+ ├── default.svg # Fallback icon
+ ├── gitea.svg
+ ├── jellyfin.svg
+ ├── nextcloud.svg
+ └── ...
+```
+
+## Updating Icons
+
+### Replace All Icons with Simple Icons
+
+```bash
+cd logos
+for f in *.svg; do
+ basename=$(basename "$f" .svg)
+ match=$(find simple-icons/icons -type f -iname "*${basename}*.svg" -print -quit)
+ [ -n "$match" ] && cp "$match" "$f" && echo "Updated: $f"
+done
+```
+
+### Find Available Icons
+
+```bash
+ls logos/simple-icons/icons/ | grep -i "keyword"
+```
+
+## Backup and Recovery
+
+Icon backups are automatically created in:
+```
+logos/backup-YYYYMMDD-HHMMSS/
+```
+
+To restore from backup:
+```bash
+cp logos/backup-20251123-231406/*.svg logos/
+docker-compose restart
+```
+
+## Troubleshooting
+
+### Services Not Loading
+
+1. Check `services.xml` syntax:
+```bash
+xmllint --noout services.xml
+```
+
+2. Check browser console for errors (F12)
+
+3. Verify file permissions:
+```bash
+chmod 644 services.xml index.html styles.css
+chmod 755 logos/
+```
+
+### Icons Not Displaying
+
+1. Verify icon exists:
+```bash
+ls -lh logos/youricon.svg
+```
+
+2. Check icon reference in `services.xml` matches filename exactly
+
+3. Clear browser cache (Ctrl+Shift+R)
+
+### Container Issues
+
+```bash
+# View logs
+docker logs services-homepage
+
+# Restart container
+docker-compose restart
+
+# Rebuild if files changed
+docker-compose up -d --force-recreate
+```
+
+## Performance
+
+- **Image Size**: ~45MB (nginx:alpine base)
+- **Memory Usage**: ~5-10MB
+- **Load Time**: <100ms (local network)
+- **Icons**: Cached by browser after first load
+
+## Browser Support
+
+- ✅ Chrome/Edge 90+
+- ✅ Firefox 88+
+- ✅ Safari 14+
+- ✅ Mobile browsers (iOS Safari, Chrome Android)
+
+## Security
+
+- All volumes mounted read-only (`:ro`)
+- No external dependencies at runtime
+- Logs automatically rotated (5MB max, 2 files)
+- CORS not enabled (same-origin only)
+
+## Advanced Usage
+
+### Custom Nginx Config
+
+Create `nginx.conf` and mount it:
+
+```yaml
+volumes:
+ - ./nginx.conf:/etc/nginx/nginx.conf:ro
+```
+
+### Adding Authentication
+
+Use a reverse proxy (Nginx Proxy Manager, Caddy, Traefik) with basic auth:
+
+```nginx
+location / {
+ auth_basic "Services";
+ auth_basic_user_file /etc/nginx/.htpasswd;
+ proxy_pass http://services-homepage:80;
+}
+```
+
+### Dynamic Port Updates
+
+For services with dynamic ports (e.g., Transmission behind VPN), use environment variables:
+
+```xml
+
+```
+
+Then update via script or use a template processor.
+
+## Contributing
+
+Contributions welcome! Areas for improvement:
+- Search/filter functionality
+- Dark/light mode toggle
+- Service health checks
+- Drag-and-drop reordering
+- Categorized sections
+
+## License
+
+MIT License - See LICENSE file for details
+
+## Credits
+
+- **Icons**: [Simple Icons](https://simpleicons.org/) (CC0 1.0 Universal)
+- **Design Inspiration**: Holographic UI by vishnu137 on CodePen
+- **Web Server**: nginx Alpine
+
+## Support
+
+For issues, questions, or suggestions:
+1. Check this README first
+2. Review browser console for errors
+3. Check Docker logs: `docker logs services-homepage`
+4. Verify `services.xml` syntax
+
+---
+
+**Version**: 1.0.0
+**Last Updated**: November 23, 2025
\ No newline at end of file