diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 100644
index 0000000..14be877
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1,176 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+**Awesome Web** is a Next.js 15 web application for browsing and searching "awesome lists" from GitHub. It features full-text search powered by SQLite FTS5, personal list management with a rich markdown editor, and automated database builds via GitHub Actions.
+
+**Tech Stack:**
+- Next.js 15 (App Router) + TypeScript
+- Tailwind CSS 4 with custom theme (purple/pink/gold gradients)
+- shadcn/ui components (New York style)
+- SQLite3 with better-sqlite3 + FTS5 for full-text search
+- Zustand for state management
+- TipTap for WYSIWYG markdown editing
+- Node.js 22+ required
+
+## Common Development Commands
+
+```bash
+# Development server
+npm run dev
+
+# Production build
+npm run build
+npm start
+
+# Type checking
+npm run type-check
+
+# Linting
+npm run lint
+```
+
+## Architecture Overview
+
+### Database Layer (`lib/db.ts`)
+
+Central database abstraction for SQLite operations:
+- **Connection Management**: Singleton pattern with WAL mode for concurrency
+- **Database Path**: `$AWESOME_DB_PATH` or `~/.awesome/awesome.db` (from awesome CLI)
+- **Core Functions**:
+ - `searchRepositories()` - FTS5 full-text search with faceted filtering (language, stars, category)
+ - `getAwesomeLists()` - Hierarchical list of awesome lists
+ - `getRepositoryWithReadme()` - Fetch repository details with README content
+ - `getCategories()` / `getLanguages()` - Facet data for filters
+ - `getStats()` - Database statistics for homepage
+
+**Search Architecture**: Uses SQLite FTS5 with `readmes_fts` virtual table. Queries are parsed into FTS format (`"term1"* OR "term2"*`) and support sorting by relevance, stars, or recent activity.
+
+### Personal List Management (`lib/personal-list-store.ts`)
+
+Zustand store with localStorage persistence for user-curated lists:
+- **Items Management**: CRUD operations for saved repositories/resources
+- **Markdown Sync**: Bidirectional sync between structured items and markdown representation
+- **Editor Integration**: State for TipTap editor (view modes: editor/preview/split)
+- **Export/Import**: JSON export and markdown generation
+
+### API Routes (`app/api/*`)
+
+- `/api/search` - Repository search endpoint (wraps `lib/db.ts`)
+- `/api/repositories/[id]` - Single repository details
+- `/api/lists` - User personal lists CRUD
+- `/api/lists/[id]` - Single list operations
+- `/api/stats` - Database statistics
+- `/api/db-version` - Database version for cache invalidation
+- `/api/webhook` - GitHub Actions webhook for database update notifications
+
+### Component Structure
+
+**Layout Components** (`components/layout/`):
+- `app-header.tsx` - Main navigation with command menu trigger
+- `app-sidebar.tsx` - Tree navigation for awesome lists hierarchy
+- `command-menu.tsx` - Global search command palette (Cmd+K)
+
+**Personal List Components** (`components/personal-list/`):
+- `personal-list-editor.tsx` - TipTap-based markdown editor with rich formatting
+- `push-to-list-button.tsx` - "Add to list" button for repositories
+- `sliding-panel.tsx` - Side panel for personal list management
+- `personal-list-items.tsx` - Structured view of saved items
+
+**README Viewer** (`components/readme/`):
+- `readme-viewer.tsx` - Markdown rendering with syntax highlighting (marked + highlight.js)
+- `readme-header.tsx` - Repository metadata header (stars, language, actions)
+
+**UI Components** (`components/ui/`):
+- shadcn/ui components (New York style)
+- Custom `kbd.tsx` for keyboard shortcut displays
+
+### Theme System
+
+Custom Tailwind theme matching the awesome CLI branding:
+- **Primary Colors**: `--awesome-purple: #DA22FF`, `--awesome-pink: #FF69B4`, `--awesome-gold: #FFD700`
+- **Gradients**: Utility classes for purple-to-gold gradients (buttons, text, backgrounds)
+- **Dark Mode**: Next-themes integration with system preference detection
+- **Typography**: Tailwind typography plugin for markdown rendering
+
+Configuration in `tailwind.config.ts` and `app/globals.css`.
+
+### Database Build System
+
+**Automated Builds** (`.github/workflows/db.yml`):
+- Runs every 6 hours or manual trigger
+- Two modes:
+ 1. **Download mode** (default, ~5 min): Downloads pre-built DB from `valknarness/awesome` repository
+ 2. **Build mode** (~1-2 hours): Clones awesome CLI and runs full indexing
+- Artifacts retained for 90 days with metadata JSON
+
+**Build Script** (`scripts/build-db.js`):
+- Uses GitHub CLI to download artifacts or spawns awesome CLI indexer
+- Generates `db-metadata.json` with build stats
+- Fallback to local build if download fails
+
+### Page Routes
+
+- `/` - Landing page with statistics and featured lists
+- `/browse` - Browse all awesome lists
+- `/search` - Search interface with faceted filtering
+- `/list/[id]` - Single awesome list view with repositories
+- `/repository/[id]` - Repository detail with README
+- `/readme/[owner]/[repo]` - Direct README viewer
+- `/my-list` - Personal list editor
+- `/legal`, `/disclaimer`, `/imprint` - Legal pages
+
+## Important Development Notes
+
+### Database Schema Expectations
+
+The SQLite database must have these tables:
+- `awesome_lists` - List metadata (id, name, url, description, category, stars, parent_id, level)
+- `repositories` - Repository data (id, awesome_list_id, name, url, description, stars, language, topics)
+- `readmes` - README content (id, repository_id, raw_content)
+- `readmes_fts` - FTS5 virtual table for full-text search
+
+### Path Aliases
+
+- `@/` maps to project root
+- `@/components` - React components
+- `@/lib` - Utilities and shared logic
+- `@/hooks` - Custom React hooks
+- `@/app` - Next.js app router pages
+
+### Service Worker
+
+`public/worker.js` implements background polling for database updates:
+- Polls `/api/db-version` with exponential backoff
+- Notifies client on version change for cache invalidation
+- Smart polling reduces when page inactive
+
+### Node.js Version
+
+Requires Node.js 22+ (specified in `package.json` engines). Use pnpm for package management.
+
+### shadcn/ui Components
+
+Components use "New York" style variant. When adding new shadcn components, ensure they match the custom theme colors defined in `components.json` and `app/globals.css`.
+
+### Adding New Search Filters
+
+When extending search functionality:
+1. Update `SearchOptions` interface in `lib/db.ts`
+2. Add filter logic to SQL query in `searchRepositories()`
+3. Update API route in `app/api/search/route.ts`
+4. Add UI controls in search page components
+
+### TipTap Editor Extensions
+
+The personal list editor uses these TipTap extensions:
+- Starter Kit (basic formatting)
+- Code Block Lowlight (syntax highlighting)
+- Table extensions (table support)
+- Task List/Item (checklist support)
+- Character Count (word count display)
+- Typography (smart quotes, em dashes)
+
+When modifying the editor, ensure all extensions are properly configured in `personal-list-editor.tsx`.
diff --git a/README.md b/README.md
index 6359359..0cc035f 100644
--- a/README.md
+++ b/README.md
@@ -1,339 +1,349 @@
-# ✨ AWESOME WEB - Next-Level Ground-Breaking AAA Webapp ✨
+
-> A stunning, feature-rich web application for exploring and discovering awesome lists from GitHub
+# 🕶️ ✨ AWESOME WEB ✨ 🕶️
+### *The Most Funkadelic, Cosmically-Enhanced, Star-Powered GitHub Explorer in the Known Universe!*
-**🚀 Built with:** Next.js 18 • Tailwind CSS 4 • shadcn/ui • SQLite3 • Web Workers • PWA
+
-## 🎨 Design Philosophy
+> 🎤 *"Yeah baby! We got that COSMIC SLOP of awesome lists, sprinkled with STARDUST and served on a MOTHERSHIP of Next.js goodness! Slide into the funkiest GitHub explorer this side of the galaxy, ya dig?"*
+>
+> **— Bootsy Collins, Minister of Funk & Chief Awesome Officer**
-This webapp perfectly matches the **beautiful purple/pink/gold theme** from the Awesome CLI:
-- 💜 **Awesome Purple**: `#DA22FF`
-- 💗 **Awesome Pink**: `#FF69B4`
-- 💛 **Awesome Gold**: `#FFD700`
+[](https://github.com)
+[](https://github.com)
+[](https://github.com)
+[](https://github.com)
-## 🌟 Features Implemented
-
-### ✅ Core Infrastructure
-
-1. **Next.js 18 Setup**
- - App router with TypeScript
- - Optimized build configuration
- - PWA support ready
- - Image optimization
-
-2. **Tailwind CSS 4 Custom Theme**
- - Matching CLI color scheme
- - Custom gradient utilities
- - Beautiful button styles
- - Smooth animations
- - Custom scrollbar
- - Typography plugin
-
-3. **GitHub Actions Workflow**
- - Two build modes:
- - **Download Mode**: Fast (~5 min) - downloads pre-built database from awesome CLI repo
- - **Build Mode**: Slow (~1-2 hours) - builds locally using awesome CLI indexer
- - Runs every 6 hours (download mode by default)
- - Manual trigger with mode selection
- - Configurable source repository
- - Artifact upload (90-day retention)
- - Metadata generation with build stats
- - Fallback to local build if download fails
-
-4. **Web Worker System**
- - Smart polling with exponential backoff
- - Cache invalidation
- - Client notification system
- - Efficient resource usage
- - Background updates
-
-5. **API Routes**
- - `/api/db-version` - Database version endpoint
- - `/api/webhook` - GitHub Actions webhook handler
- - Signature verification
- - Metadata management
-
-### 🎯 Architecture
-
-```
-awesome-web/
-├── .github/workflows/
-│ └── db.yml ✅ Automated DB building
-├── app/
-│ ├── layout.tsx ✅ Root layout with theme
-│ ├── globals.css ✅ Custom awesome styles
-│ ├── api/
-│ │ ├── db-version/ ✅ Version checking
-│ │ └── webhook/ ✅ Update notifications
-│ ├── page.tsx 🔨 Landing hero (to build)
-│ ├── list/[id]/ 🔨 List index page
-│ ├── readme/[...]/ 🔨 README viewer
-│ ├── legal/ 🔨 Legal pages
-│ └── not-found.tsx 🔨 404 with easter egg
-├── components/
-│ ├── ui/ 🔨 shadcn components
-│ ├── layout/
-│ │ ├── sidebar.tsx 🔨 Tree navigation
-│ │ └── command-menu.tsx🔨 Search command
-│ ├── search/
-│ │ ├── facets.tsx 🔨 Search facets
-│ │ └── filters.tsx 🔨 Advanced filters
-│ └── providers/
-│ └── worker-provider.tsx 🔨 Worker integration
-├── public/
-│ ├── worker.js ✅ Service worker
-│ ├── manifest.json ✅ PWA manifest
-│ └── icons/ 🔨 Generate from logo
-├── scripts/
-│ └── build-db.js ✅ Database builder (download/build modes)
-├── tailwind.config.ts ✅ Custom theme
-└── next.config.js ✅ PWA & optimization
-```
-
-## 🚀 Getting Started
-
-### Installation
-
-```bash
-cd /home/valknar/Projects/node.js/awesome-web
-npm install
-```
-
-### Development
-
-```bash
-npm run dev
-```
-
-Open [http://localhost:3000](http://localhost:3000)
-
-### Build
-
-```bash
-npm run build
-npm start
-```
-
-## 📋 Next Steps to Complete
-
-### 1. Landing Page 🔨
-- [ ] Hero section with gradient buttons
-- [ ] Feature showcase
-- [ ] Statistics display
-- [ ] Call-to-action sections
-
-### 2. Command Search (kbd bindings) 🔨
-- [ ] shadcn Command component
-- [ ] Full-text search integration
-- [ ] Search facets (language, stars, topics)
-- [ ] Sorting options
-- [ ] Live preview
-- [ ] Pagination
-
-### 3. Sidebar Navigation 🔨
-- [ ] Tree structure of awesome lists
-- [ ] Live search/filter
-- [ ] Collapsible categories
-- [ ] Active state indicators
-
-### 4. README Viewer 🔨
-- [ ] State-of-the-art markdown rendering
-- [ ] Syntax highlighting
-- [ ] Sticky action header
-- [ ] Share functionality
-- [ ] Star button
-- [ ] Original link
-
-### 5. UI Components 🔨
-- [ ] Install shadcn/ui components
-- [ ] Create custom components
-- [ ] Toast notifications
-- [ ] Loading states
-- [ ] Error boundaries
-
-### 6. Logo & Assets 🔨
-- [ ] Adapt sindresorhus/awesome logo
-- [ ] Generate favicon
-- [ ] Create PWA icons (all sizes)
-- [ ] Header logo
-- [ ] OG image
-
-### 7. Legal Pages 🔨
-- [ ] Legal page
-- [ ] Disclaimer
-- [ ] Imprint
-- [ ] Beautiful styling
-
-### 8. 404 Page with Easter Egg 🔨
-- [ ] Custom 404 design
-- [ ] AWESOME easter egg
-- [ ] Interactive elements
-- [ ] Animated graphics
-
-### 9. Database Integration 🔨
-- [ ] SQLite connection
-- [ ] Search implementation
-- [ ] Faceted search
-- [ ] Results pagination
-- [ ] Error handling
-
-### 10. Worker Provider 🔨
-- [ ] React context for worker
-- [ ] Update notifications
-- [ ] Cache management
-- [ ] Toast integration
-
-## 🎨 Theme Showcase
-
-### Colors
-```css
-/* Primary Purple */
---awesome-purple: #DA22FF;
---awesome-purple-light: #E855FF;
---awesome-purple-dark: #9733EE;
-
-/* Secondary Pink */
---awesome-pink: #FF69B4;
---awesome-pink-light: #FFB6D9;
---awesome-pink-dark: #FF1493;
-
-/* Accent Gold */
---awesome-gold: #FFD700;
---awesome-gold-light: #FFE44D;
---awesome-gold-dark: #FFC700;
-```
-
-### Gradients
-```css
-/* Main Gradient */
-background: linear-gradient(135deg, #DA22FF 0%, #9733EE 50%, #FFD700 100%);
-
-/* Pink Gradient */
-background: linear-gradient(135deg, #FF1493 0%, #DA22FF 50%, #9733EE 100%);
-
-/* Gold Gradient */
-background: linear-gradient(135deg, #FFD700 0%, #FF69B4 50%, #FF1493 100%);
-```
-
-### Components
-- **Buttons**: Gradient background with hover lift
-- **Cards**: Border glow on hover
-- **Text**: Gradient text utility classes
-- **Scrollbar**: Gradient thumb
-- **Focus**: Purple ring
-- **Selection**: Purple highlight
-
-## 🔧 Technical Stack
-
-### Frontend
-- **Next.js 18** - React framework
-- **TypeScript** - Type safety
-- **Tailwind CSS 4** - Utility-first CSS
-- **shadcn/ui** - Component library
-- **Radix UI** - Headless components
-- **cmdk** - Command palette
-- **Lucide** - Icons
-
-### Backend
-- **SQLite3** - Database
-- **better-sqlite3** - Node.js driver
-- **FTS5** - Full-text search
-- **Node.js 22+** - Runtime
-
-### Build & Deploy
-- **GitHub Actions** - CI/CD
-- **Web Workers** - Background sync
-- **PWA** - Progressive web app
-- **Service Worker** - Offline support
-
-## 🎯 Key Features to Implement
-
-### Search Excellence
-- ⚡ Lightning-fast FTS5
-- 🎨 Faceted filtering
-- 🔤 Syntax highlighting
-- 📄 Live preview
-- 🔀 Multiple sort options
-- 📊 Result statistics
-
-### Smart Updates
-- 🔄 Auto-detect new DB versions
-- 📢 User notifications
-- ♻️ Cache invalidation
-- 🎯 Background sync
-- ⚡ Zero downtime updates
-
-### Beautiful UX
-- 🎨 Gorgeous gradients
-- ✨ Smooth animations
-- 📱 Responsive design
-- ♿ Accessibility
-- 🌗 Dark mode
-- ⌨️ Keyboard shortcuts
-
-## 📝 Development Notes
-
-### shadcn/ui Installation
-```bash
-npx shadcn-ui@latest init
-npx shadcn-ui@latest add button dialog dropdown-menu toast command scroll-area
-```
-
-### Environment Variables
-```env
-# .env.local
-WEBHOOK_SECRET=your-secret-here
-DB_URL=https://your-host.com/awesome.db
-GITHUB_TOKEN=your-github-token
-```
-
-### GitHub Secrets
-- `WEBHOOK_SECRET` - For webhook verification
-- `WEBHOOK_URL` - Your Next.js webhook endpoint
-
-## 🎉 What Makes This AWESOME
-
-1. **Perfect Theme Match** - Exact CLI color scheme
-2. **Smart Updates** - Worker polls, notifies, updates seamlessly
-3. **GitHub Integration** - Automated builds every 6 hours
-4. **PWA Ready** - Install as app on any device
-5. **Next-Level Search** - Facets, filters, live preview
-6. **Beautiful Design** - State-of-the-art UI/UX
-7. **Intelligent** - Smart polling, cache management
-8. **Complete** - End-to-end solution
-
-## 📖 Documentation
-
-- [GitHub Workflow](.github/workflows/db.yml) - Database building
-- [Web Worker](public/worker.js) - Background sync
-- [API Routes](app/api/) - Webhook & version checking
-- [Tailwind Config](tailwind.config.ts) - Custom theme
-
-## 🚀 Deployment
-
-### Vercel (Recommended)
-```bash
-vercel deploy
-```
-
-### Environment Setup
-1. Add environment variables
-2. Configure GitHub webhook
-3. Set up database hosting
-4. Generate PWA icons
-
-## 💡 Future Enhancements
-
-- [ ] Advanced analytics
-- [ ] User accounts
-- [ ] Saved searches
-- [ ] Export functionality
-- [ ] Mobile app
-- [ ] Browser extension
-- [ ] API for developers
+**🚀 Powered By The Funk:** Next.js 15 • Tailwind CSS 4 • shadcn/ui • SQLite3 • Web Workers • PWA Magic
---
-**Built with 💜💗💛 and maximum awesomeness!**
+
-*This is a GROUND-BREAKING, NEXT-LEVEL, AAA webapp that perfectly complements the awesome CLI!*
+## 🎸 What's This Funkadelic Trip All About?
+
+Yo, check it! This ain't your grandma's GitHub list browser (no disrespect to grandma). This is a **FULL-BLOWN PSYCHEDELIC EXPERIENCE** for exploring awesome lists from GitHub. We're talkin' purple, pink, and GOLD, baby! We're talkin' FULL-TEXT SEARCH powered by SQLite FTS5 running at the SPEED OF FUNK! We're talkin' a personal list editor so smooth it'll make you wanna BOOGIE!
+
+### 🌟 The Cosmic Feature List (Funkometer: 11/10)
+
+#### 🎯 **The P-Funk Database Experience**
+- **FTS5 Full-Text Search** - Search faster than Bootsy's bass licks! ⚡
+- **Faceted Filtering** - Filter by language, stars, topics - smooth as silk! 🎨
+- **Hierarchical Navigation** - Browse awesome lists like you're navigating the Mothership 🚀
+- **Personal List Curation** - Save your faves with our WYSIWYG markdown editor (powered by TipTap) ✍️
+- **Real-time Updates** - Web workers polling for fresh data every 6 hours! 🔄
+- **PWA Ready** - Install it on ANY device and take the funk MOBILE! 📱
+
+#### 🕶️ **The Aesthetic Funk**
+- **Purple/Pink/Gold Theme** - Colors so fly, they'll make you CRY! 💜💗💛
+ - `#DA22FF` - That FUNKY Purple
+ - `#FF69B4` - That SASSY Pink
+ - `#FFD700` - That COSMIC Gold
+- **Gradient Everything** - Buttons, text, backgrounds - all sliding through the rainbow! 🌈
+- **Smooth Animations** - Transitions smoother than a James Brown slide! ✨
+- **Dark Mode** - For those late-night funk sessions! 🌙
+- **Custom Scrollbar** - Even the scrollbar got STYLE! 📜
+
+#### 🤖 **The Technical Groove**
+
+**Frontend Funk:**
+- Next.js 15 (App Router) + TypeScript - Modern as tomorrow!
+- Tailwind CSS 4 - Utility-first FUNK!
+- shadcn/ui Components - Beautiful AND accessible!
+- Radix UI - Headless but not heartless!
+- Motion/Framer Motion - Animations that MOVE you!
+- Lucide Icons - Icons with SOUL!
+
+**Backend Bass Line:**
+- SQLite3 + better-sqlite3 - Database with GROOVE!
+- FTS5 Full-Text Search - Finding stuff at LIGHT SPEED!
+- Node.js 22+ - The latest and GREATEST!
+- Zustand State Management - State so fresh it squeaks!
+
+**DevOps Drumbeat:**
+- GitHub Actions - Automated builds every 6 hours!
+- Web Workers - Background sync like a BACKBEAT!
+- PWA Support - Offline? NO PROBLEM!
+- Docker Ready - Container that CONTAINS the funk!
+
+---
+
+## 🎤 Getting Your Funk On (Installation)
+
+Alright, space cadets! Let's get this MOTHERSHIP launched!
+
+### 🛸 Prerequisites
+
+You're gonna need:
+- **Node.js 22+** (The funk requires modern tech!)
+- **pnpm** (Package manager with STYLE!)
+- **Better-sqlite3** (For that database GROOVE!)
+
+### 🚀 Launch Sequence
+
+```bash
+# Clone this funkadelic masterpiece
+git clone https://github.com/yourusername/awesome-web.git
+cd awesome-web
+
+# Install the cosmic dependencies
+pnpm install
+
+# Fire up the development server (Mothership: ACTIVATED!)
+pnpm dev
+
+# Open your browser to http://localhost:3000
+# Put on your sunglasses
+# Prepare for MAXIMUM FUNK! 🕶️
+```
+
+### 🏗️ Building for Production
+
+```bash
+# Build that funky fresh production bundle
+pnpm build
+
+# Launch the production server
+pnpm start
+
+# Deploy to Vercel/wherever and SPREAD THE FUNK! 🌍
+```
+
+---
+
+## 🎨 The Funkadelic Architecture
+
+```
+awesome-web/ 🏛️ THE MOTHERSHIP
+├── 🎸 app/
+│ ├── layout.tsx 💜 Root layout with COSMIC theme
+│ ├── globals.css 🎨 Where the MAGIC happens
+│ ├── page.tsx 🏠 Landing page of FUNK
+│ ├── search/ 🔍 Search with STYLE
+│ ├── browse/ 📚 Browse with GROOVE
+│ ├── my-list/ ✨ Personal list MAGIC
+│ └── api/ 🚀 API routes for DATA
+│ ├── search/ 💫 Full-text search endpoint
+│ ├── repositories/ 📦 Repository details
+│ ├── stats/ 📊 Database statistics
+│ └── db-version/ 🔄 Version checking
+│
+├── 🎵 components/
+│ ├── layout/
+│ │ ├── app-header.tsx 🎩 Header with ATTITUDE
+│ │ ├── app-sidebar.tsx 📂 Sidebar with SOUL
+│ │ └── command-menu.tsx ⌨️ Cmd+K for COSMIC search
+│ ├── personal-list/
+│ │ ├── personal-list-editor.tsx ✍️ WYSIWYG editor
+│ │ ├── push-to-list-button.tsx 💾 Save with STYLE
+│ │ └── sliding-panel.tsx 📱 Panel that SLIDES
+│ ├── readme/
+│ │ ├── readme-viewer.tsx 📖 Markdown with FLAVOR
+│ │ └── readme-header.tsx 🎯 Header with STARS
+│ └── ui/ 🎨 shadcn components with FUNK
+│
+├── 🎹 lib/
+│ ├── db.ts 💾 Database GROOVE
+│ ├── personal-list-store.ts 🗂️ Zustand state MAGIC
+│ ├── themes.ts 🎨 Theme POWER
+│ └── utils.ts 🔧 Utility FUNK
+│
+├── 🌟 public/
+│ ├── worker.js 🤖 Service worker MAGIC
+│ ├── manifest.json 📱 PWA manifest
+│ └── icons/ ✨ Funkadelic icons
+│
+├── 🎬 scripts/
+│ └── build-db.js 🏗️ Database builder (2 modes!)
+│
+└── 🚀 .github/workflows/
+ └── db.yml ⚙️ Automated builds every 6 hours
+```
+
+---
+
+## 🎯 Key Features (The Funk Breakdown)
+
+### 🔍 **Search Like You Mean It!**
+Our FTS5-powered search is FASTER than a cheetah on roller skates! Search by:
+- **Keywords** - Find ANYTHING in milliseconds!
+- **Language** - JavaScript? Python? We got 'em all!
+- **Stars** - Filter by popularity (but everything's a STAR here!)
+- **Category** - Organize that KNOWLEDGE!
+
+### 📝 **Personal List Editor - Your Own Awesome Creation!**
+Built with TipTap, this editor got MORE extensions than Parliament-Funkadelic:
+- ✨ Rich text formatting (bold, italic, strikethrough)
+- 📋 Tables, task lists, code blocks
+- 🎨 Syntax highlighting for code
+- 📊 Character count
+- 💾 Auto-save to localStorage (your funk is SAFE!)
+- 📤 Export to markdown (SHARE the funk!)
+
+### 🔄 **Smart Updates - Set It and Forget It!**
+Our Web Worker is like a ROBOT BASSIST - always keeping the rhythm:
+- Polls database version every 6 hours
+- Notifies you when new data drops
+- Cache invalidation (OLD data? GONE!)
+- Exponential backoff (SMART and efficient!)
+
+### 🎨 **Theme System - Purple Rain Meets Cosmic Slop!**
+
+```css
+/* The Funkadelic Palette */
+--awesome-purple: #DA22FF; /* 💜 Primary FUNK */
+--awesome-pink: #FF69B4; /* 💗 Secondary GROOVE */
+--awesome-gold: #FFD700; /* 💛 Accent SHINE */
+
+/* Gradients that'll BLOW YOUR MIND */
+background: linear-gradient(135deg,
+ #DA22FF 0%, /* Purple PASSION */
+ #9733EE 50%, /* Violet VIBES */
+ #FFD700 100% /* Golden GLORY */
+);
+```
+
+---
+
+## 🏗️ Automated Database Building (The GitHub Actions GROOVE)
+
+We got TWO build modes, baby!
+
+### ⚡ **Download Mode** (Default - Fast Like Lightning!)
+- Downloads pre-built database from `valknarness/awesome` repo
+- Takes ~5 minutes (TIME is money, honey!)
+- Runs every 6 hours automatically
+- Fallback to build mode if download fails (SMART!)
+
+### 🔨 **Build Mode** (Slow But Thorough!)
+- Clones awesome CLI and runs FULL indexing
+- Takes 1-2 hours (PATIENCE is a virtue!)
+- Manual trigger only (for the CONTROL FREAKS!)
+- Generates fresh database with ALL the data
+
+**Trigger it manually:**
+```bash
+# Via GitHub Actions UI
+# Select "Build mode" and hit "Run workflow"
+# Then sit back and let the FUNK flow! 🎸
+```
+
+---
+
+## 🚀 Deployment (Spread the Funk Worldwide!)
+
+### Deploy to Vercel (Recommended!)
+
+```bash
+# Install Vercel CLI
+pnpm i -g vercel
+
+# Deploy!
+vercel deploy
+
+# BOOM! Your funk is LIVE! 🌍
+```
+
+### Environment Variables (Keep 'em Secret, Keep 'em Safe!)
+
+```env
+# .env.local
+AWESOME_DB_PATH=/path/to/awesome.db
+WEBHOOK_SECRET=your-secret-here
+GITHUB_TOKEN=your-github-token
+```
+
+---
+
+## 🎯 What Makes This COSMICALLY AWESOME?
+
+1. **🎨 Perfect Theme Match** - Colors straight from the awesome CLI! HARMONIOUS!
+2. **⚡ Lightning Search** - FTS5 search faster than a meteor! ZOOM!
+3. **💾 Smart Caching** - Web workers keeping things FRESH!
+4. **🤖 Automation** - GitHub Actions building databases while you SLEEP!
+5. **📱 PWA Ready** - Install it ANYWHERE! Desktop! Mobile! TOASTER!
+6. **♿ Accessible** - Keyboard shortcuts, ARIA labels, semantic HTML - EVERYONE gets the funk!
+7. **🌗 Dark Mode** - Light mode for DAY, dark mode for NIGHT!
+8. **✨ Smooth UX** - Animations smoother than BUTTER on a hot skillet!
+
+---
+
+## 🎵 Development Notes (For the Funkateers!)
+
+### Adding shadcn/ui Components
+
+```bash
+npx shadcn@latest add button dialog dropdown-menu toast command scroll-area
+# Add ALL the components! MORE is MORE!
+```
+
+### Database Schema
+
+The SQLite database vibes with these tables:
+- `awesome_lists` - List metadata (ALL the lists!)
+- `repositories` - Repository data (ALL the repos!)
+- `readmes` - README content (ALL the docs!)
+- `readmes_fts` - FTS5 virtual table (SEARCH POWER!)
+
+### Path Aliases (Keep It Clean!)
+
+- `@/` - Project root (HOME base!)
+- `@/components` - UI components (BUILDING blocks!)
+- `@/lib` - Utilities (TOOL box!)
+- `@/app` - Next.js pages (THE routes!)
+
+---
+
+## 🌟 Future Enhancements (The Cosmic Roadmap!)
+
+- [ ] 🎮 **Gamification** - Earn badges for exploring lists! COLLECT 'EM ALL!
+- [ ] 👥 **User Accounts** - Save preferences in the CLOUD!
+- [ ] 📊 **Analytics Dashboard** - See what's TRENDING!
+- [ ] 🔔 **Push Notifications** - Get alerted when lists UPDATE!
+- [ ] 🌐 **Internationalization** - FUNK in every language!
+- [ ] 📱 **Mobile App** - React Native version (THE REMIX!)
+- [ ] 🔌 **Browser Extension** - Search from ANYWHERE!
+- [ ] 🤖 **AI Recommendations** - "You might also like..." with INTELLIGENCE!
+
+---
+
+## 📜 License
+
+MIT License - Free as a bird, baby! Use it, share it, FUNK IT UP!
+
+---
+
+
+
+## ⭐ CREDITS ⭐
+
+### 🎸 The One and Only FUNK Himself 🎸
+
+
+
+**Built with 💜💗💛 by funkateers worldwide**
+
+*"Free your mind and your code will follow!"*
+
+---
+
+### Special Shoutout To:
+
+🎤 **Bootsy Collins** - For inspiring the COSMIC vision
+🌟 **George Clinton** - For the MOTHERSHIP connection
+🎸 **Parliament-Funkadelic** - For the GROOVE foundation
+⭐ **sindresorhus/awesome** - For the original awesome lists
+💜 **The Open Source Community** - For keeping the FUNK alive
+
+---
+
+### 🕶️ One Nation Under A Groove 🕶️
+
+*If you dig this funkadelic masterpiece, drop us a ⭐ STAR ⭐ on GitHub!*
+*Let's spread the FUNK across the galaxy, one awesome list at a time!*
+
+
+
+**P-FUNK NEVER DIES!** 🎸✨🚀
+
+