Add comprehensive user guide and documentation

Co-authored-by: 0xrinegade <[email protected]>

Author: Copilot

docs/USER_GUIDE.md

@@ -0,0 +1,187 @@
+# GitHub Pages Site - User Guide
+
+Welcome to the Awesome Stargazer interactive web application!
+
+## Quick Start
+
+The site is deployed at: `https://opensvm.github.io/awesome-stargazer/`
+
+## Features Overview
+
+### 1. Repository Explorer (Tab 1)
+
+**What it does:** Browse all 19,564 repositories in a beautiful grid layout
+
+**How to use:**
+- View repository cards with name, description, and category
+- Click the bookmark icon to save repos for later
+- Click the heart icon to like repositories
+- Click the share icon to share on Twitter/X
+- Click the + icon to add to a learning path
+
+**Search:**
+- Type in the search bar to filter repos by name, description, or category
+- Results update instantly as you type
+- Use ⌘K (or Ctrl+K) to focus the search bar from anywhere
+- Press Esc to clear the search
+
+**Filters:**
+- **Category dropdown:** Filter by one of 567 categories
+- **Sort dropdown:** Sort by Name (A-Z), Name (Z-A), Category, or Most Liked
+
+### 2. Learning Paths Builder (Tab 2)
+
+**What it does:** Create personalized learning journeys by organizing repositories
+
+**How to use:**
+1. Click "Create New Path" button
+2. Enter a name and optional description
+3. From the Explorer tab, add repos using the + button
+4. Select which learning path to add the repo to
+5. Check off repos as you complete them
+6. Export your path as Markdown using the export button
+7. Share your path on Twitter/X
+8. Delete paths you no longer need
+
+**Features:**
+- Progress tracker shows completion percentage
+- Checkboxes to mark repos as completed
+- Remove individual repos from paths
+- Export as downloadable .md file
+
+### 3. Bookmarks (Tab 3)
+
+**What it does:** Quick access to your saved repositories
+
+**How to use:**
+- Bookmark repos from the Explorer tab
+- View all bookmarked repos in one place
+- Remove bookmarks by clicking the bookmark icon again
+- All bookmarks persist in your browser's localStorage
+
+**Tip:** The bookmark count appears as a badge in the navigation
+
+### 4. Statistics Dashboard (Tab 4)
+
+**What it does:** View aggregate statistics and trends
+
+**Shows:**
+- Total number of repositories
+- Total number of categories
+- Total likes given
+- Total bookmarks saved
+- Top 10 categories by repository count
+- Top 10 most liked repositories
+
+## Keyboard Shortcuts
+
+Power users can navigate faster with keyboard shortcuts:
+
+| Shortcut | Action |
+|----------|--------|
+| `⌘K` or `Ctrl+K` | Focus search bar |
+| `Esc` | Clear search or close modal |
+| `T` | Toggle dark/light theme |
+| `?` | Show keyboard shortcuts help |
+| `1` | Switch to Explorer tab |
+| `2` | Switch to Learning Paths tab |
+| `3` | Switch to Bookmarks tab |
+| `4` | Switch to Statistics tab |
+
+## Theme Switching
+
+Toggle between dark and light modes:
+- Click the sun/moon icon in the header
+- Press the `T` key
+- Your preference is saved and persists across sessions
+
+## Data Persistence
+
+All your data is saved locally in your browser:
+- **Bookmarks** - Saved repositories
+- **Likes** - Repositories you've liked
+- **Learning Paths** - All your created paths and progress
+- **Theme Preference** - Dark or light mode choice
+
+**Note:** Data is stored in localStorage and persists between sessions, but only on the device/browser you're using. Clearing browser data will reset everything.
+
+## Mobile Usage
+
+The site is fully responsive and works great on mobile:
+- Tap to interact with all buttons
+- Swipe to scroll through repositories
+- Navigation adapts to small screens
+- All features work on touch devices
+
+## Tips & Tricks
+
+1. **Quick Search:** Use ⌘K to instantly start searching from any tab
+
+2. **Bulk Bookmarking:** Bookmark multiple repos while browsing, then view them all in the Bookmarks tab
+
+3. **Learning Path Strategy:** Create paths by topic (e.g., "Learn React", "Master DevOps") for organized learning
+
+4. **Export for Backup:** Export your learning paths as Markdown files to keep external backups
+
+5. **Sort by Likes:** Use "Most Liked" sorting to see trending repositories
+
+6. **Category Exploration:** Use the category filter to discover repos in specific domains
+
+7. **Share Discoveries:** Use the share button to tweet about interesting repos you find
+
+## Troubleshooting
+
+**Site loads slowly:**
+- The initial load fetches 6.2MB of repository data
+- Subsequent visits should be faster due to browser caching
+- Try a faster internet connection
+
+**Data not persisting:**
+- Make sure you're not in private/incognito mode
+- Check that browser localStorage is enabled
+- Try a different browser if issues persist
+
+**Search not working:**
+- Clear the search box with Esc and try again
+- Refresh the page if needed
+- Make sure JavaScript is enabled
+
+**Mobile layout issues:**
+- Rotate device to landscape for more space
+- Zoom in/out if text is too small/large
+- Try updating to the latest browser version
+
+## Browser Compatibility
+
+Works in all modern browsers:
+- ✅ Chrome/Edge (recommended)
+- ✅ Firefox
+- ✅ Safari
+- ✅ Mobile Safari (iOS)
+- ✅ Chrome Mobile (Android)
+
+## Privacy
+
+- No tracking or analytics
+- No cookies used
+- All data stays on your device
+- No account required
+- No data sent to servers
+
+## Need Help?
+
+- Press `?` to see keyboard shortcuts
+- Check the README.md in the repository
+- Open an issue on GitHub for bugs or feature requests
+
+## Contributing
+
+Found a bug or have a suggestion? Contributions welcome!
+
+1. Fork the repository
+2. Make your changes
+3. Submit a pull request
+
+---
+
+Enjoy exploring 19,564 amazing repositories! 🚀