diff --git a/.github/ISSUES/01-unit-tests-useFetchStories.md b/.github/ISSUES/01-unit-tests-useFetchStories.md
new file mode 100644
index 0000000..009e8e2
--- /dev/null
+++ b/.github/ISSUES/01-unit-tests-useFetchStories.md
@@ -0,0 +1,62 @@
+---
+title: Add unit tests for useFetchStories hook
+labels: testing, enhancement, good-first-issue
+---
+
+## Description
+
+Create comprehensive unit tests for the `useFetchStories` custom hook to test caching logic, error handling, and API response handling.
+
+## Background
+
+Currently, the project README mentions Jest and React Testing Library but no test files exist in the repository. The `useFetchStories` hook has complex caching logic with ETag support and localStorage fallback that needs thorough testing to ensure reliability.
+
+## Requirements
+
+Tests should cover the following scenarios:
+
+1. **Successful API fetch**
+   - Fetches stories from DEV.to API successfully
+   - Sorts stories by published date
+   - Updates state correctly
+
+2. **Cache hit scenario**
+   - Returns cached data when cache is valid (within 5 minutes)
+   - Doesn't make API call when cache is fresh
+
+3. **Cache miss scenario**
+   - Makes API call when cache is expired
+   - Updates cache with new data
+
+4. **304 Not Modified response**
+   - Handles ETag-based cache validation
+   - Uses cached data when server returns 304
+
+5. **Error states**
+   - Handles API errors gracefully
+   - Sets appropriate error messages
+   - Falls back to expired cache when available
+
+6. **Expired cache fallback**
+   - Uses stale cache data when API fails
+   - Shows error message but displays cached content
+
+## Technical Details
+
+- File location: `hooks/useFetchStories.ts`
+- Test framework: Jest
+- Testing library: React Testing Library / React Hooks Testing Library
+- Mock localStorage and fetch API
+
+## Acceptance Criteria
+
+- [ ] Test file created at `hooks/useFetchStories.test.ts`
+- [ ] All 6 scenarios covered with tests
+- [ ] Tests pass successfully
+- [ ] Code coverage for the hook is above 90%
+- [ ] Tests are well-documented with clear descriptions
+
+## Related Files
+
+- `hooks/useFetchStories.ts` - Hook to be tested
+- `types/index.ts` - Type definitions used by the hook
diff --git a/.github/ISSUES/02-e2e-tests-playwright.md b/.github/ISSUES/02-e2e-tests-playwright.md
new file mode 100644
index 0000000..e4ea138
--- /dev/null
+++ b/.github/ISSUES/02-e2e-tests-playwright.md
@@ -0,0 +1,83 @@
+---
+title: Add comprehensive E2E tests with Playwright
+labels: testing, enhancement, infrastructure
+---
+
+## Description
+
+Implement end-to-end testing suite using Playwright to test critical user flows and prevent regressions.
+
+## Background
+
+Currently, no E2E tests exist despite having critical user flows like story navigation, mini-game interaction, and API error handling. E2E tests would ensure quality before deployment and catch integration issues early.
+
+## Requirements
+
+### Test Coverage
+
+1. **Story Navigation Flow**
+   - Load application and verify stories are displayed
+   - Navigate forward through stories
+   - Navigate backward through stories
+   - Verify story counter updates correctly
+
+2. **Mini-Game Interaction**
+   - Toggle mini-game visibility
+   - Start the game
+   - Use arrow keys to move player
+   - Verify collision detection
+   - Check score updates
+
+3. **API Error Handling**
+   - Mock API failures
+   - Verify error messages are displayed
+   - Verify fallback to cached data works
+
+4. **Caching Behavior**
+   - Verify localStorage caching
+   - Test cache expiration
+   - Test ETag-based validation
+
+5. **Accessibility Features**
+   - Test keyboard navigation
+   - Verify ARIA labels
+   - Test focus management
+
+6. **Responsive Design**
+   - Test on mobile viewport
+   - Test on tablet viewport
+   - Test on desktop viewport
+
+## Technical Details
+
+- Install Playwright: `npm install -D @playwright/test`
+- Create test configuration: `playwright.config.ts`
+- Create test directory: `e2e/` or `tests/e2e/`
+- Add script to package.json: `"test:e2e": "playwright test"`
+
+## Acceptance Criteria
+
+- [ ] Playwright installed and configured
+- [ ] All 6 test categories implemented
+- [ ] Tests pass on Chromium, Firefox, and WebKit
+- [ ] GitHub Actions workflow includes E2E tests
+- [ ] Test reports generated and accessible
+- [ ] README updated with testing instructions
+
+## CI/CD Integration
+
+Add to `.github/workflows/nextjs.yml`:
+```yaml
+- name: Install Playwright Browsers
+  run: npx playwright install --with-deps
+  
+- name: Run E2E tests
+  run: npm run test:e2e
+```
+
+## Related Files
+
+- `app/page.tsx` - Main page component
+- `components/StoryCard.tsx` - Story display component
+- `components/MiniGame.tsx` - Mini-game component
+- `hooks/useFetchStories.ts` - Data fetching logic
diff --git a/.github/ISSUES/03-loading-skeleton-storycard.md b/.github/ISSUES/03-loading-skeleton-storycard.md
new file mode 100644
index 0000000..9ff266a
--- /dev/null
+++ b/.github/ISSUES/03-loading-skeleton-storycard.md
@@ -0,0 +1,94 @@
+---
+title: Add loading skeleton for StoryCard component
+labels: enhancement, ui/ux, performance
+---
+
+## Description
+
+Replace the simple "Loading stories..." text with an animated skeleton loader that matches the StoryCard layout to improve perceived performance.
+
+## Background
+
+Currently, when stories are loading, users see only plain text saying "Loading stories...". A skeleton loader provides visual feedback about the layout structure and creates a better perceived performance, making the app feel faster and more polished.
+
+## Requirements
+
+### Skeleton Structure
+
+The skeleton should include placeholders for:
+1. **Header section**
+   - Title placeholder (2-3 lines)
+   - XP badge placeholder
+
+2. **Content section**
+   - Description placeholder (4-5 lines)
+
+3. **Author section**
+   - Avatar placeholder (circular, 48x48px)
+   - Author name placeholder (1 line)
+   - Username placeholder (1 line)
+
+4. **Footer section**
+   - Progress bar placeholder
+   - Navigation buttons placeholders
+   - Level indicator placeholder
+
+### Animation
+
+- Use CSS shimmer/pulse animation effect
+- Animation should be smooth and subtle
+- **Must respect `prefers-reduced-motion`** - no animation for users who prefer reduced motion
+
+## Technical Details
+
+**Option 1: Pure CSS Implementation**
+```css
+.skeleton {
+  background: linear-gradient(
+    90deg,
+    var(--skeleton-base) 0%,
+    var(--skeleton-highlight) 50%,
+    var(--skeleton-base) 100%
+  );
+  background-size: 200% 100%;
+  animation: shimmer 1.5s infinite;
+}
+
+@keyframes shimmer {
+  0% { background-position: -200% 0; }
+  100% { background-position: 200% 0; }
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .skeleton {
+    animation: none;
+  }
+}
+```
+
+**Option 2: Use a library**
+- `react-loading-skeleton` or similar
+
+## Acceptance Criteria
+
+- [ ] Create `SkeletonCard` component or skeleton variant of `StoryCard`
+- [ ] Skeleton matches the actual `StoryCard` layout
+- [ ] Smooth shimmer/pulse animation implemented
+- [ ] Animation respects `prefers-reduced-motion`
+- [ ] Skeleton shown during initial load
+- [ ] Skeleton shown when refetching stories
+- [ ] Works well with dark/light themes (if theme toggle exists)
+- [ ] No layout shift when skeleton is replaced with actual content
+
+## Design Considerations
+
+- Use existing CSS variables for colors
+- Skeleton should be subtle, not distracting
+- Border radius should match actual card
+- Spacing should match actual card layout
+
+## Related Files
+
+- `components/StoryCard.tsx` - Main card component
+- `app/page.tsx` - Page that shows loading state
+- `components/StoryCard.module.css` - Card styles
diff --git a/.github/ISSUES/04-bundle-optimization-code-splitting.md b/.github/ISSUES/04-bundle-optimization-code-splitting.md
new file mode 100644
index 0000000..f9830e4
--- /dev/null
+++ b/.github/ISSUES/04-bundle-optimization-code-splitting.md
@@ -0,0 +1,114 @@
+---
+title: Optimize bundle size and implement code splitting
+labels: performance, enhancement, optimization
+---
+
+## Description
+
+Analyze and optimize bundle size using next/bundle-analyzer to improve initial load time and Core Web Vitals scores.
+
+## Background
+
+Currently, no bundle analysis is configured, and all components load upfront. The MiniGame component, in particular, is loaded even when not used, increasing the initial bundle size unnecessarily.
+
+## Requirements
+
+### 1. Bundle Analysis Setup
+
+Install and configure `@next/bundle-analyzer`:
+```bash
+npm install --save-dev @next/bundle-analyzer
+```
+
+Configure in `next.config.mjs`:
+```javascript
+import bundleAnalyzer from '@next/bundle-analyzer';
+
+const withBundleAnalyzer = bundleAnalyzer({
+  enabled: process.env.ANALYZE === 'true',
+});
+
+export default withBundleAnalyzer({
+  // ... existing config
+});
+```
+
+Add script to `package.json`:
+```json
+"analyze": "ANALYZE=true npm run build"
+```
+
+### 2. Dynamic Imports
+
+Implement dynamic imports for components that are:
+- Not needed on initial render
+- Behind user interaction
+- Heavy/large components
+
+**Priority: MiniGame component**
+```tsx
+const MiniGame = dynamic(() => import('../components/MiniGame').then(mod => ({ default: mod.MiniGame })), {
+  loading: () => <div>Loading game...</div>,
+  ssr: false
+});
+```
+
+### 3. Image Optimization
+
+Ensure all images are properly optimized:
+- Use `next/image` consistently (already done for profile images)
+- Optimize SVG files in `/public`
+- Consider using WebP format where appropriate
+
+### 4. Dependency Audit
+
+Review and optimize dependencies:
+- Check for unused dependencies
+- Look for lighter alternatives to heavy libraries
+- Ensure proper tree-shaking
+
+### 5. Route-Based Code Splitting
+
+Verify Next.js automatic code splitting is working:
+- Check each route has its own bundle
+- Verify shared chunks are optimized
+
+## Target Metrics
+
+- **Initial bundle size**: < 200KB (gzipped)
+- **First Contentful Paint (FCP)**: < 1.8s
+- **Largest Contentful Paint (LCP)**: < 2.5s
+- **Time to Interactive (TTI)**: < 3.8s
+
+## Acceptance Criteria
+
+- [ ] Bundle analyzer installed and configured
+- [ ] Analysis script added to package.json
+- [ ] MiniGame component dynamically imported
+- [ ] Bundle analysis report generated and reviewed
+- [ ] Identified and removed unused dependencies (if any)
+- [ ] Documentation added explaining bundle optimization strategy
+- [ ] Performance improvements measured and documented
+- [ ] Core Web Vitals scores improved
+
+## Implementation Steps
+
+1. Install and configure bundle analyzer
+2. Run initial analysis to establish baseline
+3. Implement dynamic import for MiniGame
+4. Re-run analysis to measure improvement
+5. Identify other optimization opportunities
+6. Document findings and results
+
+## Related Files
+
+- `next.config.mjs` - Next.js configuration
+- `package.json` - Dependencies and scripts
+- `app/page.tsx` - Main page (imports MiniGame)
+- `components/MiniGame.tsx` - Component to be dynamically loaded
+
+## Resources
+
+- [Next.js Bundle Analyzer](https://www.npmjs.com/package/@next/bundle-analyzer)
+- [Next.js Dynamic Imports](https://nextjs.org/docs/advanced-features/dynamic-import)
+- [Web Vitals](https://web.dev/vitals/)
diff --git a/.github/ISSUES/05-rate-limiting-retry-logic.md b/.github/ISSUES/05-rate-limiting-retry-logic.md
new file mode 100644
index 0000000..74d6dbe
--- /dev/null
+++ b/.github/ISSUES/05-rate-limiting-retry-logic.md
@@ -0,0 +1,120 @@
+---
+title: Implement rate limiting and error retry logic
+labels: enhancement, reliability, bug
+---
+
+## Description
+
+Add exponential backoff retry logic and proper rate limit handling for DEV.to API calls to improve reliability and user experience.
+
+## Background
+
+Currently, if an API call to DEV.to fails, the app only tries once. This can lead to failures during temporary network issues or API rate limiting. Implementing retry logic with exponential backoff would significantly improve reliability.
+
+## Requirements
+
+### 1. Exponential Backoff Retry
+
+Implement retry logic with exponential backoff:
+- **Maximum retries**: 3 attempts
+- **Backoff strategy**: 1s, 2s, 4s
+- **Jitter**: Add random jitter to prevent thundering herd
+
+Example implementation:
+```typescript
+async function fetchWithRetry(url: string, options: RequestInit, maxRetries = 3) {
+  for (let i = 0; i < maxRetries; i++) {
+    try {
+      const response = await fetch(url, options);
+      
+      // Don't retry on 4xx errors (except 429)
+      if (response.status >= 400 && response.status < 500 && response.status !== 429) {
+        throw new Error(`Client error: ${response.status}`);
+      }
+      
+      if (!response.ok) {
+        throw new Error(`HTTP error: ${response.status}`);
+      }
+      
+      return response;
+    } catch (error) {
+      const isLastAttempt = i === maxRetries - 1;
+      if (isLastAttempt) throw error;
+      
+      // Exponential backoff with jitter
+      const delay = Math.pow(2, i) * 1000 + Math.random() * 1000;
+      await new Promise(resolve => setTimeout(resolve, delay));
+    }
+  }
+}
+```
+
+### 2. Rate Limit Handling
+
+Properly handle 429 (Too Many Requests) responses:
+- Check for `Retry-After` header
+- Show user-friendly message explaining rate limit
+- Automatically retry after specified time
+- Consider implementing request throttling
+
+### 3. User-Friendly Error Messages
+
+Provide specific error messages for different scenarios:
+- **Network error**: "Unable to connect. Please check your internet connection."
+- **Rate limited**: "Too many requests. Retrying in [X] seconds..."
+- **Server error**: "DEV.to is temporarily unavailable. Using cached stories."
+- **Timeout**: "Request timed out. Please try again."
+
+### 4. Request Debouncing
+
+If implementing a refresh button, add debouncing to prevent rapid requests:
+```typescript
+const debouncedFetch = debounce(fetchStories, 2000);
+```
+
+## Technical Implementation
+
+### Files to Modify
+
+**`hooks/useFetchStories.ts`**
+- Add retry logic to fetch function
+- Handle rate limiting
+- Improve error messages
+- Add request debouncing (if refresh functionality exists)
+
+### New Utility (Optional)
+
+Create `utils/fetchWithRetry.ts` for reusable retry logic
+
+## Acceptance Criteria
+
+- [ ] Retry logic implemented with exponential backoff
+- [ ] Maximum 3 retry attempts
+- [ ] Random jitter added to prevent thundering herd
+- [ ] 429 rate limit responses handled with Retry-After header
+- [ ] User-friendly error messages for different error types
+- [ ] Cached data used as fallback when available
+- [ ] Loading states properly reflect retry attempts
+- [ ] Tests added for retry logic
+- [ ] Documentation updated
+
+## Testing
+
+Test scenarios to verify:
+1. Successful fetch after 1 retry
+2. Successful fetch after 2 retries
+3. Failure after 3 retries
+4. Rate limit handling with Retry-After
+5. Immediate failure on 4xx errors (except 429)
+6. Fallback to cache on repeated failures
+
+## Related Files
+
+- `hooks/useFetchStories.ts` - Main hook to modify
+- `types/index.ts` - Type definitions
+
+## Resources
+
+- [Exponential Backoff](https://en.wikipedia.org/wiki/Exponential_backoff)
+- [DEV.to API Rate Limits](https://developers.forem.com/api/#section/Rate-limiting)
+- [HTTP 429 Status Code](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/429)
diff --git a/.github/ISSUES/06-keyboard-shortcuts-navigation.md b/.github/ISSUES/06-keyboard-shortcuts-navigation.md
new file mode 100644
index 0000000..e4f537a
--- /dev/null
+++ b/.github/ISSUES/06-keyboard-shortcuts-navigation.md
@@ -0,0 +1,134 @@
+---
+title: Implement keyboard shortcuts for story navigation
+labels: enhancement, accessibility, a11y
+---
+
+## Description
+
+Add keyboard shortcuts (arrow keys) for navigating between stories when the mini-game is not active, improving accessibility and user experience.
+
+## Background
+
+Currently, users can only navigate between stories using mouse clicks on the "Previous" and "Next" buttons. Adding keyboard navigation would significantly improve accessibility for keyboard-only users and provide a more efficient navigation experience for all users.
+
+## Requirements
+
+### Keyboard Shortcuts
+
+- **Left Arrow** (←): Navigate to previous story
+- **Right Arrow** (→): Navigate to next story
+- **Escape**: Close mini-game (if open)
+
+### Behavior
+
+1. **When mini-game is NOT active**:
+   - Arrow keys navigate between stories
+   - Visual feedback on button when key is pressed
+
+2. **When mini-game IS active**:
+   - Arrow keys control the game (existing behavior)
+   - Story navigation is disabled
+
+3. **Focus management**:
+   - Shortcuts work regardless of which element has focus
+   - Don't interfere with form inputs (if any added in future)
+
+### Accessibility Considerations
+
+- Add visual indicator showing keyboard shortcuts are available
+- Include keyboard shortcuts in "How to Play" section
+- Add `aria-live` announcement when story changes via keyboard
+- Ensure shortcuts don't conflict with browser/screen reader shortcuts
+
+## Technical Implementation
+
+```typescript
+// In app/page.tsx
+useEffect(() => {
+  const handleKeyDown = (e: KeyboardEvent) => {
+    // Don't handle shortcuts in input fields
+    if (e.target instanceof HTMLInputElement || e.target instanceof HTMLTextAreaElement) {
+      return;
+    }
+    
+    // Don't handle shortcuts when mini-game is active
+    if (showMiniGame) {
+      return;
+    }
+    
+    if (e.key === 'ArrowLeft') {
+      e.preventDefault();
+      prevStory();
+    } else if (e.key === 'ArrowRight') {
+      e.preventDefault();
+      nextStory();
+    }
+  };
+  
+  window.addEventListener('keydown', handleKeyDown);
+  return () => window.removeEventListener('keydown', handleKeyDown);
+}, [showMiniGame, prevStory, nextStory]);
+```
+
+### Visual Indicators
+
+Add keyboard shortcut hints to the navigation buttons:
+```tsx
+<button onClick={onPrevious} className={styles.navButton}>
+  ← Previous
+  <span className={styles.keyboardHint}>Left arrow</span>
+</button>
+```
+
+## Acceptance Criteria
+
+- [ ] Left arrow key navigates to previous story
+- [ ] Right arrow key navigates to next story
+- [ ] Shortcuts disabled when mini-game is active
+- [ ] Shortcuts work from anywhere on the page (except form inputs)
+- [ ] Visual indicators added to show keyboard shortcuts
+- [ ] "How to Play" section updated with keyboard shortcuts
+- [ ] ARIA announcements added for screen reader users
+- [ ] No conflicts with existing functionality
+- [ ] Works across all major browsers
+
+## UI Updates
+
+### Navigation Buttons
+Add subtle keyboard shortcut hints to buttons:
+```css
+.keyboardHint {
+  font-size: 0.75rem;
+  opacity: 0.6;
+  margin-left: 0.5rem;
+}
+```
+
+### How to Play Section
+Update the "Read Stories" card to include:
+```markdown
+- Use Left/Right arrow keys for quick navigation
+- Click Previous/Next buttons to navigate between stories
+```
+
+## Testing Checklist
+
+- [ ] Arrow keys navigate stories when game is closed
+- [ ] Arrow keys control game when game is open
+- [ ] Escape key closes mini-game (if implemented)
+- [ ] No interference with form inputs
+- [ ] Screen reader announces story changes
+- [ ] Visual feedback on keyboard navigation
+- [ ] Works without mouse interaction
+
+## Related Files
+
+- `app/page.tsx` - Add keyboard event listeners
+- `components/StoryCard.tsx` - Update button UI with hints
+- `components/HowToPlay.tsx` - Add keyboard shortcut documentation
+- `components/StoryCard.module.css` - Styles for keyboard hints
+
+## Accessibility Resources
+
+- [WCAG 2.1 Keyboard Accessible](https://www.w3.org/WAI/WCAG21/Understanding/keyboard.html)
+- [MDN Keyboard Events](https://developer.mozilla.org/en-US/docs/Web/API/KeyboardEvent)
diff --git a/.github/ISSUES/07-dark-light-theme-toggle.md b/.github/ISSUES/07-dark-light-theme-toggle.md
new file mode 100644
index 0000000..490e678
--- /dev/null
+++ b/.github/ISSUES/07-dark-light-theme-toggle.md
@@ -0,0 +1,180 @@
+---
+title: Add dark/light theme toggle
+labels: enhancement, accessibility, ui/ux, a11y
+---
+
+## Description
+
+Implement a theme toggle feature to switch between light and dark modes, enhancing user experience and accessibility.
+
+## Background
+
+The application currently has CSS variables defined in the codebase that suggest theme support, but there's no user-facing toggle to switch themes. Many users prefer dark mode for reduced eye strain, especially during extended reading sessions.
+
+## Requirements
+
+### Core Functionality
+
+1. **Theme Toggle UI**
+   - Add theme toggle button in the header (near score/title)
+   - Use icon: 🌙 for dark mode, ☀️ for light mode
+   - Smooth transition between themes (respect prefers-reduced-motion)
+
+2. **Theme Persistence**
+   - Save user preference in localStorage
+   - Restore theme on page load
+   - Prevent flash of wrong theme (FOUT)
+
+3. **System Preference Detection**
+   - Detect `prefers-color-scheme` media query
+   - Use system preference as default (if no saved preference)
+   - Allow user to override system preference
+
+4. **Theme Implementation**
+   - Light mode (default)
+   - Dark mode with appropriate color palette
+
+### Color Palette
+
+Define CSS variables for both themes:
+
+```css
+/* Light Theme (default) */
+:root {
+  --background-primary: rgb(255, 255, 255);
+  --background-secondary: rgb(245, 245, 247);
+  --foreground: rgb(0, 0, 0);
+  --foreground-secondary: rgb(60, 60, 67);
+  --border-color: rgb(229, 229, 234);
+  --card-background: rgb(255, 255, 255);
+  --card-shadow: rgba(0, 0, 0, 0.1);
+}
+
+/* Dark Theme */
+[data-theme="dark"] {
+  --background-primary: rgb(0, 0, 0);
+  --background-secondary: rgb(28, 28, 30);
+  --foreground: rgb(255, 255, 255);
+  --foreground-secondary: rgb(174, 174, 178);
+  --border-color: rgb(58, 58, 60);
+  --card-background: rgb(28, 28, 30);
+  --card-shadow: rgba(0, 0, 0, 0.3);
+}
+```
+
+## Technical Implementation
+
+### 1. Theme Context/Hook
+
+Create `hooks/useTheme.ts`:
+```typescript
+export function useTheme() {
+  const [theme, setTheme] = useState<'light' | 'dark'>('light');
+  
+  useEffect(() => {
+    // Check localStorage
+    const saved = localStorage.getItem('theme');
+    if (saved) {
+      setTheme(saved as 'light' | 'dark');
+      return;
+    }
+    
+    // Check system preference
+    const prefersDark = window.matchMedia('(prefers-color-scheme: dark)').matches;
+    setTheme(prefersDark ? 'dark' : 'light');
+  }, []);
+  
+  useEffect(() => {
+    document.documentElement.setAttribute('data-theme', theme);
+    localStorage.setItem('theme', theme);
+  }, [theme]);
+  
+  const toggleTheme = () => {
+    setTheme(prev => prev === 'light' ? 'dark' : 'light');
+  };
+  
+  return { theme, toggleTheme };
+}
+```
+
+### 2. Theme Toggle Component
+
+Create `components/ThemeToggle.tsx`:
+```tsx
+export const ThemeToggle: React.FC = () => {
+  const { theme, toggleTheme } = useTheme();
+  
+  return (
+    <button
+      onClick={toggleTheme}
+      aria-label={`Switch to ${theme === 'light' ? 'dark' : 'light'} mode`}
+      className={styles.themeToggle}
+    >
+      {theme === 'light' ? '🌙' : '☀️'}
+    </button>
+  );
+};
+```
+
+### 3. Prevent Flash of Unstyled Theme
+
+Add inline script in `app/layout.tsx` (before other content):
+```tsx
+<script
+  dangerouslySetInnerHTML={{
+    __html: `
+      (function() {
+        const theme = localStorage.getItem('theme') || 
+          (window.matchMedia('(prefers-color-scheme: dark)').matches ? 'dark' : 'light');
+        document.documentElement.setAttribute('data-theme', theme);
+      })();
+    `
+  }}
+/>
+```
+
+## Acceptance Criteria
+
+- [ ] Theme toggle button added to header
+- [ ] Dark and light themes fully implemented
+- [ ] Theme persists across page reloads
+- [ ] System preference detected and used as default
+- [ ] No flash of unstyled content (FOUT)
+- [ ] Smooth transitions between themes
+- [ ] Transitions respect `prefers-reduced-motion`
+- [ ] All components render correctly in both themes
+- [ ] Contrast ratios meet WCAG AA standards in both themes
+- [ ] Documentation updated with theme feature
+
+## Testing Checklist
+
+- [ ] Toggle switches between light and dark mode
+- [ ] Theme persists after page reload
+- [ ] System preference properly detected
+- [ ] User preference overrides system preference
+- [ ] No FOUT on initial page load
+- [ ] All components readable in both themes
+- [ ] Icons/images appropriate for each theme
+- [ ] Proper ARIA labels on toggle button
+
+## Accessibility Considerations
+
+- Toggle button has proper ARIA label
+- Keyboard accessible (tab + enter/space)
+- Visual focus indicator on toggle button
+- Sufficient contrast in both themes (WCAG AA: 4.5:1 for text)
+- Icons clearly indicate current/next theme state
+
+## Related Files
+
+- `app/globals.css` - Theme variables
+- `app/styles/variables.css` - CSS variables
+- `app/layout.tsx` - Add theme prevention script
+- `components/GameHeader.tsx` - Add toggle button
+- `hooks/useTheme.ts` - New theme hook (to create)
+- `components/ThemeToggle.tsx` - New toggle component (to create)
+
+## Resources
+
+- [Dark Mode Best Practices](https://web.dev/prefers-color-scheme/)
+- [CSS Custom Properties](https://developer.mozilla.org/en-US/docs/Web/CSS/Using_CSS_custom_properties)
diff --git a/.github/ISSUES/08-accessibility-audit.md b/.github/ISSUES/08-accessibility-audit.md
new file mode 100644
index 0000000..81a2530
--- /dev/null
+++ b/.github/ISSUES/08-accessibility-audit.md
@@ -0,0 +1,216 @@
+---
+title: Implement comprehensive accessibility audit fixes
+labels: accessibility, a11y, enhancement, bug
+---
+
+## Description
+
+Conduct a comprehensive accessibility audit using automated tools and fix identified issues to ensure WCAG 2.1 AA compliance.
+
+## Background
+
+While the README claims WCAG 2.1 AA compliance, no formal accessibility testing has been documented. A thorough audit will identify and fix any accessibility barriers for users with disabilities.
+
+## Audit Tools to Use
+
+1. **Automated Testing**
+   - [axe DevTools](https://www.deque.com/axe/devtools/) browser extension
+   - [Lighthouse](https://developers.google.com/web/tools/lighthouse) in Chrome DevTools
+   - [WAVE](https://wave.webaim.org/) browser extension
+   - `@axe-core/react` for runtime testing
+
+2. **Manual Testing**
+   - Keyboard-only navigation
+   - Screen reader testing (NVDA/JAWS/VoiceOver)
+   - Browser zoom to 200%
+   - High contrast mode testing
+
+## Areas to Audit
+
+### 1. Semantic HTML
+
+- [ ] Proper heading hierarchy (h1 → h2 → h3, no skipping)
+- [ ] Use semantic elements (`<nav>`, `<main>`, `<article>`, etc.)
+- [ ] Buttons vs. links used appropriately
+- [ ] Form elements have associated labels
+
+### 2. ARIA Labels and Roles
+
+- [ ] All interactive elements have accessible names
+- [ ] ARIA roles used correctly (not overriding semantics)
+- [ ] ARIA attributes have valid values
+- [ ] Live regions for dynamic content updates
+- [ ] Current state communicated (aria-current, aria-expanded)
+
+### 3. Keyboard Navigation
+
+- [ ] All interactive elements keyboard accessible
+- [ ] Logical tab order
+- [ ] Visible focus indicators on all focusable elements
+- [ ] No keyboard traps
+- [ ] Skip links for main content
+
+### 4. Color and Contrast
+
+- [ ] Text contrast ratio ≥ 4.5:1 (WCAG AA)
+- [ ] Large text (18pt+) contrast ratio ≥ 3:1
+- [ ] Information not conveyed by color alone
+- [ ] UI component contrast ≥ 3:1
+
+### 5. Images and Media
+
+- [ ] All images have descriptive alt text
+- [ ] Decorative images have empty alt=""
+- [ ] SVG images have titles or aria-labels
+- [ ] Profile images have meaningful alt text
+
+### 6. Forms and Inputs
+
+- [ ] All form inputs have labels
+- [ ] Error messages associated with inputs
+- [ ] Required fields indicated
+- [ ] Input purposes identified (autocomplete)
+
+### 7. Focus Management
+
+- [ ] Focus set appropriately after dynamic changes
+- [ ] Modal dialogs trap focus
+- [ ] Focus restored when modals close
+- [ ] No focus on hidden elements
+
+### 8. Screen Reader Experience
+
+- [ ] Page title is descriptive
+- [ ] Landmarks used appropriately
+- [ ] Content has logical reading order
+- [ ] Announcements for important updates
+- [ ] Links have descriptive text (no "click here")
+
+### 9. Touch Targets
+
+- [ ] Minimum touch target size: 44x44 pixels
+- [ ] Adequate spacing between targets
+- [ ] Works with touch and pointer devices
+
+### 10. Responsive and Zoom
+
+- [ ] Content reflows at 400% zoom
+- [ ] No horizontal scrolling at 320px width
+- [ ] Text can be resized to 200%
+- [ ] No loss of content or functionality
+
+## Implementation Tasks
+
+### Setup Automated Testing
+
+Add to `package.json`:
+```json
+{
+  "scripts": {
+    "a11y:test": "axe localhost:3000 --exit",
+    "lighthouse": "lighthouse http://localhost:3000 --view"
+  },
+  "devDependencies": {
+    "@axe-core/cli": "^4.7.0",
+    "@axe-core/react": "^4.7.0"
+  }
+}
+```
+
+### Create Accessibility Testing Script
+
+Create `scripts/test-accessibility.js`:
+```javascript
+const { AxePuppeteer } = require('@axe-core/puppeteer');
+const puppeteer = require('puppeteer');
+
+async function runAccessibilityTest() {
+  const browser = await puppeteer.launch();
+  const page = await browser.newPage();
+  await page.goto('http://localhost:3000');
+  
+  const results = await new AxePuppeteer(page).analyze();
+  
+  console.log(`Found ${results.violations.length} accessibility violations`);
+  console.log(JSON.stringify(results.violations, null, 2));
+  
+  await browser.close();
+  
+  process.exit(results.violations.length > 0 ? 1 : 0);
+}
+
+runAccessibilityTest();
+```
+
+## Known Issues to Fix
+
+Based on initial review, likely issues include:
+
+1. **StoryCard.tsx**
+   - Progress bar needs aria-label
+   - XP badge might need better context
+   - Links need more descriptive text than just icons
+
+2. **MiniGame.tsx**
+   - Game canvas/area needs accessible alternative
+   - Score updates need aria-live region
+   - Game state changes need announcements
+
+3. **Navigation.tsx**
+   - Ensure buttons have accessible names
+   - Active state communicated
+
+4. **GameHeader.tsx**
+   - Score display might need semantic markup
+   - Toggle button needs proper ARIA
+
+## Acceptance Criteria
+
+- [ ] Automated accessibility tests pass with 0 violations
+- [ ] Lighthouse accessibility score ≥ 95
+- [ ] Manual keyboard navigation test passed
+- [ ] Manual screen reader test passed
+- [ ] Color contrast ratios verified (WCAG AA)
+- [ ] All images have appropriate alt text
+- [ ] Accessibility testing script added to package.json
+- [ ] CI/CD includes accessibility tests
+- [ ] Documentation updated with accessibility features
+- [ ] Accessibility statement added to footer
+
+## Documentation
+
+Create `ACCESSIBILITY.md`:
+```markdown
+# Accessibility Statement
+
+WeCoded Game is committed to ensuring digital accessibility for people with disabilities. We are continually improving the user experience for everyone and applying relevant accessibility standards.
+
+## Conformance Status
+This website is partially conformant with WCAG 2.1 level AA.
+
+## Feedback
+We welcome your feedback on the accessibility of WeCoded Game. Please contact us if you encounter accessibility barriers.
+
+## Features
+- Keyboard navigation
+- Screen reader support
+- High contrast mode
+- Reduced motion support
+- Responsive design with zoom support
+```
+
+## Related Files
+
+- `components/StoryCard.tsx`
+- `components/MiniGame.tsx`
+- `components/GameHeader.tsx`
+- `components/Navigation.tsx`
+- `app/page.tsx`
+- `app/globals.css`
+
+## Resources
+
+- [WCAG 2.1 Guidelines](https://www.w3.org/WAI/WCAG21/quickref/)
+- [axe DevTools](https://www.deque.com/axe/devtools/)
+- [WebAIM Contrast Checker](https://webaim.org/resources/contrastchecker/)
+- [A11y Project Checklist](https://www.a11yproject.com/checklist/)
diff --git a/.github/ISSUES/09-story-bookmarking.md b/.github/ISSUES/09-story-bookmarking.md
new file mode 100644
index 0000000..8f37672
--- /dev/null
+++ b/.github/ISSUES/09-story-bookmarking.md
@@ -0,0 +1,181 @@
+---
+title: Implement story bookmarking/favorites feature
+labels: enhancement, feature, user-experience
+---
+
+## Description
+
+Add the ability for users to bookmark/favorite stories they like, allowing them to save content for later reading and increase engagement.
+
+## Background
+
+Currently, users can read stories but have no way to save them for later reference. A bookmarking feature would allow users to curate their own collection of favorite stories, increasing user engagement and retention.
+
+## Requirements
+
+### Core Functionality
+
+1. **Bookmark Button**
+   - Add bookmark icon to StoryCard component
+   - Visual states: bookmarked vs. not bookmarked
+   - Toggle bookmark on click
+   - Icon: ⭐ (filled) for bookmarked, ☆ (outline) for not bookmarked
+
+2. **Data Persistence**
+   - Store bookmarked story IDs in localStorage
+   - Key: `wecoded_bookmarks`
+   - Format: `{ bookmarks: number[], timestamp: number }`
+
+3. **Bookmarks View**
+   - Add "Bookmarks" or "Favorites" button in navigation
+   - Filter to show only bookmarked stories
+   - Show count of bookmarked stories
+   - Handle empty state: "No bookmarks yet"
+
+4. **Visual Indicators**
+   - Badge showing bookmark count
+   - Visual indicator on bookmarked stories in main view
+   - Confirmation animation when bookmarking
+
+## UI Design
+
+### Bookmark Button on StoryCard
+
+Add to header section alongside XP badge:
+```tsx
+<div className={styles.header}>
+  <h3 className={styles.title}>{story.title}</h3>
+  <div className={styles.badges}>
+    <span className={styles.xp}>+100 XP</span>
+    <button
+      onClick={toggleBookmark}
+      className={styles.bookmarkButton}
+      aria-label={isBookmarked ? 'Remove bookmark' : 'Add bookmark'}
+    >
+      {isBookmarked ? '⭐' : '☆'}
+    </button>
+  </div>
+</div>
+```
+
+### Navigation Enhancement
+
+```tsx
+<button onClick={toggleBookmarksView} className={styles.navButton}>
+  {showBookmarks ? 'Show All' : `Bookmarks (${bookmarkCount})`}
+</button>
+```
+
+## Technical Implementation
+
+### Create Hook: `hooks/useBookmarks.ts`
+
+```typescript
+export function useBookmarks() {
+  const [bookmarks, setBookmarks] = useState<number[]>([]);
+  
+  useEffect(() => {
+    const saved = localStorage.getItem('wecoded_bookmarks');
+    if (saved) {
+      const data = JSON.parse(saved);
+      setBookmarks(data.bookmarks || []);
+    }
+  }, []);
+  
+  const toggleBookmark = (storyId: number) => {
+    setBookmarks(prev => {
+      const updated = prev.includes(storyId)
+        ? prev.filter(id => id !== storyId)
+        : [...prev, storyId];
+      
+      localStorage.setItem('wecoded_bookmarks', JSON.stringify({
+        bookmarks: updated,
+        timestamp: Date.now()
+      }));
+      
+      return updated;
+    });
+  };
+  
+  const isBookmarked = (storyId: number) => bookmarks.includes(storyId);
+  
+  return { bookmarks, toggleBookmark, isBookmarked };
+}
+```
+
+### Update Page Component
+
+In `app/page.tsx`:
+```typescript
+const { bookmarks, toggleBookmark, isBookmarked } = useBookmarks();
+const [showBookmarks, setShowBookmarks] = useState(false);
+
+const filteredStories = showBookmarks
+  ? stories.filter(story => bookmarks.includes(story.id))
+  : stories;
+```
+
+## Features
+
+1. **Quick Actions**
+   - Double-click to bookmark
+   - Keyboard shortcut: 'B' key to bookmark current story
+
+2. **Visual Feedback**
+   - Smooth animation when bookmarking
+   - Toast notification: "Story bookmarked!" / "Bookmark removed"
+   - Pulse animation on bookmark button
+
+3. **Export/Share**
+   - Optional: Export bookmarked story links
+   - Optional: Share bookmark collection
+
+## Acceptance Criteria
+
+- [ ] Bookmark button added to StoryCard
+- [ ] Bookmarks persist in localStorage
+- [ ] Toggle bookmarks view in navigation
+- [ ] Visual indicator shows bookmarked status
+- [ ] Bookmark count displayed in navigation
+- [ ] Empty state shown when no bookmarks
+- [ ] Animation/feedback when bookmarking
+- [ ] Keyboard shortcut 'B' to bookmark
+- [ ] Accessible (proper ARIA labels)
+- [ ] Works across browser sessions
+- [ ] Handle storage quota exceeded gracefully
+
+## Edge Cases to Handle
+
+- localStorage is full
+- localStorage is disabled
+- User has many bookmarks (100+)
+- Story no longer exists but is bookmarked
+- Clearing browser data
+
+## Testing Checklist
+
+- [ ] Can bookmark a story
+- [ ] Can unbookmark a story
+- [ ] Bookmarks persist after page reload
+- [ ] Bookmarks view shows only bookmarked stories
+- [ ] Bookmark count updates correctly
+- [ ] Empty state displays when no bookmarks
+- [ ] Works with localStorage disabled (graceful degradation)
+- [ ] Keyboard shortcut works
+- [ ] ARIA labels are correct
+
+## Related Files
+
+- `components/StoryCard.tsx` - Add bookmark button
+- `components/StoryCard.module.css` - Bookmark button styles
+- `app/page.tsx` - Bookmark filtering logic
+- `components/Navigation.tsx` - Add bookmarks toggle
+- `hooks/useBookmarks.ts` - New bookmark hook (to create)
+- `types/index.ts` - Add bookmark-related types
+
+## Future Enhancements
+
+- Sync bookmarks across devices (requires backend)
+- Bookmark collections/folders
+- Share bookmark collections
+- Export as reading list
diff --git a/.github/ISSUES/10-social-sharing.md b/.github/ISSUES/10-social-sharing.md
new file mode 100644
index 0000000..912ed3e
--- /dev/null
+++ b/.github/ISSUES/10-social-sharing.md
@@ -0,0 +1,313 @@
+---
+title: Add social sharing functionality
+labels: enhancement, feature, social
+---
+
+## Description
+
+Implement social media sharing buttons for stories (Twitter, LinkedIn, Facebook) to help increase visibility of the WeCoded initiative.
+
+## Background
+
+Currently, users can read inspiring stories but cannot easily share them with their networks. Adding social sharing would amplify the reach of diverse tech stories and promote the WeCoded community.
+
+## Requirements
+
+### Supported Platforms
+
+1. **Twitter/X**
+   - Pre-populated tweet with story title
+   - Include author mention if available
+   - Add #WeCoded hashtag
+   - Link to original DEV.to article
+
+2. **LinkedIn**
+   - Share with story title and description
+   - Link to original article
+
+3. **Facebook**
+   - Share story URL
+   - Auto-populate title and description
+
+4. **Copy Link**
+   - Copy story URL to clipboard
+   - Show confirmation toast
+
+### Share Button UI
+
+Add share menu to StoryCard:
+```tsx
+<div className={styles.shareSection}>
+  <button 
+    onClick={toggleShareMenu}
+    className={styles.shareButton}
+    aria-label="Share this story"
+  >
+    🔗 Share
+  </button>
+  
+  {showShareMenu && (
+    <div className={styles.shareMenu}>
+      <button onClick={() => shareOn('twitter')}>
+        Share on Twitter
+      </button>
+      <button onClick={() => shareOn('linkedin')}>
+        Share on LinkedIn
+      </button>
+      <button onClick={() => shareOn('facebook')}>
+        Share on Facebook
+      </button>
+      <button onClick={copyLink}>
+        Copy Link
+      </button>
+    </div>
+  )}
+</div>
+```
+
+## Technical Implementation
+
+### Share Utility: `utils/share.ts`
+
+```typescript
+interface ShareOptions {
+  title: string;
+  url: string;
+  author?: string;
+  authorTwitter?: string;
+}
+
+export function shareOnTwitter(options: ShareOptions) {
+  const text = `${options.title} by ${options.author || 'a developer'} #WeCoded`;
+  const url = options.url;
+  const via = 'ThePracticalDev'; // DEV.to's Twitter
+  
+  const shareUrl = `https://twitter.com/intent/tweet?text=${encodeURIComponent(text)}&url=${encodeURIComponent(url)}&via=${via}`;
+  
+  window.open(shareUrl, '_blank', 'width=550,height=420');
+}
+
+export function shareOnLinkedIn(options: ShareOptions) {
+  const shareUrl = `https://www.linkedin.com/sharing/share-offsite/?url=${encodeURIComponent(options.url)}`;
+  
+  window.open(shareUrl, '_blank', 'width=550,height=500');
+}
+
+export function shareOnFacebook(options: ShareOptions) {
+  const shareUrl = `https://www.facebook.com/sharer/sharer.php?u=${encodeURIComponent(options.url)}`;
+  
+  window.open(shareUrl, '_blank', 'width=550,height=500');
+}
+
+export async function copyToClipboard(text: string): Promise<boolean> {
+  try {
+    await navigator.clipboard.writeText(text);
+    return true;
+  } catch (error) {
+    // Fallback for older browsers
+    const textarea = document.createElement('textarea');
+    textarea.value = text;
+    textarea.style.position = 'fixed';
+    textarea.style.opacity = '0';
+    document.body.appendChild(textarea);
+    textarea.select();
+    const success = document.execCommand('copy');
+    document.body.removeChild(textarea);
+    return success;
+  }
+}
+```
+
+### Web Share API (Mobile)
+
+For mobile devices, use native share dialog:
+```typescript
+export async function nativeShare(options: ShareOptions) {
+  if (!navigator.share) {
+    return false;
+  }
+  
+  try {
+    await navigator.share({
+      title: options.title,
+      text: `${options.title} by ${options.author || 'a developer'} #WeCoded`,
+      url: options.url,
+    });
+    return true;
+  } catch (error) {
+    if (error.name === 'AbortError') {
+      // User cancelled, not an error
+      return false;
+    }
+    throw error;
+  }
+}
+```
+
+### Component: `components/ShareButton.tsx`
+
+```tsx
+interface ShareButtonProps {
+  story: DevArticle;
+}
+
+export const ShareButton: React.FC<ShareButtonProps> = ({ story }) => {
+  const [showMenu, setShowMenu] = useState(false);
+  const [copied, setCopied] = useState(false);
+  
+  const handleShare = async (platform: string) => {
+    const options = {
+      title: story.title,
+      url: story.url,
+      author: story.user.name,
+      authorTwitter: story.user.twitter_username || undefined,
+    };
+    
+    switch (platform) {
+      case 'twitter':
+        shareOnTwitter(options);
+        break;
+      case 'linkedin':
+        shareOnLinkedIn(options);
+        break;
+      case 'facebook':
+        shareOnFacebook(options);
+        break;
+      case 'native':
+        await nativeShare(options);
+        break;
+    }
+    
+    setShowMenu(false);
+  };
+  
+  const handleCopyLink = async () => {
+    const success = await copyToClipboard(story.url);
+    if (success) {
+      setCopied(true);
+      setTimeout(() => setCopied(false), 2000);
+    }
+  };
+  
+  return (
+    <div className={styles.shareContainer}>
+      <button onClick={() => setShowMenu(!showMenu)}>
+        🔗 Share
+      </button>
+      {/* Share menu UI */}
+    </div>
+  );
+};
+```
+
+## Analytics Integration
+
+Track share events (if analytics implemented):
+```typescript
+function trackShare(platform: string, storyId: number) {
+  // Analytics event
+  if (window.analytics) {
+    window.analytics.track('Story Shared', {
+      platform,
+      storyId,
+      storyTitle: story.title,
+    });
+  }
+}
+```
+
+## Acceptance Criteria
+
+- [ ] Share button added to StoryCard
+- [ ] Share menu with 4 options (Twitter, LinkedIn, Facebook, Copy)
+- [ ] Twitter share includes pre-populated text with #WeCoded
+- [ ] LinkedIn share opens with story URL
+- [ ] Facebook share opens with story URL
+- [ ] Copy link to clipboard works
+- [ ] Confirmation shown after copying link
+- [ ] Native share dialog used on mobile (Web Share API)
+- [ ] Share popups have appropriate size
+- [ ] Menu closes after selection
+- [ ] Click outside closes share menu
+- [ ] Keyboard accessible (Escape to close)
+- [ ] ARIA labels for accessibility
+- [ ] Works across all major browsers
+
+## UI Considerations
+
+### Share Menu Position
+- Position relative to share button
+- Ensure menu doesn't overflow viewport
+- Mobile: Consider bottom sheet or native share
+
+### Visual Design
+```css
+.shareButton {
+  background: var(--accent-color);
+  border: none;
+  padding: 0.5rem 1rem;
+  border-radius: var(--border-radius-sm);
+  cursor: pointer;
+}
+
+.shareMenu {
+  position: absolute;
+  background: var(--card-background);
+  box-shadow: var(--shadow-lg);
+  border-radius: var(--border-radius);
+  padding: 0.5rem 0;
+  min-width: 200px;
+}
+
+.shareMenuItem {
+  display: flex;
+  align-items: center;
+  padding: 0.75rem 1rem;
+  border: none;
+  background: none;
+  cursor: pointer;
+  width: 100%;
+  text-align: left;
+}
+
+.shareMenuItem:hover {
+  background: var(--hover-background);
+}
+```
+
+## Testing Checklist
+
+- [ ] Share buttons open correct platforms
+- [ ] Twitter share includes proper hashtags
+- [ ] Share URLs are properly encoded
+- [ ] Copy to clipboard works
+- [ ] Confirmation toast appears after copy
+- [ ] Native share works on mobile
+- [ ] Fallback works when Web Share API unavailable
+- [ ] Share menu closes on selection
+- [ ] Share menu closes on outside click
+- [ ] Share menu closes on Escape key
+- [ ] Popup blockers don't prevent sharing
+
+## Related Files
+
+- `components/StoryCard.tsx` - Add share button
+- `components/ShareButton.tsx` - New share component (to create)
+- `components/ShareButton.module.css` - Share button styles (to create)
+- `utils/share.ts` - Share utility functions (to create)
+- `types/index.ts` - Add share-related types if needed
+
+## Resources
+
+- [Twitter Web Intent](https://developer.twitter.com/en/docs/twitter-for-websites/tweet-button/overview)
+- [LinkedIn Share](https://www.linkedin.com/help/linkedin/answer/a519849)
+- [Facebook Share Dialog](https://developers.facebook.com/docs/sharing/reference/share-dialog)
+- [Web Share API](https://developer.mozilla.org/en-US/docs/Web/API/Navigator/share)
+
+## Future Enhancements
+
+- Reddit share
+- Email share
+- Download as image (story card screenshot)
+- WhatsApp share
+- Share stats/analytics
diff --git a/.github/ISSUES/11-search-filter-stories.md b/.github/ISSUES/11-search-filter-stories.md
new file mode 100644
index 0000000..298d9b0
--- /dev/null
+++ b/.github/ISSUES/11-search-filter-stories.md
@@ -0,0 +1,308 @@
+---
+title: Add search and filter functionality for stories
+labels: enhancement, feature, user-experience
+---
+
+## Description
+
+Implement search bar and filters to help users find specific stories by title, author, or tags, improving content discoverability.
+
+## Background
+
+Currently, users can only navigate sequentially through stories using Previous/Next buttons. As the story collection grows, users need better ways to find relevant content quickly. Search and filtering would significantly improve the user experience.
+
+## Requirements
+
+### Search Functionality
+
+1. **Search Bar**
+   - Place in header or above story card
+   - Search by: story title, author name, or content
+   - Real-time filtering as user types
+   - Clear/reset button
+   - Keyboard shortcut: '/' to focus search
+
+2. **Search Behavior**
+   - Debounce input (300ms delay)
+   - Case-insensitive matching
+   - Highlight matching terms in results
+   - Show result count: "Showing 5 of 20 stories"
+
+### Filter Functionality
+
+1. **Filter by Tags**
+   - Show available tags from stories
+   - Multi-select tag filter
+   - Pills/chips UI for selected tags
+   - Clear all filters button
+
+2. **Filter by Author**
+   - Dropdown or autocomplete for authors
+   - Show only unique authors
+   - Display author count
+
+3. **Sort Options**
+   - Most recent (default)
+   - Oldest first
+   - Most popular (if read count available)
+   - Alphabetical by title
+
+## UI Design
+
+### Search Bar Component
+
+```tsx
+<div className={styles.searchSection}>
+  <div className={styles.searchBar}>
+    <input
+      type="search"
+      placeholder="Search stories, authors..."
+      value={searchQuery}
+      onChange={handleSearch}
+      className={styles.searchInput}
+      aria-label="Search stories"
+    />
+    <button 
+      onClick={clearSearch}
+      className={styles.clearButton}
+      aria-label="Clear search"
+    >
+      ✕
+    </button>
+  </div>
+  
+  <div className={styles.filters}>
+    <FilterTags tags={availableTags} selected={selectedTags} onChange={setSelectedTags} />
+    <FilterAuthor authors={uniqueAuthors} selected={selectedAuthor} onChange={setSelectedAuthor} />
+    <SortDropdown value={sortBy} onChange={setSortBy} />
+  </div>
+  
+  <div className={styles.resultCount}>
+    Showing {filteredStories.length} of {totalStories} stories
+  </div>
+</div>
+```
+
+### Filter Tags Component
+
+```tsx
+<div className={styles.tagFilters}>
+  {availableTags.map(tag => (
+    <button
+      key={tag}
+      className={`${styles.tagChip} ${selectedTags.includes(tag) ? styles.active : ''}`}
+      onClick={() => toggleTag(tag)}
+    >
+      #{tag}
+    </button>
+  ))}
+</div>
+```
+
+## Technical Implementation
+
+### Search Hook: `hooks/useSearch.ts`
+
+```typescript
+export function useSearch(stories: DevArticle[]) {
+  const [searchQuery, setSearchQuery] = useState('');
+  const [selectedTags, setSelectedTags] = useState<string[]>([]);
+  const [selectedAuthor, setSelectedAuthor] = useState<string>('');
+  const [sortBy, setSortBy] = useState<'newest' | 'oldest' | 'alpha'>('newest');
+  
+  // Debounced search
+  const debouncedQuery = useDebounce(searchQuery, 300);
+  
+  const filteredStories = useMemo(() => {
+    let filtered = [...stories];
+    
+    // Search filter
+    if (debouncedQuery) {
+      filtered = filtered.filter(story => 
+        story.title.toLowerCase().includes(debouncedQuery.toLowerCase()) ||
+        story.user.name.toLowerCase().includes(debouncedQuery.toLowerCase()) ||
+        story.description?.toLowerCase().includes(debouncedQuery.toLowerCase())
+      );
+    }
+    
+    // Tag filter
+    if (selectedTags.length > 0) {
+      filtered = filtered.filter(story =>
+        selectedTags.some(tag => story.tag_list.includes(tag))
+      );
+    }
+    
+    // Author filter
+    if (selectedAuthor) {
+      filtered = filtered.filter(story => 
+        story.user.name === selectedAuthor
+      );
+    }
+    
+    // Sort
+    filtered.sort((a, b) => {
+      switch (sortBy) {
+        case 'newest':
+          return new Date(b.published_timestamp).getTime() - new Date(a.published_timestamp).getTime();
+        case 'oldest':
+          return new Date(a.published_timestamp).getTime() - new Date(b.published_timestamp).getTime();
+        case 'alpha':
+          return a.title.localeCompare(b.title);
+        default:
+          return 0;
+      }
+    });
+    
+    return filtered;
+  }, [stories, debouncedQuery, selectedTags, selectedAuthor, sortBy]);
+  
+  const availableTags = useMemo(() => {
+    const tags = new Set<string>();
+    stories.forEach(story => {
+      story.tag_list.forEach(tag => tags.add(tag));
+    });
+    return Array.from(tags).sort();
+  }, [stories]);
+  
+  const uniqueAuthors = useMemo(() => {
+    const authors = new Set(stories.map(story => story.user.name));
+    return Array.from(authors).sort();
+  }, [stories]);
+  
+  return {
+    searchQuery,
+    setSearchQuery,
+    selectedTags,
+    setSelectedTags,
+    selectedAuthor,
+    setSelectedAuthor,
+    sortBy,
+    setSortBy,
+    filteredStories,
+    availableTags,
+    uniqueAuthors,
+  };
+}
+```
+
+### Debounce Hook: `hooks/useDebounce.ts`
+
+```typescript
+export function useDebounce<T>(value: T, delay: number): T {
+  const [debouncedValue, setDebouncedValue] = useState<T>(value);
+  
+  useEffect(() => {
+    const handler = setTimeout(() => {
+      setDebouncedValue(value);
+    }, delay);
+    
+    return () => clearTimeout(handler);
+  }, [value, delay]);
+  
+  return debouncedValue;
+}
+```
+
+### Update Page Component
+
+```typescript
+const { 
+  searchQuery, 
+  setSearchQuery,
+  selectedTags,
+  setSelectedTags,
+  filteredStories,
+  availableTags,
+  // ... other returned values
+} = useSearch(stories);
+
+// Use filteredStories instead of stories for display
+```
+
+## Features
+
+### Advanced Features
+
+1. **Search Highlighting**
+   - Highlight matching text in results
+   - Use `mark` element for semantics
+
+2. **Search History**
+   - Store recent searches in localStorage
+   - Quick access to previous searches
+
+3. **URL Parameters**
+   - Reflect filters in URL query params
+   - Allow sharing filtered views
+   - Example: `?search=react&tags=javascript,webdev`
+
+4. **Empty States**
+   - No results found message
+   - Suggestions for alternative searches
+   - "Clear filters" prompt
+
+## Acceptance Criteria
+
+- [ ] Search bar added to UI
+- [ ] Real-time search with 300ms debounce
+- [ ] Tag filter with multi-select
+- [ ] Author filter dropdown
+- [ ] Sort options implemented
+- [ ] Result count displayed
+- [ ] Clear filters button works
+- [ ] Keyboard shortcut '/' focuses search
+- [ ] Empty state shown when no results
+- [ ] Search works across title, author, description
+- [ ] Filters can be combined (AND logic)
+- [ ] Performance: handles 100+ stories smoothly
+- [ ] Accessible (proper ARIA labels and keyboard nav)
+- [ ] Mobile-responsive design
+
+## Performance Considerations
+
+- Use `useMemo` for filtered results
+- Debounce search input to reduce re-renders
+- Virtual scrolling if story list grows large
+- Consider IndexedDB for large datasets
+
+## Accessibility
+
+- Search input has clear label
+- Announce result count with aria-live
+- Keyboard navigation through filters
+- Clear focus indicators
+- Screen reader announces filter changes
+
+## Testing Checklist
+
+- [ ] Search filters stories correctly
+- [ ] Debounce prevents excessive filtering
+- [ ] Tag filter works with multiple tags
+- [ ] Author filter works correctly
+- [ ] Sort changes order as expected
+- [ ] Combining filters works (search + tags + author)
+- [ ] Clear filters resets everything
+- [ ] Empty state displays when no matches
+- [ ] Keyboard shortcut focuses search
+- [ ] Works with 1 story
+- [ ] Works with 100+ stories
+- [ ] Mobile UI is usable
+
+## Related Files
+
+- `app/page.tsx` - Add search UI and logic
+- `components/SearchBar.tsx` - New search component (to create)
+- `components/FilterTags.tsx` - New filter component (to create)
+- `components/SearchBar.module.css` - Search styles (to create)
+- `hooks/useSearch.ts` - New search hook (to create)
+- `hooks/useDebounce.ts` - New debounce hook (to create)
+- `types/index.ts` - Add search-related types
+
+## Future Enhancements
+
+- Full-text search using search index
+- Fuzzy search for typos
+- Search suggestions/autocomplete
+- Save search filters
+- Filter by date range
+- Filter by reading time
diff --git a/.github/ISSUES/12-error-boundary.md b/.github/ISSUES/12-error-boundary.md
new file mode 100644
index 0000000..7dd02d4
--- /dev/null
+++ b/.github/ISSUES/12-error-boundary.md
@@ -0,0 +1,368 @@
+---
+title: Implement proper error boundary component
+labels: enhancement, bug, reliability
+---
+
+## Description
+
+Create and implement React Error Boundary component to gracefully handle runtime errors and prevent the entire application from crashing.
+
+## Background
+
+Currently, if a component crashes due to a runtime error, the entire application breaks and shows a blank screen. Error boundaries allow us to catch errors in child components, display user-friendly error messages, and maintain partial app functionality.
+
+## Requirements
+
+### Error Boundary Features
+
+1. **Error Catching**
+   - Catch errors in child components
+   - Catch errors during rendering
+   - Catch errors in lifecycle methods
+   - Catch errors in constructors
+
+2. **Error UI**
+   - Display user-friendly error message
+   - Show "Try Again" button to reset
+   - Optional: Show error details in development
+   - Maintain app header/footer when possible
+
+3. **Error Logging**
+   - Log errors to console
+   - Include component stack trace
+   - Include error boundary name/location
+   - Optional: Send to error tracking service
+
+4. **Recovery Options**
+   - Reset error boundary on button click
+   - Auto-reset after time delay (optional)
+   - Reload page button
+   - Navigate to home
+
+## Implementation
+
+### Create Error Boundary Component
+
+`components/ErrorBoundary.tsx`:
+```tsx
+'use client';
+
+import React, { Component, ErrorInfo, ReactNode } from 'react';
+import styles from './ErrorBoundary.module.css';
+
+interface Props {
+  children: ReactNode;
+  fallback?: ReactNode;
+  onError?: (error: Error, errorInfo: ErrorInfo) => void;
+  name?: string;
+}
+
+interface State {
+  hasError: boolean;
+  error: Error | null;
+}
+
+export class ErrorBoundary extends Component<Props, State> {
+  constructor(props: Props) {
+    super(props);
+    this.state = { hasError: false, error: null };
+  }
+
+  static getDerivedStateFromError(error: Error): State {
+    return { hasError: true, error };
+  }
+
+  componentDidCatch(error: Error, errorInfo: ErrorInfo) {
+    // Log error details
+    console.error(`Error in ${this.props.name || 'component'}:`, error);
+    console.error('Component stack:', errorInfo.componentStack);
+    
+    // Call optional error handler
+    if (this.props.onError) {
+      this.props.onError(error, errorInfo);
+    }
+    
+    // Optional: Send to error tracking service
+    // trackError(error, errorInfo);
+  }
+
+  resetError = () => {
+    this.setState({ hasError: false, error: null });
+  };
+
+  render() {
+    if (this.state.hasError) {
+      if (this.props.fallback) {
+        return this.props.fallback;
+      }
+
+      return (
+        <div className={styles.errorContainer}>
+          <div className={styles.errorContent}>
+            <h2 className={styles.errorTitle}>
+              Oops! Something went wrong
+            </h2>
+            <p className={styles.errorMessage}>
+              We're sorry for the inconvenience. The application encountered an error.
+            </p>
+            
+            {process.env.NODE_ENV === 'development' && this.state.error && (
+              <details className={styles.errorDetails}>
+                <summary>Error details (development only)</summary>
+                <pre>{this.state.error.toString()}</pre>
+                <pre>{this.state.error.stack}</pre>
+              </details>
+            )}
+            
+            <div className={styles.errorActions}>
+              <button 
+                onClick={this.resetError}
+                className={styles.primaryButton}
+              >
+                Try Again
+              </button>
+              <button 
+                onClick={() => window.location.reload()}
+                className={styles.secondaryButton}
+              >
+                Reload Page
+              </button>
+            </div>
+          </div>
+        </div>
+      );
+    }
+
+    return this.props.children;
+  }
+}
+```
+
+### Error Boundary Styles
+
+`components/ErrorBoundary.module.css`:
+```css
+.errorContainer {
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  min-height: 400px;
+  padding: 2rem;
+}
+
+.errorContent {
+  max-width: 600px;
+  text-align: center;
+  padding: 2rem;
+  background: var(--card-background);
+  border-radius: var(--border-radius);
+  box-shadow: var(--card-shadow);
+}
+
+.errorTitle {
+  font-size: 1.5rem;
+  margin-bottom: 1rem;
+  color: var(--error-color, #dc2626);
+}
+
+.errorMessage {
+  margin-bottom: 2rem;
+  color: var(--foreground-secondary);
+}
+
+.errorDetails {
+  text-align: left;
+  margin: 1rem 0;
+  padding: 1rem;
+  background: var(--background-secondary);
+  border-radius: 0.5rem;
+  font-size: 0.875rem;
+}
+
+.errorDetails pre {
+  overflow-x: auto;
+  margin-top: 0.5rem;
+}
+
+.errorActions {
+  display: flex;
+  gap: 1rem;
+  justify-content: center;
+  flex-wrap: wrap;
+}
+
+.primaryButton,
+.secondaryButton {
+  padding: 0.75rem 1.5rem;
+  border: none;
+  border-radius: 0.5rem;
+  font-size: 1rem;
+  cursor: pointer;
+  transition: all 0.2s;
+}
+
+.primaryButton {
+  background: var(--accent-color, #3b82f6);
+  color: white;
+}
+
+.primaryButton:hover {
+  background: var(--accent-color-hover, #2563eb);
+}
+
+.secondaryButton {
+  background: var(--background-secondary);
+  color: var(--foreground);
+}
+
+.secondaryButton:hover {
+  background: var(--hover-background);
+}
+```
+
+## Usage
+
+### Wrap Entire App
+
+In `app/layout.tsx`:
+```tsx
+export default function RootLayout({ children }: { children: ReactNode }) {
+  return (
+    <html lang="en">
+      <body>
+        <ErrorBoundary name="App Root">
+          {children}
+        </ErrorBoundary>
+      </body>
+    </html>
+  );
+}
+```
+
+### Wrap Individual Sections
+
+In `app/page.tsx`:
+```tsx
+<ErrorBoundary name="Story Section">
+  <StoryCard {...props} />
+</ErrorBoundary>
+
+<ErrorBoundary name="Mini Game">
+  <MiniGame />
+</ErrorBoundary>
+```
+
+### With Custom Fallback
+
+```tsx
+<ErrorBoundary
+  name="Story Card"
+  fallback={
+    <div className={styles.simpleError}>
+      <p>Unable to load this story</p>
+      <button onClick={nextStory}>Skip to Next</button>
+    </div>
+  }
+>
+  <StoryCard story={currentStory} />
+</ErrorBoundary>
+```
+
+## Error Tracking Integration
+
+Optional integration with error tracking services:
+
+```typescript
+// utils/errorTracking.ts
+export function trackError(error: Error, errorInfo: ErrorInfo) {
+  if (process.env.NODE_ENV === 'production') {
+    // Sentry
+    // Sentry.captureException(error, { contexts: { react: errorInfo } });
+    
+    // Or other service
+    // LogRocket.captureException(error, { extra: errorInfo });
+  }
+}
+```
+
+## Acceptance Criteria
+
+- [ ] ErrorBoundary component created
+- [ ] Catches rendering errors in child components
+- [ ] Displays user-friendly error UI
+- [ ] "Try Again" button resets error state
+- [ ] "Reload Page" button refreshes the app
+- [ ] Error details shown in development mode
+- [ ] Error details hidden in production
+- [ ] Errors logged to console with stack trace
+- [ ] Multiple error boundaries wrap different sections
+- [ ] App header/footer remain visible when section errors
+- [ ] Works with Next.js App Router
+- [ ] Styles match app design system
+- [ ] Accessible (proper semantic HTML, focus management)
+
+## Testing
+
+### Manual Testing
+
+Test error boundary by temporarily throwing errors:
+
+```tsx
+// In any component
+if (shouldError) {
+  throw new Error('Test error boundary');
+}
+```
+
+Test scenarios:
+1. Error in StoryCard component
+2. Error in MiniGame component
+3. Error during data fetching
+4. Error in nested component
+5. Reset functionality works
+6. Reload functionality works
+
+### Automated Testing
+
+```typescript
+// ErrorBoundary.test.tsx
+test('catches errors and displays fallback', () => {
+  const ThrowError = () => {
+    throw new Error('Test error');
+  };
+  
+  render(
+    <ErrorBoundary>
+      <ThrowError />
+    </ErrorBoundary>
+  );
+  
+  expect(screen.getByText(/something went wrong/i)).toBeInTheDocument();
+});
+
+test('resets error on button click', () => {
+  // Test reset functionality
+});
+```
+
+## Related Files
+
+- `components/ErrorBoundary.tsx` - New component (to create)
+- `components/ErrorBoundary.module.css` - Styles (to create)
+- `app/layout.tsx` - Wrap root
+- `app/page.tsx` - Wrap sections
+- `utils/errorTracking.ts` - Optional error tracking (to create)
+
+## Resources
+
+- [React Error Boundaries](https://react.dev/reference/react/Component#catching-rendering-errors-with-an-error-boundary)
+- [Error Boundaries in Next.js](https://nextjs.org/docs/advanced-features/error-handling)
+- [Error Boundary Best Practices](https://kentcdodds.com/blog/use-react-error-boundary-to-handle-errors-in-react)
+
+## Future Enhancements
+
+- Integration with Sentry or similar service
+- Automatic error recovery attempts
+- Error reporting to backend
+- User feedback form in error UI
+- Different error UIs for different error types
diff --git a/.github/ISSUES/13-animation-transitions.md b/.github/ISSUES/13-animation-transitions.md
new file mode 100644
index 0000000..35b3f59
--- /dev/null
+++ b/.github/ISSUES/13-animation-transitions.md
@@ -0,0 +1,328 @@
+---
+title: Add animation transitions between stories
+labels: enhancement, ui/ux, animation
+---
+
+## Description
+
+Implement smooth slide or fade animations when navigating between stories to enhance the gamified feel and improve user experience.
+
+## Background
+
+Currently, story changes are instant which feels abrupt and doesn't provide good visual feedback. Smooth animations would make the navigation feel more polished, provide directional context (which direction the user is moving), and enhance the overall game-like experience.
+
+## Requirements
+
+### Animation Types
+
+1. **Slide Animation**
+   - Slide right when going to previous story
+   - Slide left when going to next story
+   - Duration: 300-400ms
+   - Easing: cubic-bezier for smooth motion
+
+2. **Fade Animation** (alternative/combined)
+   - Fade out current story
+   - Fade in next story
+   - Duration: 200-300ms
+   - Overlap for seamless transition
+
+### Accessibility
+
+- **Must respect `prefers-reduced-motion`**
+  - Disable animations for users who prefer reduced motion
+  - Use instant transitions or simple fade instead
+  - Test with browser/OS motion settings
+
+### Performance
+
+- Use CSS transforms for 60fps animations
+- GPU acceleration with `will-change` or `transform: translate3d`
+- Avoid layout thrashing
+- Prevent animations during slow network
+
+## Technical Implementation
+
+### Option 1: CSS Transitions
+
+Add to `StoryCard.module.css`:
+```css
+.card {
+  animation: slideIn 0.3s cubic-bezier(0.4, 0, 0.2, 1);
+}
+
+@keyframes slideIn {
+  from {
+    opacity: 0;
+    transform: translateX(100%);
+  }
+  to {
+    opacity: 1;
+    transform: translateX(0);
+  }
+}
+
+.card.exitLeft {
+  animation: slideOutLeft 0.3s cubic-bezier(0.4, 0, 0.2, 1);
+}
+
+@keyframes slideOutLeft {
+  from {
+    opacity: 1;
+    transform: translateX(0);
+  }
+  to {
+    opacity: 0;
+    transform: translateX(-100%);
+  }
+}
+
+.card.exitRight {
+  animation: slideOutRight 0.3s cubic-bezier(0.4, 0, 0.2, 1);
+}
+
+@keyframes slideOutRight {
+  from {
+    opacity: 1;
+    transform: translateX(0);
+  }
+  to {
+    opacity: 0;
+    transform: translateX(100%);
+  }
+}
+
+/* Respect reduced motion preference */
+@media (prefers-reduced-motion: reduce) {
+  .card {
+    animation: fadeIn 0.15s ease-in;
+  }
+  
+  @keyframes fadeIn {
+    from { opacity: 0; }
+    to { opacity: 1; }
+  }
+  
+  .card.exitLeft,
+  .card.exitRight {
+    animation: fadeOut 0.15s ease-out;
+  }
+  
+  @keyframes fadeOut {
+    from { opacity: 1; }
+    to { opacity: 0; }
+  }
+}
+```
+
+### Option 2: Framer Motion (Recommended)
+
+Install Framer Motion:
+```bash
+npm install framer-motion
+```
+
+Update `StoryCard.tsx`:
+```tsx
+import { motion, AnimatePresence } from 'framer-motion';
+
+const slideVariants = {
+  enter: (direction: number) => ({
+    x: direction > 0 ? 1000 : -1000,
+    opacity: 0
+  }),
+  center: {
+    x: 0,
+    opacity: 1
+  },
+  exit: (direction: number) => ({
+    x: direction < 0 ? 1000 : -1000,
+    opacity: 0
+  })
+};
+
+const StoryCard = ({ story, direction, ...props }) => {
+  return (
+    <AnimatePresence initial={false} custom={direction} mode="wait">
+      <motion.div
+        key={story.id}
+        custom={direction}
+        variants={slideVariants}
+        initial="enter"
+        animate="center"
+        exit="exit"
+        transition={{
+          x: { type: 'spring', stiffness: 300, damping: 30 },
+          opacity: { duration: 0.2 }
+        }}
+        className={styles.card}
+      >
+        {/* Card content */}
+      </motion.div>
+    </AnimatePresence>
+  );
+};
+```
+
+Update `app/page.tsx`:
+```tsx
+const [direction, setDirection] = useState(0);
+
+const nextStory = () => {
+  setDirection(1);
+  setCurrentStoryIndex((prev) => (prev + 1) % stories.length);
+};
+
+const prevStory = () => {
+  setDirection(-1);
+  setCurrentStoryIndex((prev) => (prev - 1 + stories.length) % stories.length);
+};
+```
+
+### Option 3: React Transition Group
+
+Alternative using React Transition Group:
+```bash
+npm install react-transition-group
+npm install --save-dev @types/react-transition-group
+```
+
+## Animation Variants
+
+### Slide Variants
+
+1. **Horizontal Slide**
+   - Left/Right based on navigation direction
+   - Most intuitive for forward/back navigation
+
+2. **Vertical Slide**
+   - Up/Down animation
+   - Alternative feel, like card flip
+
+3. **Fade + Scale**
+   - Current card fades and scales down
+   - New card fades and scales up
+   - Subtle and elegant
+
+### Combined Effects
+
+```tsx
+const advancedVariants = {
+  enter: {
+    x: 100,
+    opacity: 0,
+    scale: 0.95
+  },
+  center: {
+    x: 0,
+    opacity: 1,
+    scale: 1
+  },
+  exit: {
+    x: -100,
+    opacity: 0,
+    scale: 0.95
+  }
+};
+```
+
+## Acceptance Criteria
+
+- [ ] Animation library installed (Framer Motion recommended)
+- [ ] Slide animation when navigating to next story
+- [ ] Slide animation when navigating to previous story
+- [ ] Direction-aware animations (left/right based on navigation)
+- [ ] Smooth 60fps animations
+- [ ] No layout shift during animation
+- [ ] Animations disabled for `prefers-reduced-motion`
+- [ ] Animation duration is appropriate (300-400ms)
+- [ ] Works on mobile devices
+- [ ] No performance issues with animations
+- [ ] Loading states handled gracefully
+- [ ] Works with keyboard navigation
+
+## Performance Considerations
+
+```css
+/* Optimize for animation */
+.card {
+  will-change: transform, opacity;
+}
+
+/* Use GPU acceleration */
+.card {
+  transform: translate3d(0, 0, 0);
+}
+
+/* Remove will-change after animation */
+.card.animated {
+  will-change: auto;
+}
+```
+
+## Testing Checklist
+
+- [ ] Next button triggers left slide
+- [ ] Previous button triggers right slide
+- [ ] Animation duration feels right
+- [ ] No janky frame drops
+- [ ] Works on low-end devices
+- [ ] Respects reduced motion
+- [ ] Works with keyboard shortcuts
+- [ ] Works on mobile (touch)
+- [ ] Multiple rapid clicks handled gracefully
+- [ ] Animation doesn't block interaction
+
+## Edge Cases
+
+1. **Rapid Navigation**
+   - Prevent animation queue buildup
+   - Cancel previous animation if new navigation starts
+   
+2. **First/Last Story**
+   - Handle wrap-around smoothly
+   - Consider if animation should differ at boundaries
+
+3. **Loading States**
+   - Don't animate while loading
+   - Graceful transition from loading to story
+
+4. **Error States**
+   - No animation when error occurs
+   - Or subtle animation to error UI
+
+## Mobile Considerations
+
+- Touch gestures (swipe) could trigger animations
+- Reduce animation complexity on mobile
+- Test on various devices and screen sizes
+
+## Related Files
+
+- `components/StoryCard.tsx` - Add animation wrapper
+- `components/StoryCard.module.css` - Animation CSS (if using CSS)
+- `app/page.tsx` - Track navigation direction
+- `package.json` - Add animation library
+- `app/globals.css` - Reduced motion media query
+
+## Alternative Libraries
+
+If not using Framer Motion:
+- `react-spring` - Spring-based animations
+- `react-transition-group` - Lower-level transition control
+- CSS Animations - No dependencies, good performance
+
+## Resources
+
+- [Framer Motion Documentation](https://www.framer.com/motion/)
+- [prefers-reduced-motion](https://developer.mozilla.org/en-US/docs/Web/CSS/@media/prefers-reduced-motion)
+- [CSS Animation Performance](https://web.dev/animations-guide/)
+- [React Animation Best Practices](https://www.joshwcomeau.com/react/animating-the-unanimatable/)
+
+## Future Enhancements
+
+- Swipe gestures for mobile
+- Custom animation based on story type
+- Particle effects for gamification
+- Page transition animations
+- Micro-interactions on buttons
diff --git a/.github/ISSUES/14-achievement-badge-system.md b/.github/ISSUES/14-achievement-badge-system.md
new file mode 100644
index 0000000..e8dd548
--- /dev/null
+++ b/.github/ISSUES/14-achievement-badge-system.md
@@ -0,0 +1,351 @@
+---
+title: Implement achievement/badge system
+labels: enhancement, feature, gamification
+---
+
+## Description
+
+Create an achievement system that awards badges for milestones, increasing user engagement and gamification.
+
+## Background
+
+Currently, there's a basic score/level system, but no persistent achievements. A badge system would reward user engagement, encourage exploration of all content, and add meaningful gamification beyond simple scores.
+
+## Requirements
+
+### Achievement Types
+
+1. **Reading Milestones**
+   - 📚 "First Story" - Read your first story
+   - 📖 "Story Enthusiast" - Read 5 stories
+   - 🎓 "Knowledge Seeker" - Read 10 stories
+   - 🏆 "Story Master" - Read 20 stories
+   - 💯 "Completionist" - Read all available stories
+
+2. **Diversity Achievements**
+   - 🌍 "Global Perspective" - Read stories from 3 different authors
+   - 🌟 "Diversity Champion" - Read stories from 5 different authors
+   - 🎯 "Tag Explorer" - Read stories with 5 different tags
+
+3. **Engagement Achievements**
+   - 🎮 "Gamer" - Play the mini-game once
+   - 🏅 "Mini-Game Master" - Score 100+ in mini-game
+   - 🔖 "Collector" - Bookmark 5 stories (if bookmarks implemented)
+   - 🔗 "Sharer" - Share a story on social media (if sharing implemented)
+
+4. **Time-Based Achievements**
+   - ⏰ "Early Bird" - Visit during morning hours (6-10am)
+   - 🌙 "Night Owl" - Visit during night hours (10pm-2am)
+   - 📅 "Regular" - Visit 3 days in a row
+   - 🔥 "Streak" - Visit 7 days in a row
+
+5. **Special Achievements**
+   - 🎉 "Launch Member" - Visited during launch week
+   - 💝 "WeCoded Advocate" - Complete all reading achievements
+
+### Achievement Structure
+
+```typescript
+interface Achievement {
+  id: string;
+  title: string;
+  description: string;
+  icon: string;
+  category: 'reading' | 'diversity' | 'engagement' | 'time' | 'special';
+  requirement: {
+    type: 'count' | 'unique' | 'score' | 'action' | 'time';
+    target: number | string;
+  };
+  reward?: {
+    xp?: number;
+    title?: string;
+  };
+}
+
+interface UserAchievement {
+  achievementId: string;
+  unlockedAt: string;
+  progress?: number;
+  isNew?: boolean;
+}
+```
+
+## Technical Implementation
+
+### Achievement Definitions
+
+`data/achievements.ts`:
+```typescript
+export const ACHIEVEMENTS: Achievement[] = [
+  {
+    id: 'first-story',
+    title: 'First Story',
+    description: 'Read your first story',
+    icon: '📚',
+    category: 'reading',
+    requirement: { type: 'count', target: 1 },
+    reward: { xp: 100, title: 'Story Reader' }
+  },
+  {
+    id: 'story-enthusiast',
+    title: 'Story Enthusiast',
+    description: 'Read 5 different stories',
+    icon: '📖',
+    category: 'reading',
+    requirement: { type: 'count', target: 5 },
+    reward: { xp: 250 }
+  },
+  // ... more achievements
+];
+```
+
+### Achievement Hook
+
+`hooks/useAchievements.ts`:
+```typescript
+export function useAchievements() {
+  const [unlockedAchievements, setUnlockedAchievements] = useState<UserAchievement[]>([]);
+  const [newAchievements, setNewAchievements] = useState<Achievement[]>([]);
+  
+  useEffect(() => {
+    // Load from localStorage
+    const saved = localStorage.getItem('wecoded_achievements');
+    if (saved) {
+      setUnlockedAchievements(JSON.parse(saved));
+    }
+  }, []);
+  
+  const checkAndUnlockAchievements = (stats: UserStats) => {
+    const newlyUnlocked: Achievement[] = [];
+    
+    ACHIEVEMENTS.forEach(achievement => {
+      const isUnlocked = unlockedAchievements.some(
+        ua => ua.achievementId === achievement.id
+      );
+      
+      if (!isUnlocked && meetsRequirement(achievement, stats)) {
+        const userAchievement: UserAchievement = {
+          achievementId: achievement.id,
+          unlockedAt: new Date().toISOString(),
+          isNew: true
+        };
+        
+        setUnlockedAchievements(prev => {
+          const updated = [...prev, userAchievement];
+          localStorage.setItem('wecoded_achievements', JSON.stringify(updated));
+          return updated;
+        });
+        
+        newlyUnlocked.push(achievement);
+      }
+    });
+    
+    if (newlyUnlocked.length > 0) {
+      setNewAchievements(newlyUnlocked);
+    }
+  };
+  
+  const meetsRequirement = (achievement: Achievement, stats: UserStats): boolean => {
+    switch (achievement.requirement.type) {
+      case 'count':
+        return stats.storiesRead >= achievement.requirement.target;
+      case 'unique':
+        return stats.uniqueAuthors >= achievement.requirement.target;
+      // ... other types
+      default:
+        return false;
+    }
+  };
+  
+  return {
+    unlockedAchievements,
+    newAchievements,
+    checkAndUnlockAchievements,
+    dismissNewAchievements: () => setNewAchievements([]),
+    progress: calculateProgress(unlockedAchievements)
+  };
+}
+```
+
+### Achievement Display
+
+#### Achievement Notification
+
+`components/AchievementNotification.tsx`:
+```tsx
+export const AchievementNotification: React.FC<{ achievement: Achievement }> = ({ 
+  achievement 
+}) => {
+  return (
+    <motion.div
+      initial={{ y: -100, opacity: 0 }}
+      animate={{ y: 0, opacity: 1 }}
+      exit={{ y: -100, opacity: 0 }}
+      className={styles.notification}
+    >
+      <div className={styles.icon}>{achievement.icon}</div>
+      <div className={styles.content}>
+        <div className={styles.badge}>🎉 Achievement Unlocked!</div>
+        <div className={styles.title}>{achievement.title}</div>
+        <div className={styles.description}>{achievement.description}</div>
+        {achievement.reward && (
+          <div className={styles.reward}>+{achievement.reward.xp} XP</div>
+        )}
+      </div>
+    </motion.div>
+  );
+};
+```
+
+#### Achievements Page/Modal
+
+`components/AchievementsModal.tsx`:
+```tsx
+export const AchievementsModal: React.FC = () => {
+  const { unlockedAchievements } = useAchievements();
+  
+  return (
+    <div className={styles.modal}>
+      <h2>Your Achievements</h2>
+      
+      <div className={styles.progress}>
+        <div className={styles.progressBar}>
+          <div 
+            className={styles.progressFill}
+            style={{ width: `${(unlockedAchievements.length / ACHIEVEMENTS.length) * 100}%` }}
+          />
+        </div>
+        <div className={styles.progressText}>
+          {unlockedAchievements.length} / {ACHIEVEMENTS.length}
+        </div>
+      </div>
+      
+      <div className={styles.grid}>
+        {ACHIEVEMENTS.map(achievement => {
+          const unlocked = unlockedAchievements.find(
+            ua => ua.achievementId === achievement.id
+          );
+          
+          return (
+            <div 
+              key={achievement.id}
+              className={`${styles.card} ${unlocked ? styles.unlocked : styles.locked}`}
+            >
+              <div className={styles.icon}>
+                {unlocked ? achievement.icon : '🔒'}
+              </div>
+              <div className={styles.title}>{achievement.title}</div>
+              <div className={styles.description}>
+                {achievement.description}
+              </div>
+              {unlocked && (
+                <div className={styles.unlockedDate}>
+                  Unlocked: {new Date(unlocked.unlockedAt).toLocaleDateString()}
+                </div>
+              )}
+            </div>
+          );
+        })}
+      </div>
+    </div>
+  );
+};
+```
+
+## UI Components
+
+1. **Achievement Notification**
+   - Toast/banner at top of screen
+   - Shows for 5 seconds
+   - Celebration animation
+   - Sound effect (optional, respecting user preferences)
+
+2. **Achievements Button**
+   - In header or navigation
+   - Shows badge count
+   - Opens achievements modal
+
+3. **Achievements Modal**
+   - Grid of all achievements
+   - Locked/unlocked states
+   - Progress bar
+   - Filter by category
+   - Share achievements
+
+4. **Profile Summary**
+   - Recently unlocked badges
+   - Total achievements
+   - XP earned from achievements
+
+## Animation Effects
+
+```css
+@keyframes celebrate {
+  0%, 100% { transform: scale(1) rotate(0deg); }
+  25% { transform: scale(1.1) rotate(-5deg); }
+  75% { transform: scale(1.1) rotate(5deg); }
+}
+
+.achievement-unlocked {
+  animation: celebrate 0.5s ease-in-out;
+}
+
+/* Confetti effect */
+@keyframes confetti {
+  0% { transform: translateY(0) rotateZ(0deg); opacity: 1; }
+  100% { transform: translateY(100vh) rotateZ(360deg); opacity: 0; }
+}
+```
+
+## Acceptance Criteria
+
+- [ ] Achievement system implemented with data structure
+- [ ] 15+ achievements defined across 5 categories
+- [ ] Progress tracked in localStorage
+- [ ] Achievement notifications show when unlocked
+- [ ] Achievements modal shows all achievements
+- [ ] Locked/unlocked states clearly differentiated
+- [ ] Progress bar shows completion percentage
+- [ ] Celebration animation plays on unlock
+- [ ] Respects `prefers-reduced-motion`
+- [ ] XP rewards added to total score
+- [ ] Share achievements on social media (optional)
+- [ ] Works across browser sessions
+- [ ] Mobile-responsive design
+
+## Testing Checklist
+
+- [ ] First story achievement unlocks
+- [ ] Multiple story achievement unlocks at correct count
+- [ ] Mini-game achievement unlocks
+- [ ] Time-based achievements work
+- [ ] Notifications display correctly
+- [ ] Achievements persist after reload
+- [ ] Modal shows correct locked/unlocked states
+- [ ] Progress bar updates correctly
+- [ ] No duplicate unlocks
+- [ ] Handles edge cases gracefully
+
+## Related Files
+
+- `data/achievements.ts` - Achievement definitions (to create)
+- `hooks/useAchievements.ts` - Achievement logic (to create)
+- `components/AchievementNotification.tsx` - Notification UI (to create)
+- `components/AchievementsModal.tsx` - Achievements view (to create)
+- `app/page.tsx` - Integrate achievement checking
+- `types/index.ts` - Add achievement types
+
+## Resources
+
+- [Gamification Best Practices](https://www.nngroup.com/articles/gamification/)
+- [Achievement Design Patterns](https://www.gamedeveloper.com/design/designing-achievements)
+
+## Future Enhancements
+
+- Rare/epic achievement tiers
+- Hidden achievements
+- Achievement leaderboard
+- Share on social media
+- Achievement statistics
+- Custom achievement icons
+- Seasonal achievements
diff --git a/.github/ISSUES/15-pwa-support.md b/.github/ISSUES/15-pwa-support.md
new file mode 100644
index 0000000..c91ff5d
--- /dev/null
+++ b/.github/ISSUES/15-pwa-support.md
@@ -0,0 +1,477 @@
+---
+title: Add progressive web app (PWA) support
+labels: enhancement, pwa, mobile, offline
+---
+
+## Description
+
+Convert the application to a Progressive Web App with service worker for offline support, installability, and app-like experience.
+
+## Background
+
+Currently, the app requires an internet connection and isn't installable. PWA support would allow users to install the app on their devices, work offline with cached content, and provide an app-like experience with faster load times.
+
+## Requirements
+
+### Core PWA Features
+
+1. **Web App Manifest**
+   - App name, short name, description
+   - Icons (192x192, 512x512, maskable)
+   - Theme colors
+   - Display mode (standalone)
+   - Start URL and scope
+
+2. **Service Worker**
+   - Cache static assets
+   - Cache API responses
+   - Offline fallback page
+   - Background sync (optional)
+   - Push notifications (future)
+
+3. **Installability**
+   - Install prompt
+   - Custom install button
+   - Track installation
+   - Update notifications
+
+4. **Offline Support**
+   - Cached stories available offline
+   - Offline indicator
+   - Sync when back online
+   - Queue actions for later sync
+
+## Implementation
+
+### 1. Web App Manifest
+
+Create `public/manifest.json`:
+```json
+{
+  "name": "WeCoded Game - Diversity in Tech Stories",
+  "short_name": "WeCoded",
+  "description": "A gamified experience celebrating diversity in tech through storytelling",
+  "start_url": "/",
+  "display": "standalone",
+  "background_color": "#ffffff",
+  "theme_color": "#3b82f6",
+  "orientation": "portrait-primary",
+  "icons": [
+    {
+      "src": "/icons/icon-192x192.png",
+      "sizes": "192x192",
+      "type": "image/png",
+      "purpose": "any"
+    },
+    {
+      "src": "/icons/icon-512x512.png",
+      "sizes": "512x512",
+      "type": "image/png",
+      "purpose": "any"
+    },
+    {
+      "src": "/icons/icon-192x192-maskable.png",
+      "sizes": "192x192",
+      "type": "image/png",
+      "purpose": "maskable"
+    },
+    {
+      "src": "/icons/icon-512x512-maskable.png",
+      "sizes": "512x512",
+      "type": "image/png",
+      "purpose": "maskable"
+    }
+  ],
+  "categories": ["education", "social", "entertainment"],
+  "screenshots": [
+    {
+      "src": "/screenshots/screenshot-1.png",
+      "sizes": "1280x720",
+      "type": "image/png"
+    }
+  ],
+  "shortcuts": [
+    {
+      "name": "Read Stories",
+      "short_name": "Stories",
+      "description": "Browse tech stories",
+      "url": "/?utm_source=homescreen",
+      "icons": [{ "src": "/icons/stories-96x96.png", "sizes": "96x96" }]
+    },
+    {
+      "name": "Play Mini Game",
+      "short_name": "Game",
+      "description": "Play the mini game",
+      "url": "/?game=true",
+      "icons": [{ "src": "/icons/game-96x96.png", "sizes": "96x96" }]
+    }
+  ]
+}
+```
+
+Add to `app/layout.tsx`:
+```tsx
+<link rel="manifest" href="/manifest.json" />
+<meta name="theme-color" content="#3b82f6" />
+<link rel="apple-touch-icon" href="/icons/icon-192x192.png" />
+```
+
+### 2. Service Worker
+
+Create `public/sw.js`:
+```javascript
+const CACHE_NAME = 'wecoded-v1';
+const STATIC_CACHE = 'wecoded-static-v1';
+const DYNAMIC_CACHE = 'wecoded-dynamic-v1';
+
+const STATIC_ASSETS = [
+  '/',
+  '/offline.html',
+  '/wecoded.svg',
+  // Add other static assets
+];
+
+// Install event - cache static assets
+self.addEventListener('install', (event) => {
+  event.waitUntil(
+    caches.open(STATIC_CACHE).then((cache) => {
+      return cache.addAll(STATIC_ASSETS);
+    })
+  );
+  self.skipWaiting();
+});
+
+// Activate event - clean old caches
+self.addEventListener('activate', (event) => {
+  event.waitUntil(
+    caches.keys().then((cacheNames) => {
+      return Promise.all(
+        cacheNames
+          .filter((name) => name.startsWith('wecoded-') && name !== CACHE_NAME)
+          .map((name) => caches.delete(name))
+      );
+    })
+  );
+  self.clients.claim();
+});
+
+// Fetch event - serve from cache, fallback to network
+self.addEventListener('fetch', (event) => {
+  const { request } = event;
+  
+  // Skip non-GET requests
+  if (request.method !== 'GET') {
+    return;
+  }
+  
+  // API requests - Network first, cache fallback
+  if (request.url.includes('/api/') || request.url.includes('dev.to/api')) {
+    event.respondWith(
+      fetch(request)
+        .then((response) => {
+          const responseClone = response.clone();
+          caches.open(DYNAMIC_CACHE).then((cache) => {
+            cache.put(request, responseClone);
+          });
+          return response;
+        })
+        .catch(() => {
+          return caches.match(request);
+        })
+    );
+    return;
+  }
+  
+  // Static assets - Cache first, network fallback
+  event.respondWith(
+    caches.match(request).then((cached) => {
+      return (
+        cached ||
+        fetch(request).then((response) => {
+          const responseClone = response.clone();
+          caches.open(STATIC_CACHE).then((cache) => {
+            cache.put(request, responseClone);
+          });
+          return response;
+        })
+      );
+    }).catch(() => {
+      // Offline fallback
+      if (request.destination === 'document') {
+        return caches.match('/offline.html');
+      }
+    })
+  );
+});
+```
+
+### 3. Service Worker Registration
+
+Create `utils/serviceWorker.ts`:
+```typescript
+export function registerServiceWorker() {
+  if ('serviceWorker' in navigator && process.env.NODE_ENV === 'production') {
+    window.addEventListener('load', () => {
+      navigator.serviceWorker
+        .register('/sw.js')
+        .then((registration) => {
+          console.log('SW registered:', registration);
+          
+          // Check for updates
+          registration.addEventListener('updatefound', () => {
+            const newWorker = registration.installing;
+            if (newWorker) {
+              newWorker.addEventListener('statechange', () => {
+                if (newWorker.state === 'installed' && navigator.serviceWorker.controller) {
+                  // New service worker installed, show update notification
+                  showUpdateNotification();
+                }
+              });
+            }
+          });
+        })
+        .catch((error) => {
+          console.error('SW registration failed:', error);
+        });
+    });
+  }
+}
+
+function showUpdateNotification() {
+  if (confirm('A new version is available! Reload to update?')) {
+    window.location.reload();
+  }
+}
+```
+
+Register in `app/layout.tsx`:
+```tsx
+'use client';
+
+useEffect(() => {
+  registerServiceWorker();
+}, []);
+```
+
+### 4. Install Prompt
+
+Create `components/InstallPrompt.tsx`:
+```tsx
+export const InstallPrompt: React.FC = () => {
+  const [deferredPrompt, setDeferredPrompt] = useState<any>(null);
+  const [showPrompt, setShowPrompt] = useState(false);
+  
+  useEffect(() => {
+    const handler = (e: Event) => {
+      e.preventDefault();
+      setDeferredPrompt(e);
+      setShowPrompt(true);
+    };
+    
+    window.addEventListener('beforeinstallprompt', handler);
+    
+    return () => window.removeEventListener('beforeinstallprompt', handler);
+  }, []);
+  
+  const handleInstall = async () => {
+    if (!deferredPrompt) return;
+    
+    deferredPrompt.prompt();
+    const { outcome } = await deferredPrompt.userChoice;
+    
+    if (outcome === 'accepted') {
+      console.log('PWA installed');
+    }
+    
+    setDeferredPrompt(null);
+    setShowPrompt(false);
+  };
+  
+  if (!showPrompt) return null;
+  
+  return (
+    <div className={styles.installBanner}>
+      <div className={styles.content}>
+        <span className={styles.icon}>📱</span>
+        <div className={styles.text}>
+          <strong>Install WeCoded</strong>
+          <p>Get the app experience with offline access!</p>
+        </div>
+      </div>
+      <div className={styles.actions}>
+        <button onClick={handleInstall} className={styles.installButton}>
+          Install
+        </button>
+        <button onClick={() => setShowPrompt(false)} className={styles.dismissButton}>
+          Not now
+        </button>
+      </div>
+    </div>
+  );
+};
+```
+
+### 5. Offline Page
+
+Create `public/offline.html`:
+```html
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>Offline - WeCoded</title>
+  <style>
+    body {
+      font-family: system-ui, -apple-system, sans-serif;
+      display: flex;
+      align-items: center;
+      justify-content: center;
+      min-height: 100vh;
+      margin: 0;
+      background: linear-gradient(to bottom, #f0f9ff, #e0f2fe);
+      text-align: center;
+      padding: 2rem;
+    }
+    .container {
+      max-width: 500px;
+    }
+    h1 {
+      font-size: 2rem;
+      margin-bottom: 1rem;
+    }
+    .icon {
+      font-size: 5rem;
+      margin-bottom: 1rem;
+    }
+    button {
+      margin-top: 2rem;
+      padding: 0.75rem 1.5rem;
+      font-size: 1rem;
+      background: #3b82f6;
+      color: white;
+      border: none;
+      border-radius: 0.5rem;
+      cursor: pointer;
+    }
+    button:hover {
+      background: #2563eb;
+    }
+  </style>
+</head>
+<body>
+  <div class="container">
+    <div class="icon">📡</div>
+    <h1>You're Offline</h1>
+    <p>
+      It looks like you've lost your internet connection. 
+      Don't worry, you can still view cached stories!
+    </p>
+    <button onclick="window.location.reload()">Try Again</button>
+  </div>
+</body>
+</html>
+```
+
+### 6. Online/Offline Indicator
+
+Create `components/OnlineStatus.tsx`:
+```tsx
+export const OnlineStatus: React.FC = () => {
+  const [isOnline, setIsOnline] = useState(navigator.onLine);
+  
+  useEffect(() => {
+    const handleOnline = () => setIsOnline(true);
+    const handleOffline = () => setIsOnline(false);
+    
+    window.addEventListener('online', handleOnline);
+    window.addEventListener('offline', handleOffline);
+    
+    return () => {
+      window.removeEventListener('online', handleOnline);
+      window.removeEventListener('offline', handleOffline);
+    };
+  }, []);
+  
+  if (isOnline) return null;
+  
+  return (
+    <div className={styles.offlineBanner}>
+      <span>📡</span> You're offline. Viewing cached content.
+    </div>
+  );
+};
+```
+
+## App Icons
+
+Generate icons using tools like:
+- [PWA Asset Generator](https://www.pwabuilder.com/imageGenerator)
+- [Favicon Generator](https://realfavicongenerator.net/)
+- [Maskable.app](https://maskable.app/) for maskable icons
+
+Required sizes:
+- 192x192 (minimum)
+- 512x512 (recommended)
+- Maskable variants
+- Apple touch icon (180x180)
+- Favicon (16x16, 32x32)
+
+## Acceptance Criteria
+
+- [ ] Web app manifest created and linked
+- [ ] Service worker implemented
+- [ ] Static assets cached
+- [ ] API responses cached
+- [ ] Offline fallback page created
+- [ ] Install prompt component added
+- [ ] Online/offline indicator implemented
+- [ ] App icons created (all sizes)
+- [ ] App installable on mobile and desktop
+- [ ] Works offline with cached content
+- [ ] Update notification shows for new versions
+- [ ] Lighthouse PWA score ≥ 90
+- [ ] Tested on Chrome, Safari, Firefox
+- [ ] Tested on iOS and Android
+
+## Testing Checklist
+
+- [ ] App shows install prompt
+- [ ] App installs successfully
+- [ ] Installed app opens in standalone mode
+- [ ] Service worker registers correctly
+- [ ] Static assets load from cache
+- [ ] API responses cached and served offline
+- [ ] Offline page shows when no network
+- [ ] Online indicator updates correctly
+- [ ] Update notification appears for new SW
+- [ ] Icons display correctly when installed
+- [ ] Theme color applied correctly
+
+## Related Files
+
+- `public/manifest.json` - Web app manifest (to create)
+- `public/sw.js` - Service worker (to create)
+- `public/offline.html` - Offline fallback (to create)
+- `public/icons/` - App icons (to create)
+- `utils/serviceWorker.ts` - SW registration (to create)
+- `components/InstallPrompt.tsx` - Install UI (to create)
+- `components/OnlineStatus.tsx` - Online status (to create)
+- `app/layout.tsx` - Add manifest link and SW registration
+
+## Tools & Resources
+
+- [PWABuilder](https://www.pwabuilder.com/)
+- [Workbox](https://developers.google.com/web/tools/workbox) (advanced SW library)
+- [PWA Checklist](https://web.dev/pwa-checklist/)
+- [Service Worker API](https://developer.mozilla.org/en-US/docs/Web/API/Service_Worker_API)
+- [Lighthouse PWA Audit](https://web.dev/lighthouse-pwa/)
+
+## Future Enhancements
+
+- Background sync for bookmarks/achievements
+- Push notifications for new stories
+- Share target (share to app)
+- Periodic background sync
+- Advanced caching strategies
+- Offline analytics queue
diff --git a/.github/ISSUES/16-analytics-tracking.md b/.github/ISSUES/16-analytics-tracking.md
new file mode 100644
index 0000000..2b96ed5
--- /dev/null
+++ b/.github/ISSUES/16-analytics-tracking.md
@@ -0,0 +1,459 @@
+---
+title: Implement analytics tracking
+labels: enhancement, analytics, monitoring
+---
+
+## Description
+
+Add privacy-friendly analytics tracking to understand user behavior, measure engagement, and improve the user experience based on data.
+
+## Background
+
+Currently, there's no visibility into how users interact with the WeCoded game. Analytics would help answer questions like: Which stories are most popular? How long do users stay? What features are most used? This data is crucial for improving the product while respecting user privacy.
+
+## Requirements
+
+### Privacy-First Approach
+
+1. **Privacy-Friendly Analytics**
+   - Use privacy-focused service (Plausible, Simple Analytics, or self-hosted)
+   - No cookies or personal data collection
+   - GDPR & CCPA compliant by default
+   - Anonymous IP addresses
+   - No cross-site tracking
+
+2. **User Consent**
+   - Optional: Opt-out mechanism
+   - Privacy policy link
+   - Clear data usage explanation
+   - Respect Do Not Track (DNT) header
+
+### Metrics to Track
+
+1. **Page Views**
+   - Total page views
+   - Unique visitors
+   - Session duration
+   - Bounce rate
+
+2. **Story Engagement**
+   - Story views (which stories are popular)
+   - Navigation patterns (next vs previous usage)
+   - Time spent per story
+   - Stories read per session
+   - Completion rate (% of stories viewed)
+
+3. **Feature Usage**
+   - Mini-game plays
+   - Mini-game average score
+   - Mini-game play duration
+   - Bookmark usage (if implemented)
+   - Share button clicks (if implemented)
+   - Search usage (if implemented)
+   - Filter usage (if implemented)
+
+4. **User Journey**
+   - Entry points
+   - Exit points
+   - Navigation flow
+   - Feature discovery rate
+
+5. **Technical Metrics**
+   - Load times
+   - Error rates
+   - Browser/device breakdown
+   - Geographic distribution (country level only)
+
+6. **Accessibility Metrics**
+   - Keyboard navigation usage
+   - Screen reader detection
+   - Reduced motion preference
+   - High contrast mode usage
+
+## Implementation
+
+### Option 1: Plausible Analytics (Recommended)
+
+Install Plausible:
+```bash
+npm install plausible-tracker
+```
+
+Create `utils/analytics.ts`:
+```typescript
+import Plausible from 'plausible-tracker';
+
+const plausible = Plausible({
+  domain: 'wecoded.yourdomain.com',
+  apiHost: 'https://plausible.io', // Or self-hosted instance
+  trackLocalhost: process.env.NODE_ENV === 'development',
+});
+
+export const analytics = {
+  // Page views
+  trackPageView: () => {
+    if (!shouldTrack()) return;
+    plausible.trackPageview();
+  },
+  
+  // Custom events
+  trackEvent: (eventName: string, props?: Record<string, string | number>) => {
+    if (!shouldTrack()) return;
+    plausible.trackEvent(eventName, { props });
+  },
+  
+  // Story interactions
+  trackStoryView: (storyId: number, storyTitle: string) => {
+    plausible.trackEvent('Story View', {
+      props: { storyId: String(storyId), storyTitle }
+    });
+  },
+  
+  trackStoryNavigation: (direction: 'next' | 'previous') => {
+    plausible.trackEvent('Story Navigation', {
+      props: { direction }
+    });
+  },
+  
+  // Mini-game
+  trackMiniGameStart: () => {
+    plausible.trackEvent('Mini Game Start');
+  },
+  
+  trackMiniGameEnd: (score: number, duration: number) => {
+    plausible.trackEvent('Mini Game End', {
+      props: { score: String(score), duration: String(duration) }
+    });
+  },
+  
+  // Bookmarks
+  trackBookmark: (action: 'add' | 'remove') => {
+    plausible.trackEvent('Bookmark', {
+      props: { action }
+    });
+  },
+  
+  // Sharing
+  trackShare: (platform: string, storyId: number) => {
+    plausible.trackEvent('Share', {
+      props: { platform, storyId: String(storyId) }
+    });
+  },
+  
+  // Search
+  trackSearch: (query: string, resultsCount: number) => {
+    plausible.trackEvent('Search', {
+      props: { query, resultsCount: String(resultsCount) }
+    });
+  },
+  
+  // Accessibility
+  trackAccessibilityFeature: (feature: string, enabled: boolean) => {
+    plausible.trackEvent('Accessibility Feature', {
+      props: { feature, enabled: String(enabled) }
+    });
+  },
+  
+  // Errors
+  trackError: (errorMessage: string, errorStack?: string) => {
+    plausible.trackEvent('Error', {
+      props: { errorMessage, errorStack: errorStack?.substring(0, 100) }
+    });
+  },
+};
+
+function shouldTrack(): boolean {
+  // Respect Do Not Track
+  if (navigator.doNotTrack === '1') {
+    return false;
+  }
+  
+  // Check if user has opted out
+  const optOut = localStorage.getItem('analytics_opt_out');
+  if (optOut === 'true') {
+    return false;
+  }
+  
+  return true;
+}
+
+export function enableAnalytics() {
+  plausible.enableAutoPageviews();
+  plausible.enableAutoOutboundTracking();
+}
+```
+
+### Option 2: Google Analytics 4 (GA4)
+
+If using GA4, install:
+```bash
+npm install react-ga4
+```
+
+Create `utils/analytics.ts`:
+```typescript
+import ReactGA from 'react-ga4';
+
+export function initializeAnalytics() {
+  if (!shouldTrack()) return;
+  
+  ReactGA.initialize('G-XXXXXXXXXX', {
+    gaOptions: {
+      anonymizeIp: true,
+    },
+  });
+}
+
+export const analytics = {
+  trackPageView: (page: string) => {
+    if (!shouldTrack()) return;
+    ReactGA.send({ hitType: 'pageview', page });
+  },
+  
+  trackEvent: (category: string, action: string, label?: string, value?: number) => {
+    if (!shouldTrack()) return;
+    ReactGA.event({
+      category,
+      action,
+      label,
+      value,
+    });
+  },
+  
+  // ... similar methods
+};
+```
+
+### Integration in App
+
+#### Page Tracking
+
+In `app/layout.tsx`:
+```tsx
+'use client';
+
+import { useEffect } from 'react';
+import { usePathname, useSearchParams } from 'next/navigation';
+import { enableAnalytics, analytics } from '@/utils/analytics';
+
+export default function RootLayout({ children }) {
+  const pathname = usePathname();
+  const searchParams = useSearchParams();
+  
+  useEffect(() => {
+    enableAnalytics();
+  }, []);
+  
+  useEffect(() => {
+    analytics.trackPageView();
+  }, [pathname, searchParams]);
+  
+  return (
+    <html lang="en">
+      <body>{children}</body>
+    </html>
+  );
+}
+```
+
+#### Event Tracking Examples
+
+In `components/StoryCard.tsx`:
+```tsx
+useEffect(() => {
+  analytics.trackStoryView(story.id, story.title);
+}, [story]);
+
+const handleNext = () => {
+  analytics.trackStoryNavigation('next');
+  onNext();
+};
+```
+
+In `components/MiniGame.tsx`:
+```tsx
+const startGame = () => {
+  analytics.trackMiniGameStart();
+  setIsActive(true);
+  setStartTime(Date.now());
+};
+
+useEffect(() => {
+  if (collision && isActive) {
+    const duration = Date.now() - startTime;
+    analytics.trackMiniGameEnd(score, duration);
+    setIsActive(false);
+  }
+}, [collision, isActive]);
+```
+
+### Privacy Notice Component
+
+Create `components/PrivacyNotice.tsx`:
+```tsx
+export const PrivacyNotice: React.FC = () => {
+  const [dismissed, setDismissed] = useState(false);
+  
+  useEffect(() => {
+    const noticeDismissed = localStorage.getItem('privacy_notice_dismissed');
+    setDismissed(noticeDismissed === 'true');
+  }, []);
+  
+  const handleAccept = () => {
+    localStorage.setItem('privacy_notice_dismissed', 'true');
+    setDismissed(true);
+  };
+  
+  const handleOptOut = () => {
+    localStorage.setItem('analytics_opt_out', 'true');
+    localStorage.setItem('privacy_notice_dismissed', 'true');
+    setDismissed(true);
+  };
+  
+  if (dismissed) return null;
+  
+  return (
+    <div className={styles.notice}>
+      <p>
+        We use privacy-friendly analytics to understand how people use WeCoded. 
+        No personal data is collected. <a href="/privacy">Learn more</a>
+      </p>
+      <div className={styles.actions}>
+        <button onClick={handleAccept}>Accept</button>
+        <button onClick={handleOptOut}>Opt Out</button>
+      </div>
+    </div>
+  );
+};
+```
+
+## Analytics Dashboard
+
+Access analytics through:
+- Plausible: `plausible.io/wecoded.yourdomain.com`
+- GA4: Google Analytics dashboard
+- Self-hosted: Custom dashboard
+
+## Acceptance Criteria
+
+- [ ] Analytics library installed and configured
+- [ ] Privacy-friendly service selected
+- [ ] Page views tracked automatically
+- [ ] Story views tracked
+- [ ] Navigation events tracked
+- [ ] Mini-game events tracked
+- [ ] Feature usage tracked
+- [ ] Error events tracked
+- [ ] DNT header respected
+- [ ] Opt-out mechanism implemented
+- [ ] Privacy notice displayed (if required)
+- [ ] Privacy policy updated
+- [ ] No personal data collected
+- [ ] No cookies used (for Plausible)
+- [ ] Analytics tested in production
+
+## Privacy Compliance
+
+### GDPR Compliance
+- No personal data collected
+- No cookies (with Plausible)
+- Anonymous IP addresses
+- Opt-out available
+- Data retention policy
+
+### CCPA Compliance
+- No selling of personal information
+- Opt-out mechanism
+- Privacy policy disclosure
+
+## Testing Checklist
+
+- [ ] Events fire correctly
+- [ ] DNT is respected
+- [ ] Opt-out works
+- [ ] No analytics in development (unless enabled)
+- [ ] Dashboard shows data
+- [ ] Custom events appear in dashboard
+- [ ] No console errors
+- [ ] Works across browsers
+- [ ] Mobile tracking works
+
+## Documentation
+
+Create `docs/ANALYTICS.md`:
+```markdown
+# Analytics Documentation
+
+## Tracked Events
+
+### Story Engagement
+- `Story View` - When a story is displayed
+- `Story Navigation` - Next/Previous navigation
+
+### Feature Usage
+- `Mini Game Start` - Game started
+- `Mini Game End` - Game ended (with score)
+- `Bookmark` - Story bookmarked/unbookmarked
+- `Share` - Story shared (with platform)
+
+### Search & Discovery
+- `Search` - Search performed (with query)
+- `Filter Applied` - Filters used
+
+## Privacy
+
+We use Plausible Analytics, a privacy-friendly service that:
+- Doesn't use cookies
+- Doesn't collect personal data
+- Anonymizes IP addresses
+- Is GDPR & CCPA compliant
+
+Users can opt out at any time.
+```
+
+## Related Files
+
+- `utils/analytics.ts` - Analytics utility (to create)
+- `components/PrivacyNotice.tsx` - Privacy notice (to create)
+- `app/layout.tsx` - Initialize analytics
+- `components/StoryCard.tsx` - Track story events
+- `components/MiniGame.tsx` - Track game events
+- `docs/ANALYTICS.md` - Documentation (to create)
+- Privacy policy page
+
+## Recommended Service: Plausible
+
+**Pros:**
+- Privacy-first
+- No cookies
+- GDPR compliant
+- Simple API
+- Beautiful dashboard
+- Open source (can self-host)
+
+**Cons:**
+- Paid service (after trial)
+- Less detailed than GA4
+
+## Alternative: Self-Hosted
+
+For complete control, self-host:
+- Plausible (open source)
+- Matomo
+- Umami
+- GoatCounter
+
+## Resources
+
+- [Plausible Documentation](https://plausible.io/docs)
+- [Google Analytics 4](https://developers.google.com/analytics/devguides/collection/ga4)
+- [Privacy-Friendly Analytics](https://github.com/plausible/analytics)
+
+## Future Enhancements
+
+- A/B testing
+- Funnel analysis
+- Cohort analysis
+- Custom dashboards
+- Automated reports
+- Goal tracking
diff --git a/.github/ISSUES/17-minigame-difficulty-variations.md b/.github/ISSUES/17-minigame-difficulty-variations.md
new file mode 100644
index 0000000..51746e5
--- /dev/null
+++ b/.github/ISSUES/17-minigame-difficulty-variations.md
@@ -0,0 +1,382 @@
+---
+title: Add mini-game difficulty levels and variations
+labels: enhancement, feature, gamification
+---
+
+## Description
+
+Enhance the mini-game with difficulty settings (Easy, Medium, Hard) and multiple game variations to increase replay value and engagement.
+
+## Background
+
+Currently, the mini-game has fixed difficulty and a single gameplay mode (dodge obstacles). Adding difficulty levels and game variations would make it more engaging, appeal to different skill levels, and increase the time users spend on the platform.
+
+## Requirements
+
+### Difficulty Levels
+
+1. **Easy Mode**
+   - Slower obstacle speed (50% of current)
+   - Lower spawn rate (5% chance vs 10%)
+   - Larger player hitbox tolerance
+   - Good for beginners
+
+2. **Medium Mode** (Current)
+   - Current speed and spawn rate
+   - Default selection
+   - Balanced gameplay
+
+3. **Hard Mode**
+   - Faster obstacle speed (150% of current)
+   - Higher spawn rate (15% chance)
+   - Stricter collision detection
+   - For experienced players
+
+4. **Expert Mode** (Unlock after achieving score milestones)
+   - Very fast obstacles (200% speed)
+   - Very high spawn rate (20% chance)
+   - Multiple obstacle types
+   - Unlocked after scoring 200+ on Hard
+
+### Game Variations
+
+1. **Classic Mode** (Current)
+   - Dodge falling obstacles
+   - Score increases over time
+   - Single player type
+
+2. **Collector Mode**
+   - Catch falling good items (stars ⭐)
+   - Avoid bad items (×)
+   - Score based on items collected
+   - Time limit: 60 seconds
+
+3. **Time Attack Mode**
+   - Survive as long as possible
+   - Obstacles speed increases over time
+   - Leaderboard for longest survival
+
+4. **Challenge Mode**
+   - Complete specific objectives
+   - "Collect 10 stars without getting hit"
+   - "Survive 30 seconds on Hard"
+   - "Reach score of 500"
+
+### Progression System
+
+1. **High Scores**
+   - Track best score per difficulty
+   - Track best score per game mode
+   - Persist in localStorage
+   - Display in game UI
+
+2. **Unlocks**
+   - Unlock Hard mode after Easy score > 100
+   - Unlock Expert mode after Hard score > 200
+   - Unlock game variations after playing Classic 5 times
+
+3. **Achievements Integration**
+   - Unlock achievements for high scores
+   - Unlock achievements for trying all modes
+   - Unlock achievements for difficulty completion
+
+## Technical Implementation
+
+### Game Configuration
+
+Create `types/gameTypes.ts`:
+```typescript
+export type Difficulty = 'easy' | 'medium' | 'hard' | 'expert';
+export type GameMode = 'classic' | 'collector' | 'timeAttack' | 'challenge';
+
+export interface GameConfig {
+  difficulty: Difficulty;
+  mode: GameMode;
+  obstacleSpeed: number;
+  spawnRate: number;
+  collisionTolerance: number;
+}
+
+export interface GameScore {
+  difficulty: Difficulty;
+  mode: GameMode;
+  score: number;
+  timestamp: string;
+}
+
+export const DIFFICULTY_CONFIGS: Record<Difficulty, Partial<GameConfig>> = {
+  easy: {
+    obstacleSpeed: 2.5,
+    spawnRate: 0.05,
+    collisionTolerance: 3,
+  },
+  medium: {
+    obstacleSpeed: 5,
+    spawnRate: 0.1,
+    collisionTolerance: 2,
+  },
+  hard: {
+    obstacleSpeed: 7.5,
+    spawnRate: 0.15,
+    collisionTolerance: 1.5,
+  },
+  expert: {
+    obstacleSpeed: 10,
+    spawnRate: 0.2,
+    collisionTolerance: 1,
+  },
+};
+```
+
+### Enhanced Mini-Game Component
+
+Update `components/MiniGame.tsx`:
+```tsx
+export const MiniGame: React.FC = () => {
+  const [difficulty, setDifficulty] = useState<Difficulty>('medium');
+  const [gameMode, setGameMode] = useState<GameMode>('classic');
+  const [highScores, setHighScores] = useState<Record<string, GameScore>>({});
+  const [unlockedDifficulties, setUnlockedDifficulties] = useState<Difficulty[]>(['easy', 'medium']);
+  
+  const config = DIFFICULTY_CONFIGS[difficulty];
+  
+  useEffect(() => {
+    // Load high scores and unlocks from localStorage
+    const saved = localStorage.getItem('minigame_data');
+    if (saved) {
+      const data = JSON.parse(saved);
+      setHighScores(data.highScores || {});
+      setUnlockedDifficulties(data.unlockedDifficulties || ['easy', 'medium']);
+    }
+  }, []);
+  
+  const checkUnlocks = (score: number) => {
+    const key = `${difficulty}-${gameMode}`;
+    
+    // Check if this unlocks new difficulties
+    if (difficulty === 'easy' && score > 100 && !unlockedDifficulties.includes('hard')) {
+      setUnlockedDifficulties(prev => [...prev, 'hard']);
+      showNotification('Hard mode unlocked!');
+    }
+    
+    if (difficulty === 'hard' && score > 200 && !unlockedDifficulties.includes('expert')) {
+      setUnlockedDifficulties(prev => [...prev, 'expert']);
+      showNotification('Expert mode unlocked!');
+    }
+    
+    // Save high score
+    const currentHigh = highScores[key]?.score || 0;
+    if (score > currentHigh) {
+      const newScore: GameScore = {
+        difficulty,
+        mode: gameMode,
+        score,
+        timestamp: new Date().toISOString(),
+      };
+      
+      const updated = { ...highScores, [key]: newScore };
+      setHighScores(updated);
+      
+      localStorage.setItem('minigame_data', JSON.stringify({
+        highScores: updated,
+        unlockedDifficulties,
+      }));
+      
+      showNotification('New high score!');
+    }
+  };
+  
+  // ... rest of game logic with config-based parameters
+};
+```
+
+### Game Mode Selection UI
+
+```tsx
+<div className={styles.modeSelection}>
+  <h3>Select Difficulty</h3>
+  <div className={styles.difficultyButtons}>
+    {(['easy', 'medium', 'hard', 'expert'] as Difficulty[]).map(diff => (
+      <button
+        key={diff}
+        onClick={() => setDifficulty(diff)}
+        disabled={!unlockedDifficulties.includes(diff)}
+        className={`${styles.diffButton} ${difficulty === diff ? styles.active : ''}`}
+      >
+        {diff.charAt(0).toUpperCase() + diff.slice(1)}
+        {!unlockedDifficulties.includes(diff) && ' 🔒'}
+      </button>
+    ))}
+  </div>
+  
+  <h3>Select Game Mode</h3>
+  <div className={styles.modeButtons}>
+    {(['classic', 'collector', 'timeAttack'] as GameMode[]).map(mode => (
+      <button
+        key={mode}
+        onClick={() => setGameMode(mode)}
+        className={`${styles.modeButton} ${gameMode === mode ? styles.active : ''}`}
+      >
+        {getModeDisplayName(mode)}
+      </button>
+    ))}
+  </div>
+  
+  <div className={styles.highScore}>
+    Best Score: {highScores[`${difficulty}-${gameMode}`]?.score || 0}
+  </div>
+</div>
+```
+
+### Collector Mode Implementation
+
+```tsx
+interface CollectibleItem {
+  id: number;
+  left: number;
+  top: number;
+  type: 'good' | 'bad';
+}
+
+// In game loop
+if (gameMode === 'collector') {
+  // Spawn good and bad items
+  if (Math.random() < config.spawnRate) {
+    const newItem: CollectibleItem = {
+      id: Date.now(),
+      left: Math.random() * 90,
+      top: -20,
+      type: Math.random() > 0.3 ? 'good' : 'bad'
+    };
+    setCollectibles(prev => [...prev, newItem]);
+  }
+  
+  // Check collisions
+  collectibles.forEach(item => {
+    if (checkCollision(playerPosition, item)) {
+      if (item.type === 'good') {
+        setScore(prev => prev + 10);
+        playSound('collect');
+      } else {
+        setScore(prev => Math.max(0, prev - 5));
+        playSound('hit');
+      }
+      // Remove collected item
+      setCollectibles(prev => prev.filter(c => c.id !== item.id));
+    }
+  });
+}
+```
+
+### Leaderboard Component
+
+Create `components/GameLeaderboard.tsx`:
+```tsx
+export const GameLeaderboard: React.FC = () => {
+  const [scores, setScores] = useState<GameScore[]>([]);
+  
+  useEffect(() => {
+    const data = localStorage.getItem('minigame_data');
+    if (data) {
+      const { highScores } = JSON.parse(data);
+      const scoreArray = Object.values(highScores) as GameScore[];
+      scoreArray.sort((a, b) => b.score - a.score);
+      setScores(scoreArray.slice(0, 10));
+    }
+  }, []);
+  
+  return (
+    <div className={styles.leaderboard}>
+      <h3>Your Top Scores</h3>
+      <table>
+        <thead>
+          <tr>
+            <th>Rank</th>
+            <th>Mode</th>
+            <th>Difficulty</th>
+            <th>Score</th>
+            <th>Date</th>
+          </tr>
+        </thead>
+        <tbody>
+          {scores.map((score, index) => (
+            <tr key={`${score.difficulty}-${score.mode}`}>
+              <td>{index + 1}</td>
+              <td>{score.mode}</td>
+              <td>{score.difficulty}</td>
+              <td>{score.score}</td>
+              <td>{new Date(score.timestamp).toLocaleDateString()}</td>
+            </tr>
+          ))}
+        </tbody>
+      </table>
+    </div>
+  );
+};
+```
+
+## UI/UX Enhancements
+
+1. **Visual Indicators**
+   - Different colors for each difficulty
+   - Icons for each game mode
+   - Animated unlock notifications
+
+2. **Sound Effects** (optional, with mute option)
+   - Collection sound
+   - Hit sound
+   - Level up sound
+   - Unlock sound
+
+3. **Particles/Effects**
+   - Particle burst on item collection
+   - Speed lines in hard/expert mode
+   - Celebration effect on high score
+
+## Acceptance Criteria
+
+- [ ] Four difficulty levels implemented
+- [ ] Three game modes implemented
+- [ ] Difficulty-based configurations working
+- [ ] High scores tracked per difficulty/mode
+- [ ] Hard mode unlocks after easy score > 100
+- [ ] Expert mode unlocks after hard score > 200
+- [ ] Collector mode with good/bad items
+- [ ] Time attack mode implemented
+- [ ] Leaderboard shows top 10 scores
+- [ ] Visual feedback for unlocks
+- [ ] Persists in localStorage
+- [ ] Responsive on mobile
+- [ ] Accessible (keyboard controls)
+
+## Testing Checklist
+
+- [ ] Easy mode is easier than medium
+- [ ] Hard mode is harder than medium
+- [ ] Expert mode is very challenging
+- [ ] Unlocks work correctly
+- [ ] High scores save correctly
+- [ ] Collector mode items spawn correctly
+- [ ] Collision detection works for all modes
+- [ ] Leaderboard displays correctly
+- [ ] Mobile touch controls work
+- [ ] Locked modes can't be selected
+
+## Related Files
+
+- `components/MiniGame.tsx` - Update with new features
+- `components/GameLeaderboard.tsx` - New leaderboard component (to create)
+- `types/gameTypes.ts` - Game type definitions (to create)
+- `components/MiniGame.module.css` - Updated styles
+- `utils/gameUtils.ts` - Game utility functions (to create)
+
+## Future Enhancements
+
+- Multiplayer mode
+- Daily challenges
+- Power-ups
+- Global leaderboard (requires backend)
+- Custom skins/themes
+- Tutorial mode
+- Mobile swipe controls
+- Achievements for game-specific milestones
diff --git a/.github/ISSUES/18-internationalization-i18n.md b/.github/ISSUES/18-internationalization-i18n.md
new file mode 100644
index 0000000..fa5613a
--- /dev/null
+++ b/.github/ISSUES/18-internationalization-i18n.md
@@ -0,0 +1,458 @@
+---
+title: Add internationalization (i18n) support
+labels: enhancement, i18n, accessibility, global
+---
+
+## Description
+
+Implement internationalization to support multiple languages, making the application accessible to the global tech community and aligning with WeCoded's diversity mission.
+
+## Background
+
+Currently, all text is hardcoded in English, limiting accessibility for non-English speakers in the global tech community. Since WeCoded celebrates diversity in tech, supporting multiple languages would significantly expand its reach and impact.
+
+## Requirements
+
+### Core i18n Features
+
+1. **Language Support** (Initial)
+   - English (en) - default
+   - Spanish (es) - large Spanish-speaking tech community
+   - Portuguese (pt) - Brazilian tech community
+   - French (fr) - growing tech community
+
+2. **Translation Coverage**
+   - UI labels and buttons
+   - Instructions and help text
+   - Error messages
+   - Achievements and notifications
+   - Meta tags (title, description)
+
+3. **Language Selection**
+   - Language picker in header/settings
+   - Persist user preference
+   - Auto-detect browser language
+   - Flag icons for visual identification
+
+4. **RTL Support** (for future Arabic/Hebrew)
+   - Layout adjustments for RTL languages
+   - Flip icons and navigation
+   - Mirror animations
+
+### What to Translate
+
+**DO translate:**
+- UI text, buttons, labels
+- Instructions and help
+- Error messages
+- Achievements
+- Form labels
+- Notifications
+
+**DON'T translate:**
+- Story content (fetched from DEV.to API)
+- Author names
+- Code examples
+- URLs
+
+## Technical Implementation
+
+### Option 1: next-intl (Recommended for Next.js)
+
+Install:
+```bash
+npm install next-intl
+```
+
+Create locale files:
+
+`messages/en.json`:
+```json
+{
+  "header": {
+    "title": "WeCoded Game",
+    "score": "Score: {score}"
+  },
+  "navigation": {
+    "previous": "Previous",
+    "next": "Next",
+    "miniGame": "Mini Game",
+    "howToPlay": "How to Play"
+  },
+  "storyCard": {
+    "xp": "+{amount} XP",
+    "level": "Level {current}/{total}",
+    "readMore": "Read full article"
+  },
+  "howToPlay": {
+    "title": "How to Play",
+    "readStories": "Read Stories",
+    "playGame": "Play Mini Game",
+    "trackProgress": "Track Progress",
+    "instruction1": "Browse through inspiring tech stories",
+    "instruction2": "Use arrow keys to navigate"
+  },
+  "miniGame": {
+    "title": "Mini Game",
+    "start": "Start Game",
+    "score": "Score: {score}",
+    "gameOver": "Game Over!",
+    "instructions": "Use arrow keys to move and dodge obstacles"
+  },
+  "loading": {
+    "stories": "Loading stories...",
+    "please_wait": "Please wait"
+  },
+  "errors": {
+    "failed_to_load": "Failed to load stories",
+    "try_again": "Try again",
+    "network_error": "Network error. Please check your connection."
+  }
+}
+```
+
+`messages/es.json`:
+```json
+{
+  "header": {
+    "title": "Juego WeCoded",
+    "score": "Puntuación: {score}"
+  },
+  "navigation": {
+    "previous": "Anterior",
+    "next": "Siguiente",
+    "miniGame": "Mini Juego",
+    "howToPlay": "Cómo Jugar"
+  },
+  "storyCard": {
+    "xp": "+{amount} XP",
+    "level": "Nivel {current}/{total}",
+    "readMore": "Leer artículo completo"
+  },
+  "howToPlay": {
+    "title": "Cómo Jugar",
+    "readStories": "Leer Historias",
+    "playGame": "Jugar Mini Juego",
+    "trackProgress": "Seguir Progreso",
+    "instruction1": "Navega por historias tecnológicas inspiradoras",
+    "instruction2": "Usa las teclas de flecha para navegar"
+  },
+  "miniGame": {
+    "title": "Mini Juego",
+    "start": "Iniciar Juego",
+    "score": "Puntuación: {score}",
+    "gameOver": "¡Juego Terminado!",
+    "instructions": "Usa las teclas de flecha para moverte y esquivar obstáculos"
+  },
+  "loading": {
+    "stories": "Cargando historias...",
+    "please_wait": "Por favor espera"
+  },
+  "errors": {
+    "failed_to_load": "Error al cargar historias",
+    "try_again": "Intentar de nuevo",
+    "network_error": "Error de red. Por favor verifica tu conexión."
+  }
+}
+```
+
+### Configuration
+
+Create `i18n.ts`:
+```typescript
+import { getRequestConfig } from 'next-intl/server';
+import { notFound } from 'next/navigation';
+
+export const locales = ['en', 'es', 'pt', 'fr'] as const;
+export type Locale = typeof locales[number];
+
+export default getRequestConfig(async ({ locale }) => {
+  if (!locales.includes(locale as Locale)) {
+    notFound();
+  }
+  
+  return {
+    messages: (await import(`./messages/${locale}.json`)).default
+  };
+});
+```
+
+Update `next.config.mjs`:
+```javascript
+import createNextIntlPlugin from 'next-intl/plugin';
+
+const withNextIntl = createNextIntlPlugin();
+
+export default withNextIntl({
+  // ... existing config
+});
+```
+
+### App Structure
+
+Create locale-based routing:
+```
+app/
+  [locale]/
+    layout.tsx
+    page.tsx
+    ...
+```
+
+Update `app/[locale]/layout.tsx`:
+```tsx
+import { NextIntlClientProvider } from 'next-intl';
+import { getMessages } from 'next-intl/server';
+
+export default async function LocaleLayout({
+  children,
+  params: { locale }
+}: {
+  children: React.ReactNode;
+  params: { locale: string };
+}) {
+  const messages = await getMessages();
+  
+  return (
+    <html lang={locale}>
+      <body>
+        <NextIntlClientProvider messages={messages}>
+          {children}
+        </NextIntlClientProvider>
+      </body>
+    </html>
+  );
+}
+```
+
+### Using Translations
+
+In components:
+```tsx
+'use client';
+
+import { useTranslations } from 'next-intl';
+
+export const GameHeader: React.FC = ({ score }) => {
+  const t = useTranslations('header');
+  
+  return (
+    <header>
+      <h1>{t('title')}</h1>
+      <div>{t('score', { score })}</div>
+    </header>
+  );
+};
+```
+
+### Language Switcher Component
+
+Create `components/LanguageSwitcher.tsx`:
+```tsx
+'use client';
+
+import { useLocale } from 'next-intl';
+import { useRouter, usePathname } from 'next/navigation';
+
+const languages = {
+  en: { name: 'English', flag: '🇺🇸' },
+  es: { name: 'Español', flag: '🇪🇸' },
+  pt: { name: 'Português', flag: '🇧🇷' },
+  fr: { name: 'Français', flag: '🇫🇷' },
+};
+
+export const LanguageSwitcher: React.FC = () => {
+  const locale = useLocale();
+  const router = useRouter();
+  const pathname = usePathname();
+  
+  const changeLanguage = (newLocale: string) => {
+    // Remove current locale from path
+    const pathWithoutLocale = pathname.replace(`/${locale}`, '');
+    // Add new locale
+    router.push(`/${newLocale}${pathWithoutLocale}`);
+    // Save preference
+    localStorage.setItem('preferred_locale', newLocale);
+  };
+  
+  return (
+    <div className={styles.languageSwitcher}>
+      <button className={styles.currentLanguage}>
+        {languages[locale].flag} {languages[locale].name}
+      </button>
+      <div className={styles.languageMenu}>
+        {Object.entries(languages).map(([code, lang]) => (
+          <button
+            key={code}
+            onClick={() => changeLanguage(code)}
+            className={code === locale ? styles.active : ''}
+          >
+            {lang.flag} {lang.name}
+          </button>
+        ))}
+      </div>
+    </div>
+  );
+};
+```
+
+### Auto-detect Browser Language
+
+In `middleware.ts`:
+```typescript
+import createMiddleware from 'next-intl/middleware';
+import { locales } from './i18n';
+
+export default createMiddleware({
+  locales,
+  defaultLocale: 'en',
+  localeDetection: true,
+});
+
+export const config = {
+  matcher: ['/', '/(en|es|pt|fr)/:path*']
+};
+```
+
+## RTL Support
+
+For future RTL languages (Arabic, Hebrew):
+
+```css
+[dir="rtl"] {
+  direction: rtl;
+}
+
+[dir="rtl"] .navigation {
+  flex-direction: row-reverse;
+}
+
+[dir="rtl"] .icon {
+  transform: scaleX(-1);
+}
+```
+
+In layout:
+```tsx
+<html lang={locale} dir={locale === 'ar' || locale === 'he' ? 'rtl' : 'ltr'}>
+```
+
+## Date/Time Formatting
+
+Use Intl API for dates:
+```tsx
+const formatDate = (date: string) => {
+  return new Intl.DateTimeFormat(locale, {
+    year: 'numeric',
+    month: 'long',
+    day: 'numeric'
+  }).format(new Date(date));
+};
+```
+
+## Number Formatting
+
+```tsx
+const formatNumber = (num: number) => {
+  return new Intl.NumberFormat(locale).format(num);
+};
+```
+
+## Acceptance Criteria
+
+- [ ] next-intl installed and configured
+- [ ] 4 languages supported (en, es, pt, fr)
+- [ ] All UI text extracted to translation files
+- [ ] Language switcher component added
+- [ ] Language preference persists
+- [ ] Auto-detect browser language
+- [ ] Translations complete for all languages
+- [ ] Date/number formatting respects locale
+- [ ] URLs include locale prefix
+- [ ] Meta tags translated
+- [ ] Works on all pages
+- [ ] Mobile-responsive language switcher
+- [ ] Fallback to English for missing translations
+
+## Translation Process
+
+1. **Extract all strings** to en.json
+2. **Use translation service** (DeepL, Google Translate as starting point)
+3. **Native speaker review** for accuracy and cultural appropriateness
+4. **Test with each language**
+5. **Handle pluralization** properly
+6. **Context-aware translations** where needed
+
+### Translation Tools
+
+- [DeepL](https://www.deepl.com/) - High-quality translations
+- [Google Translate](https://translate.google.com/)
+- [Crowdin](https://crowdin.com/) - Translation management platform
+- [POEditor](https://poeditor.com/) - Collaborative translation
+
+## Testing Checklist
+
+- [ ] All text displays correctly in each language
+- [ ] Language switcher works
+- [ ] Language preference persists
+- [ ] URLs include correct locale
+- [ ] Dates formatted correctly
+- [ ] Numbers formatted correctly
+- [ ] No hardcoded strings remain
+- [ ] Fallback to English works
+- [ ] Long text doesn't break layout
+- [ ] Special characters display correctly
+- [ ] Works on mobile
+
+## Pluralization
+
+Handle plural forms correctly:
+```json
+{
+  "stories": {
+    "count": "{count, plural, =0 {No stories} =1 {1 story} other {# stories}}"
+  }
+}
+```
+
+Usage:
+```tsx
+t('stories.count', { count: storyCount })
+```
+
+## Related Files
+
+- `messages/en.json` - English translations (to create)
+- `messages/es.json` - Spanish translations (to create)
+- `messages/pt.json` - Portuguese translations (to create)
+- `messages/fr.json` - French translations (to create)
+- `i18n.ts` - i18n configuration (to create)
+- `middleware.ts` - Locale detection (to create)
+- `components/LanguageSwitcher.tsx` - Language selector (to create)
+- `app/[locale]/layout.tsx` - Update layout structure
+- All component files - Replace hardcoded strings with `t()` calls
+
+## Resources
+
+- [next-intl Documentation](https://next-intl-docs.vercel.app/)
+- [CLDR Plural Rules](https://cldr.unicode.org/index/cldr-spec/plural-rules)
+- [Internationalization Best Practices](https://phrase.com/blog/posts/i18n-best-practices/)
+- [RTL Layout Guide](https://rtlstyling.com/)
+
+## Future Languages
+
+Consider adding:
+- German (de)
+- Japanese (ja)
+- Chinese (zh)
+- Arabic (ar) - requires RTL support
+- Russian (ru)
+- Hindi (hi)
+
+## Future Enhancements
+
+- Crowdsourced translations
+- Translation management platform
+- Automatic story translation (optional)
+- Regional variants (pt-BR vs pt-PT)
+- Locale-specific content
diff --git a/.github/ISSUES/19-reading-progress-resume.md b/.github/ISSUES/19-reading-progress-resume.md
new file mode 100644
index 0000000..16ddad2
--- /dev/null
+++ b/.github/ISSUES/19-reading-progress-resume.md
@@ -0,0 +1,446 @@
+---
+title: Add story reading progress indicator and resume feature
+labels: enhancement, feature, user-experience
+---
+
+## Description
+
+Implement a system to track which stories users have read and allow resuming where they left off, improving user experience and encouraging continued engagement.
+
+## Background
+
+Currently, progress resets on page reload and users can't track what they've already read. As the story collection grows, users need a way to track their reading history and continue from where they stopped. This feature would significantly improve UX and encourage users to read more stories.
+
+## Requirements
+
+### Reading Progress Tracking
+
+1. **Mark Stories as Read**
+   - Automatically mark story as "read" when viewed
+   - Threshold: viewed for at least 5 seconds
+   - Store read story IDs in localStorage
+
+2. **Visual Indicators**
+   - Badge/checkmark on read stories
+   - Progress ring showing completion %
+   - "New" badge for unread stories
+   - Distinct styling for read vs unread
+
+3. **Resume Functionality**
+   - On page load, jump to first unread story
+   - "Continue Reading" button
+   - Skip already-read stories option
+
+4. **Reading Statistics**
+   - Total stories read
+   - Reading streak (consecutive days)
+   - Time spent reading
+   - Completion percentage
+
+### Reading History
+
+1. **History View**
+   - List of all read stories
+   - Grouped by date (Today, Yesterday, This Week, etc.)
+   - Re-read stories from history
+   - Clear history option
+
+2. **Filters**
+   - Show only unread stories
+   - Show only read stories
+   - Show all stories
+
+## Technical Implementation
+
+### Data Structure
+
+```typescript
+interface ReadingProgress {
+  storyId: number;
+  readAt: string;
+  readCount: number; // How many times viewed
+  timeSpent: number; // Seconds spent viewing
+}
+
+interface ReadingStats {
+  totalRead: number;
+  uniqueAuthors: Set<string>;
+  lastReadDate: string;
+  streakDays: number;
+  totalTimeSpent: number;
+}
+
+interface StorageData {
+  progress: Record<number, ReadingProgress>;
+  currentStoryIndex: number;
+  stats: ReadingStats;
+  version: string;
+}
+```
+
+### Reading Progress Hook
+
+Create `hooks/useReadingProgress.ts`:
+```typescript
+const STORAGE_KEY = 'wecoded_reading_progress_v1';
+const READ_THRESHOLD = 5000; // 5 seconds
+
+export function useReadingProgress() {
+  const [readStories, setReadStories] = useState<Set<number>>(new Set());
+  const [currentViewStart, setCurrentViewStart] = useState<number | null>(null);
+  const [stats, setStats] = useState<ReadingStats>({
+    totalRead: 0,
+    uniqueAuthors: new Set(),
+    lastReadDate: '',
+    streakDays: 0,
+    totalTimeSpent: 0
+  });
+  
+  // Load progress on mount
+  useEffect(() => {
+    const saved = localStorage.getItem(STORAGE_KEY);
+    if (saved) {
+      const data: StorageData = JSON.parse(saved);
+      setReadStories(new Set(Object.keys(data.progress).map(Number)));
+      setStats(data.stats);
+    }
+  }, []);
+  
+  // Mark story as viewed (start timer)
+  const startViewing = (storyId: number) => {
+    setCurrentViewStart(Date.now());
+  };
+  
+  // Mark story as read (if threshold met)
+  const stopViewing = (storyId: number, story: DevArticle) => {
+    if (!currentViewStart) return;
+    
+    const timeSpent = Date.now() - currentViewStart;
+    
+    if (timeSpent >= READ_THRESHOLD) {
+      markAsRead(storyId, story, timeSpent);
+    }
+    
+    setCurrentViewStart(null);
+  };
+  
+  const markAsRead = (storyId: number, story: DevArticle, timeSpent: number) => {
+    // Get existing data
+    const saved = localStorage.getItem(STORAGE_KEY);
+    const data: StorageData = saved ? JSON.parse(saved) : {
+      progress: {},
+      currentStoryIndex: 0,
+      stats: { ...stats },
+      version: '1'
+    };
+    
+    // Update or create progress entry
+    const existing = data.progress[storyId];
+    data.progress[storyId] = {
+      storyId,
+      readAt: new Date().toISOString(),
+      readCount: (existing?.readCount || 0) + 1,
+      timeSpent: (existing?.timeSpent || 0) + timeSpent
+    };
+    
+    // Update stats
+    const newStats = { ...data.stats };
+    if (!existing) {
+      newStats.totalRead++;
+      newStats.uniqueAuthors.add(story.user.name);
+    }
+    newStats.totalTimeSpent += timeSpent;
+    newStats.lastReadDate = new Date().toISOString();
+    newStats.streakDays = calculateStreak(data.progress);
+    
+    data.stats = newStats;
+    
+    // Save
+    localStorage.setItem(STORAGE_KEY, JSON.stringify(data));
+    
+    // Update state
+    setReadStories(new Set([...readStories, storyId]));
+    setStats(newStats);
+  };
+  
+  const calculateStreak = (progress: Record<number, ReadingProgress>): number => {
+    const dates = Object.values(progress)
+      .map(p => new Date(p.readAt).toDateString())
+      .filter((date, index, self) => self.indexOf(date) === index)
+      .sort()
+      .reverse();
+    
+    let streak = 0;
+    const today = new Date().toDateString();
+    
+    for (let i = 0; i < dates.length; i++) {
+      const expectedDate = new Date();
+      expectedDate.setDate(expectedDate.getDate() - i);
+      
+      if (dates[i] === expectedDate.toDateString()) {
+        streak++;
+      } else {
+        break;
+      }
+    }
+    
+    return streak;
+  };
+  
+  const isRead = (storyId: number) => readStories.has(storyId);
+  
+  const getNextUnread = (stories: DevArticle[], currentIndex: number): number => {
+    for (let i = 0; i < stories.length; i++) {
+      const nextIndex = (currentIndex + i) % stories.length;
+      if (!readStories.has(stories[nextIndex].id)) {
+        return nextIndex;
+      }
+    }
+    return currentIndex; // All read, stay at current
+  };
+  
+  const clearProgress = () => {
+    localStorage.removeItem(STORAGE_KEY);
+    setReadStories(new Set());
+    setStats({
+      totalRead: 0,
+      uniqueAuthors: new Set(),
+      lastReadDate: '',
+      streakDays: 0,
+      totalTimeSpent: 0
+    });
+  };
+  
+  return {
+    readStories,
+    stats,
+    startViewing,
+    stopViewing,
+    isRead,
+    getNextUnread,
+    clearProgress
+  };
+}
+```
+
+### Integration in Page
+
+Update `app/page.tsx`:
+```tsx
+const { 
+  readStories, 
+  stats, 
+  startViewing, 
+  stopViewing, 
+  isRead, 
+  getNextUnread 
+} = useReadingProgress();
+
+useEffect(() => {
+  if (stories.length > 0) {
+    startViewing(stories[currentStoryIndex].id);
+    
+    return () => {
+      stopViewing(stories[currentStoryIndex].id, stories[currentStoryIndex]);
+    };
+  }
+}, [currentStoryIndex, stories]);
+
+// Resume on load
+useEffect(() => {
+  if (stories.length > 0) {
+    const nextUnread = getNextUnread(stories, 0);
+    setCurrentStoryIndex(nextUnread);
+  }
+}, [stories]);
+```
+
+### Visual Indicators
+
+Update `StoryCard.tsx`:
+```tsx
+<div className={`${styles.card} ${isRead(story.id) ? styles.read : styles.unread}`}>
+  <div className={styles.header}>
+    <h3 className={styles.title}>
+      {story.title}
+      {isRead(story.id) && <span className={styles.readBadge}>✓ Read</span>}
+      {!isRead(story.id) && <span className={styles.newBadge}>New</span>}
+    </h3>
+  </div>
+  {/* ... rest of card */}
+</div>
+```
+
+### Reading Stats Component
+
+Create `components/ReadingStats.tsx`:
+```tsx
+export const ReadingStats: React.FC<{ stats: ReadingStats }> = ({ stats }) => {
+  const formatTime = (seconds: number) => {
+    const minutes = Math.floor(seconds / 60);
+    if (minutes < 60) return `${minutes}m`;
+    const hours = Math.floor(minutes / 60);
+    return `${hours}h ${minutes % 60}m`;
+  };
+  
+  return (
+    <div className={styles.statsContainer}>
+      <div className={styles.statCard}>
+        <div className={styles.statValue}>{stats.totalRead}</div>
+        <div className={styles.statLabel}>Stories Read</div>
+      </div>
+      
+      <div className={styles.statCard}>
+        <div className={styles.statValue}>{stats.uniqueAuthors.size}</div>
+        <div className={styles.statLabel}>Authors Discovered</div>
+      </div>
+      
+      <div className={styles.statCard}>
+        <div className={styles.statValue}>{stats.streakDays}</div>
+        <div className={styles.statLabel}>Day Streak 🔥</div>
+      </div>
+      
+      <div className={styles.statCard}>
+        <div className={styles.statValue}>{formatTime(stats.totalTimeSpent / 1000)}</div>
+        <div className={styles.statLabel}>Time Reading</div>
+      </div>
+    </div>
+  );
+};
+```
+
+### Continue Reading Button
+
+```tsx
+<div className={styles.resumeSection}>
+  {hasUnreadStories && (
+    <button 
+      onClick={() => {
+        const nextUnread = getNextUnread(stories, currentStoryIndex);
+        setCurrentStoryIndex(nextUnread);
+      }}
+      className={styles.continueButton}
+    >
+      📖 Continue Reading ({unreadCount} stories left)
+    </button>
+  )}
+</div>
+```
+
+### Filter Controls
+
+```tsx
+const [filter, setFilter] = useState<'all' | 'read' | 'unread'>('all');
+
+const filteredStories = useMemo(() => {
+  if (filter === 'all') return stories;
+  if (filter === 'read') return stories.filter(s => isRead(s.id));
+  if (filter === 'unread') return stories.filter(s => !isRead(s.id));
+  return stories;
+}, [stories, filter, readStories]);
+
+<div className={styles.filters}>
+  <button 
+    onClick={() => setFilter('all')}
+    className={filter === 'all' ? styles.active : ''}
+  >
+    All ({stories.length})
+  </button>
+  <button 
+    onClick={() => setFilter('unread')}
+    className={filter === 'unread' ? styles.active : ''}
+  >
+    Unread ({stories.filter(s => !isRead(s.id)).length})
+  </button>
+  <button 
+    onClick={() => setFilter('read')}
+    className={filter === 'read' ? styles.active : ''}
+  >
+    Read ({readStories.size})
+  </button>
+</div>
+```
+
+## Progress Indicator UI
+
+```css
+.progressRing {
+  position: relative;
+  width: 60px;
+  height: 60px;
+}
+
+.progressRing svg {
+  transform: rotate(-90deg);
+}
+
+.progressRing .background {
+  fill: none;
+  stroke: var(--border-color);
+  stroke-width: 4;
+}
+
+.progressRing .progress {
+  fill: none;
+  stroke: var(--accent-color);
+  stroke-width: 4;
+  stroke-dasharray: 188.5; /* 2 * PI * 30 */
+  stroke-dashoffset: calc(188.5 * (1 - var(--progress)));
+  transition: stroke-dashoffset 0.3s;
+}
+
+.progressText {
+  position: absolute;
+  top: 50%;
+  left: 50%;
+  transform: translate(-50%, -50%);
+  font-weight: bold;
+}
+```
+
+## Acceptance Criteria
+
+- [ ] Stories marked as read after 5 seconds
+- [ ] Read status persists in localStorage
+- [ ] Visual badge shows read status
+- [ ] "Continue Reading" button jumps to first unread
+- [ ] Reading stats component displays metrics
+- [ ] Streak calculation works correctly
+- [ ] Filter by read/unread works
+- [ ] Progress ring shows completion %
+- [ ] Clear history functionality
+- [ ] Works across browser sessions
+- [ ] Mobile-responsive design
+- [ ] Performance: handles 100+ stories
+
+## Testing Checklist
+
+- [ ] Story marked read after 5 seconds
+- [ ] Quick navigation doesn't mark as read
+- [ ] Progress persists after reload
+- [ ] Continue button finds next unread
+- [ ] Stats update correctly
+- [ ] Streak calculates correctly
+- [ ] Filters work correctly
+- [ ] Read badge displays on read stories
+- [ ] New badge displays on unread stories
+- [ ] Clear history works
+- [ ] No performance issues with many stories
+
+## Related Files
+
+- `hooks/useReadingProgress.ts` - Progress tracking hook (to create)
+- `components/ReadingStats.tsx` - Stats display (to create)
+- `components/StoryCard.tsx` - Add read indicators
+- `app/page.tsx` - Integrate progress tracking
+- `types/index.ts` - Add progress types
+
+## Future Enhancements
+
+- Sync progress across devices (requires backend)
+- Export reading history
+- Reading goals (e.g., 10 stories this week)
+- Estimated time to complete all stories
+- Reading heatmap (calendar view)
+- Recommended stories based on history
+- Share reading stats
diff --git a/.github/ISSUES/20-contributing-guide-templates.md b/.github/ISSUES/20-contributing-guide-templates.md
new file mode 100644
index 0000000..3b987cc
--- /dev/null
+++ b/.github/ISSUES/20-contributing-guide-templates.md
@@ -0,0 +1,500 @@
+---
+title: Create contributing guide and issue templates
+labels: documentation, community, good-first-issue
+---
+
+## Description
+
+Add comprehensive CONTRIBUTING.md and GitHub issue/PR templates to lower the barrier for community contributions and maintain code quality.
+
+## Background
+
+Currently, the README mentions contributing but lacks detailed guidelines. As the project grows and attracts contributors, clear documentation and templates will help maintain consistency, quality, and make it easier for newcomers to contribute effectively.
+
+## Requirements
+
+### 1. CONTRIBUTING.md
+
+Create a comprehensive contributing guide covering:
+
+#### Getting Started
+- Prerequisites (Node.js version, etc.)
+- Fork and clone instructions
+- Installation steps
+- Running the development server
+- Building the project
+
+#### Development Workflow
+- Branch naming conventions
+- Commit message format
+- Code style guidelines
+- Testing requirements
+- Linting and formatting
+
+#### Making Changes
+- Finding issues to work on
+- Creating feature branches
+- Writing tests
+- Updating documentation
+- Running tests locally
+
+#### Submitting Changes
+- Creating pull requests
+- PR description requirements
+- Review process
+- Merge criteria
+- What to do if PR is rejected
+
+#### Code Standards
+- TypeScript usage
+- Component structure
+- CSS modules patterns
+- Accessibility requirements
+- Performance considerations
+
+### 2. Issue Templates
+
+Create templates for common issue types:
+
+#### Bug Report Template
+- Bug description
+- Steps to reproduce
+- Expected behavior
+- Actual behavior
+- Screenshots
+- Environment (browser, OS, version)
+- Additional context
+
+#### Feature Request Template
+- Feature description
+- Use case / motivation
+- Proposed solution
+- Alternatives considered
+- Additional context
+
+#### Documentation Issue Template
+- What needs documenting
+- Current state
+- Desired state
+- Related files
+
+### 3. Pull Request Template
+
+Create PR template with:
+- Description of changes
+- Related issue number
+- Type of change (bug fix, feature, docs, etc.)
+- Checklist (tests, docs, linting)
+- Screenshots (for UI changes)
+- Breaking changes notice
+
+### 4. CODE_OF_CONDUCT.md
+
+Add code of conduct covering:
+- Our pledge
+- Our standards
+- Enforcement responsibilities
+- Scope
+- Enforcement
+- Attribution
+
+## Implementation
+
+### CONTRIBUTING.md
+
+Create `.github/CONTRIBUTING.md`:
+```markdown
+# Contributing to WeCoded Game
+
+Thank you for your interest in contributing to WeCoded! This document provides guidelines and instructions for contributing.
+
+## 🚀 Quick Start
+
+### Prerequisites
+
+- Node.js 20 or higher
+- npm or yarn
+- Git
+
+### Setup
+
+1. Fork the repository
+2. Clone your fork:
+   \`\`\`bash
+   git clone https://github.com/YOUR_USERNAME/we-coded.git
+   cd we-coded
+   \`\`\`
+
+3. Install dependencies:
+   \`\`\`bash
+   npm install
+   \`\`\`
+
+4. Create a branch:
+   \`\`\`bash
+   git checkout -b feature/your-feature-name
+   \`\`\`
+
+5. Start development server:
+   \`\`\`bash
+   npm run dev
+   \`\`\`
+
+## 📝 Development Guidelines
+
+### Code Style
+
+- Use TypeScript for all new code
+- Follow existing code patterns
+- Use functional components with hooks
+- Use CSS modules for styling
+- Add JSDoc comments for functions and components
+
+### Component Guidelines
+
+- Place components in `components/` directory
+- One component per file
+- Create corresponding `.module.css` file for styles
+- Export as default or named export
+- Add proper TypeScript types
+
+Example:
+\`\`\`tsx
+'use client';
+
+import React from 'react';
+import styles from './MyComponent.module.css';
+
+interface MyComponentProps {
+  title: string;
+  onAction: () => void;
+}
+
+/**
+ * MyComponent does something specific
+ */
+export const MyComponent: React.FC<MyComponentProps> = ({ title, onAction }) => {
+  return (
+    <div className={styles.container}>
+      <h2>{title}</h2>
+      <button onClick={onAction}>Action</button>
+    </div>
+  );
+};
+\`\`\`
+
+### Commit Messages
+
+Follow conventional commits format:
+
+- `feat: add new feature`
+- `fix: fix bug in component`
+- `docs: update README`
+- `style: format code`
+- `refactor: restructure component`
+- `test: add tests`
+- `chore: update dependencies`
+
+### Testing
+
+- Write tests for new features
+- Ensure existing tests pass: `npm test`
+- Add E2E tests for user flows
+- Test accessibility with keyboard and screen reader
+
+### Accessibility
+
+All contributions must meet WCAG 2.1 AA standards:
+
+- Proper semantic HTML
+- ARIA labels where needed
+- Keyboard navigation support
+- Sufficient color contrast
+- Screen reader compatibility
+- Respect `prefers-reduced-motion`
+
+### Linting
+
+Run linting before committing:
+\`\`\`bash
+npm run lint
+\`\`\`
+
+## 🔄 Pull Request Process
+
+1. **Update documentation** if needed
+2. **Add tests** for new features
+3. **Run tests** and linting locally
+4. **Create PR** with clear description
+5. **Link related issue** using "Closes #123"
+6. **Respond to review** feedback
+7. **Squash commits** if requested
+
+### PR Checklist
+
+- [ ] Code follows style guidelines
+- [ ] Self-review completed
+- [ ] Comments added for complex code
+- [ ] Documentation updated
+- [ ] No console errors or warnings
+- [ ] Tests added/updated
+- [ ] All tests pass
+- [ ] Accessibility verified
+- [ ] UI changes include screenshots
+
+## 🎯 Finding Issues
+
+Look for issues labeled:
+- `good-first-issue` - Great for newcomers
+- `help-wanted` - Community help needed
+- `enhancement` - New features
+- `bug` - Bug fixes
+
+## 🤝 Community
+
+- Be respectful and inclusive
+- Help others learn
+- Follow the Code of Conduct
+- Ask questions in issues/discussions
+
+## 📚 Resources
+
+- [Next.js Documentation](https://nextjs.org/docs)
+- [React Documentation](https://react.dev)
+- [TypeScript Handbook](https://www.typescriptlang.org/docs/)
+- [WCAG Guidelines](https://www.w3.org/WAI/WCAG21/quickref/)
+
+## ❓ Questions
+
+If you have questions:
+- Check existing issues
+- Create a new issue with "question" label
+- Join our discussions
+
+Thank you for contributing to WeCoded! 🎉
+```
+
+### Bug Report Template
+
+Create `.github/ISSUE_TEMPLATE/bug_report.md`:
+```markdown
+---
+name: Bug report
+about: Create a report to help us improve
+title: '[BUG] '
+labels: bug
+assignees: ''
+---
+
+## Bug Description
+A clear and concise description of what the bug is.
+
+## Steps To Reproduce
+1. Go to '...'
+2. Click on '...'
+3. Scroll down to '...'
+4. See error
+
+## Expected Behavior
+A clear description of what you expected to happen.
+
+## Actual Behavior
+What actually happened.
+
+## Screenshots
+If applicable, add screenshots to help explain your problem.
+
+## Environment
+- Browser: [e.g. Chrome 120, Safari 17]
+- OS: [e.g. Windows 11, macOS 14, iOS 17]
+- Device: [e.g. Desktop, iPhone 15]
+- Screen size: [e.g. 1920x1080, mobile]
+
+## Additional Context
+Add any other context about the problem here.
+
+## Possible Solution
+If you have ideas on how to fix this, please share.
+```
+
+### Feature Request Template
+
+Create `.github/ISSUE_TEMPLATE/feature_request.md`:
+```markdown
+---
+name: Feature request
+about: Suggest an idea for this project
+title: '[FEATURE] '
+labels: enhancement
+assignees: ''
+---
+
+## Feature Description
+A clear and concise description of the feature you'd like to see.
+
+## Problem/Motivation
+What problem does this solve? Why is this feature needed?
+
+## Proposed Solution
+Describe how you envision this feature working.
+
+## Alternatives Considered
+Describe any alternative solutions or features you've considered.
+
+## Additional Context
+Add any other context, screenshots, or mockups about the feature here.
+
+## Would you like to implement this?
+- [ ] Yes, I'd like to implement this feature
+- [ ] No, but I can help with testing/review
+- [ ] No, just suggesting
+```
+
+### Pull Request Template
+
+Create `.github/PULL_REQUEST_TEMPLATE.md`:
+```markdown
+## Description
+<!-- Describe your changes in detail -->
+
+## Related Issue
+<!-- Link to the issue this PR addresses -->
+Closes #
+
+## Type of Change
+<!-- Mark the relevant option with an "x" -->
+- [ ] 🐛 Bug fix (non-breaking change which fixes an issue)
+- [ ] ✨ New feature (non-breaking change which adds functionality)
+- [ ] 💥 Breaking change (fix or feature that would cause existing functionality to not work as expected)
+- [ ] 📝 Documentation update
+- [ ] 🎨 Style/UI update
+- [ ] ♿ Accessibility improvement
+- [ ] ⚡ Performance improvement
+- [ ] ✅ Test update
+
+## Checklist
+<!-- Mark completed items with an "x" -->
+- [ ] My code follows the style guidelines of this project
+- [ ] I have performed a self-review of my own code
+- [ ] I have commented my code, particularly in hard-to-understand areas
+- [ ] I have made corresponding changes to the documentation
+- [ ] My changes generate no new warnings or errors
+- [ ] I have added tests that prove my fix is effective or that my feature works
+- [ ] New and existing unit tests pass locally with my changes
+- [ ] I have checked my code for accessibility issues
+- [ ] I have tested on multiple browsers (if applicable)
+
+## Screenshots
+<!-- If applicable, add screenshots to demonstrate the changes -->
+
+### Before
+<!-- Screenshot or description of the before state -->
+
+### After
+<!-- Screenshot or description of the after state -->
+
+## Testing
+<!-- Describe the tests you ran to verify your changes -->
+- [ ] Tested locally
+- [ ] Tested on mobile
+- [ ] Tested with keyboard navigation
+- [ ] Tested with screen reader
+
+## Additional Notes
+<!-- Any additional information that reviewers should know -->
+```
+
+### Code of Conduct
+
+Create `.github/CODE_OF_CONDUCT.md`:
+```markdown
+# Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in our community a harassment-free experience for everyone, regardless of age, body size, visible or invisible disability, ethnicity, sex characteristics, gender identity and expression, level of experience, education, socio-economic status, nationality, personal appearance, race, religion, or sexual identity and orientation.
+
+We pledge to act and interact in ways that contribute to an open, welcoming, diverse, inclusive, and healthy community.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment:
+
+* Using welcoming and inclusive language
+* Being respectful of differing viewpoints and experiences
+* Gracefully accepting constructive criticism
+* Focusing on what is best for the community
+* Showing empathy towards other community members
+
+Examples of unacceptable behavior:
+
+* The use of sexualized language or imagery
+* Trolling, insulting/derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information without explicit permission
+* Other conduct which could reasonably be considered inappropriate
+
+## Enforcement Responsibilities
+
+Community leaders are responsible for clarifying and enforcing our standards of acceptable behavior and will take appropriate and fair corrective action in response to any behavior that they deem inappropriate, threatening, offensive, or harmful.
+
+## Scope
+
+This Code of Conduct applies within all community spaces, and also applies when an individual is officially representing the community in public spaces.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be reported to the community leaders responsible for enforcement. All complaints will be reviewed and investigated promptly and fairly.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant](https://www.contributor-covenant.org/), version 2.0.
+```
+
+## Acceptance Criteria
+
+- [ ] CONTRIBUTING.md created with comprehensive guidelines
+- [ ] Bug report issue template created
+- [ ] Feature request issue template created
+- [ ] Documentation issue template created
+- [ ] Pull request template created
+- [ ] CODE_OF_CONDUCT.md created
+- [ ] Templates use GitHub issue template format
+- [ ] Templates include all necessary fields
+- [ ] README links to CONTRIBUTING.md
+- [ ] Templates are easy to understand
+- [ ] Examples provided where helpful
+
+## Testing Checklist
+
+- [ ] Create test issue using each template
+- [ ] Verify all template fields render correctly
+- [ ] Create test PR to verify template
+- [ ] Links in CONTRIBUTING.md work
+- [ ] Instructions are clear and followable
+- [ ] Code examples are correct
+- [ ] No broken links
+
+## Related Files
+
+- `.github/CONTRIBUTING.md` (to create)
+- `.github/CODE_OF_CONDUCT.md` (to create)
+- `.github/ISSUE_TEMPLATE/bug_report.md` (to create)
+- `.github/ISSUE_TEMPLATE/feature_request.md` (to create)
+- `.github/ISSUE_TEMPLATE/documentation.md` (to create)
+- `.github/PULL_REQUEST_TEMPLATE.md` (to create)
+- `README.md` - Add link to CONTRIBUTING.md
+
+## Resources
+
+- [GitHub Issue Templates](https://docs.github.com/en/communities/using-templates-to-encourage-useful-issues-and-pull-requests/configuring-issue-templates-for-your-repository)
+- [Contributor Covenant](https://www.contributor-covenant.org/)
+- [Conventional Commits](https://www.conventionalcommits.org/)
+
+## Future Enhancements
+
+- GitHub Discussions setup
+- Contributor recognition system
+- Automated PR checks
+- Welcome bot for first-time contributors
+- Contributor guide video
diff --git a/.github/ISSUES/README.md b/.github/ISSUES/README.md
new file mode 100644
index 0000000..a41bdd3
--- /dev/null
+++ b/.github/ISSUES/README.md
@@ -0,0 +1,165 @@
+# WeCoded Improvement Issues
+
+This directory contains 20 improvement proposals for the WeCoded project, organized as individual markdown files.
+
+## 📋 Issue Overview
+
+### Testing & Quality Assurance (2 issues)
+1. **01-unit-tests-useFetchStories.md** - Add unit tests for useFetchStories hook
+2. **02-e2e-tests-playwright.md** - Add comprehensive E2E tests with Playwright
+
+### Performance Optimization (3 issues)
+3. **03-loading-skeleton-storycard.md** - Add loading skeleton for StoryCard component
+4. **04-bundle-optimization-code-splitting.md** - Optimize bundle size and implement code splitting
+5. **05-rate-limiting-retry-logic.md** - Implement rate limiting and error retry logic
+
+### Accessibility (3 issues)
+6. **06-keyboard-shortcuts-navigation.md** - Implement keyboard shortcuts for story navigation
+7. **07-dark-light-theme-toggle.md** - Add dark/light theme toggle
+8. **08-accessibility-audit.md** - Implement comprehensive accessibility audit fixes
+
+### New Features (7 issues)
+9. **09-story-bookmarking.md** - Implement story bookmarking/favorites feature
+10. **10-social-sharing.md** - Add social sharing functionality
+11. **11-search-filter-stories.md** - Add search and filter functionality for stories
+12. **14-achievement-badge-system.md** - Implement achievement/badge system
+13. **17-minigame-difficulty-variations.md** - Add mini-game difficulty levels and variations
+14. **18-internationalization-i18n.md** - Add internationalization (i18n) support
+15. **19-reading-progress-resume.md** - Add story reading progress indicator and resume feature
+
+### UI/UX Enhancements (1 issue)
+16. **13-animation-transitions.md** - Add animation transitions between stories
+
+### Code Architecture (2 issues)
+17. **12-error-boundary.md** - Implement proper error boundary component
+18. **15-pwa-support.md** - Add progressive web app (PWA) support
+
+### Documentation & Process (2 issues)
+19. **16-analytics-tracking.md** - Implement analytics tracking
+20. **20-contributing-guide-templates.md** - Create contributing guide and issue templates
+
+## 🚀 Creating Issues on GitHub
+
+### Option 1: Manual Creation
+
+1. Navigate to the GitHub repository
+2. Click on "Issues" → "New Issue"
+3. Copy the content from each `.md` file
+4. Paste into the issue body
+5. Extract the `title` from the frontmatter
+6. Add `labels` from the frontmatter
+7. Create the issue
+
+### Option 2: Using GitHub CLI (Recommended)
+
+If you have GitHub CLI installed and authenticated, run:
+
+```bash
+cd .github/ISSUES
+bash create-issues.sh
+```
+
+This script will automatically create all 20 issues on GitHub.
+
+### Option 3: Using the gh CLI Manually
+
+For each issue file:
+
+```bash
+gh issue create --title "Issue Title" --body-file filename.md --label "label1,label2"
+```
+
+Example:
+```bash
+gh issue create \
+  --title "Add unit tests for useFetchStories hook" \
+  --body-file 01-unit-tests-useFetchStories.md \
+  --label "testing,enhancement,good-first-issue"
+```
+
+## 📝 Issue Format
+
+Each issue file contains:
+
+- **Frontmatter** (YAML): Title and labels
+- **Description**: Overview of the improvement
+- **Background**: Why this improvement is needed
+- **Requirements**: Detailed specifications
+- **Technical Implementation**: Code examples and approach
+- **Acceptance Criteria**: Definition of done
+- **Testing Checklist**: How to verify the implementation
+- **Related Files**: Files that need to be modified
+- **Resources**: Helpful links and documentation
+
+## 🎯 Getting Started
+
+### For Maintainers
+
+1. Review each issue file
+2. Prioritize issues based on project goals
+3. Create issues on GitHub using one of the methods above
+4. Assign appropriate labels, milestones, and assignees
+5. Link related issues
+
+### For Contributors
+
+1. Browse the issue files to understand available work
+2. Once issues are created on GitHub, pick one that matches your skills
+3. Comment on the issue to express interest
+4. Follow the CONTRIBUTING.md guide (once created via issue #20)
+
+## 📊 Priority Suggestions
+
+### High Priority (Do First)
+- Testing infrastructure (issues #1, #2)
+- Accessibility audit (#8)
+- Error boundaries (#12)
+- Contributing guide (#20)
+
+### Medium Priority
+- Performance optimizations (#3, #4, #5)
+- Core features (#9, #10, #11)
+- Theme toggle (#7)
+
+### Low Priority (Nice to Have)
+- Advanced features (#14, #17, #19)
+- PWA support (#15)
+- i18n (#18)
+- Analytics (#16)
+- Animations (#13)
+
+## 🔄 Issue Dependencies
+
+Some issues have dependencies:
+
+- **#16 (Analytics)** should be after #20 (Contributing guide) to ensure privacy policy exists
+- **#14 (Achievements)** works well with #19 (Reading progress)
+- **#13 (Animations)** should respect #8 (Accessibility - reduced motion)
+- **#9 (Bookmarks)** enhances #19 (Reading progress)
+
+## 📚 Additional Resources
+
+- [WeCoded Repository](https://github.com/AndreaGriffiths11/we-coded)
+- [Next.js Documentation](https://nextjs.org/docs)
+- [React Documentation](https://react.dev)
+- [WCAG Guidelines](https://www.w3.org/WAI/WCAG21/quickref/)
+
+## 🤝 Contributing
+
+These issues were created to provide a roadmap for improving the WeCoded project. If you'd like to work on any of these:
+
+1. Wait for the issue to be created on GitHub
+2. Comment on the issue expressing your interest
+3. Get assigned to the issue
+4. Create a PR referencing the issue number
+
+## 📞 Questions?
+
+If you have questions about any of these issues:
+- Open a discussion on GitHub
+- Comment on the specific issue once created
+- Reach out to the maintainers
+
+---
+
+**Note**: These are proposals. Maintainers may modify, merge, or decline any of these issues based on project priorities and direction.
diff --git a/.github/ISSUES/SUMMARY.md b/.github/ISSUES/SUMMARY.md
new file mode 100644
index 0000000..a16e3a5
--- /dev/null
+++ b/.github/ISSUES/SUMMARY.md
@@ -0,0 +1,207 @@
+# Issue Creation Summary
+
+## 📦 What Was Created
+
+This PR adds **20 comprehensive improvement issues** for the WeCoded project, organized as individual markdown files that can be easily converted to GitHub issues.
+
+### File Structure
+```
+.github/ISSUES/
+├── README.md                                    # Overview and instructions
+├── create-issues.sh                             # Automation script
+├── SUMMARY.md                                   # This file
+├── 01-unit-tests-useFetchStories.md            # Testing
+├── 02-e2e-tests-playwright.md                  # Testing
+├── 03-loading-skeleton-storycard.md            # Performance
+├── 04-bundle-optimization-code-splitting.md    # Performance
+├── 05-rate-limiting-retry-logic.md             # Performance
+├── 06-keyboard-shortcuts-navigation.md         # Accessibility
+├── 07-dark-light-theme-toggle.md               # Accessibility
+├── 08-accessibility-audit.md                   # Accessibility
+├── 09-story-bookmarking.md                     # Feature
+├── 10-social-sharing.md                        # Feature
+├── 11-search-filter-stories.md                 # Feature
+├── 12-error-boundary.md                        # Architecture
+├── 13-animation-transitions.md                 # UI/UX
+├── 14-achievement-badge-system.md              # Feature
+├── 15-pwa-support.md                           # Architecture
+├── 16-analytics-tracking.md                    # Documentation
+├── 17-minigame-difficulty-variations.md        # Feature
+├── 18-internationalization-i18n.md             # Feature
+├── 19-reading-progress-resume.md               # Feature
+└── 20-contributing-guide-templates.md          # Documentation
+
+ISSUE_CREATION_GUIDE.md                         # Root-level guide
+```
+
+## 🎯 Issue Breakdown
+
+### By Category
+- **Testing & QA**: 2 issues (10%)
+- **Performance**: 3 issues (15%)
+- **Accessibility**: 3 issues (15%)
+- **Features**: 7 issues (35%)
+- **UI/UX**: 1 issue (5%)
+- **Architecture**: 2 issues (10%)
+- **Documentation**: 2 issues (10%)
+
+### By Priority (Suggested)
+- **High Priority**: 4 issues (#1, #2, #8, #12, #20)
+- **Medium Priority**: 8 issues (#3, #4, #5, #6, #7, #9, #10, #11)
+- **Low Priority**: 8 issues (#13, #14, #15, #16, #17, #18, #19)
+
+### By Difficulty
+- **Good First Issue**: #1, #20 (explicitly labeled)
+- **Intermediate**: #3, #4, #5, #6, #7, #9, #10, #11, #12, #13
+- **Advanced**: #2, #8, #14, #15, #16, #17, #18, #19
+
+## 📊 Statistics
+
+- **Total Files**: 23 (20 issues + 3 supporting files)
+- **Total Lines**: 5,925+ lines of documentation
+- **Average Issue Length**: ~286 lines
+- **Code Examples**: 50+ code snippets across all issues
+- **External Resources**: 40+ helpful links
+
+## ✨ What Makes These Issues High Quality
+
+Each issue includes:
+
+1. **Clear Description** - What the improvement is
+2. **Background Context** - Why it's needed
+3. **Detailed Requirements** - Specific features to implement
+4. **Technical Implementation** - Code examples and architecture
+5. **Acceptance Criteria** - Clear definition of done
+6. **Testing Checklist** - How to verify it works
+7. **Related Files** - What needs to change
+8. **Resources** - Links to docs and examples
+9. **Future Enhancements** - Ideas for iteration
+
+## 🚀 How to Use
+
+### For Repository Maintainers
+
+1. **Review the issues** in `.github/ISSUES/`
+2. **Prioritize** based on your roadmap
+3. **Create on GitHub** using one of three methods:
+   - Run `cd .github/ISSUES && bash create-issues.sh` (automated)
+   - Use `gh issue create` for each file (selective)
+   - Copy/paste into GitHub web UI (manual)
+4. **Organize** with labels, milestones, and project boards
+5. **Share** with potential contributors
+
+### For Contributors
+
+1. Wait for issues to be created on GitHub
+2. Browse available issues
+3. Look for `good-first-issue` label if you're new
+4. Comment to express interest
+5. Get assigned and start working
+
+## 📈 Expected Impact
+
+Implementing these issues would:
+
+- ✅ Add comprehensive test coverage (unit + E2E)
+- ✅ Improve performance (bundle size, loading states, caching)
+- ✅ Achieve WCAG 2.1 AA accessibility compliance
+- ✅ Add 7+ major features (bookmarks, sharing, search, achievements, etc.)
+- ✅ Enable offline support (PWA)
+- ✅ Support global audience (i18n)
+- ✅ Establish contribution guidelines
+- ✅ Enhance user engagement and retention
+
+## 🔗 Dependencies
+
+Some issues depend on others:
+
+```
+#20 (Contributing Guide)
+  └─> #16 (Analytics) - needs privacy policy
+
+#19 (Reading Progress)
+  ├─> #9 (Bookmarks) - complements nicely
+  └─> #14 (Achievements) - can integrate
+
+#8 (Accessibility Audit)
+  └─> #13 (Animations) - must respect reduced motion
+
+#2 (E2E Tests)
+  └─> All features - should test new features
+```
+
+## 💡 Implementation Suggestions
+
+### Sprint 1: Foundation (High Priority)
+- #1: Unit tests
+- #8: Accessibility audit
+- #12: Error boundaries
+- #20: Contributing guide
+
+### Sprint 2: Performance & Core Features
+- #3: Loading skeleton
+- #4: Bundle optimization
+- #5: Rate limiting
+- #9: Bookmarks
+- #10: Social sharing
+
+### Sprint 3: Enhanced Features
+- #6: Keyboard shortcuts
+- #7: Theme toggle
+- #11: Search/filter
+- #19: Reading progress
+
+### Sprint 4: Advanced Features
+- #2: E2E tests
+- #14: Achievements
+- #15: PWA
+- #17: Mini-game enhancements
+
+### Sprint 5: Global & Analytics
+- #16: Analytics
+- #18: Internationalization
+
+## 🎓 Learning Opportunities
+
+These issues cover a wide range of technologies:
+
+- **Testing**: Jest, React Testing Library, Playwright
+- **Performance**: Bundle analysis, code splitting, caching
+- **Accessibility**: WCAG, ARIA, screen readers
+- **State Management**: localStorage, React hooks
+- **APIs**: DEV.to API, Web Share API, Service Workers
+- **Internationalization**: next-intl, locale handling
+- **PWA**: Service workers, manifest, caching strategies
+- **Animation**: Framer Motion, CSS animations
+- **TypeScript**: Type definitions, interfaces
+
+## 📝 Notes for Maintainers
+
+- Issues are numbered 01-20 for easy reference
+- All include YAML frontmatter for GitHub
+- Labels follow common conventions
+- Each issue is standalone and can be worked on independently
+- Code examples use the project's actual structure
+- All respect the Next.js 15 + TypeScript stack
+
+## 🙏 Acknowledgments
+
+These issues were created by thoroughly analyzing:
+- The current codebase structure
+- Next.js 15 best practices
+- Accessibility guidelines (WCAG 2.1 AA)
+- PWA specifications
+- Modern React patterns
+- Performance optimization techniques
+- UX best practices for gamification
+
+## 📞 Questions?
+
+See the main README or ISSUE_CREATION_GUIDE.md for detailed instructions.
+
+---
+
+**Created**: January 2026  
+**Format**: Markdown with YAML frontmatter  
+**Total Issues**: 20  
+**Ready to Deploy**: ✅ Yes
diff --git a/.github/ISSUES/create-issues.sh b/.github/ISSUES/create-issues.sh
new file mode 100755
index 0000000..3629216
--- /dev/null
+++ b/.github/ISSUES/create-issues.sh
@@ -0,0 +1,132 @@
+#!/bin/bash
+
+# Script to create GitHub issues from markdown files
+# Requires: gh CLI (GitHub CLI) to be installed and authenticated
+
+set -e
+
+# Colors for output
+GREEN='\033[0;32m'
+BLUE='\033[0;34m'
+RED='\033[0;31m'
+NC='\033[0m' # No Color
+
+echo -e "${BLUE}================================================${NC}"
+echo -e "${BLUE}  WeCoded - Creating GitHub Issues${NC}"
+echo -e "${BLUE}================================================${NC}"
+echo ""
+
+# Check if gh CLI is installed
+if ! command -v gh &> /dev/null; then
+    echo -e "${RED}Error: GitHub CLI (gh) is not installed.${NC}"
+    echo "Please install it from: https://cli.github.com/"
+    exit 1
+fi
+
+# Check if authenticated
+if ! gh auth status &> /dev/null; then
+    echo -e "${RED}Error: Not authenticated with GitHub CLI.${NC}"
+    echo "Please run: gh auth login"
+    exit 1
+fi
+
+echo -e "${GREEN}✓ GitHub CLI is installed and authenticated${NC}"
+echo ""
+
+# Function to extract title from frontmatter
+get_title() {
+    local file=$1
+    grep "^title:" "$file" | sed 's/title: //' | tr -d "'"
+}
+
+# Function to extract labels from frontmatter
+get_labels() {
+    local file=$1
+    grep "^labels:" "$file" | sed 's/labels: //'
+}
+
+# Function to create issue from file
+create_issue() {
+    local file=$1
+    local number=$(basename "$file" | cut -d'-' -f1)
+    
+    echo -e "${BLUE}Creating issue from: $file${NC}"
+    
+    # Extract metadata
+    local title=$(get_title "$file")
+    local labels=$(get_labels "$file")
+    
+    # Remove frontmatter for body (everything between --- markers)
+    local body=$(sed '1,/^---$/d' "$file" | sed '1,/^---$/d')
+    
+    if [ -z "$title" ]; then
+        echo -e "${RED}  ✗ Could not extract title from $file${NC}"
+        return 1
+    fi
+    
+    echo "  Title: $title"
+    echo "  Labels: $labels"
+    
+    # Create issue
+    if echo "$body" | gh issue create --title "$title" --body-file - --label "$labels" > /dev/null; then
+        echo -e "${GREEN}  ✓ Issue created successfully${NC}"
+    else
+        echo -e "${RED}  ✗ Failed to create issue${NC}"
+        return 1
+    fi
+    
+    echo ""
+}
+
+# Get all issue files sorted by number
+issue_files=$(ls -1 [0-9][0-9]-*.md 2>/dev/null | sort)
+
+if [ -z "$issue_files" ]; then
+    echo -e "${RED}No issue files found in current directory.${NC}"
+    echo "Please run this script from the .github/ISSUES directory."
+    exit 1
+fi
+
+# Count total issues
+total=$(echo "$issue_files" | wc -l)
+echo -e "Found ${GREEN}$total${NC} issue files to process"
+echo ""
+
+# Ask for confirmation
+read -p "Do you want to create all $total issues? (y/n) " -n 1 -r
+echo ""
+
+if [[ ! $REPLY =~ ^[Yy]$ ]]; then
+    echo "Cancelled."
+    exit 0
+fi
+
+echo ""
+echo -e "${BLUE}Creating issues...${NC}"
+echo ""
+
+# Counter for created issues
+created=0
+failed=0
+
+# Create each issue
+for file in $issue_files; do
+    if create_issue "$file"; then
+        ((created++))
+    else
+        ((failed++))
+    fi
+    
+    # Add a small delay to avoid rate limiting
+    sleep 1
+done
+
+echo -e "${BLUE}================================================${NC}"
+echo -e "${GREEN}✓ Successfully created: $created issues${NC}"
+if [ $failed -gt 0 ]; then
+    echo -e "${RED}✗ Failed to create: $failed issues${NC}"
+fi
+echo -e "${BLUE}================================================${NC}"
+echo ""
+echo "View all issues at:"
+echo "$(gh repo view --json url -q .url)/issues"
diff --git a/ISSUE_CREATION_GUIDE.md b/ISSUE_CREATION_GUIDE.md
new file mode 100644
index 0000000..e94e369
--- /dev/null
+++ b/ISSUE_CREATION_GUIDE.md
@@ -0,0 +1,186 @@
+# How to Create GitHub Issues from Templates
+
+This repository contains 20 detailed improvement issue templates in the `.github/ISSUES/` directory. Here's how to create them as actual GitHub issues.
+
+## Quick Start
+
+### Prerequisites
+
+1. **GitHub CLI** installed and authenticated
+   ```bash
+   # Check if installed
+   gh --version
+   
+   # If not installed, visit: https://cli.github.com/
+   
+   # Authenticate
+   gh auth login
+   ```
+
+2. Navigate to the issues directory:
+   ```bash
+   cd .github/ISSUES
+   ```
+
+## Method 1: Automated Script (Recommended)
+
+Run the provided script to create all 20 issues automatically:
+
+```bash
+bash create-issues.sh
+```
+
+The script will:
+- ✅ Verify GitHub CLI is installed and authenticated
+- ✅ Extract title and labels from each file
+- ✅ Create issues in the correct order
+- ✅ Add a 1-second delay between issues to avoid rate limiting
+- ✅ Show progress and success/failure status
+
+**Example output:**
+```
+================================================
+  WeCoded - Creating GitHub Issues
+================================================
+
+✓ GitHub CLI is installed and authenticated
+
+Found 20 issue files to process
+
+Do you want to create all 20 issues? (y/n) y
+
+Creating issues...
+
+Creating issue from: 01-unit-tests-useFetchStories.md
+  Title: Add unit tests for useFetchStories hook
+  Labels: testing, enhancement, good-first-issue
+  ✓ Issue created successfully
+
+...
+
+================================================
+✓ Successfully created: 20 issues
+================================================
+```
+
+## Method 2: Manual Creation (One at a Time)
+
+If you prefer to create issues individually or selectively:
+
+```bash
+# Format:
+gh issue create --title "TITLE" --body-file FILENAME.md --label "LABELS"
+
+# Example for first issue:
+gh issue create \
+  --title "Add unit tests for useFetchStories hook" \
+  --body-file 01-unit-tests-useFetchStories.md \
+  --label "testing,enhancement,good-first-issue"
+```
+
+### Create Specific Issues
+
+To create only certain issues:
+
+```bash
+# Just testing issues (#1 and #2)
+gh issue create --title "Add unit tests for useFetchStories hook" \
+  --body-file 01-unit-tests-useFetchStories.md \
+  --label "testing,enhancement,good-first-issue"
+
+gh issue create --title "Add comprehensive E2E tests with Playwright" \
+  --body-file 02-e2e-tests-playwright.md \
+  --label "testing,enhancement,infrastructure"
+
+# Just accessibility issues (#6, #7, #8)
+gh issue create --title "Implement keyboard shortcuts for story navigation" \
+  --body-file 06-keyboard-shortcuts-navigation.md \
+  --label "enhancement,accessibility,a11y"
+
+gh issue create --title "Add dark/light theme toggle" \
+  --body-file 07-dark-light-theme-toggle.md \
+  --label "enhancement,accessibility,ui/ux,a11y"
+
+gh issue create --title "Implement comprehensive accessibility audit fixes" \
+  --body-file 08-accessibility-audit.md \
+  --label "accessibility,a11y,enhancement,bug"
+```
+
+## Method 3: Via GitHub Web Interface
+
+If you can't use GitHub CLI:
+
+1. Go to your repository on GitHub
+2. Click the **Issues** tab
+3. Click **New Issue**
+4. Open one of the markdown files (e.g., `01-unit-tests-useFetchStories.md`)
+5. Copy everything **after** the frontmatter (after the second `---`)
+6. Paste into the issue body
+7. Add the title from the frontmatter
+8. Add labels from the frontmatter
+9. Click **Submit new issue**
+
+## Verification
+
+After creating issues, verify they were created successfully:
+
+```bash
+# List all issues
+gh issue list
+
+# List issues with specific label
+gh issue list --label "testing"
+gh issue list --label "enhancement"
+gh issue list --label "accessibility"
+
+# View a specific issue
+gh issue view 1
+```
+
+## Troubleshooting
+
+### "gh: command not found"
+Install GitHub CLI from https://cli.github.com/
+
+### "Not authenticated"
+Run `gh auth login` and follow the prompts
+
+### "API rate limit exceeded"
+Wait a few minutes, or create issues more slowly
+
+### "Permission denied"
+Ensure you have write access to the repository
+
+### Script doesn't execute
+Make it executable: `chmod +x create-issues.sh`
+
+## Next Steps
+
+After creating issues:
+
+1. **Review and prioritize** - Some issues have dependencies
+2. **Assign labels and milestones** - Organize by priority/sprint
+3. **Add to project board** - Track progress visually
+4. **Link related issues** - Use "Related to #X" or "Depends on #Y"
+5. **Invite contributors** - Share issues labeled `good-first-issue`
+
+## Issue Categories Summary
+
+- 🧪 **Testing** (2 issues): #1, #2
+- ⚡ **Performance** (3 issues): #3, #4, #5
+- ♿ **Accessibility** (3 issues): #6, #7, #8
+- ✨ **Features** (7 issues): #9, #10, #11, #14, #17, #18, #19
+- 🎨 **UI/UX** (1 issue): #13
+- 🏗️ **Architecture** (2 issues): #12, #15
+- 📚 **Documentation** (2 issues): #16, #20
+
+## Support
+
+If you encounter any issues with the templates or script:
+- Check the README.md in `.github/ISSUES/`
+- Open a discussion on GitHub
+- Contact the repository maintainers
+
+---
+
+**Happy issue creating! 🎉**