diff --git a/.github/GITHUB_AUTH_SETUP.md b/.github/GITHUB_AUTH_SETUP.md
new file mode 100644
index 0000000..19d6946
--- /dev/null
+++ b/.github/GITHUB_AUTH_SETUP.md
@@ -0,0 +1,171 @@
+# GitHub Authentication Setup Guide
+
+This guide helps you set up authentication for GitHub CLI and the mcp_github tools.
+
+## Current Status ✅
+
+Your system is already configured with:
+- **GitHub CLI**: v2.52.0 installed
+- **Primary Account**: `ericthayer` (Active & Authenticated)
+- **Token Scopes**: gist, read:org, repo, workflow
+- **Protocol**: HTTPS
+- **Storage**: Keyring (secure credential storage)
+
+## Option 1: Use GitHub CLI for PR Creation (Recommended)
+
+### Create PR with `gh` CLI
+
+Use your terminal to create the PR directly:
+
+```bash
+cd /Users/thayere/Documents/_DEV/devlog
+
+# Create PR using the pr-template-commits.md file
+gh pr create \
+  --title "perf: Restructure project, add AI guidance system, and testing infrastructure" \
+  --body "$(cat .github/pr-template-commits.md)" \
+  --base main \
+  --head feat/update-logic
+```
+
+**Or interactively:**
+
+```bash
+gh pr create --base main --head feat/update-logic
+```
+
+The interactive mode will prompt you for:
+- Title (auto-fill from commit suggested)
+- Body (open editor)
+- Additional options
+
+### Verify PR Creation
+
+```bash
+# List your open PRs
+gh pr list --state open
+
+# View specific PR
+gh pr view <pr-number>
+```
+
+## Option 2: Configure GitHub Token for mcp_github Tools
+
+The mcp_github tools require a GitHub personal access token (PAT) via environment variable.
+
+### Step 1: Generate a Personal Access Token
+
+1. Go to: https://github.com/settings/tokens/new
+2. Fill in:
+   - **Token name**: `devlog-mcp`
+   - **Expiration**: 90 days (or your preference)
+   - **Scopes**: Select these:
+     - ✅ `repo` (full control of private repositories)
+     - ✅ `workflow` (manage GitHub Actions workflows)
+     - ✅ `read:org` (read access to organization)
+     - ✅ `gist` (create and manage gists)
+
+3. Click **Generate token**
+4. Copy the token (starts with `ghp_` or `gho_`)
+
+### Step 2: Configure Environment Variable
+
+Add the token to your `.env` file:
+
+```bash
+# In /Users/thayere/Documents/_DEV/devlog/.env
+GITHUB_TOKEN=ghp_xxxxxxxxxxxxxxxxxxxxxxxxxxxx
+```
+
+Or set it in your shell:
+
+```bash
+# Bash/Zsh
+export GITHUB_TOKEN=ghp_xxxxxxxxxxxxxxxxxxxxxxxxxxxx
+
+# Add to ~/.zshrc for persistence
+echo 'export GITHUB_TOKEN=ghp_xxxxxxxxxxxxxxxxxxxxxxxxxxxx' >> ~/.zshrc
+source ~/.zshrc
+```
+
+### Step 3: Verify Token
+
+```bash
+# Test with curl
+curl -H "Authorization: token $GITHUB_TOKEN" https://api.github.com/user
+```
+
+Should return your GitHub user information.
+
+## Option 3: Re-authenticate if Needed
+
+If your token expires or you need to update:
+
+```bash
+# Re-authenticate with GitHub CLI
+gh auth login -h github.com
+
+# You'll be prompted to choose:
+# - Protocol: HTTPS
+# - Authentication: Paste your token
+# - Set as default account: Yes
+
+# Verify new authentication
+gh auth status
+```
+
+## Troubleshooting
+
+### "404 Not Found" Error
+- **Cause**: Repository doesn't exist at specified owner/repo
+- **Fix**: Verify you're using the correct owner (`ericthayer`) and repo (`devlog`)
+
+### "403 Unauthorized" Error
+- **Cause**: Token lacks required scopes or is invalid
+- **Fix**: Generate new PAT with `repo`, `workflow`, `read:org` scopes
+
+### Token Not Found
+- **Cause**: `GITHUB_TOKEN` environment variable not set
+- **Fix**: Add token to `.env` or shell profile
+
+### Multiple Accounts
+You have multiple accounts configured. To use specific account:
+
+```bash
+# Switch active account
+gh auth select
+# or
+gh auth switch -u ericthayer
+```
+
+## Security Best Practices
+
+1. **Never commit tokens** - `.env` is in `.gitignore`
+2. **Use keyring storage** - GitHub CLI stores tokens securely
+3. **Set expiration** - PATs should expire in 30-90 days
+4. **Rotate regularly** - Delete old tokens from Settings
+5. **Minimal scopes** - Only grant required permissions
+
+## Files Created
+
+- `.github/pr-template-commits.md` - PR description template (can be copied to GitHub)
+- `.github/GITHUB_AUTH_SETUP.md` - This authentication guide
+
+## Quick Reference
+
+| Task | Command |
+|------|---------|
+| Check auth status | `gh auth status` |
+| Create PR | `gh pr create --base main --head feat/update-logic` |
+| List PRs | `gh pr list --state open` |
+| View PR | `gh pr view <number>` |
+| Re-auth | `gh auth login -h github.com` |
+| Export token | `echo $GITHUB_TOKEN` |
+
+## Next Steps
+
+1. ✅ GitHub CLI already authenticated as `ericthayer`
+2. 🔄 Option A: Create PR with `gh pr create` (easiest)
+3. 🔄 Option B: Generate PAT and set `GITHUB_TOKEN` for mcp_github tools
+
+Both options will work - choose based on your preference!
diff --git a/.github/README.md b/.github/README.md
new file mode 100644
index 0000000..a84a792
--- /dev/null
+++ b/.github/README.md
@@ -0,0 +1,328 @@
+# DevLog AI Guidance System
+
+This directory contains a comprehensive framework for AI-assisted development, ensuring consistency, quality, and adherence to best practices across the project.
+
+## 📁 Directory Structure
+
+```
+.github/
+├── README.md                    # This file
+├── copilot-instructions.md      # Main AI architecture guide
+├── GITHUB_AUTH_SETUP.md         # GitHub authentication setup
+├── pr-template-commits.md       # PR description template
+├── instructions/                # Scope-specific guidelines
+│   ├── development-standards.instructions.md
+│   ├── web-interface-guidelines.instructions.md
+│   ├── github-issue.instructions.md
+│   ├── github-release-notes.instructions.md
+│   └── storybook.instructions.md
+├── rules/                       # Architectural principles
+│   ├── accessibility.md
+│   ├── component-architecture.md
+│   ├── react-19-compiler.md
+│   ├── spec-driven-development.md
+│   ├── supabase.md
+│   ├── tailwind-v4.md
+│   ├── three-js-react.md
+│   └── web-performance.md
+├── skills/                      # Executable workflows
+│   ├── accessibility_audit/
+│   ├── scaffold_component/
+│   ├── vercel-react-best-practices/
+│   └── workflows/
+└── prompts/                     # Agent prompt templates
+    └── create-pr.prompt.md
+```
+
+## 🎯 Three-Layer Framework
+
+### Layer 1: Instructions (Scope-Specific)
+
+Files in `instructions/` apply to specific file types or contexts using frontmatter:
+
+```yaml
+---
+applyTo: '**/*.tsx'
+---
+```
+
+**When these apply:**
+- Automatically loaded by AI when working with matching files
+- Referenced in code reviews for specific file types
+- Used to enforce patterns on particular scopes
+
+**Key files:**
+- `development-standards.instructions.md` - TypeScript/React standards, Airbnb style, APCA contrast
+- `web-interface-guidelines.instructions.md` - MUST/SHOULD/NEVER UI rules, accessibility (24px targets, keyboard)
+- `github-issue.instructions.md` - Issue template and format
+- `github-release-notes.instructions.md` - Release notes structure
+- `storybook.instructions.md` - Storybook usage patterns
+
+### Layer 2: Rules (Architectural Principles)
+
+Files in `rules/` define non-negotiable architectural patterns:
+
+**When to reference:**
+- Making architectural decisions
+- Designing new features
+- Reviewing code structure
+- Setting up infrastructure
+
+**Key files:**
+- `component-architecture.md` - Folder-per-component with named exports
+- `spec-driven-development.md` - Create SPEC.md before coding ("Zero Vibe Rule")
+- `supabase.md` - Database, auth, RLS, storage best practices
+- `accessibility.md` - WCAG compliance requirements
+- `react-19-compiler.md` - React 19 optimization patterns
+- `web-performance.md` - Performance optimization guidelines
+
+### Layer 3: Skills (Executable Workflows)
+
+Files in `skills/` provide step-by-step workflows:
+
+**When to use:**
+- Creating new components
+- Running audits
+- Following complex procedures
+- Applying best practice patterns
+
+**Key skills:**
+
+#### `scaffold_component/`
+Component creation workflow with SDD:
+1. Create SPEC.md with requirements
+2. Generate component structure
+3. Implement with tests
+4. Document in Storybook
+
+#### `accessibility_audit/`
+Comprehensive accessibility testing:
+- Keyboard navigation check
+- Screen reader compatibility
+- Color contrast validation
+- ARIA attributes review
+
+#### `vercel-react-best-practices/`
+45 performance rules across 8 categories:
+- **Async** (7 rules) - API routes, dependencies, parallel fetching, suspense
+- **Bundle** (6 rules) - Dynamic imports, barrel imports, tree shaking
+- **Client** (4 rules) - Event listeners, localStorage, SWR dedup
+- **JS** (11 rules) - Caching, batching, early exits
+- **Rendering** (8 rules) - SVG, hydration, transitions
+- **Re-render** (10 rules) - Memo, derived state, lazy init
+- **Server** (7 rules) - Auth, caching, serialization
+
+## 🚀 How to Use This System
+
+### For Developers
+
+#### Starting a New Feature
+
+1. **Check Instructions**
+   - Read relevant `instructions/` files for your file types
+   - Example: Building a component? Read `web-interface-guidelines.instructions.md`
+
+2. **Review Rules**
+   - Understand architectural constraints
+   - Example: New component? Follow `component-architecture.md` folder structure
+
+3. **Follow Skills**
+   - Use workflow templates
+   - Example: Run `scaffold_component/` to create proper structure
+
+4. **Reference in PRs**
+   - Cite specific rules when reviewing
+   - Link to guidance files in comments
+
+#### Making Changes
+
+```bash
+# Before coding a component
+cat .github/rules/component-architecture.md
+cat .github/instructions/web-interface-guidelines.instructions.md
+
+# During development
+# Follow patterns in .github/skills/scaffold_component/
+
+# Before PR
+cat .github/pr-template-commits.md
+```
+
+### For AI Assistants
+
+The guidance system is automatically integrated into AI tools:
+
+**GitHub Copilot:**
+- Reads `copilot-instructions.md` for architecture
+- Applies `instructions/` files based on `applyTo` patterns
+- References `rules/` for decision-making
+
+**Creating Features:**
+1. Read relevant `instructions/` and `rules/`
+2. Generate code following patterns
+3. Reference `skills/` for workflows
+4. Use `prompts/` for common tasks
+
+### Common Workflows
+
+#### Creating a New Component
+
+```bash
+# 1. Review guidance
+cat .github/rules/component-architecture.md
+cat .github/rules/spec-driven-development.md
+
+# 2. Create SPEC.md first (SDD)
+# Document requirements, props, behavior
+
+# 3. Scaffold component following folder pattern
+mkdir src/components/MyComponent
+touch src/components/MyComponent/{MyComponent.tsx,index.ts,SPEC.md}
+
+# 4. Implement with accessibility in mind
+cat .github/instructions/web-interface-guidelines.instructions.md
+```
+
+#### Running an Accessibility Audit
+
+```bash
+# Follow the checklist
+cat .github/skills/accessibility_audit/SKILL.md
+
+# Check key requirements:
+# - 24px × 24px minimum hit targets
+# - APCA contrast ≥60 (normal) / ≥45 (large)
+# - Keyboard navigation functional
+# - Screen reader labels present
+```
+
+#### Optimizing Performance
+
+```bash
+# Review best practices
+cat .github/skills/vercel-react-best-practices/SKILL.md
+
+# Check specific patterns
+cat .github/skills/vercel-react-best-practices/rules/rerender-memo.md
+cat .github/skills/vercel-react-best-practices/rules/bundle-dynamic-imports.md
+```
+
+## 📖 Key Concepts
+
+### Spec-Driven Development (SDD)
+
+From `rules/spec-driven-development.md`:
+
+> Create SPEC.md BEFORE writing code. No exceptions.
+
+**The "Zero Vibe Rule":** If you're coding based on vibes, stop and write the spec.
+
+**Template:**
+```markdown
+# Component/Feature Name
+
+## Purpose
+[Why this exists]
+
+## Requirements
+- [ ] Requirement 1
+- [ ] Requirement 2
+
+## API/Props
+[Interface definition]
+
+## Behavior
+[How it works]
+
+## Changelog
+[Track changes to spec during implementation]
+```
+
+### Folder-per-Component
+
+From `rules/component-architecture.md`:
+
+```
+src/components/MyComponent/
+├── MyComponent.tsx       # Implementation
+├── MyComponent.test.tsx  # Tests
+├── index.ts             # export { MyComponent } from './MyComponent'
+└── SPEC.md              # Specification
+```
+
+**Why:** Encapsulation, discoverability, and maintainability.
+
+### Accessibility First
+
+From `instructions/web-interface-guidelines.instructions.md`:
+
+**MUST:**
+- Hit targets ≥24px × 24px
+- APCA contrast ≥60 (normal text)
+- Full keyboard navigation
+- Proper ARIA labels
+
+**SHOULD:**
+- Focus indicators visible
+- Skip links for navigation
+- Semantic HTML
+
+## 🔄 Updating the Guidance System
+
+### When to Update
+
+- **New patterns emerge** → Add to `rules/`
+- **Common mistakes** → Add to `instructions/`
+- **Repeated workflows** → Create in `skills/`
+- **File type standards** → Update `instructions/` `applyTo` patterns
+
+### How to Update
+
+1. **Create/edit file** in appropriate directory
+2. **Test with AI** to verify it's followed correctly
+3. **Document in this README** if structural change
+4. **Update `copilot-instructions.md`** if architecture changes
+5. **Commit with `docs:` prefix**
+
+### File Naming
+
+- **Instructions:** `topic.instructions.md`
+- **Rules:** `topic.md`
+- **Skills:** `skill-name/SKILL.md`
+- **Prompts:** `action-name.prompt.md`
+
+## 🛠️ Utilities
+
+### GitHub Authentication
+See [GITHUB_AUTH_SETUP.md](GITHUB_AUTH_SETUP.md) for:
+- GitHub CLI setup
+- Personal access token generation
+- mcp_github tools configuration
+
+### PR Templates
+Use [pr-template-commits.md](pr-template-commits.md) for consistent PR descriptions.
+
+### Prompts
+Reusable AI prompts in `prompts/`:
+- `create-pr.prompt.md` - Automated PR creation from commits
+
+## 📚 Additional Resources
+
+- **[copilot-instructions.md](copilot-instructions.md)** - Complete architecture guide for AI
+- **[CONTRIBUTING.md](../CONTRIBUTING.md)** - Developer contribution guide
+- **[AGENTS.md](../AGENTS.md)** - AI agent-specific guidelines
+- **[README.md](../README.md)** - Project overview
+
+## 💡 Philosophy
+
+This guidance system embodies:
+
+1. **Explicit over Implicit** - Written standards beat tribal knowledge
+2. **Automation over Documentation** - Executable workflows beat manuals
+3. **Consistency over Cleverness** - Predictable patterns beat one-off solutions
+4. **Accessibility First** - Inclusive design is not optional
+5. **Performance by Default** - Optimization patterns built-in
+
+---
+
+**Questions?** See [CONTRIBUTING.md](../CONTRIBUTING.md) or open a discussion.
diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md
new file mode 100644
index 0000000..20a1344
--- /dev/null
+++ b/.github/copilot-instructions.md
@@ -0,0 +1,200 @@
+# Copilot Instructions - DevLog (Brutalist Case Study Engine)
+
+## Project Overview
+A React + TypeScript app for generating UX/FE case studies from design artifacts using Gemini AI. Brutalist UI aesthetic with yellow/black theme. Now includes role-based authentication (publisher/reader).
+
+**IMPORTANT!** Before you start a task, or make a new change, follow these _rules_:
+
+- DO NOT change the visual design, theme styling, or composition of the UI once a `checkpoint`, and/or a component or pattern has been established. 
+
+- DO NOT revert any "styling" (CSS/Layout) or "scripting" (TS/JSX) change intentionally made by me.
+
+- DO NOT make changes outside the scope of the requested feature, i.e., don't modify the main navigation when asked to build a data table.
+
+- ALWAYS break out code into reusable components ready for export via ES module
+
+## Development Guidelines - Standards and Best Practices
+Refer to the `.github/instructions/development-standards.instructions.md` file for detailed coding standards and best practices.
+
+## Agent Instructions
+When contributing to the DevLog application with AI chat agents, please adhere to the following guidelines: `./AGENTS.md`
+
+## Architecture & Data Flow
+
+### Authentication & Authorization
+- **Roles**: `publisher` (full CRUD) and `reader` (read-only published content)
+- **Sign-up Flow**: New users default to `reader` role; can request publisher access
+- **Publisher Requests**: Tracked in `user_roles.publisher_requested` column for admin approval
+- **OAuth Support**: Google and GitHub providers enabled via Supabase Auth
+- **Auth Pattern**: App checks `user` from context, shows [LoginView](src/components/LoginView.tsx) if not authenticated
+- **Permission Checks**: Pass `canEdit` (bool) down to components based on `user.role === 'publisher'`
+
+### Three-Layer Data System
+1. **Supabase (Primary)**: PostgreSQL database + Storage bucket for production data
+2. **LocalStorage (Secondary)**: Browser persistence fallback (`devsigner_data_v3` key)
+3. **Demo Data**: Default content in `src/utils/demoData.ts` if no data exists
+
+**Critical Pattern**: [App.tsx](src/App.tsx#L52-L88) loads Supabase first, then overlays localStorage synchronously (they race). DB write operations in `src/services/dbService.ts` handle BOTH database records AND storage uploads.
+
+### Authentication & Authorization
+- **AuthContext**: [contexts/AuthContext.tsx](src/contexts/AuthContext.tsx) manages auth state with Supabase Auth
+- **Roles**: `publisher` (full CRUD) and `reader` (read-only published content)
+- **User Roles Table**: Links `auth.users` to roles in `user_roles` table
+- **RLS Policies**: Database-level permissions enforce role-based access (see [supabase/migrations/001_auth_and_rls.sql](supabase/migrations/001_auth_and_rls.sql))
+
+**Auth Pattern**: App checks `user` from context, shows [LoginView](src/components/LoginView.tsx) if not authenticated. Pass `canEdit` (bool) down to components based on `user.role === 'publisher'`.
+
+### Database Schema Mapping
+**Frontend (camelCase) ↔ Database (snake_case)**:
+- `nextSteps` ↔ `next_steps`
+- `seoMetadata` ↔ `seo_metadata`
+- `originalName` ↔ `original_name`
+- `aiName` ↔ `ai_name`
+- `date` ↔ `created_at`
+
+Assets use `case_study_id` foreign key. Always map in both directions (see [App.tsx](src/App.tsx#L56-L73) and [dbService.ts](src/services/dbService.ts#L99-L101)).
+
+## AI-Powered Workflows
+
+### Asset Analysis
+Files uploaded trigger two-phase AI analysis via [geminiService.ts](src/services/geminiService.ts):
+1. **analyzeAsset**: Extracts metadata for naming convention `[topic]-[type]-[context]-[variant]-[version].[ext]`
+2. **generateCaseStudy**: Synthesizes all assets into structured case study
+
+**Models Used**:
+- `gemini-2.5-flash`: With thinking mode (set `thinkingBudget` + `maxOutputTokens` together)
+- `gemini-2.0-flash`: Faster, no thinking mode
+
+All Gemini calls use typed JSON schemas via `responseSchema` parameter.
+
+### Storage Upload Pattern
+[dbService.ts](src/services/dbService.ts#L54-L78) converts blob URLs to Supabase Storage:
+```typescript
+if (assetUrl.startsWith('blob:')) {
+  const blob = await fetch(assetUrl).then(r => r.blob());
+  await supabase.storage.from('assets').upload(`${newId}/${asset.aiName}`, blob, { upsert: true });
+  assetUrl = supabase.storage.from('assets').getPublicUrl(filePath).data.publicUrl;
+}
+```
+
+## Error Handling Patterns
+
+### Toast Notifications
+[Toast](src/components/Toast.tsx) component displays error messages. Usage pattern in [App.tsx](src/App.tsx):
+```typescript
+const [errorMessage, setErrorMessage] = useState<string | null>(null);
+
+// Show error
+setErrorMessage(`Failed to save: ${error.message}`);
+
+// Toast auto-dismisses or user closes
+{errorMessage && <Toast message={errorMessage} onClose={() => setErrorMessage(null)} type="error" />}
+```
+
+### Try-Catch Patterns
+- **AI Operations**: Catch and retry without thinking mode if thinking fails ([geminiService.ts](src/services/geminiService.ts#L64-L68))
+- **Database Operations**: Catch, log, show toast, but don't block UI ([App.tsx](src/App.tsx#L284-L290))
+- **File Processing**: Return `null` for failed files, continue processing others ([App.tsx](src/App.tsx#L164-L167))
+
+### Optimistic Updates
+Save operations update UI immediately, then sync to database. If DB fails, show error but keep optimistic UI state ([App.tsx](src/App.tsx#L337-L345)).
+
+## Environment Variables
+Required in `.env`:
+- `VITE_API_KEY`: Google Gemini API key
+- `VITE_SUPABASE_URL`: Supabase project URL
+- `VITE_SUPABASE_ANON_KEY`: Public anon key (client-side safe)
+
+## Development Commands
+- `npm run dev`: Vite dev server on port 3000
+- `npm run build`: TypeScript compile + Vite build
+- `npm test`: Run Vitest tests
+- `npm run test:ui`: Interactive test UI
+- `npm run test:coverage`: Test coverage report
+
+## Testing Strategy
+
+### Test Files Location
+Tests in `src/tests/` directory. Name tests `*.test.tsx` or `*.test.ts`.
+
+### Testing Libraries
+- **Vitest**: Test runner (Jest-compatible API)
+- **React Testing Library**: Component testing
+- **@testing-library/jest-dom**: Custom matchers
+
+### Running Tests
+```bash
+npm test              # Watch mode
+npm run test:ui       # Interactive UI
+npm run test:coverage # Coverage report
+```
+
+### Example Test Pattern
+See [src/tests/BrutalistButton.test.tsx](src/tests/BrutalistButton.test.tsx) for component testing and [src/tests/geminiService.test.ts](src/tests/geminiService.test.ts) for service mocking.
+
+## Key Conventions
+
+### File Uploads
+- ZIP files auto-extract (filters by `SUPPORTED_UNPACK_EXTENSIONS` in [App.tsx](src/App.tsx#L27))
+- Files >30MB skip blob URL creation to prevent browser memory issues
+- Auto-rename controlled by `preferences.autoRename` (calls Gemini on every file)
+
+### Component Structure
+- **Views**: Full-screen pages (TimelineView, EditorView, ArticleView, SettingsView, LoginView)
+- **Modal Components**: ProcessingModal, ManualAssetModal, Toast
+- **Contexts**: AuthContext for authentication state
+- All use `lucide-react` icons, Tailwind + brutalist yellow/black theme
+
+### State Management
+Single root state in [App.tsx](src/App.tsx) - no Redux/Context except AuthContext. Pass callbacks down for mutations.
+
+### Permission Checks
+Check `canEdit` (derived from `user.role === 'publisher'`) before showing create/edit/delete UI. Readers can only view published case studies.
+
+## Supabase Configuration
+
+### Authentication Setup
+1. Enable email auth + OAuth (Google, GitHub) in Supabase Dashboard
+2. Run migration: [supabase/migrations/001_auth_and_rls.sql](supabase/migrations/001_auth_and_rls.sql)
+3. Creates `user_roles` table with publisher/reader roles + `publisher_requested` flag
+4. Sets up RLS policies for role-based access
+
+### OAuth Provider Setup
+1. Enable Google/GitHub in Supabase Dashboard → Authentication → Providers
+2. Add OAuth credentials from Google Cloud Console / GitHub Developer Settings
+3. Set redirect URLs to your deployment URL
+4. Users signing in via OAuth default to reader role
+
+### Publisher Role Approval Workflow
+New users can request publisher access during sign-up. Admin approval required:
+1. Query: `SELECT * FROM user_roles WHERE publisher_requested = true`
+2. Approve: `UPDATE user_roles SET role = 'publisher', publisher_requested = false WHERE user_id = '...'`
+3. User must re-login to see updated permissions
+
+### Storage Bucket Policies
+The `assets` bucket needs RLS policies for authenticated access:
+```sql
+-- Insert policy (publishers only)
+CREATE POLICY "Publishers can upload" ON storage.objects FOR INSERT TO authenticated
+WITH CHECK (bucket_id = 'assets' AND EXISTS (SELECT 1 FROM user_roles WHERE user_id = auth.uid() AND role = 'publisher'));
+
+-- Read policy (all authenticated users)
+CREATE POLICY "Authenticated users can view assets" ON storage.objects FOR SELECT TO authenticated
+USING (bucket_id = 'assets');
+```
+
+### Common Issues
+- **Authorization errors**: Check RLS policies and user role in `user_roles` table
+- **UUID mismatch**: [dbService.ts](src/services/dbService.ts#L5-L7) checks if `id` is UUID before upserting; temp IDs ignored
+- **Asset deletion**: On save, old assets for case study are deleted then re-inserted ([dbService.ts](src/services/dbService.ts#L47))
+- **Storage upload fails**: Ensure user is authenticated and has publisher role
+
+## Styling Notes
+- Tailwind + custom brutalist theme in [constants.tsx](src/constants.tsx)
+- Yellow (`#fcd34d`) as primary, black borders `border-4 border-black`
+- No smooth animations - hard state transitions match brutalist aesthetic
+- Error states use red (`#dc2626`), success uses green (`#16a34a`)
+
+## Deployment
+See [DEPLOYMENT.md](DEPLOYMENT.md) for complete deployment guide covering Vercel, Netlify, and Supabase configuration.
+
diff --git a/.github/instructions/development-standards.instructions.md b/.github/instructions/development-standards.instructions.md
new file mode 100644
index 0000000..61a9bf0
--- /dev/null
+++ b/.github/instructions/development-standards.instructions.md
@@ -0,0 +1,47 @@
+---
+applyTo: '**'
+---
+# Development Standards and Best Practices
+
+This document outlines the standards and best practices for DevLog Application Development which uses React, TypeScript, Material UI, and follows the [Airbnb style guide](https://airbnb.io/javascript/) page.
+
+## Web Interface Guidelines - Development Standards and Guidelines
+ALWAYS refer to the `.github/instructions/web-interface-guidelines.instructions.md` file for detailed explicit guidelines to follow when building _any_ web interface.
+
+## React
+
+- **Components**:
+  - Use PascalCase for filenames. E.g., ReservationCard.jsx.
+  - Use .tsx extension for React components.
+  - Use the filename as the component name.
+  - Only include one React component per file. However, multiple Stateless, or Pure, Components are allowed per file.
+  - Prefer functional components and use React Hooks for state and side effects.
+  
+- **Props**:
+  - Always use camelCase for prop names.
+  - Define prop types using TypeScript interfaces.
+  - Always define explicit defaultProps for all non-required props.
+  - Consider using the Context API when passing props more than 2-3 component levels.
+  - Use spread props sparingly.
+  
+- **JSX/TSX**:
+  - Keep JSX/TSX readable and concise.
+  - Extract complex parts into separate functions or components.
+  - Proper JSX/TSX alignment follows the `react/jsx-closing-bracket-location` and `react/jsx-closing-tag-location` linting rules.
+
+## TypeScript
+
+- **Types**: Always specify types. Avoid using `any`.
+- **Interfaces**: Use interfaces to define object shapes, especially for component props.
+- **Enums**: Use enums for sets of related constants.
+- **Variables**: Use `const` and `let` over `var`.
+- **Functions**: Use named function expressions instead of function declarations
+- **Semicolons**: Use them
+
+## APCA
+
+- Use the [APCA](https://www.w3.org/TR/UNDERSTANDING-WCAG20/visual-audio-contrast-contrast.html) standard for color contrast calculations instead of the older WCAG 2.0 method.
+- Aim for an APCA contrast value of at least 60 for normal text and 45 for large text.
+- Use tools like the [APCA Contrast Checker](https://toolness.github.io/apca/) to verify color contrast compliance.
+- Ensure that interactive elements have sufficient contrast in all states (default, hover, active, focus, disabled).
+- Document any exceptions to the APCA contrast requirements with a clear rationale.
\ No newline at end of file
diff --git a/.github/instructions/github-issue.instructions.md b/.github/instructions/github-issue.instructions.md
new file mode 100644
index 0000000..b212497
--- /dev/null
+++ b/.github/instructions/github-issue.instructions.md
@@ -0,0 +1,324 @@
+---
+applyTo: '**/*.md, **/*.mdx'
+---
+
+# GitHub Issue Creation Instructions
+
+Use these instructions to create well-structured, comprehensive GitHub issues for the DevLog application.
+
+## Issue Structure Template
+
+Every GitHub issue should follow this standardized structure:
+
+```markdown
+# [Clear, Descriptive Title - No Emojis]
+
+## Problem Description
+
+[2-3 paragraph overview of the issue, providing context and impact]
+
+## Current Behavior ❌
+
+[Describe what's currently happening]
+
+### [Subsection 1]
+- **Issue point**: Description
+- **Issue point**: Description
+
+### [Subsection 2]
+- Bullet points describing specific problems
+- Include technical details and symptoms
+
+## Expected Behavior ✅
+
+[Describe the desired outcome]
+
+### [Subsection 1]
+- **Expected point**: Description
+- **Expected point**: Description
+
+## Technical Context
+
+[Provide implementation details and technical background]
+
+### Current Implementation Issues
+
+1. **[Issue Category]**:
+```typescript
+// Code example showing current problematic implementation
+// Include file path and line numbers as comments
+```
+
+2. **[Another Issue]**:
+```typescript
+// More code examples
+```
+
+## Proposed Solution
+
+[Detailed explanation of how to fix the issue]
+
+### 1. [Solution Step 1]
+```typescript
+// Code example showing proposed solution
+// Include comments explaining changes
+```
+
+### 2. [Solution Step 2]
+```typescript
+// More solution code
+```
+
+## Testing Requirements
+
+### Manual Testing
+- [ ] Test case 1
+- [ ] Test case 2
+- [ ] Test case 3
+
+### Visual Regression Testing
+- [ ] Update Playwright snapshots
+- [ ] Test in light mode
+- [ ] Test in dark mode
+
+### Accessibility Testing
+- [ ] WCAG compliance check
+- [ ] Screen reader testing
+- [ ] Keyboard navigation
+
+## Acceptance Criteria
+
+- [ ] **Criterion 1**: Description
+- [ ] **Criterion 2**: Description
+- [ ] **Criterion 3**: Description
+- [ ] **Documentation**: Updated examples and best practices
+
+## Priority
+
+**[High/Medium/Low]** - [Brief justification]
+
+## Labels
+
+`label1`, `label2`, `label3`, `component-name`, `priority-level`
+
+## Related Issues
+
+- Issue/PR #123
+- Related feature work
+- Migration tasks
+
+## Additional Notes
+
+[Any additional context, considerations, or future work]
+
+---
+
+**Environment:**
+- MUI v7 with colorSchemes API
+- React 18.3+
+- TypeScript 5+
+- [Other relevant tools/versions]
+
+**Related Files:**
+- `path/to/file.ts` (lines X-Y) - Description
+- `path/to/another/file.tsx` - Description
+```
+
+## Formatting Guidelines
+
+### Headings
+- **H1 (`#`)**: Issue title only - NO EMOJIS
+- **H2 (`##`)**: Major sections (Problem Description, Current Behavior, etc.)
+- **H3 (`###`)**: Subsections within major sections
+
+### Emojis Usage
+- **Section headers**: Use ❌ for "Current Behavior" and ✅ for "Expected Behavior" only
+- **Bullet lists**: Optional emojis for emphasis (⚡, 🚀, 💾, 🎯, 🛠️, etc.)
+- **Title**: NEVER use emojis in the H1 title
+
+### Code Blocks
+- Always specify language: ```typescript```, ```tsx```, ```bash```
+- Include file paths in comments: `// src/components/MyComponent.tsx`
+- Include line numbers when referencing existing code: `// Line 45-60`
+- Add explanatory comments: `// ❌ Wrong` or `// ✅ Correct`
+
+### Lists and Checkboxes
+- Use `- [ ]` for unchecked items in testing and acceptance criteria
+- Use `- [x]` for completed items (if updating existing issue)
+- Use bullet lists (`-`) for descriptions and problem statements
+- Use numbered lists (`1.`) for sequential steps
+
+### Emphasis
+- **Bold** for key terms, component names, and important points
+- `Inline code` for file paths, function names, props, and code references
+- _Italic_ sparingly for slight emphasis
+
+## Content Guidelines
+
+### Problem Description
+- Provide context: What component/feature is affected?
+- Explain impact: How does this affect users or developers?
+- Keep it concise: 2-3 paragraphs maximum
+
+### Current Behavior
+- Be specific about symptoms
+- Include visual descriptions for UI issues
+- Group related issues under subsections
+- Use bullet points for clarity
+
+### Expected Behavior
+- Describe the ideal state
+- Match structure to Current Behavior for easy comparison
+- Include user experience improvements
+
+### Technical Context
+- Show current implementation code
+- Reference specific files and line numbers
+- Explain why current approach is problematic
+- Include links to MUI documentation when relevant
+
+### Proposed Solution
+- Provide concrete code examples
+- Break down into numbered steps
+- Show complete implementations, not fragments
+- Include comments explaining changes
+
+### Testing Requirements
+- Cover manual testing scenarios
+- Include visual regression testing needs
+- Address accessibility testing
+- Add integration or performance testing if relevant
+
+### Acceptance Criteria
+- Make criteria specific and measurable
+- Use checkboxes for tracking
+- Include non-functional requirements (performance, accessibility)
+- Always include documentation requirement
+
+## Issue Types
+
+### Bug Report
+Focus on:
+- What's broken
+- Steps to reproduce
+- Current vs expected behavior
+- Impact on users
+
+### Enhancement Request
+Focus on:
+- Current limitations
+- Benefits of enhancement
+- Performance improvements
+- Developer experience improvements
+
+### Refactor/Technical Debt
+Focus on:
+- Why current implementation is problematic
+- Technical benefits of refactor
+- Migration strategy
+- Breaking changes
+
+## Priority Levels
+
+### High Priority
+- Breaks core functionality
+- Security issues
+- Significant user experience problems
+- Blocks other development work
+
+### Medium Priority
+- Visual inconsistencies
+- Performance improvements
+- Developer experience issues
+- Non-critical bugs
+
+### Low Priority
+- Nice-to-have features
+- Minor optimizations
+- Documentation improvements
+- Cosmetic issues
+
+## Label Categories
+
+### Type Labels
+- `bug` - Something isn't working
+- `enhancement` - New feature or improvement
+- `documentation` - Documentation updates
+- `refactor` - Code restructuring
+
+### Component Labels
+- Component name (e.g., `CbAppHeader`, `CbButton`, `CbAlert`)
+- System area (e.g., `theme-system`, `storybook`, `build-process`)
+
+### Priority Labels
+- `high-priority` - Needs immediate attention
+- `medium-priority` - Should be addressed soon
+- `low-priority` - Can be deferred
+
+### Status Labels
+- `breaking-change` - Will require version bump
+- `needs-testing` - Requires additional testing
+- `accessibility` - Related to a11y
+
+## Best Practices
+
+1. **Be specific**: Use concrete examples and code snippets
+2. **Reference files**: Always include file paths and line numbers
+3. **Show, don't tell**: Use code examples to illustrate problems and solutions
+4. **Think about testing**: Include comprehensive testing requirements
+5. **Consider impact**: Explain how changes affect users and developers
+6. **Link resources**: Include MUI docs, related issues, or external references
+7. **Use checkboxes**: Make acceptance criteria actionable and trackable
+8. **Be consistent**: Follow the template structure for all issues
+9. **Update environment**: Keep technology versions current
+10. **Think future**: Consider migration paths and breaking changes
+
+## Example Prompts for Creating Issues
+
+### Bug Report Prompt
+```
+Create a GitHub issue for a bug in [Component Name]. The problem is [brief description].
+Include:
+- Current behavior with code examples from [file path]
+- Expected behavior
+- Technical context showing the implementation issue
+- Proposed solution with code
+- Testing requirements for manual, visual regression, and accessibility
+- Acceptance criteria
+```
+
+### Enhancement Prompt
+```
+Create a GitHub issue for enhancing [Feature/Component]. We need to [brief description].
+Include:
+- Current limitations
+- Benefits of enhancement
+- Technical approach with code examples
+- Migration strategy if breaking changes
+- Testing and acceptance criteria
+```
+
+### Refactor Prompt
+```
+Create a GitHub issue for refactoring [System/Component] to [new approach].
+Include:
+- Problems with current implementation
+- Proposed new architecture with code examples
+- Migration plan
+- Performance/DX benefits
+- Comprehensive testing strategy
+```
+
+## Validation Checklist
+
+Before submitting an issue, verify:
+- [ ] Title is clear and descriptive (no emojis)
+- [ ] All required sections are present
+- [ ] Code examples include file paths
+- [ ] Testing requirements are comprehensive
+- [ ] Acceptance criteria are specific and measurable
+- [ ] Priority level is justified
+- [ ] Labels are appropriate
+- [ ] Related issues/PRs are linked
+- [ ] Environment details are current
+- [ ] Formatting is consistent (emojis only in section headers)
\ No newline at end of file
diff --git a/.github/instructions/github-release-notes.instructions.md b/.github/instructions/github-release-notes.instructions.md
new file mode 100644
index 0000000..325aac7
--- /dev/null
+++ b/.github/instructions/github-release-notes.instructions.md
@@ -0,0 +1,888 @@
+---
+applyTo: '**/*.md, **/*.mdx'
+---
+
+# GitHub Release Notes Instructions
+
+This document provides comprehensive instructions for creating professional, well-structured GitHub release notes for the DevLog application. Release notes are published in two formats: a **detailed version** and a **summary version**.
+
+## File Naming and Location
+
+### Detailed Release Notes
+
+- **Filename:** `release-vX.X.X.md`
+- **Location:** `docs/published/`
+- **Purpose:** Comprehensive documentation of all changes with code examples, technical details, and migration guidance
+
+### Summary Release Notes
+
+- **Filename:** `release-vX.X.X.summary.md`
+- **Location:** `docs/published/`
+- **Purpose:** Condensed version highlighting key changes for quick review
+
+## Release Type Determination
+
+Determine the release type based on semantic versioning and commit messages:
+
+### Patch Release (x.x.X)
+
+- Bug fixes (`fix:`)
+- Documentation updates (`docs:`)
+- Minor code quality improvements
+- Non-breaking changes
+- **Example:** v18.31.1, v18.31.3
+
+### Minor Release (x.X.0)
+
+- New features (`feat:`)
+- Enhancements to existing features
+- New components or utilities
+- Non-breaking additions
+- **Example:** v18.29.0, v18.31.0
+
+### Major Release (X.0.0)
+
+- Breaking changes (`BREAKING CHANGE:`)
+- API changes requiring migration
+- Major architectural changes
+- **Example:** v19.0.0
+
+---
+
+## Detailed Release Notes Structure
+
+### Required Sections
+
+#### 1. Title and Metadata
+
+```markdown
+# Release Notes: vX.X.X
+
+**Release Date:** Month DD, YYYY
+```
+
+**Rules:**
+- Use H1 heading for title
+- Include version number with `v` prefix
+- Release date in bold, format: "Month DD, YYYY"
+- No emojis in the H1 title
+
+---
+
+#### 2. Overview (## 🎉 Overview)
+
+**Purpose:** Provide high-level summary of the release focus and impact
+
+**Structure:**
+- 2-3 paragraphs
+- First sentence states release type and primary focus
+- Explain what changed and why
+- Describe overall impact
+
+**Template:**
+
+```markdown
+## 🎉 Overview
+
+This [patch/minor/major] release [primary focus/goal]. [Additional context about the changes].
+
+[Impact statement and benefits overview].
+```
+
+**Example:**
+
+```markdown
+## 🎉 Overview
+
+This patch release fixes utility export issues and improves code consistency by consolidating exports and updating function syntax. The primary change resolves missing utility exports from the main library entry point, ensuring all utilities introduced in v18.31.0 are properly accessible to consumers.
+```
+
+---
+
+#### 3. Main Content Sections
+
+Organize changes by category with appropriate emoji headers:
+
+**For Features (✨):**
+
+```markdown
+## ✨ New Features
+
+### Feature Name
+
+Description of the feature and its purpose.
+
+#### **Key Aspects**
+
+Detailed explanation with sub-sections as needed.
+
+**Code Example:**
+
+```tsx
+// Usage example
+```
+
+**Benefits:**
+
+- ✅ Benefit one
+- ✅ Benefit two
+- ✅ Benefit three
+```
+
+**For Bug Fixes (🐛):**
+
+```markdown
+## 🐛 Bug Fixes
+
+### Issue Name
+
+Description of the problem that was fixed.
+
+#### **Root Cause Analysis**
+
+Explanation of why the issue occurred.
+
+**Before (vX.X.X):**
+
+```tsx
+// Problematic code
+```
+
+**After (vX.X.X):**
+
+```tsx
+// Fixed code
+```
+
+**Impact:**
+
+- ✅ What is now fixed
+- ✅ What users can now do
+```
+
+**For Enhancements (🔧):**
+
+```markdown
+## 🔧 Code Quality Improvements
+
+### Improvement Name
+
+Description of what was improved and why.
+
+**Before:**
+
+```tsx
+// Old approach
+```
+
+**After:**
+
+```tsx
+// Improved approach
+```
+
+**Benefits:**
+
+- 📦 Bundle size impact
+- ⚡ Performance improvement
+- 🔍 Developer experience enhancement
+```
+
+**For Documentation (📚):**
+
+```markdown
+## 📚 Documentation
+
+### Documentation Updates
+
+Description of documentation changes.
+
+**New Documentation:**
+- Document name and purpose
+- Location/link
+
+**Updated Documentation:**
+- What was updated
+- Why it was updated
+```
+
+**For Testing (🧪):**
+
+```markdown
+## 🧪 Testing Updates
+
+### Test Changes
+
+Description of test updates.
+
+**New Tests:**
+- Test description
+- Coverage area
+
+**Updated Tests:**
+- What was updated
+- Why it was updated
+```
+
+---
+
+#### 4. Technical Details (## 🔧 Technical Details)
+
+**Purpose:** Provide in-depth technical information for developers
+
+**Include:**
+- API changes with TypeScript interfaces
+- Component structure changes
+- Implementation details
+- Code examples showing internal changes
+
+**Template:**
+
+```markdown
+## 🔧 Technical Details
+
+### Component API Changes
+
+**Updated Interface:**
+
+```typescript
+interface ComponentProps {
+  existingProp: string;
+  newProp?: boolean;  // NEW
+}
+```
+
+### Component Structure
+
+Explanation of structural changes with code examples.
+```
+
+---
+
+#### 5. Files Changed (## 📊 Files Changed)
+
+**Purpose:** Show what files were modified and the scope of changes
+
+**Format:** Use a table with columns: File | Changes | Description
+
+```markdown
+## 📊 Files Changed
+
+| File | Changes | Description |
+|------|---------|-------------|
+| `src/components/Component.tsx` | 87 +/- | Component implementation |
+| `src/utils/utility.ts` | 24 +/- | Utility function |
+| `docs/GUIDE.md` | 175 + | New documentation |
+
+**Total:** X files changed, X insertions(+), X deletions(-)
+```
+
+**Rules:**
+- Use inline code for file paths
+- Show +/- for modifications, + for new files, - for deletions
+- Include total summary
+- Order by significance (main changes first)
+
+---
+
+#### 6. Migration Guide (## 🔄 Migration Guide)
+
+**Purpose:** Help users upgrade from previous version
+
+**Structure:**
+
+```markdown
+## 🔄 Migration Guide
+
+### For Existing Users
+
+**Breaking Changes:**
+
+[If none:]
+✅ **No breaking changes** - Backward compatible
+
+[If yes:]
+⚠️ **Breaking Changes:**
+
+- Change description
+- Required action
+
+**To Upgrade:**
+
+```typescript
+// Before
+oldCode();
+
+// After
+newCode();
+```
+
+### For New Users
+
+- Getting started guidance
+- Key features to know
+- Important notes
+```
+
+---
+
+#### 7. Benefits Summary (## 🎯 Benefits Summary)
+
+**Purpose:** Highlight improvements across different concerns
+
+**Required Subsections:**
+
+```markdown
+## 🎯 Benefits Summary
+
+### Developer Experience
+
+- ✅ Benefit related to development workflow
+- ✅ Benefit related to API usage
+- ✅ Benefit related to documentation
+
+### User Experience
+
+- ✅ Benefit for end users
+- ✅ Benefit for interaction
+- ✅ Benefit for visual design
+
+### Code Quality
+
+- ✅ Benefit for maintainability
+- ✅ Benefit for performance
+- ✅ Benefit for best practices
+```
+
+**Rules:**
+- Always use checkmarks (✅)
+- 3-5 bullets per subsection
+- Be specific and measurable when possible
+- Use blank lines around each subsection
+
+---
+
+#### 8. Installation (## 📦 Installation)
+
+```markdown
+## 📦 Installation
+
+```bash
+npm install @cobank-acb/shd-agrikit-ui-lib@X.X.X
+```
+```
+
+---
+
+#### 9. Resources (## 📚 Resources)
+
+```markdown
+## 📚 Resources
+
+- [Full Changelog](https://github.com/cobank-acb/shd-agrikit-ui-lib/compare/vPREV...vCURRENT)
+- [Component Documentation](link-if-applicable)
+- [Related Documentation](link-if-applicable)
+- [GitHub Repository](https://github.com/cobank-acb/shd-agrikit-ui-lib)
+```
+
+---
+
+#### 10. Footer Metadata
+
+```markdown
+---
+
+**Version:** X.X.X  
+**Release Date:** Month DD, YYYY  
+**Previous Version:** X.X.X  
+**Type:** Patch/Minor/Major Release
+```
+
+---
+
+## Summary Release Notes Structure
+
+### Key Differences from Detailed Version
+
+1. **Shorter sections** - 1-2 paragraphs vs 3-5
+2. **Fewer code examples** - Only essential ones
+3. **Condensed tables** - Simplified information
+4. **No deep technical details** - High-level only
+5. **Bottom Line section** - Single sentence summary at end
+
+### Required Sections
+
+#### 1. Title and Metadata
+
+```markdown
+# Release Summary: vX.X.X
+
+**Release Date:** Month DD, YYYY
+```
+
+---
+
+#### 2. Overview
+
+```markdown
+## Overview
+
+Single paragraph summarizing the release. [One sentence about the main change or focus].
+```
+
+---
+
+#### 3. Key Changes
+
+```markdown
+## Key Changes / Key Feature
+
+### Change/Feature Name
+
+Brief description (1-2 paragraphs).
+
+**Essential Code Example:**
+
+```tsx
+// Minimal example showing the change
+```
+
+**Key Points:**
+
+- Important point 1
+- Important point 2
+```
+
+---
+
+#### 4. Benefits (Condensed)
+
+```markdown
+## Benefits
+
+- ✅ Key benefit 1
+- ✅ Key benefit 2
+- ✅ Key benefit 3
+- ✅ Key benefit 4
+```
+
+---
+
+#### 5. Files Changed (Condensed)
+
+```markdown
+## Files Changed
+
+X files changed, X insertions(+), X deletions(-)
+
+- `file1.tsx` - Brief description
+- `file2.ts` - Brief description
+- `docs/FILE.md` - **New** documentation
+```
+
+---
+
+#### 6. Migration (Brief)
+
+```markdown
+## Migration
+
+✅ **No breaking changes** - Backward compatible
+
+[Or if changes needed:]
+
+**To upgrade:**
+
+```typescript
+// Quick example
+```
+```
+
+---
+
+#### 7. Resources
+
+```markdown
+## Resources
+
+- [GitHub Comparison](https://github.com/cobank-acb/shd-agrikit-ui-lib/compare/vPREV...vCURRENT)
+- [Documentation](link-if-applicable)
+- Commit: `hash`
+```
+
+---
+
+#### 8. Bottom Line
+
+```markdown
+---
+
+**Bottom Line:** [One sentence summary of what this release achieves and why it matters].
+```
+
+---
+
+## Formatting Rules
+
+### Markdown Linting Compliance
+
+**Critical Rules:**
+
+1. **MD032** - Lists must have blank lines before and after
+2. **MD031** - Code fences must have blank lines before and after
+3. **MD022** - Headings must have blank lines before and after
+4. **MD026** - No trailing punctuation in headings (colons allowed in sub-headings only)
+5. **MD009** - No trailing spaces
+
+**Correct:**
+
+```markdown
+Description text.
+
+**Label:**
+
+- List item 1
+- List item 2
+
+Next section.
+```
+
+**Incorrect:**
+
+```markdown
+Description text.
+**Label:**
+- List item 1
+- List item 2
+Next section.
+```
+
+---
+
+### Code Blocks
+
+**Requirements:**
+- Always specify language: ```tsx```, ```typescript```, ```bash```
+- Use blank lines before and after
+- Include comments for clarity
+- Use single quotes in code examples
+- Show file paths in comments when relevant
+
+**Example:**
+
+```markdown
+Description text.
+
+```tsx
+// src/components/Component.tsx
+import Component from '@mui/material/Component';
+
+export const MyComponent = () => {
+  return <Component prop='value' />;
+};
+```
+
+Next section.
+```
+
+---
+
+### Tables
+
+**Requirements:**
+- Proper alignment with pipes
+- Header row with separators
+- Consistent spacing
+- Use inline code for technical terms
+
+**Example:**
+
+```markdown
+| Column 1 | Column 2 | Column 3 |
+|----------|----------|----------|
+| `code` | Value | Description |
+| `code2` | Value2 | Description2 |
+```
+
+---
+
+### Emoji Usage
+
+**Standard Emojis:**
+- 🎉 Overview
+- ✨ New Features
+- 🐛 Bug Fixes
+- 🔧 Enhancements/Technical Details/Code Quality
+- 📚 Documentation
+- 🧪 Testing
+- 📊 Files Changed
+- 🔄 Migration Guide
+- 🎯 Benefits Summary
+- 📦 Installation
+- 💡 Use Cases
+- 🎨 Visual Impact
+
+**In Lists:**
+- ✅ Positive benefits/features
+- ❌ Anti-patterns/what not to do
+- ⚠️ Warnings/breaking changes
+- 📦 Bundle size
+- ⚡ Performance
+- 🔍 Developer experience
+
+---
+
+### Text Formatting
+
+**Bold (`**text**`):**
+- Important terms
+- Section labels (Before:, After:, Benefits:)
+- Emphasized points
+
+**Inline Code (`` `text` ``):**
+- File paths
+- Function names
+- Variable names
+- Property names
+- npm commands
+- Short code snippets
+
+**Headings:**
+- Use proper hierarchy (don't skip levels)
+- Title case for main headings
+- Sentence case for descriptive headings
+- No emojis in H1 titles
+- Emojis in H2 section headers
+
+---
+
+## Content Guidelines
+
+### What to Include
+
+**Always Include:**
+- Version number and release date
+- Overview of changes
+- Code examples (before/after when applicable)
+- Benefits and impact
+- Migration guidance
+- Files changed
+- Resources and links
+
+**Include When Applicable:**
+- Breaking changes
+- New components or utilities
+- API changes
+- Performance improvements
+- Visual changes
+- Test coverage updates
+
+### What to Avoid
+
+**Don't Include:**
+- Internal implementation details unless relevant
+- Overly technical jargon without explanation
+- Incomplete code examples
+- Vague benefits ("better performance" without context)
+- Personal opinions or subjective statements
+
+### Writing Style
+
+**Tone:**
+- Professional and clear
+- Factual and specific
+- Helpful and educational
+- Positive but honest
+
+**Voice:**
+- Use active voice
+- Be direct and concise
+- Explain "why" not just "what"
+- Provide context for decisions
+
+---
+
+## Comparison Tables
+
+Use comparison tables to show:
+- Before/After values
+- Old/New API
+- Different approaches
+- Feature comparisons
+
+**Template:**
+
+```markdown
+| Previous | New | Impact |
+|----------|-----|--------|
+| Old value | New value | What this means |
+```
+
+---
+
+## Code Example Patterns
+
+### Before/After Pattern
+
+```markdown
+**Before (vX.X.X):**
+
+```tsx
+// Old implementation
+const old = 'approach';
+```
+
+**After (vX.X.X):**
+
+```tsx
+// New implementation
+const new = 'approach';
+```
+```
+
+### Usage Example Pattern
+
+```markdown
+**Usage:**
+
+```tsx
+import { utility } from '@cobank-acb/shd-agrikit-ui-lib';
+
+// Example usage
+const result = utility(input);
+```
+```
+
+### Problem/Solution Pattern
+
+```markdown
+**Problem:**
+
+```tsx
+// Code showing the issue
+```
+
+**Solution:**
+
+```tsx
+// Code showing the fix
+```
+```
+
+---
+
+## Version References
+
+**In Text:**
+- Always use `v` prefix: v18.31.3
+- Reference previous version in comparisons
+- Include version in code comments when showing changes
+
+**In Links:**
+- GitHub comparison: `vPREV...vCURRENT`
+- Use full version numbers
+- Link to specific commits when relevant
+
+---
+
+## Validation Checklist
+
+Before publishing, verify:
+
+### Detailed Release Notes
+
+- [ ] Title follows format: "# Release Notes: vX.X.X"
+- [ ] Release date included and formatted correctly
+- [ ] Overview section (2-3 paragraphs)
+- [ ] All changes categorized appropriately
+- [ ] Code examples include language specification
+- [ ] Before/After examples where applicable
+- [ ] Benefits listed with checkmarks
+- [ ] Files changed table included
+- [ ] Migration guide included
+- [ ] Benefits summary with 3 subsections
+- [ ] Installation section
+- [ ] Resources section with links
+- [ ] Footer metadata
+- [ ] No markdown linting errors
+- [ ] All blank lines properly placed
+- [ ] Consistent emoji usage
+
+### Summary Release Notes
+
+- [ ] Title follows format: "# Release Summary: vX.X.X"
+- [ ] Overview is single paragraph
+- [ ] Key changes highlighted
+- [ ] Essential code examples only
+- [ ] Benefits condensed to single list
+- [ ] Files changed condensed
+- [ ] Migration brief
+- [ ] Bottom Line section at end
+- [ ] No markdown linting errors
+
+---
+
+## Example Patterns by Release Type
+
+### Patch Release Example
+
+**Focus:** Bug fixes, minor improvements, documentation
+
+**Key Sections:**
+- Bug Fixes (primary)
+- Code Quality Improvements
+- Documentation (if applicable)
+- Migration (emphasize no breaking changes)
+
+### Minor Release Example
+
+**Focus:** New features, enhancements
+
+**Key Sections:**
+- New Features (primary)
+- Enhancements
+- Documentation
+- Testing
+- Use Cases/Examples
+- Migration (new capabilities)
+
+### Major Release Example
+
+**Focus:** Breaking changes, major features
+
+**Key Sections:**
+- Breaking Changes (highlight at top)
+- New Features
+- Migration Guide (comprehensive)
+- Benefits Summary (emphasize value of upgrade)
+
+---
+
+## Cross-References
+
+**Link to:**
+- Related GitHub issues
+- Related pull requests
+- Component documentation
+- External documentation (MUI, etc.)
+- Previous release notes
+- Migration guides
+
+**Format:**
+
+```markdown
+- [Issue #123](url) - Description
+- [PR #456](url) - Description
+- [Component Docs](url)
+```
+
+---
+
+## Final Notes
+
+- **Consistency is key** - Follow the established patterns
+- **Be thorough** - Include all relevant information
+- **Be clear** - Write for developers of all skill levels
+- **Be helpful** - Provide migration guidance and examples
+- **Validate** - Check markdown linting before committing
+- **Review examples** - Reference existing release notes in `docs/published/`
diff --git a/.github/instructions/storybook.instructions.md b/.github/instructions/storybook.instructions.md
new file mode 100644
index 0000000..886242d
--- /dev/null
+++ b/.github/instructions/storybook.instructions.md
@@ -0,0 +1,57 @@
+---
+applyTo: '**/*.stories.@(js|jsx|ts|tsx)'
+---
+Provide project context and coding guidelines that AI should follow when generating code, answering questions, or reviewing changes.
+
+# /build.storybook - Scaffold Storybook Story
+
+Generate a Storybook story file following the DevLog application patterns.
+
+## Usage
+- `/build.storybook ComponentName` - Creates basic story with Primary/Secondary variants
+- `/build.storybook ComponentName --visual` - Includes visual regression testing tag
+- `/build.storybook ComponentName --variants variant1,variant2` - Custom story variants
+
+## Story Template Structure
+
+Based on `src/examples/StarterComponent/CbStarter.stories.tsx`:
+
+```tsx
+import type { Meta, StoryObj } from '@storybook/react-vite';
+import Stack from '@mui/material/Stack';
+import { ComponentName } from './ComponentName';
+
+const meta: Meta = {
+  title: 'Category/Subcategory/ComponentName',
+  component: ComponentName,
+  argTypes: {
+    // Define component prop controls
+  },
+  parameters: {
+    layout: 'fullscreen',
+  },
+  decorators: [(Story) => <Story />],
+  tags: ['!visual:check'], // Use 'visual:check' for visual regression testing
+} satisfies Meta<typeof ComponentName>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+export const Primary = {
+  args: {
+    // Primary story args
+  },
+  render: (args) => {
+    return (
+      <ComponentName {...args} />
+    );
+  },
+} satisfies Story;
+```
+
+## Requirements
+Don't assume, always ask for the following inputs before generating code:
+- Use proper Storybook title categorization matching file structure
+- Add `'visual:check'` tag only when component is ready for visual regression testing
+- Define argTypes for interactive controls in Storybook
+- Use `satisfies` for type safety with Meta and Story types
\ No newline at end of file
diff --git a/.github/instructions/web-interface-guidelines.instructions.md b/.github/instructions/web-interface-guidelines.instructions.md
new file mode 100644
index 0000000..f10be51
--- /dev/null
+++ b/.github/instructions/web-interface-guidelines.instructions.md
@@ -0,0 +1,331 @@
+---
+description: Review UI code for Web Interface Guidelines compliance
+applyTo: <file-or-pattern>
+---
+
+# Web Interface Guidelines
+
+Concise rules for building accessible, fast, delightful UIs. Use MUST/SHOULD/NEVER to guide decisions.
+
+## Interactions
+
+### Keyboard
+
+- MUST: Full keyboard support per [WAI-ARIA APG](https://www.w3.org/WAI/ARIA/apg/patterns/)
+- MUST: Visible focus rings (`:focus-visible`; group with `:focus-within`)
+- MUST: Manage focus (trap, move, return) per APG patterns
+- NEVER: `outline: none` without visible focus replacement
+
+### Targets & Input
+
+- MUST: Hit target ≥24px (mobile ≥44px); if visual <24px, expand hit area
+- MUST: Mobile `<input>` font-size ≥16px to prevent iOS zoom
+- NEVER: Disable browser zoom (`user-scalable=no`, `maximum-scale=1`)
+- MUST: `touch-action: manipulation` to prevent double-tap zoom
+- SHOULD: Set `-webkit-tap-highlight-color` to match design
+
+### Forms
+
+- MUST: Hydration-safe inputs (no lost focus/value)
+- NEVER: Block paste in `<input>`/`<textarea>`
+- MUST: Loading buttons show spinner and keep original label
+- MUST: Enter submits focused input; in `<textarea>`, ⌘/Ctrl+Enter submits
+- MUST: Keep submit enabled until request starts; then disable with spinner
+- MUST: Accept free text, validate after—don't block typing
+- MUST: Allow incomplete form submission to surface validation
+- MUST: Errors inline next to fields; on submit, focus first error
+- MUST: `autocomplete` + meaningful `name`; correct `type` and `inputmode`
+- SHOULD: Disable spellcheck for emails/codes/usernames
+- SHOULD: Placeholders end with `…` and show example pattern
+- MUST: Warn on unsaved changes before navigation
+- MUST: Compatible with password managers & 2FA; allow pasting codes
+- MUST: Trim values to handle text expansion trailing spaces
+- MUST: No dead zones on checkboxes/radios; label+control share one hit target
+
+### State & Navigation
+
+- MUST: URL reflects state (deep-link filters/tabs/pagination/expanded panels)
+- MUST: Back/Forward restores scroll position
+- MUST: Links use `<a>`/`<Link>` for navigation (support Cmd/Ctrl/middle-click)
+- NEVER: Use `<div onClick>` for navigation
+
+### Feedback
+
+- SHOULD: Optimistic UI; reconcile on response; on failure rollback or offer Undo
+- MUST: Confirm destructive actions or provide Undo window
+- MUST: Use polite `aria-live` for toasts/inline validation
+- SHOULD: Ellipsis (`…`) for options opening follow-ups ("Rename…") and loading states ("Loading…")
+
+### Touch & Drag
+
+- MUST: Generous targets, clear affordances; avoid finicky interactions
+- MUST: Delay first tooltip; subsequent peers instant
+- MUST: `overscroll-behavior: contain` in modals/drawers
+- MUST: During drag, disable text selection and set `inert` on dragged elements
+- MUST: If it looks clickable, it must be clickable
+
+### Autofocus
+
+- SHOULD: Autofocus on desktop with single primary input; rarely on mobile
+
+## Animation
+
+- MUST: Honor `prefers-reduced-motion` (provide reduced variant or disable)
+- SHOULD: Prefer CSS > Web Animations API > JS libraries
+- MUST: Animate compositor-friendly props (`transform`, `opacity`) only
+- NEVER: Animate layout props (`top`, `left`, `width`, `height`)
+- NEVER: `transition: all`—list properties explicitly
+- SHOULD: Animate only to clarify cause/effect or add deliberate delight
+- SHOULD: Choose easing to match the change (size/distance/trigger)
+- MUST: Animations interruptible and input-driven (no autoplay)
+- MUST: Correct `transform-origin` (motion starts where it "physically" should)
+- MUST: SVG transforms on `<g>` wrapper with `transform-box: fill-box`
+
+## Layout
+
+- SHOULD: Optical alignment; adjust ±1px when perception beats geometry
+- MUST: Deliberate alignment to grid/baseline/edges—no accidental placement
+- SHOULD: Balance icon/text lockups (weight/size/spacing/color)
+- MUST: Verify mobile, laptop, ultra-wide (simulate ultra-wide at 50% zoom)
+- MUST: Respect safe areas (`env(safe-area-inset-*)`)
+- MUST: Avoid unwanted scrollbars; fix overflows
+- SHOULD: Flex/grid over JS measurement for layout
+
+## Content & Accessibility
+
+- SHOULD: Inline help first; tooltips last resort
+- MUST: Skeletons mirror final content to avoid layout shift
+- MUST: `<title>` matches current context
+- MUST: No dead ends; always offer next step/recovery
+- MUST: Design empty/sparse/dense/error states
+- SHOULD: Curly quotes (" "); avoid widows/orphans (`text-wrap: balance`)
+- MUST: `font-variant-numeric: tabular-nums` for number comparisons
+- MUST: Redundant status cues (not color-only); icons have text labels
+- MUST: Accessible names exist even when visuals omit labels
+- MUST: Use `…` character (not `...`)
+- MUST: `scroll-margin-top` on headings; "Skip to content" link; hierarchical `<h1>`–`<h6>`
+- MUST: Resilient to user-generated content (short/avg/very long)
+- MUST: Locale-aware dates/times/numbers (`Intl.DateTimeFormat`, `Intl.NumberFormat`)
+- MUST: Accurate `aria-label`; decorative elements `aria-hidden`
+- MUST: Icon-only buttons have descriptive `aria-label`
+- MUST: Prefer native semantics (`button`, `a`, `label`, `table`) before ARIA
+- MUST: Non-breaking spaces: `10&nbsp;MB`, `⌘&nbsp;K`, brand names
+
+## Content Handling
+
+- MUST: Text containers handle long content (`truncate`, `line-clamp-*`, `break-words`)
+- MUST: Flex children need `minWidth: 0` to allow truncation
+- MUST: Handle empty states—no broken UI for empty strings/arrays
+
+## Performance
+
+- SHOULD: Test iOS Low Power Mode and macOS Safari
+- MUST: Measure reliably (disable extensions that skew runtime)
+- MUST: Track and minimize re-renders (React DevTools/React Scan)
+- MUST: Profile with CPU/network throttling
+- MUST: Batch layout reads/writes; avoid reflows/repaints
+- MUST: Mutations (`POST`/`PATCH`/`DELETE`) target <500ms
+- SHOULD: Prefer uncontrolled inputs; controlled inputs cheap per keystroke
+- MUST: Virtualize large lists (>50 items)
+- MUST: Preload above-fold images; lazy-load the rest
+- MUST: Prevent CLS (explicit image dimensions)
+- SHOULD: `<link rel="preconnect">` for CDN domains
+- SHOULD: Critical fonts: `<link rel="preload" as="font">` with `font-display: swap`
+
+## Dark Mode & Theming
+
+- MUST: `color-scheme: dark` on `<html>` for dark themes
+- SHOULD: `<meta name="theme-color">` matches page background
+- MUST: Native `<select>`: explicit `background-color` and `color` (Windows fix)
+
+## Hydration
+
+- MUST: Inputs with `value` need `onChange` (or use `defaultValue`)
+- SHOULD: Guard date/time rendering against hydration mismatch
+
+## Design
+
+- SHOULD: Layered shadows (ambient + direct)
+- SHOULD: Crisp edges via semi-transparent borders + shadows
+- SHOULD: Nested radii: child ≤ parent; concentric
+- SHOULD: Hue consistency: tint borders/shadows/text toward bg hue
+- MUST: Accessible charts (color-blind-friendly palettes)
+- MUST: Meet contrast—prefer [APCA](https://apcacontrast.com/) over WCAG 2
+- MUST: Increase contrast on `:hover`/`:active`/`:focus`
+- SHOULD: Match browser UI to bg
+- SHOULD: Avoid dark color gradient banding (use background images when needed)
+
+## Output Instructions
+
+Review these files for compliance: $ARGUMENTS
+
+Read files, check against rules below. Output concise but comprehensive—sacrifice grammar for brevity. High signal-to-noise.
+
+## Rules
+
+### Accessibility
+
+- Icon-only buttons need `aria-label`
+- Form controls need `<label>` or `aria-label`
+- Interactive elements need keyboard handlers (`onKeyDown`/`onKeyUp`)
+- `<button>` for actions, `<a>`/`<Link>` for navigation (not `<div onClick>`)
+- Images need `alt` (or `alt=""` if decorative)
+- Decorative icons need `aria-hidden="true"`
+- Async updates (toasts, validation) need `aria-live="polite"`
+- Use semantic HTML (`<button>`, `<a>`, `<label>`, `<table>`) before ARIA
+- Headings hierarchical `<h1>`–`<h6>`; include skip link for main content
+- `scroll-margin-top` on heading anchors
+
+### Focus States
+
+- Interactive elements need visible focus: `focus-visible:ring-*` or equivalent
+- Never `outline-none` / `outline: none` without focus replacement
+- Use `:focus-visible` over `:focus` (avoid focus ring on click)
+- Group focus with `:focus-within` for compound controls
+
+### Forms
+
+- Inputs need `autocomplete` and meaningful `name`
+- Use correct `type` (`email`, `tel`, `url`, `number`) and `inputmode`
+- Never block paste (`onPaste` + `preventDefault`)
+- Labels clickable (`htmlFor` or wrapping control)
+- Disable spellcheck on emails, codes, usernames (`spellCheck={false}`)
+- Checkboxes/radios: label + control share single hit target (no dead zones)
+- Submit button stays enabled until request starts; spinner during request
+- Errors inline next to fields; focus first error on submit
+- Placeholders end with `…` and show example pattern
+- `autocomplete="off"` on non-auth fields to avoid password manager triggers
+- Warn before navigation with unsaved changes (`beforeunload` or router guard)
+
+### Animation
+
+- Honor `prefers-reduced-motion` (provide reduced variant or disable)
+- Animate `transform`/`opacity` only (compositor-friendly)
+- Never `transition: all`—list properties explicitly
+- Set correct `transform-origin`
+- SVG: transforms on `<g>` wrapper with `transform-box: fill-box; transform-origin: center`
+- Animations interruptible—respond to user input mid-animation
+
+### Typography
+
+- `…` not `...`
+- Curly quotes `"` `"` not straight `"`
+- Non-breaking spaces: `10&nbsp;MB`, `⌘&nbsp;K`, brand names
+- Loading states end with `…`: `"Loading…"`, `"Saving…"`
+- `font-variant-numeric: tabular-nums` for number columns/comparisons
+- Use `text-wrap: balance` or `text-pretty` on headings (prevents widows)
+
+### Content Handling
+
+- Text containers handle long content: `truncate`, `line-clamp-*`, or `break-words`
+- Flex children need `minWidth: 0` to allow text truncation
+- Handle empty states—don't render broken UI for empty strings/arrays
+- User-generated content: anticipate short, average, and very long inputs
+
+### Images
+
+- `<img>` needs explicit `width` and `height` (prevents CLS)
+- Below-fold images: `loading="lazy"`
+- Above-fold critical images: `priority` or `fetchpriority="high"`
+
+### Performance
+
+- Large lists (>50 items): virtualize (`virtua`, `content-visibility: auto`)
+- No layout reads in render (`getBoundingClientRect`, `offsetHeight`, `offsetWidth`, `scrollTop`)
+- Batch DOM reads/writes; avoid interleaving
+- Prefer uncontrolled inputs; controlled inputs must be cheap per keystroke
+- Add `<link rel="preconnect">` for CDN/asset domains
+- Critical fonts: `<link rel="preload" as="font">` with `font-display: swap`
+
+### Navigation & State
+
+- URL reflects state—filters, tabs, pagination, expanded panels in query params
+- Links use `<a>`/`<Link>` (Cmd/Ctrl+click, middle-click support)
+- Deep-link all stateful UI (if uses `useState`, consider URL sync via nuqs or similar)
+- Destructive actions need confirmation modal or undo window—never immediate
+
+### Touch & Interaction
+
+- `touch-action: manipulation` (prevents double-tap zoom delay)
+- `-webkit-tap-highlight-color` set intentionally
+- `overscroll-behavior: contain` in modals/drawers/sheets
+- During drag: disable text selection, `inert` on dragged elements
+- `autoFocus` sparingly—desktop only, single primary input; avoid on mobile
+
+### Safe Areas & Layout
+
+- Full-bleed layouts need `env(safe-area-inset-*)` for notches
+- Avoid unwanted scrollbars: `overflow-x-hidden` on containers, fix content overflow
+- Flex/grid over JS measurement for layout
+
+### Dark Mode & Theming
+
+- `color-scheme: dark` on `<html>` for dark themes (fixes scrollbar, inputs)
+- `<meta name="theme-color">` matches page background
+- Native `<select>`: explicit `background-color` and `color` (Windows dark mode)
+
+### Locale & i18n
+
+- Dates/times: use `Intl.DateTimeFormat` not hardcoded formats
+- Numbers/currency: use `Intl.NumberFormat` not hardcoded formats
+- Detect language via `Accept-Language` / `navigator.languages`, not IP
+
+### Hydration Safety
+
+- Inputs with `value` need `onChange` (or use `defaultValue` for uncontrolled)
+- Date/time rendering: guard against hydration mismatch (server vs client)
+- `suppressHydrationWarning` only where truly needed
+
+### Hover & Interactive States
+
+- Buttons/links need `hover:` state (visual feedback)
+- Interactive states increase contrast: hover/active/focus more prominent than rest
+
+### Content & Copy
+
+- Active voice: "Install the CLI" not "The CLI will be installed"
+- Title Case for headings/buttons (MLA style)
+- Numerals for counts: "8 deployments" not "eight"
+- Specific button labels: "Save API Key" not "Continue"
+- Error messages include fix/next step, not just problem
+- Second person; avoid first person
+- `&` over "and" where space-constrained
+
+### Anti-patterns (flag these)
+
+- `user-scalable=no` or `maximum-scale=1` disabling zoom
+- `onPaste` with `preventDefault`
+- `transition: all`
+- `outline-none` without focus-visible replacement
+- Inline `onClick` navigation without `<a>`
+- `<div>` or `<span>` with click handlers (should be `<button>`)
+- Images without dimensions
+- Large arrays `.map()` without virtualization
+- Form inputs without labels
+- Icon buttons without `aria-label`
+- Hardcoded date/number formats (use `Intl.*`)
+- `autoFocus` without clear justification
+
+## Output Format
+
+Group by file. Use `file:line` format (VS Code clickable). Terse findings.
+
+```text
+## src/Button.tsx
+
+src/Button.tsx:42 - icon button missing aria-label
+src/Button.tsx:18 - input lacks label
+src/Button.tsx:55 - animation missing prefers-reduced-motion
+src/Button.tsx:67 - transition: all → list properties
+
+## src/Modal.tsx
+
+src/Modal.tsx:12 - missing overscroll-behavior: contain
+src/Modal.tsx:34 - "..." → "…"
+
+## src/Card.tsx
+
+✓ pass
+```
+
+State issue + location. Skip explanation unless fix non-obvious. No preamble.
\ No newline at end of file
diff --git a/.github/pr-template-commits.md b/.github/pr-template-commits.md
new file mode 100644
index 0000000..e8bee18
--- /dev/null
+++ b/.github/pr-template-commits.md
@@ -0,0 +1,106 @@
+# Pull Request Description Template
+
+> Use this file as a template for PR descriptions generated from commits.
+> Copy the content below and paste it into your GitHub PR body.
+
+---
+
+## Summary
+
+Comprehensive project restructuring moving all source code into `src/` directory, establishing a complete AI guidance framework in `.github/` for consistent development standards, and implementing testing infrastructure with Vitest and React Testing Library.
+
+## Changes
+
+### 1. Project Restructuring (`src/` Directory Migration)
+- **Moved**: All source files (components, services, utils, contexts, App.tsx, types.ts, constants.tsx, index.tsx, index.css) into `src/` directory
+- **Updated**: Configuration files (index.html, tsconfig.json, vite.config.ts, vitest.config.ts) to reference new src/ paths
+- **Fixed**: All import paths throughout codebase to resolve correctly from new locations
+- **Result**: Standard project structure following React/TypeScript conventions
+
+### 2. AI Guidance System (`.github/` Framework)
+Complete AI development framework with three layers:
+
+#### Instructions (Scope-Specific Guidelines)
+- `development-standards.instructions.md` - TypeScript/React standards, Airbnb style guide compliance, APCA contrast requirements
+- `web-interface-guidelines.instructions.md` - MUST/SHOULD/NEVER UI rules, accessibility requirements (24px hit targets, keyboard support)
+- `github-issue.instructions.md` - Issue creation standards
+- `github-release-notes.instructions.md` - Release documentation format
+- `storybook.instructions.md` - Storybook usage patterns
+
+#### Rules (Architectural Principles)
+- `component-architecture.md` - Folder-per-Component pattern with named exports
+- `spec-driven-development.md` - SDD methodology with SPEC.md template requirement
+- `supabase.md` - Database, auth, and RLS best practices
+- `accessibility.md` - WCAG compliance guidelines
+- `react-19-compiler.md` - React 19 compiler optimization rules
+- `tailwind-v4.md` - Tailwind CSS v4 setup patterns
+- `three-js-react.md` - Three.js integration patterns
+- `web-performance.md` - Performance optimization guidelines
+
+#### Skills (Executable Workflows)
+- `scaffold_component/` - Component creation workflow with SDD process
+- `accessibility_audit/` - Accessibility testing and compliance audit
+- `vercel-react-best-practices/` - 45 performance rules across 8 categories:
+  - Async patterns (API routes, dependencies, parallel fetching, suspense)
+  - Bundle optimization (dynamic imports, barrel imports, deferred third-party)
+  - Client optimizations (event listeners, localStorage, SWR deduplication)
+  - JavaScript micro-optimizations (caching, batching DOM, early exits)
+  - Rendering patterns (SVG precision, hydration, transitions)
+  - Re-render optimization (memo, derived state, lazy initialization)
+  - Server optimization (auth actions, caching, serialization)
+
+### 3. Testing Infrastructure
+- **Created**: `vitest.config.ts` with jsdom environment and jest-dom setup
+- **Added**: `src/tests/setup.ts` for test initialization
+- **Created**: Example tests:
+  - `src/tests/BrutalistButton.test.tsx` - Component testing pattern
+  - `src/tests/geminiService.test.ts` - Service mocking pattern
+- **Updated**: `package.json` with test scripts (test, test:ui, test:coverage)
+- **Updated**: `tsconfig.json` with vitest and @testing-library/jest-dom types
+
+### 4. Enhanced Documentation
+- **Updated**: `.github/copilot-instructions.md` with src/ path references
+- **Created**: `AGENTS.md` - AI agent contribution guidelines
+- **Created**: `DEPLOYMENT.md` - Complete deployment guide (Vercel, Netlify, Supabase)
+- **Created**: `IMPLEMENTATION_SUMMARY.md` - Feature implementation details
+- **Created**: `LOGIN_UX_IMPROVEMENTS.md` - UX enhancement documentation
+- **Updated**: `README.md` with project structure, testing, and deployment sections
+
+### 5. Database & Authentication
+- **Created**: `supabase/migrations/001_auth_and_rls.sql`
+  - User roles table (publisher/reader) with approval workflow
+  - RLS policies for case_studies, assets tables
+  - Storage bucket policies for authenticated access
+  - OAuth provider setup instructions
+
+### 6. GitHub Utilities
+- **Created**: `.github/prompts/create-pr.prompt.md` - PR creation automation template
+
+## Type of Change
+- [x] Refactoring (project structure and organization)
+- [x] Documentation update (comprehensive guides added)
+- [x] New feature (testing infrastructure, AI guidance system)
+- [x] Build/infrastructure change (TypeScript config updates)
+
+## Testing
+- ✅ Build succeeds: `npm run build` produces valid production bundle
+- ✅ Dev server runs: `npm run dev` starts without errors
+- ✅ Tests configured: `npm test` runs Vitest in watch mode
+- ✅ TypeScript validation: All imports resolve correctly, no type errors
+- ✅ Manual verification: Project structure follows React/TypeScript conventions
+
+## Benefits
+1. **Standard Structure**: Follows industry best practices for React projects
+2. **AI-Assisted Development**: Complete guidance system for consistent code quality
+3. **Testing Ready**: Infrastructure in place for comprehensive test coverage
+4. **Documentation**: Extensive guides for development, deployment, and AI collaboration
+5. **Maintainability**: Clear folder organization and import paths
+
+## Checklist
+- [x] Code follows project style guidelines
+- [x] All documentation updated with new paths
+- [x] Build succeeds without errors
+- [x] TypeScript compilation passes
+- [x] Test infrastructure configured and verified
+- [x] No breaking changes to existing functionality
+- [x] All imports resolve correctly
diff --git a/.github/prompts/create-pr.prompt.md b/.github/prompts/create-pr.prompt.md
new file mode 100644
index 0000000..0e27553
--- /dev/null
+++ b/.github/prompts/create-pr.prompt.md
@@ -0,0 +1,90 @@
+---
+agent: agent
+---
+
+# Create PR from Last Commit
+
+## Task
+Analyze the last git commit and create a comprehensive PR description.
+
+## Instructions
+
+1. **Get the latest commit details:**
+   - Use `mcp_github_get_commit` with:
+     - owner: `ericthayer`
+     - repo: `devlog`
+     - sha: Get from `git log -1 --pretty=format:"%H"`
+     - include_diff: `true`
+
+2. **Analyze the commit data:**
+   - Extract commit message (title and body)
+   - Review files changed (additions, deletions, modifications)
+   - Examine the diff to understand the scope of changes
+   - Identify the type of change (feat, fix, refactor, docs, etc.)
+
+3. **Build PR description following this structure:**
+   
+   ```markdown
+   ## Summary
+   [1-2 sentences describing the overall change]
+   
+   ## Changes
+   - **Files Modified:** [List key files with brief descriptions]
+   - **Key Changes:** [Bullet points of what was changed and why]
+   
+   ## Type of Change
+   - [ ] Bug fix (non-breaking)
+   - [ ] New feature (non-breaking)
+   - [ ] Breaking change
+   - [ ] Documentation update
+   - [ ] Refactoring
+   
+   ## Testing
+   [Describe testing approach or note if manual testing needed]
+   
+   ## Checklist
+   - [ ] Code follows project style guidelines
+   - [ ] Documentation updated
+   - [ ] No new warnings generated
+   - [ ] Tests added/updated
+   ```
+
+4. **Create the Pull Request:**
+   - Use `mcp_github_create_pull_request` with:
+     - owner: `ericthayer`
+     - repo: `devlog`
+     - title: [Commit message or descriptive title]
+     - head: [Current branch name]
+     - base: `main`
+     - body: [Formatted description from step 3]
+     - draft: `false` (set to `true` if WIP)
+
+## Alternative: Use GitHub CLI Directly
+
+For faster PR creation without mcp_github tools:
+
+```bash
+# Get current branch
+BRANCH=$(git branch --show-current)
+
+# Create PR with template
+gh pr create \
+  --title "$(git log -1 --pretty=format:'%s')" \
+  --body "$(cat .github/pr-template-commits.md)" \
+  --base main \
+  --head $BRANCH
+```
+
+See `.github/GITHUB_AUTH_SETUP.md` for authentication setup.
+
+## Context
+- Repository: github.com/ericthayer/devlog
+- Default base branch: `main`
+- See `.github/pr-template-commits.md` for reusable PR description template
+- See `.github/GITHUB_AUTH_SETUP.md` for GitHub authentication guide
+
+## Success Criteria
+✅ PR created with descriptive title
+✅ Body contains summary, changes, and testing info
+✅ All relevant files mentioned
+✅ Clear description of what and why
\ No newline at end of file
diff --git a/.github/rules/accessibility.md b/.github/rules/accessibility.md
new file mode 100644
index 0000000..7e721c3
--- /dev/null
+++ b/.github/rules/accessibility.md
@@ -0,0 +1,36 @@
+---
+description: Accessibility standards for Three.js and React applications.
+---
+
+**OBJECTIVE:**
+Building inclusive 3D web experiences that are accessible to keyboard users, screen reader users, and those with motion sensitivities.
+
+**REASON:**
+3D environments are inherently non-semantic. Without explicit effort, they are invisible to assistive technologies and can cause physical discomfort for users with vestibular disorders.
+
+**DESCRIPTION:**
+Guidelines for semantic canvas layering, focus management, and motion preference handling.
+
+**INSTRUCTIONS:**
+
+### Instant Perceptual Feedback
+- **Critical CSS Inlining**: Inline the minimum CSS required to render a themed background and loading indicator directly in the `<head>` of `index.html`. This prevents the "blank white screen" during bundle download.
+- **Pre-Hydration Status**: Provide a `role="status"` or `aria-live="polite"` container in the initial HTML structure. Use CSS `:empty` pseudo-classes to show a loading message that automatically disappears once React hydrates the root.
+- **Theme-Aware Loading**: Ensure the initial "Critical" background color matches the user's system preference (light/dark) to avoid "flash of un-themed content" (FOUT/FOIT).
+
+### Scene Accessibility
+- **Canvas Metadata**: Always provide a descriptive `aria-label` or `title` on the `<canvas>` element. Use `role="img"` if the scene is purely visual, or `role="application"` if it is interactive.
+- **Fallback Content**: Place a text description of the scene inside the `<canvas>` tag for older browsers or screen readers that don't support canvas metadata.
+
+### Motion Control (CRITICAL)
+- **Respect `@media (prefers-reduced-motion)`**: Use the `useMediaQuery` hook or CSS to detect if the user prefers reduced motion.
+- **Auto-Pause/Slow**: If reduced motion is active, automatically pause or significantly slow down ambient animations (rotations, particle systems, floating effects).
+- **Toggle Visibility**: Avoid rapid flashing or strobing effects in 3D scenes.
+
+### Interaction & Focus
+- **Standard UI Elements**: Use standard HTML `<button>` or `<a>` tags for interactions whenever possible, layered over the canvas.
+- **Keyboard Navigation**: Ensure every interactive element in the 3D scene can be reached and activated via the `Tab` and `Enter/Space` keys.
+- **Visual Focus States**: Never remove focus outlines (`outline: none`) without providing a clear, high-contrast alternative for navigated elements.
+
+### Contrast & Legibility
+- **Text over 3D**: Ensure text labels overlaying 3D scenes have sufficient contrast (WCAG AA 4.5:1). Use text-shadows or semi-transparent backgrounds to guarantee legibility over dynamic backgrounds.
diff --git a/.github/rules/component-architecture.md b/.github/rules/component-architecture.md
new file mode 100644
index 0000000..153af92
--- /dev/null
+++ b/.github/rules/component-architecture.md
@@ -0,0 +1,34 @@
+---
+description: Standardized directory and file structure for React components in this workspace.
+---
+
+**OBJECTIVE:**
+Maintaining a consistent, scalable, and discoverable component architecture.
+
+**REASON:**
+As the project grows, a standardized folder structure prevents "file sprawl" and makes it easier to locate styles, tests, and assets related to a specific component.
+
+**DESCRIPTION:**
+The "Folder-per-Component" pattern used throughout the `src/components` directory.
+
+**INSTRUCTIONS:**
+
+### Directory Structure
+- **Component Folders**: Every major component should live in its own folder under `src/components/`.
+- **Primary File**: The main component file must be named `ComponentName.tsx` (PascalCase).
+- **Associated Files**: Styles, local assets, and sub-components should reside within the same component folder.
+
+Example:
+```
+src/components/Hero/
+├── Hero.tsx
+├── Hero.css (if not using Tailwind)
+└── HeroBackground.tsx (local child component)
+```
+
+### Exports
+- **Named Exports**: Prefer named exports for components to ensure better IDE support and tree-shaking.
+- **Clear Boundaries**: Avoid importing local child components (e.g., `HeroBackground`) from outside their parent's folder. If a component is reused elsewhere, move it to the root of `src/components/`.
+
+### Prop Types
+- **Interfaces over Types**: Use `interface` for component props to allow for better extensibility and cleaner error messages.
diff --git a/.github/rules/react-19-compiler.md b/.github/rules/react-19-compiler.md
new file mode 100644
index 0000000..3abb190
--- /dev/null
+++ b/.github/rules/react-19-compiler.md
@@ -0,0 +1,26 @@
+---
+description: Guidelines for writing code optimized for the React Compiler (React 19+).
+---
+
+**OBJECTIVE:**
+Writing "Rules of React" compliant code to enable automatic memoization and optimization by the React Compiler.
+
+**REASON:**
+The React Compiler (`babel-plugin-react-compiler`) automatically optimizes components, but only if they follow strict functional purity and reactivity rules.
+
+**DESCRIPTION:**
+Best practices for ensuring components are "Compiler-safe," reducing the need for manual `useMemo` and `useCallback`.
+
+**INSTRUCTIONS:**
+
+### Component Purity
+- **No Mutations in Render**: Never mutate variables or objects during the render phase. Always treat props and state as immutable.
+- **Pure Functions**: Ensure components and hooks are idempotent—calling them multiple times with the same inputs should produce the same results.
+
+### Hook Usage
+- **Standard Hook Patterns**: Only use hooks at the top level and follow the standard React lifecycle. 
+- **Avoid Manual Memoization**: Stop using `useMemo` and `useCallback` for performance optimization; the compiler handles this. Only use them if they are required for stable references in external libraries or deep dependency arrays.
+
+### Compiler Safety
+- **Validate with ESLint**: Ensure `eslint-plugin-react-compiler` is active to catch potential issues that would prevent optimization.
+- **Side Effect Isolation**: Keep side effects strictly inside `useEffect` or event handlers.
diff --git a/.github/rules/spec-driven-development.md b/.github/rules/spec-driven-development.md
new file mode 100644
index 0000000..0c2c132
--- /dev/null
+++ b/.github/rules/spec-driven-development.md
@@ -0,0 +1,36 @@
+---
+description: Methodology for Spec-Driven Development (SDD) based on the "Spec Kit" principles.
+---
+
+**OBJECTIVE:**
+Ensuring high-quality implementation by defining technical requirements and intent in a structured "Spec" before writing any code.
+
+**REASON:**
+SDD eliminates "vibe coding" (vague prompting) by providing the AI with a clear technical roadmap, reducing context loss and ensuring alignment with project standards.
+
+**DESCRIPTION:**
+The SDD process involves three distinct phases: Spec Drafting, Implementation, and Verification. The Spec serves as the "source of truth."
+
+**INSTRUCTIONS:**
+
+### 1. Spec Initializing
+- **Before coding starts**, create a `SPEC.md` or equivalent in the component/feature folder.
+- **Spec Content**:
+    - **Intent**: What problem are we solving?
+    - **Usage**: How will the component be used (code examples)?
+    - **Architecture**: Tech stack, state management, and data flow.
+    - **Accessibility**: ARIA roles, focus management, reduced motion.
+    - **Performance**: Soft limits for assets, rendering loop optimizations.
+
+### 2. Implementation Phase
+- **Pure Implementation**: The implementation phase MUST follow the Spec precisely. If the Spec is missing details, the Spec should be updated first.
+- **Incremental Builds**: Build in logical steps (foundation -> features -> polish).
+- **Checkpoints**: Use checkpoints after each major component or feature to verify against the Spec.
+
+### 3. Review & Refinement
+- **Verification**: Cross-reference the final implementation against the "Implementation Checklist" in the Spec.
+- **Zero Vibe Rule**: If the code "feels" right but doesn't meet a spec requirement, it is technically a failure.
+
+### 4. Spec Evolution
+- **Living Document**: The spec is not static. If discoveries are made during OR after execution that change the architecture, update the Spec BEFORE continuing with the code, and/or AFTER final updates are made. Make sure to refactor our spec anytime an additional change or feature is added to the component.
+- **Add Changelog**: Add small and concise summary and timestamp each time the spec changes.
diff --git a/.github/rules/supabase.md b/.github/rules/supabase.md
new file mode 100644
index 0000000..c1b7d3e
--- /dev/null
+++ b/.github/rules/supabase.md
@@ -0,0 +1,40 @@
+---
+description: Best practices for integrating Supabase for auth, database, and asset storage.
+---
+
+**OBJECTIVE:**
+Implementing a secure, type-safe, and efficient integration with Supabase for data management and authentication.
+
+**REASON:**
+Ensures centralized client management, leverages TypeScript for end-to-end safety, and optimizes the handling of large 3D assets via Supabase Storage.
+
+**DESCRIPTION:**
+Guidelines for client initialization, authentication state management, and asset coordination between Supabase and Three.js.
+
+**INSTRUCTIONS:**
+
+### Environment Configuration
+- **Standard Naming**: Use `VITE_SUPABASE_URL` and `VITE_SUPABASE_ANON_KEY` in `.env` files.
+- **Validation**: Ensure these variables are present and valid before initializing the client to prevent silent runtime failures.
+
+### Client Management
+- **Singleton Pattern**: Initialize the Supabase client once in a dedicated file (e.g., `src/lib/supabase.ts`) and export it as a singleton.
+- **Type Safety**: Generate TypeScript types using the Supabase CLI (`supabase gen types typescript --project-id ...`) and pass them to the `createClient` function for full IntelliSense support.
+
+### Authentication
+- **Auth Context**: Wrap the application (or relevant branches) in a `SupabaseAuthProvider` to manage user sessions and profiles.
+- **Protecting Routes**: Use specialized hooks (e.g., `useAuth`) to handle redirects for protected versus public views.
+- **Loading States**: Always account for the initial session check to avoid "flash of unauthenticated content."
+
+### Database & RLS
+- **RLS is Mandatory**: Never disable Row Level Security (RLS) in production. Always define specific policies for `SELECT`, `INSERT`, `UPDATE`, and `DELETE`.
+- **Relational Integrity**: Use Foreign Key constraints and appropriate indexes to maintain data quality and query performance.
+
+### Asset Storage (Three.js Specific)
+- **Bucket Organization**: Store 3D models (`.glb`, `.gltf`) and textures (`.webp`, `.ktx2`) in dedicated Supabase Storage buckets.
+- **Signed URLs**: Use signed URLs for private assets or assets requiring temporary access.
+- **Caching**: Leverage Supabase's built-in CDN for public storage buckets to minimize latency when loading 3D scenes.
+
+### Error Handling
+- **User-Friendly Messages**: Transform Supabase error codes into human-readable feedback.
+- **Retry Logic**: Implement exponential backoff for network-related failures, especially when uploading or downloading large assets.
diff --git a/.github/rules/tailwind-v4.md b/.github/rules/tailwind-v4.md
new file mode 100644
index 0000000..d2b023d
--- /dev/null
+++ b/.github/rules/tailwind-v4.md
@@ -0,0 +1,29 @@
+---
+description: Best practices for using Tailwind CSS v4 in a performance-oriented React environment.
+---
+
+**OBJECTIVE:**
+Leveraging the CSS-first architecture of Tailwind CSS v4 to build high-performance, maintainable UIs.
+
+**REASON:**
+Tailwind v4 moves configuration into CSS and utilizes a high-performance engine (Lightning CSS), requiring a shift in how themes and utilities are managed compared to v3.
+
+**DESCRIPTION:**
+Guidelines for using Tailwind v4's `@theme` block, CSS variables, and modern engine features while avoiding legacy configuration patterns.
+
+**INSTRUCTIONS:**
+
+### CSS-First Configuration
+- **Use `@theme` in CSS**: Define all theme extensions (colors, fonts, spacing) inside the `@theme` block in your main CSS file, not in a JS configuration file.
+- **Prefer CSS Variables**: Use CSS custom properties defined in `@theme`. Reference them as `var(--name)` when needed in custom styles.
+- **Avoid `tailwind.config.js`**: Do not create or use a `tailwind.config.js` file unless strictly necessary for legacy plugin compatibility.
+
+### Performance & Engine
+- **Leverage Lightning CSS**: Be aware that Tailwind v4 uses Lightning CSS for ultra-fast builds. Avoid complex PostCSS plugins that might slow down the pipeline.
+- **Built-in Modern Features**: Use modern CSS features like `@import "tailwindcss"` and direct variable references which are optimized by the v4 engine.
+
+### Implementation Patterns
+- **Prioritize Container Queries**: Use `@container` queries for component-level styling and layout before resorting to viewport-based media queries whenever a component's layout depends on its parent's width.
+- **Dual Color Palettes**: Always define and implement both **light and dark** color mode palettes within the `@theme` block. Use native CSS color-scheme support and variables to ensure seamless transitions.
+- **Utility First**: Maintain the utility-first mindset, but use standard CSS for complex layouts that utilities cannot cleanly handle.
+- **Modern Color Palettes**: Use the expanded Oklch color space support provided by v4 for better perceptual uniformity in gradients and UI elements.
diff --git a/.github/rules/three-js-react.md b/.github/rules/three-js-react.md
new file mode 100644
index 0000000..c8a4d58
--- /dev/null
+++ b/.github/rules/three-js-react.md
@@ -0,0 +1,76 @@
+---
+description: Guidelines for building production-ready React applications with Three.js and AI-powered tools.
+---
+
+**OBJECTIVE:**
+Building production-ready React applications with [Three.js](https://threejs.org/manual/#en/creating-a-scene) and AI-powered APIs and tooling.
+
+**REASON:**
+Ensures high performance, proper resource management, and clean React integration when working with complex 3D scenes in a web environment.
+
+**DESCRIPTION:**
+This rule provides a comprehensive set of best practices for Three.js development within a React ecosystem, focusing on memory management, rendering optimization, and asset handling.
+
+**INSTRUCTIONS:**
+
+### Resource Management
+- **Always dispose** of `Geometry`, `Material`, `Texture`, and `Renderer` objects in component cleanup to prevent WebGL memory leaks.
+- Call `geometry.dispose()`, `material.dispose()`, `texture.dispose()`, and `renderer.dispose()` in the `useEffect` cleanup function.
+- Dispose of post-processing passes and composers when unmounting.
+
+### Performance Optimization
+- **Cap pixel ratio** to `Math.min(window.devicePixelRatio, 2)` to balance quality and performance.
+- Set `powerPreference: "high-performance"` in `WebGLRenderer` options.
+- **Reuse objects** (Vector3, Color, etc.) instead of creating new instances in the animation loop.
+- Use `BufferGeometry` instead of legacy `Geometry`.
+- Limit particle counts and geometry complexity based on device capabilities.
+
+### React Integration
+- Use `useRef` for canvas elements and Three.js objects (scene, camera, renderer).
+- Initialize Three.js in `useEffect` with proper cleanup in the return function.
+- Cancel `requestAnimationFrame` on component unmount to prevent memory leaks.
+- **Avoid storing Three.js objects in React state**; use refs instead.
+
+### Responsive Design
+- Handle window resize events to update camera aspect ratio and renderer size.
+- Update post-processing composer and pass resolutions on resize.
+- Debounce resize handlers if performing expensive recalculations.
+
+### Animation Loop
+- Use `requestAnimationFrame` for smooth 60fps rendering.
+- Store the animation frame ID and cancel it in cleanup.
+- Implement delta time for frame-rate independent animations when needed.
+
+### Scene Organization
+- Use `THREE.Group` to organize related objects for easier transformation and cleanup.
+- Separate static and dynamic objects for optimization opportunities.
+- Use meaningful names for objects to aid debugging (`object.name = "particleSystem"`).
+
+### Asset Loading
+- Use `GLTFLoader` for 3D models (preferred format for web).
+- Implement `LoadingManager` for coordinated loading with progress tracking.
+- Use `DRACOLoader` for compressed GLTF files to reduce file size.
+- Handle loading errors gracefully with user feedback.
+- Consider lazy loading non-critical 3D assets.
+
+### Shaders and Materials
+- Minimize dynamic lights; prefer baked lighting or environment maps (HDRI).
+- Use `ShaderMaterial` for custom effects but keep shaders optimized.
+- Avoid heavy branching and loops in fragment shaders.
+- Use `MeshStandardMaterial` or `MeshPhysicalMaterial` for PBR workflows.
+- Set `depthWrite: false` and `transparent: true` appropriately for particle systems.
+
+### Post-Processing
+- Use `EffectComposer` for post-processing effects.
+- Order passes efficiently (RenderPass → effects → FXAA/SMAA last).
+- Disable unused passes to save performance.
+- Update pass resolutions on window resize.
+
+### Interaction
+- Throttle or debounce mouse/touch event handlers for expensive calculations.
+- Use raycasting efficiently; limit the number of objects tested.
+- Implement smooth camera controls with lerping for better UX.
+
+### Framework Consideration
+- For complex scenes, consider migrating to `@react-three/fiber` and `@react-three/drei` for declarative Three.js in React.
+- These libraries provide React-friendly abstractions, automatic disposal, and helpful hooks.
diff --git a/.github/rules/web-performance.md b/.github/rules/web-performance.md
new file mode 100644
index 0000000..1821fb4
--- /dev/null
+++ b/.github/rules/web-performance.md
@@ -0,0 +1,29 @@
+---
+trigger: always_on
+description: Web performance and Core Web Vitals optimization guidelines.
+---
+
+**OBJECTIVE:**
+Ensuring fast load times, smooth interactions, and stable layouts for both 3D and standard web content.
+
+**REASON:**
+Large 3D assets can easily degrade performance, leading to poor Core Web Vitals scores and high bounce rates, especially on mobile devices.
+
+**DESCRIPTION:**
+Rules for asset budgeting, layout stability, and resource prioritization.
+
+**INSTRUCTIONS:**
+
+### Core Web Vitals
+- **Prevent Layout Shifts (CLS)**: Always set explicit `width` and `height` dimensions (or aspect ratio) on the canvas container to reserve space before the scene initializes.
+- **Optimize LCP**: Identify the largest above-fold element (often a hero texture or font), and utilize the CSS property, [content visibility](https://developer.mozilla.org/en-US/docs/Web/CSS/Reference/Properties/content-visibility) to help with more performant rendering. Use `<link rel="preload">` for these critical assets and **Inline Critical CSS** in the HTML `<head>` for a near-instant first paint.
+
+### Asset Budgeting
+- **Texture Compression**: Use `.webp` or `.ktx2` for textures. Avoid large 4K textures unless viewed up close; 1K or 2K is usually sufficient for web.
+- **Geometry Optimization**: Use Draco compression for GLTF models. Aim for a total initial bundle size (including models) under 5MB for the primary interactive state.
+- **Lazy Loading**: Use dynamic imports `React.lazy()` or the `useLoader` cleanup mechanism for non-critical assets (e.g., objects in future scenes or footer elements).
+
+### Rendering Performance
+- **Font Display**: Use `font-display: swap` for all web fonts to ensure text is visible while the custom font (and 3D scene) loads.
+- **Avoid Long Tasks**: Ensure that Three.js initialization or heavy computations don't block the main thread for more than 50ms. Use `setTimeout` or `requestIdleCallback` to chunk initialization if necessary.
+- **Asset Caching**: Leverage service workers or strong Cache-Control headers for 3D assets that don't change frequently.
\ No newline at end of file
diff --git a/.github/skills/accessibility_audit/SKILL.md b/.github/skills/accessibility_audit/SKILL.md
new file mode 100644
index 0000000..a98a449
--- /dev/null
+++ b/.github/skills/accessibility_audit/SKILL.md
@@ -0,0 +1,39 @@
+---
+name: accessibility_audit
+description: Verify that a component or page meets the high accessibility standards defined in AGENTS.md.
+---
+
+# `accessibility_audit`
+
+Use this skill before marking any feature as "Done". It helps you catch common accessibility issues that are strictly forbidden by `./AGENTS.md`.
+
+## Checklist
+
+### 1. Semantic Structure
+- [ ] Are buttons used for actions (`<button>`) and links for navigation (`<a>`)?
+- [ ] Do headings (`h1`-`h6`) follow a logical hierarchy? (Only one `h1` per page).
+- [ ] Are lists (`ul`, `ol`) used for grouped items?
+
+### 2. Interactive Elements
+- [ ] **Focus**: Can you tab to every interactive element?
+- [ ] **Visual Focus**: Does every element have a visible focus ring? (No `outline: none` without replacement).
+- [ ] **Labels**: Do all icon-only buttons have `aria-label`?
+- [ ] **Forms**: Do all inputs have a linked `<label>` or `aria-label`?
+
+### 3. Images & Media
+- [ ] Do all images have `alt` text (or `alt=""` if decorative)?
+- [ ] do user-uploaded or AI-generated images have proper error states?
+- [ ] Are explicit `width` and `height` attributes set to prevent layout shifts?
+
+### 4. Dynamic Content
+- [ ] **Loading**: Are loading states announced? (e.g., `aria-busy="true"` or `role="status"`).
+- [ ] **Streaming**: Is the streaming text container using `aria-live="polite"`?
+- [ ] **Updates**: Do dynamic updates trigger screen reader notifications?
+
+### 5. Motion & Validation
+- [ ] **Reduced Motion**: Is `prefers-reduced-motion` respected?
+- [ ] **Validation**: Are form errors linked to inputs via `aria-describedby`?
+- [ ] **Focus Management**: Is focus moved to the error summary or first error on submit failure?
+
+## Failure Conditions
+If any of the above are "No", the feature is **NOT** ready. Stop and fix it.
diff --git a/.github/skills/scaffold_component/SKILL.md b/.github/skills/scaffold_component/SKILL.md
new file mode 100644
index 0000000..3f3d97f
--- /dev/null
+++ b/.github/skills/scaffold_component/SKILL.md
@@ -0,0 +1,75 @@
+---
+name: scaffold_component
+description: Create a new React component following project constraints (Tailwind, MUI, or Vanilla).
+---
+
+# `scaffold_component` (Global Fallback)
+
+Use this skill when the user asks to "create a component". This skill is designed to be framework-agnostic and will adapt to the current project's stack. Adhere to the following process and development philosophy and approach.
+
+## Development Process
+
+**Philosophy & Approach**
+
+- **Spec-Driven Development (SDD)**: Always start by creating a technical specification using the `/sdd-workflow` template. Adhere to the `spec-driven-development.md` global rule.
+  - Create the spec as `[ComponentName].spec.md` within the component folder before starting implementation.
+  - **Living Document**: Refactor the spec for every new feature or discovery and maintain a timestamped **Changelog** at the bottom.
+- **Component Architecture**: Follow the `component-architecture.md` global rule (Folder-per-Component).
+
+## Usage
+1.  **Draft the Spec**: Run the `/sdd-workflow` and create `src/components/[ComponentName]/[ComponentName].spec.md`. Initialize the **Changelog** section.
+2.  **Detect Framework & Stack**: Check `package.json` for dependencies (e.g., `@mui/material`, `tailwindcss`, `react` version). Adhere to project-specific rules like `three-js-react.md` if applicable.
+3.  **Implement & Update**: Follow the spec strictly. If architecture changes during build, update the spec and the changelog **before** proceeding.
+
+## Framework-Specific Rules
+
+### If MUI is detected:
+- Use MUI components (`Box`, `Typography`, `Grid`).
+- Use the `sx` prop for custom styling.
+- Use `Grid` (v2) if on MUI v6+.
+
+### If Tailwind CSS is detected:
+- Use standard HTML tags (`div`, `header`, `main`).
+- Use `className` with Tailwind utility classes.
+- Follow mobile-first responsive patterns (e.g., `sm:`, `md:`, `lg:`).
+
+### Default (Vanilla React/CSS):
+- Use standard HTML tags.
+- Use CSS Modules or standard CSS
+- Use CSS Custom Properties to build a light/dark theme.
+
+## Base Template
+
+```tsx
+import React from 'react';
+
+/**
+ * Props for the [ComponentName] component.
+ */
+export interface [ComponentName]Props {
+  /** ARIA label for accessibility */
+  'aria-label'?: string;
+  title?: string;
+  children?: React.ReactNode;
+}
+
+/**
+ * [Brief description of the component]
+ */
+export const [ComponentName]: React.FC<[ComponentName]Props> = ({
+  'aria-label': ariaLabel,
+  title,
+  children,
+  ...props
+}) => {
+  // IMPLEMENTATION: Adapt based on detected framework (MUI vs Tailwind)
+  return (
+    <div className="[component-name-kebab-case]" {...props}>
+      {title && <h2>{title}</h2>}
+      <div role="region" aria-label={ariaLabel || "[Default Label]"}>
+        {children || <p>New component: [ComponentName]</p>}
+      </div>
+    </div>
+  );
+};
+```
diff --git a/.github/skills/vercel-react-best-practices/AGENTS.md b/.github/skills/vercel-react-best-practices/AGENTS.md
new file mode 100644
index 0000000..e7b7ca9
--- /dev/null
+++ b/.github/skills/vercel-react-best-practices/AGENTS.md
@@ -0,0 +1,2719 @@
+# React Best Practices
+
+**Version 1.0.0**  
+Vercel Engineering  
+January 2026
+
+> **Note:**  
+> This document is mainly for agents and LLMs to follow when maintaining,  
+> generating, or refactoring React and Next.js codebases at Vercel. Humans  
+> may also find it useful, but guidance here is optimized for automation  
+> and consistency by AI-assisted workflows.
+
+---
+
+## Abstract
+
+Comprehensive performance optimization guide for React and Next.js applications, designed for AI agents and LLMs. Contains 40+ rules across 8 categories, prioritized by impact from critical (eliminating waterfalls, reducing bundle size) to incremental (advanced patterns). Each rule includes detailed explanations, real-world examples comparing incorrect vs. correct implementations, and specific impact metrics to guide automated refactoring and code generation.
+
+---
+
+## Table of Contents
+
+1. [Eliminating Waterfalls](#1-eliminating-waterfalls) — **CRITICAL**
+   - 1.1 [Defer Await Until Needed](#11-defer-await-until-needed)
+   - 1.2 [Dependency-Based Parallelization](#12-dependency-based-parallelization)
+   - 1.3 [Prevent Waterfall Chains in API Routes](#13-prevent-waterfall-chains-in-api-routes)
+   - 1.4 [Promise.all() for Independent Operations](#14-promiseall-for-independent-operations)
+   - 1.5 [Strategic Suspense Boundaries](#15-strategic-suspense-boundaries)
+2. [Bundle Size Optimization](#2-bundle-size-optimization) — **CRITICAL**
+   - 2.1 [Avoid Barrel File Imports](#21-avoid-barrel-file-imports)
+   - 2.2 [Conditional Module Loading](#22-conditional-module-loading)
+   - 2.3 [Defer Non-Critical Third-Party Libraries](#23-defer-non-critical-third-party-libraries)
+   - 2.4 [Dynamic Imports for Heavy Components](#24-dynamic-imports-for-heavy-components)
+   - 2.5 [Preload Based on User Intent](#25-preload-based-on-user-intent)
+3. [Server-Side Performance](#3-server-side-performance) — **HIGH**
+   - 3.1 [Authenticate Server Actions Like API Routes](#31-authenticate-server-actions-like-api-routes)
+   - 3.2 [Avoid Duplicate Serialization in RSC Props](#32-avoid-duplicate-serialization-in-rsc-props)
+   - 3.3 [Cross-Request LRU Caching](#33-cross-request-lru-caching)
+   - 3.4 [Minimize Serialization at RSC Boundaries](#34-minimize-serialization-at-rsc-boundaries)
+   - 3.5 [Parallel Data Fetching with Component Composition](#35-parallel-data-fetching-with-component-composition)
+   - 3.6 [Per-Request Deduplication with React.cache()](#36-per-request-deduplication-with-reactcache)
+   - 3.7 [Use after() for Non-Blocking Operations](#37-use-after-for-non-blocking-operations)
+4. [Client-Side Data Fetching](#4-client-side-data-fetching) — **MEDIUM-HIGH**
+   - 4.1 [Deduplicate Global Event Listeners](#41-deduplicate-global-event-listeners)
+   - 4.2 [Use Passive Event Listeners for Scrolling Performance](#42-use-passive-event-listeners-for-scrolling-performance)
+   - 4.3 [Use SWR for Automatic Deduplication](#43-use-swr-for-automatic-deduplication)
+   - 4.4 [Version and Minimize localStorage Data](#44-version-and-minimize-localstorage-data)
+5. [Re-render Optimization](#5-re-render-optimization) — **MEDIUM**
+   - 5.1 [Defer State Reads to Usage Point](#51-defer-state-reads-to-usage-point)
+   - 5.2 [Do not wrap a simple expression with a primitive result type in useMemo](#52-do-not-wrap-a-simple-expression-with-a-primitive-result-type-in-usememo)
+   - 5.3 [Extract Default Non-primitive Parameter Value from Memoized Component to Constant](#53-extract-default-non-primitive-parameter-value-from-memoized-component-to-constant)
+   - 5.4 [Extract to Memoized Components](#54-extract-to-memoized-components)
+   - 5.5 [Narrow Effect Dependencies](#55-narrow-effect-dependencies)
+   - 5.6 [Subscribe to Derived State](#56-subscribe-to-derived-state)
+   - 5.7 [Use Functional setState Updates](#57-use-functional-setstate-updates)
+   - 5.8 [Use Lazy State Initialization](#58-use-lazy-state-initialization)
+   - 5.9 [Use Transitions for Non-Urgent Updates](#59-use-transitions-for-non-urgent-updates)
+6. [Rendering Performance](#6-rendering-performance) — **MEDIUM**
+   - 6.1 [Animate SVG Wrapper Instead of SVG Element](#61-animate-svg-wrapper-instead-of-svg-element)
+   - 6.2 [CSS content-visibility for Long Lists](#62-css-content-visibility-for-long-lists)
+   - 6.3 [Hoist Static JSX Elements](#63-hoist-static-jsx-elements)
+   - 6.4 [Optimize SVG Precision](#64-optimize-svg-precision)
+   - 6.5 [Prevent Hydration Mismatch Without Flickering](#65-prevent-hydration-mismatch-without-flickering)
+   - 6.6 [Use Activity Component for Show/Hide](#66-use-activity-component-for-showhide)
+   - 6.7 [Use Explicit Conditional Rendering](#67-use-explicit-conditional-rendering)
+   - 6.8 [Use useTransition Over Manual Loading States](#68-use-usetransition-over-manual-loading-states)
+7. [JavaScript Performance](#7-javascript-performance) — **LOW-MEDIUM**
+   - 7.1 [Avoid Layout Thrashing](#71-avoid-layout-thrashing)
+   - 7.2 [Build Index Maps for Repeated Lookups](#72-build-index-maps-for-repeated-lookups)
+   - 7.3 [Cache Property Access in Loops](#73-cache-property-access-in-loops)
+   - 7.4 [Cache Repeated Function Calls](#74-cache-repeated-function-calls)
+   - 7.5 [Cache Storage API Calls](#75-cache-storage-api-calls)
+   - 7.6 [Combine Multiple Array Iterations](#76-combine-multiple-array-iterations)
+   - 7.7 [Early Length Check for Array Comparisons](#77-early-length-check-for-array-comparisons)
+   - 7.8 [Early Return from Functions](#78-early-return-from-functions)
+   - 7.9 [Hoist RegExp Creation](#79-hoist-regexp-creation)
+   - 7.10 [Use Loop for Min/Max Instead of Sort](#710-use-loop-for-minmax-instead-of-sort)
+   - 7.11 [Use Set/Map for O(1) Lookups](#711-use-setmap-for-o1-lookups)
+   - 7.12 [Use toSorted() Instead of sort() for Immutability](#712-use-tosorted-instead-of-sort-for-immutability)
+8. [Advanced Patterns](#8-advanced-patterns) — **LOW**
+   - 8.1 [Store Event Handlers in Refs](#81-store-event-handlers-in-refs)
+   - 8.2 [useEffectEvent for Stable Callback Refs](#82-useeffectevent-for-stable-callback-refs)
+
+---
+
+## 1. Eliminating Waterfalls
+
+**Impact: CRITICAL**
+
+Waterfalls are the #1 performance killer. Each sequential await adds full network latency. Eliminating them yields the largest gains.
+
+### 1.1 Defer Await Until Needed
+
+**Impact: HIGH (avoids blocking unused code paths)**
+
+Move `await` operations into the branches where they're actually used to avoid blocking code paths that don't need them.
+
+**Incorrect: blocks both branches**
+
+```typescript
+async function handleRequest(userId: string, skipProcessing: boolean) {
+  const userData = await fetchUserData(userId)
+  
+  if (skipProcessing) {
+    // Returns immediately but still waited for userData
+    return { skipped: true }
+  }
+  
+  // Only this branch uses userData
+  return processUserData(userData)
+}
+```
+
+**Correct: only blocks when needed**
+
+```typescript
+async function handleRequest(userId: string, skipProcessing: boolean) {
+  if (skipProcessing) {
+    // Returns immediately without waiting
+    return { skipped: true }
+  }
+  
+  // Fetch only when needed
+  const userData = await fetchUserData(userId)
+  return processUserData(userData)
+}
+```
+
+**Another example: early return optimization**
+
+```typescript
+// Incorrect: always fetches permissions
+async function updateResource(resourceId: string, userId: string) {
+  const permissions = await fetchPermissions(userId)
+  const resource = await getResource(resourceId)
+  
+  if (!resource) {
+    return { error: 'Not found' }
+  }
+  
+  if (!permissions.canEdit) {
+    return { error: 'Forbidden' }
+  }
+  
+  return await updateResourceData(resource, permissions)
+}
+
+// Correct: fetches only when needed
+async function updateResource(resourceId: string, userId: string) {
+  const resource = await getResource(resourceId)
+  
+  if (!resource) {
+    return { error: 'Not found' }
+  }
+  
+  const permissions = await fetchPermissions(userId)
+  
+  if (!permissions.canEdit) {
+    return { error: 'Forbidden' }
+  }
+  
+  return await updateResourceData(resource, permissions)
+}
+```
+
+This optimization is especially valuable when the skipped branch is frequently taken, or when the deferred operation is expensive.
+
+### 1.2 Dependency-Based Parallelization
+
+**Impact: CRITICAL (2-10× improvement)**
+
+For operations with partial dependencies, use `better-all` to maximize parallelism. It automatically starts each task at the earliest possible moment.
+
+**Incorrect: profile waits for config unnecessarily**
+
+```typescript
+const [user, config] = await Promise.all([
+  fetchUser(),
+  fetchConfig()
+])
+const profile = await fetchProfile(user.id)
+```
+
+**Correct: config and profile run in parallel**
+
+```typescript
+import { all } from 'better-all'
+
+const { user, config, profile } = await all({
+  async user() { return fetchUser() },
+  async config() { return fetchConfig() },
+  async profile() {
+    return fetchProfile((await this.$.user).id)
+  }
+})
+```
+
+**Alternative without extra dependencies:**
+
+```typescript
+const userPromise = fetchUser()
+const profilePromise = userPromise.then(user => fetchProfile(user.id))
+
+const [user, config, profile] = await Promise.all([
+  userPromise,
+  fetchConfig(),
+  profilePromise
+])
+```
+
+We can also create all the promises first, and do `Promise.all()` at the end.
+
+Reference: [https://github.com/shuding/better-all](https://github.com/shuding/better-all)
+
+### 1.3 Prevent Waterfall Chains in API Routes
+
+**Impact: CRITICAL (2-10× improvement)**
+
+In API routes and Server Actions, start independent operations immediately, even if you don't await them yet.
+
+**Incorrect: config waits for auth, data waits for both**
+
+```typescript
+export async function GET(request: Request) {
+  const session = await auth()
+  const config = await fetchConfig()
+  const data = await fetchData(session.user.id)
+  return Response.json({ data, config })
+}
+```
+
+**Correct: auth and config start immediately**
+
+```typescript
+export async function GET(request: Request) {
+  const sessionPromise = auth()
+  const configPromise = fetchConfig()
+  const session = await sessionPromise
+  const [config, data] = await Promise.all([
+    configPromise,
+    fetchData(session.user.id)
+  ])
+  return Response.json({ data, config })
+}
+```
+
+For operations with more complex dependency chains, use `better-all` to automatically maximize parallelism (see Dependency-Based Parallelization).
+
+### 1.4 Promise.all() for Independent Operations
+
+**Impact: CRITICAL (2-10× improvement)**
+
+When async operations have no interdependencies, execute them concurrently using `Promise.all()`.
+
+**Incorrect: sequential execution, 3 round trips**
+
+```typescript
+const user = await fetchUser()
+const posts = await fetchPosts()
+const comments = await fetchComments()
+```
+
+**Correct: parallel execution, 1 round trip**
+
+```typescript
+const [user, posts, comments] = await Promise.all([
+  fetchUser(),
+  fetchPosts(),
+  fetchComments()
+])
+```
+
+### 1.5 Strategic Suspense Boundaries
+
+**Impact: HIGH (faster initial paint)**
+
+Instead of awaiting data in async components before returning JSX, use Suspense boundaries to show the wrapper UI faster while data loads.
+
+**Incorrect: wrapper blocked by data fetching**
+
+```tsx
+async function Page() {
+  const data = await fetchData() // Blocks entire page
+  
+  return (
+    <div>
+      <div>Sidebar</div>
+      <div>Header</div>
+      <div>
+        <DataDisplay data={data} />
+      </div>
+      <div>Footer</div>
+    </div>
+  )
+}
+```
+
+The entire layout waits for data even though only the middle section needs it.
+
+**Correct: wrapper shows immediately, data streams in**
+
+```tsx
+function Page() {
+  return (
+    <div>
+      <div>Sidebar</div>
+      <div>Header</div>
+      <div>
+        <Suspense fallback={<Skeleton />}>
+          <DataDisplay />
+        </Suspense>
+      </div>
+      <div>Footer</div>
+    </div>
+  )
+}
+
+async function DataDisplay() {
+  const data = await fetchData() // Only blocks this component
+  return <div>{data.content}</div>
+}
+```
+
+Sidebar, Header, and Footer render immediately. Only DataDisplay waits for data.
+
+**Alternative: share promise across components**
+
+```tsx
+function Page() {
+  // Start fetch immediately, but don't await
+  const dataPromise = fetchData()
+  
+  return (
+    <div>
+      <div>Sidebar</div>
+      <div>Header</div>
+      <Suspense fallback={<Skeleton />}>
+        <DataDisplay dataPromise={dataPromise} />
+        <DataSummary dataPromise={dataPromise} />
+      </Suspense>
+      <div>Footer</div>
+    </div>
+  )
+}
+
+function DataDisplay({ dataPromise }: { dataPromise: Promise<Data> }) {
+  const data = use(dataPromise) // Unwraps the promise
+  return <div>{data.content}</div>
+}
+
+function DataSummary({ dataPromise }: { dataPromise: Promise<Data> }) {
+  const data = use(dataPromise) // Reuses the same promise
+  return <div>{data.summary}</div>
+}
+```
+
+Both components share the same promise, so only one fetch occurs. Layout renders immediately while both components wait together.
+
+**When NOT to use this pattern:**
+
+- Critical data needed for layout decisions (affects positioning)
+
+- SEO-critical content above the fold
+
+- Small, fast queries where suspense overhead isn't worth it
+
+- When you want to avoid layout shift (loading → content jump)
+
+**Trade-off:** Faster initial paint vs potential layout shift. Choose based on your UX priorities.
+
+---
+
+## 2. Bundle Size Optimization
+
+**Impact: CRITICAL**
+
+Reducing initial bundle size improves Time to Interactive and Largest Contentful Paint.
+
+### 2.1 Avoid Barrel File Imports
+
+**Impact: CRITICAL (200-800ms import cost, slow builds)**
+
+Import directly from source files instead of barrel files to avoid loading thousands of unused modules. **Barrel files** are entry points that re-export multiple modules (e.g., `index.js` that does `export * from './module'`).
+
+Popular icon and component libraries can have **up to 10,000 re-exports** in their entry file. For many React packages, **it takes 200-800ms just to import them**, affecting both development speed and production cold starts.
+
+**Why tree-shaking doesn't help:** When a library is marked as external (not bundled), the bundler can't optimize it. If you bundle it to enable tree-shaking, builds become substantially slower analyzing the entire module graph.
+
+**Incorrect: imports entire library**
+
+```tsx
+import { Check, X, Menu } from 'lucide-react'
+// Loads 1,583 modules, takes ~2.8s extra in dev
+// Runtime cost: 200-800ms on every cold start
+
+import { Button, TextField } from '@mui/material'
+// Loads 2,225 modules, takes ~4.2s extra in dev
+```
+
+**Correct: imports only what you need**
+
+```tsx
+import Check from 'lucide-react/dist/esm/icons/check'
+import X from 'lucide-react/dist/esm/icons/x'
+import Menu from 'lucide-react/dist/esm/icons/menu'
+// Loads only 3 modules (~2KB vs ~1MB)
+
+import Button from '@mui/material/Button'
+import TextField from '@mui/material/TextField'
+// Loads only what you use
+```
+
+**Alternative: Next.js 13.5+**
+
+```js
+// next.config.js - use optimizePackageImports
+module.exports = {
+  experimental: {
+    optimizePackageImports: ['lucide-react', '@mui/material']
+  }
+}
+
+// Then you can keep the ergonomic barrel imports:
+import { Check, X, Menu } from 'lucide-react'
+// Automatically transformed to direct imports at build time
+```
+
+Direct imports provide 15-70% faster dev boot, 28% faster builds, 40% faster cold starts, and significantly faster HMR.
+
+Libraries commonly affected: `lucide-react`, `@mui/material`, `@mui/icons-material`, `@tabler/icons-react`, `react-icons`, `@headlessui/react`, `@radix-ui/react-*`, `lodash`, `ramda`, `date-fns`, `rxjs`, `react-use`.
+
+Reference: [https://vercel.com/blog/how-we-optimized-package-imports-in-next-js](https://vercel.com/blog/how-we-optimized-package-imports-in-next-js)
+
+### 2.2 Conditional Module Loading
+
+**Impact: HIGH (loads large data only when needed)**
+
+Load large data or modules only when a feature is activated.
+
+**Example: lazy-load animation frames**
+
+```tsx
+function AnimationPlayer({ enabled, setEnabled }: { enabled: boolean; setEnabled: React.Dispatch<React.SetStateAction<boolean>> }) {
+  const [frames, setFrames] = useState<Frame[] | null>(null)
+
+  useEffect(() => {
+    if (enabled && !frames && typeof window !== 'undefined') {
+      import('./animation-frames.js')
+        .then(mod => setFrames(mod.frames))
+        .catch(() => setEnabled(false))
+    }
+  }, [enabled, frames, setEnabled])
+
+  if (!frames) return <Skeleton />
+  return <Canvas frames={frames} />
+}
+```
+
+The `typeof window !== 'undefined'` check prevents bundling this module for SSR, optimizing server bundle size and build speed.
+
+### 2.3 Defer Non-Critical Third-Party Libraries
+
+**Impact: MEDIUM (loads after hydration)**
+
+Analytics, logging, and error tracking don't block user interaction. Load them after hydration.
+
+**Incorrect: blocks initial bundle**
+
+```tsx
+import { Analytics } from '@vercel/analytics/react'
+
+export default function RootLayout({ children }) {
+  return (
+    <html>
+      <body>
+        {children}
+        <Analytics />
+      </body>
+    </html>
+  )
+}
+```
+
+**Correct: loads after hydration**
+
+```tsx
+import dynamic from 'next/dynamic'
+
+const Analytics = dynamic(
+  () => import('@vercel/analytics/react').then(m => m.Analytics),
+  { ssr: false }
+)
+
+export default function RootLayout({ children }) {
+  return (
+    <html>
+      <body>
+        {children}
+        <Analytics />
+      </body>
+    </html>
+  )
+}
+```
+
+### 2.4 Dynamic Imports for Heavy Components
+
+**Impact: CRITICAL (directly affects TTI and LCP)**
+
+Use `next/dynamic` to lazy-load large components not needed on initial render.
+
+**Incorrect: Monaco bundles with main chunk ~300KB**
+
+```tsx
+import { MonacoEditor } from './monaco-editor'
+
+function CodePanel({ code }: { code: string }) {
+  return <MonacoEditor value={code} />
+}
+```
+
+**Correct: Monaco loads on demand**
+
+```tsx
+import dynamic from 'next/dynamic'
+
+const MonacoEditor = dynamic(
+  () => import('./monaco-editor').then(m => m.MonacoEditor),
+  { ssr: false }
+)
+
+function CodePanel({ code }: { code: string }) {
+  return <MonacoEditor value={code} />
+}
+```
+
+### 2.5 Preload Based on User Intent
+
+**Impact: MEDIUM (reduces perceived latency)**
+
+Preload heavy bundles before they're needed to reduce perceived latency.
+
+**Example: preload on hover/focus**
+
+```tsx
+function EditorButton({ onClick }: { onClick: () => void }) {
+  const preload = () => {
+    if (typeof window !== 'undefined') {
+      void import('./monaco-editor')
+    }
+  }
+
+  return (
+    <button
+      onMouseEnter={preload}
+      onFocus={preload}
+      onClick={onClick}
+    >
+      Open Editor
+    </button>
+  )
+}
+```
+
+**Example: preload when feature flag is enabled**
+
+```tsx
+function FlagsProvider({ children, flags }: Props) {
+  useEffect(() => {
+    if (flags.editorEnabled && typeof window !== 'undefined') {
+      void import('./monaco-editor').then(mod => mod.init())
+    }
+  }, [flags.editorEnabled])
+
+  return <FlagsContext.Provider value={flags}>
+    {children}
+  </FlagsContext.Provider>
+}
+```
+
+The `typeof window !== 'undefined'` check prevents bundling preloaded modules for SSR, optimizing server bundle size and build speed.
+
+---
+
+## 3. Server-Side Performance
+
+**Impact: HIGH**
+
+Optimizing server-side rendering and data fetching eliminates server-side waterfalls and reduces response times.
+
+### 3.1 Authenticate Server Actions Like API Routes
+
+**Impact: CRITICAL (prevents unauthorized access to server mutations)**
+
+Server Actions (functions with `"use server"`) are exposed as public endpoints, just like API routes. Always verify authentication and authorization **inside** each Server Action—do not rely solely on middleware, layout guards, or page-level checks, as Server Actions can be invoked directly.
+
+Next.js documentation explicitly states: "Treat Server Actions with the same security considerations as public-facing API endpoints, and verify if the user is allowed to perform a mutation."
+
+**Incorrect: no authentication check**
+
+```typescript
+'use server'
+
+export async function deleteUser(userId: string) {
+  // Anyone can call this! No auth check
+  await db.user.delete({ where: { id: userId } })
+  return { success: true }
+}
+```
+
+**Correct: authentication inside the action**
+
+```typescript
+'use server'
+
+import { verifySession } from '@/lib/auth'
+import { unauthorized } from '@/lib/errors'
+
+export async function deleteUser(userId: string) {
+  // Always check auth inside the action
+  const session = await verifySession()
+  
+  if (!session) {
+    throw unauthorized('Must be logged in')
+  }
+  
+  // Check authorization too
+  if (session.user.role !== 'admin' && session.user.id !== userId) {
+    throw unauthorized('Cannot delete other users')
+  }
+  
+  await db.user.delete({ where: { id: userId } })
+  return { success: true }
+}
+```
+
+**With input validation:**
+
+```typescript
+'use server'
+
+import { verifySession } from '@/lib/auth'
+import { z } from 'zod'
+
+const updateProfileSchema = z.object({
+  userId: z.string().uuid(),
+  name: z.string().min(1).max(100),
+  email: z.string().email()
+})
+
+export async function updateProfile(data: unknown) {
+  // Validate input first
+  const validated = updateProfileSchema.parse(data)
+  
+  // Then authenticate
+  const session = await verifySession()
+  if (!session) {
+    throw new Error('Unauthorized')
+  }
+  
+  // Then authorize
+  if (session.user.id !== validated.userId) {
+    throw new Error('Can only update own profile')
+  }
+  
+  // Finally perform the mutation
+  await db.user.update({
+    where: { id: validated.userId },
+    data: {
+      name: validated.name,
+      email: validated.email
+    }
+  })
+  
+  return { success: true }
+}
+```
+
+Reference: [https://nextjs.org/docs/app/guides/authentication](https://nextjs.org/docs/app/guides/authentication)
+
+### 3.2 Avoid Duplicate Serialization in RSC Props
+
+**Impact: LOW (reduces network payload by avoiding duplicate serialization)**
+
+RSC→client serialization deduplicates by object reference, not value. Same reference = serialized once; new reference = serialized again. Do transformations (`.toSorted()`, `.filter()`, `.map()`) in client, not server.
+
+**Incorrect: duplicates array**
+
+```tsx
+// RSC: sends 6 strings (2 arrays × 3 items)
+<ClientList usernames={usernames} usernamesOrdered={usernames.toSorted()} />
+```
+
+**Correct: sends 3 strings**
+
+```tsx
+// RSC: send once
+<ClientList usernames={usernames} />
+
+// Client: transform there
+'use client'
+const sorted = useMemo(() => [...usernames].sort(), [usernames])
+```
+
+**Nested deduplication behavior:**
+
+```tsx
+// string[] - duplicates everything
+usernames={['a','b']} sorted={usernames.toSorted()} // sends 4 strings
+
+// object[] - duplicates array structure only
+users={[{id:1},{id:2}]} sorted={users.toSorted()} // sends 2 arrays + 2 unique objects (not 4)
+```
+
+Deduplication works recursively. Impact varies by data type:
+
+- `string[]`, `number[]`, `boolean[]`: **HIGH impact** - array + all primitives fully duplicated
+
+- `object[]`: **LOW impact** - array duplicated, but nested objects deduplicated by reference
+
+**Operations breaking deduplication: create new references**
+
+- Arrays: `.toSorted()`, `.filter()`, `.map()`, `.slice()`, `[...arr]`
+
+- Objects: `{...obj}`, `Object.assign()`, `structuredClone()`, `JSON.parse(JSON.stringify())`
+
+**More examples:**
+
+```tsx
+// ❌ Bad
+<C users={users} active={users.filter(u => u.active)} />
+<C product={product} productName={product.name} />
+
+// ✅ Good
+<C users={users} />
+<C product={product} />
+// Do filtering/destructuring in client
+```
+
+**Exception:** Pass derived data when transformation is expensive or client doesn't need original.
+
+### 3.3 Cross-Request LRU Caching
+
+**Impact: HIGH (caches across requests)**
+
+`React.cache()` only works within one request. For data shared across sequential requests (user clicks button A then button B), use an LRU cache.
+
+**Implementation:**
+
+```typescript
+import { LRUCache } from 'lru-cache'
+
+const cache = new LRUCache<string, any>({
+  max: 1000,
+  ttl: 5 * 60 * 1000  // 5 minutes
+})
+
+export async function getUser(id: string) {
+  const cached = cache.get(id)
+  if (cached) return cached
+
+  const user = await db.user.findUnique({ where: { id } })
+  cache.set(id, user)
+  return user
+}
+
+// Request 1: DB query, result cached
+// Request 2: cache hit, no DB query
+```
+
+Use when sequential user actions hit multiple endpoints needing the same data within seconds.
+
+**With Vercel's [Fluid Compute](https://vercel.com/docs/fluid-compute):** LRU caching is especially effective because multiple concurrent requests can share the same function instance and cache. This means the cache persists across requests without needing external storage like Redis.
+
+**In traditional serverless:** Each invocation runs in isolation, so consider Redis for cross-process caching.
+
+Reference: [https://github.com/isaacs/node-lru-cache](https://github.com/isaacs/node-lru-cache)
+
+### 3.4 Minimize Serialization at RSC Boundaries
+
+**Impact: HIGH (reduces data transfer size)**
+
+The React Server/Client boundary serializes all object properties into strings and embeds them in the HTML response and subsequent RSC requests. This serialized data directly impacts page weight and load time, so **size matters a lot**. Only pass fields that the client actually uses.
+
+**Incorrect: serializes all 50 fields**
+
+```tsx
+async function Page() {
+  const user = await fetchUser()  // 50 fields
+  return <Profile user={user} />
+}
+
+'use client'
+function Profile({ user }: { user: User }) {
+  return <div>{user.name}</div>  // uses 1 field
+}
+```
+
+**Correct: serializes only 1 field**
+
+```tsx
+async function Page() {
+  const user = await fetchUser()
+  return <Profile name={user.name} />
+}
+
+'use client'
+function Profile({ name }: { name: string }) {
+  return <div>{name}</div>
+}
+```
+
+### 3.5 Parallel Data Fetching with Component Composition
+
+**Impact: CRITICAL (eliminates server-side waterfalls)**
+
+React Server Components execute sequentially within a tree. Restructure with composition to parallelize data fetching.
+
+**Incorrect: Sidebar waits for Page's fetch to complete**
+
+```tsx
+export default async function Page() {
+  const header = await fetchHeader()
+  return (
+    <div>
+      <div>{header}</div>
+      <Sidebar />
+    </div>
+  )
+}
+
+async function Sidebar() {
+  const items = await fetchSidebarItems()
+  return <nav>{items.map(renderItem)}</nav>
+}
+```
+
+**Correct: both fetch simultaneously**
+
+```tsx
+async function Header() {
+  const data = await fetchHeader()
+  return <div>{data}</div>
+}
+
+async function Sidebar() {
+  const items = await fetchSidebarItems()
+  return <nav>{items.map(renderItem)}</nav>
+}
+
+export default function Page() {
+  return (
+    <div>
+      <Header />
+      <Sidebar />
+    </div>
+  )
+}
+```
+
+**Alternative with children prop:**
+
+```tsx
+async function Header() {
+  const data = await fetchHeader()
+  return <div>{data}</div>
+}
+
+async function Sidebar() {
+  const items = await fetchSidebarItems()
+  return <nav>{items.map(renderItem)}</nav>
+}
+
+function Layout({ children }: { children: ReactNode }) {
+  return (
+    <div>
+      <Header />
+      {children}
+    </div>
+  )
+}
+
+export default function Page() {
+  return (
+    <Layout>
+      <Sidebar />
+    </Layout>
+  )
+}
+```
+
+### 3.6 Per-Request Deduplication with React.cache()
+
+**Impact: MEDIUM (deduplicates within request)**
+
+Use `React.cache()` for server-side request deduplication. Authentication and database queries benefit most.
+
+**Usage:**
+
+```typescript
+import { cache } from 'react'
+
+export const getCurrentUser = cache(async () => {
+  const session = await auth()
+  if (!session?.user?.id) return null
+  return await db.user.findUnique({
+    where: { id: session.user.id }
+  })
+})
+```
+
+Within a single request, multiple calls to `getCurrentUser()` execute the query only once.
+
+**Avoid inline objects as arguments:**
+
+`React.cache()` uses shallow equality (`Object.is`) to determine cache hits. Inline objects create new references each call, preventing cache hits.
+
+**Incorrect: always cache miss**
+
+```typescript
+const getUser = cache(async (params: { uid: number }) => {
+  return await db.user.findUnique({ where: { id: params.uid } })
+})
+
+// Each call creates new object, never hits cache
+getUser({ uid: 1 })
+getUser({ uid: 1 })  // Cache miss, runs query again
+```
+
+**Correct: cache hit**
+
+```typescript
+const params = { uid: 1 }
+getUser(params)  // Query runs
+getUser(params)  // Cache hit (same reference)
+```
+
+If you must pass objects, pass the same reference:
+
+**Next.js-Specific Note:**
+
+In Next.js, the `fetch` API is automatically extended with request memoization. Requests with the same URL and options are automatically deduplicated within a single request, so you don't need `React.cache()` for `fetch` calls. However, `React.cache()` is still essential for other async tasks:
+
+- Database queries (Prisma, Drizzle, etc.)
+
+- Heavy computations
+
+- Authentication checks
+
+- File system operations
+
+- Any non-fetch async work
+
+Use `React.cache()` to deduplicate these operations across your component tree.
+
+Reference: [https://react.dev/reference/react/cache](https://react.dev/reference/react/cache)
+
+### 3.7 Use after() for Non-Blocking Operations
+
+**Impact: MEDIUM (faster response times)**
+
+Use Next.js's `after()` to schedule work that should execute after a response is sent. This prevents logging, analytics, and other side effects from blocking the response.
+
+**Incorrect: blocks response**
+
+```tsx
+import { logUserAction } from '@/app/utils'
+
+export async function POST(request: Request) {
+  // Perform mutation
+  await updateDatabase(request)
+  
+  // Logging blocks the response
+  const userAgent = request.headers.get('user-agent') || 'unknown'
+  await logUserAction({ userAgent })
+  
+  return new Response(JSON.stringify({ status: 'success' }), {
+    status: 200,
+    headers: { 'Content-Type': 'application/json' }
+  })
+}
+```
+
+**Correct: non-blocking**
+
+```tsx
+import { after } from 'next/server'
+import { headers, cookies } from 'next/headers'
+import { logUserAction } from '@/app/utils'
+
+export async function POST(request: Request) {
+  // Perform mutation
+  await updateDatabase(request)
+  
+  // Log after response is sent
+  after(async () => {
+    const userAgent = (await headers()).get('user-agent') || 'unknown'
+    const sessionCookie = (await cookies()).get('session-id')?.value || 'anonymous'
+    
+    logUserAction({ sessionCookie, userAgent })
+  })
+  
+  return new Response(JSON.stringify({ status: 'success' }), {
+    status: 200,
+    headers: { 'Content-Type': 'application/json' }
+  })
+}
+```
+
+The response is sent immediately while logging happens in the background.
+
+**Common use cases:**
+
+- Analytics tracking
+
+- Audit logging
+
+- Sending notifications
+
+- Cache invalidation
+
+- Cleanup tasks
+
+**Important notes:**
+
+- `after()` runs even if the response fails or redirects
+
+- Works in Server Actions, Route Handlers, and Server Components
+
+Reference: [https://nextjs.org/docs/app/api-reference/functions/after](https://nextjs.org/docs/app/api-reference/functions/after)
+
+---
+
+## 4. Client-Side Data Fetching
+
+**Impact: MEDIUM-HIGH**
+
+Automatic deduplication and efficient data fetching patterns reduce redundant network requests.
+
+### 4.1 Deduplicate Global Event Listeners
+
+**Impact: LOW (single listener for N components)**
+
+Use `useSWRSubscription()` to share global event listeners across component instances.
+
+**Incorrect: N instances = N listeners**
+
+```tsx
+function useKeyboardShortcut(key: string, callback: () => void) {
+  useEffect(() => {
+    const handler = (e: KeyboardEvent) => {
+      if (e.metaKey && e.key === key) {
+        callback()
+      }
+    }
+    window.addEventListener('keydown', handler)
+    return () => window.removeEventListener('keydown', handler)
+  }, [key, callback])
+}
+```
+
+When using the `useKeyboardShortcut` hook multiple times, each instance will register a new listener.
+
+**Correct: N instances = 1 listener**
+
+```tsx
+import useSWRSubscription from 'swr/subscription'
+
+// Module-level Map to track callbacks per key
+const keyCallbacks = new Map<string, Set<() => void>>()
+
+function useKeyboardShortcut(key: string, callback: () => void) {
+  // Register this callback in the Map
+  useEffect(() => {
+    if (!keyCallbacks.has(key)) {
+      keyCallbacks.set(key, new Set())
+    }
+    keyCallbacks.get(key)!.add(callback)
+
+    return () => {
+      const set = keyCallbacks.get(key)
+      if (set) {
+        set.delete(callback)
+        if (set.size === 0) {
+          keyCallbacks.delete(key)
+        }
+      }
+    }
+  }, [key, callback])
+
+  useSWRSubscription('global-keydown', () => {
+    const handler = (e: KeyboardEvent) => {
+      if (e.metaKey && keyCallbacks.has(e.key)) {
+        keyCallbacks.get(e.key)!.forEach(cb => cb())
+      }
+    }
+    window.addEventListener('keydown', handler)
+    return () => window.removeEventListener('keydown', handler)
+  })
+}
+
+function Profile() {
+  // Multiple shortcuts will share the same listener
+  useKeyboardShortcut('p', () => { /* ... */ }) 
+  useKeyboardShortcut('k', () => { /* ... */ })
+  // ...
+}
+```
+
+### 4.2 Use Passive Event Listeners for Scrolling Performance
+
+**Impact: MEDIUM (eliminates scroll delay caused by event listeners)**
+
+Add `{ passive: true }` to touch and wheel event listeners to enable immediate scrolling. Browsers normally wait for listeners to finish to check if `preventDefault()` is called, causing scroll delay.
+
+**Incorrect:**
+
+```typescript
+useEffect(() => {
+  const handleTouch = (e: TouchEvent) => console.log(e.touches[0].clientX)
+  const handleWheel = (e: WheelEvent) => console.log(e.deltaY)
+  
+  document.addEventListener('touchstart', handleTouch)
+  document.addEventListener('wheel', handleWheel)
+  
+  return () => {
+    document.removeEventListener('touchstart', handleTouch)
+    document.removeEventListener('wheel', handleWheel)
+  }
+}, [])
+```
+
+**Correct:**
+
+```typescript
+useEffect(() => {
+  const handleTouch = (e: TouchEvent) => console.log(e.touches[0].clientX)
+  const handleWheel = (e: WheelEvent) => console.log(e.deltaY)
+  
+  document.addEventListener('touchstart', handleTouch, { passive: true })
+  document.addEventListener('wheel', handleWheel, { passive: true })
+  
+  return () => {
+    document.removeEventListener('touchstart', handleTouch)
+    document.removeEventListener('wheel', handleWheel)
+  }
+}, [])
+```
+
+**Use passive when:** tracking/analytics, logging, any listener that doesn't call `preventDefault()`.
+
+**Don't use passive when:** implementing custom swipe gestures, custom zoom controls, or any listener that needs `preventDefault()`.
+
+### 4.3 Use SWR for Automatic Deduplication
+
+**Impact: MEDIUM-HIGH (automatic deduplication)**
+
+SWR enables request deduplication, caching, and revalidation across component instances.
+
+**Incorrect: no deduplication, each instance fetches**
+
+```tsx
+function UserList() {
+  const [users, setUsers] = useState([])
+  useEffect(() => {
+    fetch('/api/users')
+      .then(r => r.json())
+      .then(setUsers)
+  }, [])
+}
+```
+
+**Correct: multiple instances share one request**
+
+```tsx
+import useSWR from 'swr'
+
+function UserList() {
+  const { data: users } = useSWR('/api/users', fetcher)
+}
+```
+
+**For immutable data:**
+
+```tsx
+import { useImmutableSWR } from '@/lib/swr'
+
+function StaticContent() {
+  const { data } = useImmutableSWR('/api/config', fetcher)
+}
+```
+
+**For mutations:**
+
+```tsx
+import { useSWRMutation } from 'swr/mutation'
+
+function UpdateButton() {
+  const { trigger } = useSWRMutation('/api/user', updateUser)
+  return <button onClick={() => trigger()}>Update</button>
+}
+```
+
+Reference: [https://swr.vercel.app](https://swr.vercel.app)
+
+### 4.4 Version and Minimize localStorage Data
+
+**Impact: MEDIUM (prevents schema conflicts, reduces storage size)**
+
+Add version prefix to keys and store only needed fields. Prevents schema conflicts and accidental storage of sensitive data.
+
+**Incorrect:**
+
+```typescript
+// No version, stores everything, no error handling
+localStorage.setItem('userConfig', JSON.stringify(fullUserObject))
+const data = localStorage.getItem('userConfig')
+```
+
+**Correct:**
+
+```typescript
+const VERSION = 'v2'
+
+function saveConfig(config: { theme: string; language: string }) {
+  try {
+    localStorage.setItem(`userConfig:${VERSION}`, JSON.stringify(config))
+  } catch {
+    // Throws in incognito/private browsing, quota exceeded, or disabled
+  }
+}
+
+function loadConfig() {
+  try {
+    const data = localStorage.getItem(`userConfig:${VERSION}`)
+    return data ? JSON.parse(data) : null
+  } catch {
+    return null
+  }
+}
+
+// Migration from v1 to v2
+function migrate() {
+  try {
+    const v1 = localStorage.getItem('userConfig:v1')
+    if (v1) {
+      const old = JSON.parse(v1)
+      saveConfig({ theme: old.darkMode ? 'dark' : 'light', language: old.lang })
+      localStorage.removeItem('userConfig:v1')
+    }
+  } catch {}
+}
+```
+
+**Store minimal fields from server responses:**
+
+```typescript
+// User object has 20+ fields, only store what UI needs
+function cachePrefs(user: FullUser) {
+  try {
+    localStorage.setItem('prefs:v1', JSON.stringify({
+      theme: user.preferences.theme,
+      notifications: user.preferences.notifications
+    }))
+  } catch {}
+}
+```
+
+**Always wrap in try-catch:** `getItem()` and `setItem()` throw in incognito/private browsing (Safari, Firefox), when quota exceeded, or when disabled.
+
+**Benefits:** Schema evolution via versioning, reduced storage size, prevents storing tokens/PII/internal flags.
+
+---
+
+## 5. Re-render Optimization
+
+**Impact: MEDIUM**
+
+Reducing unnecessary re-renders minimizes wasted computation and improves UI responsiveness.
+
+### 5.1 Defer State Reads to Usage Point
+
+**Impact: MEDIUM (avoids unnecessary subscriptions)**
+
+Don't subscribe to dynamic state (searchParams, localStorage) if you only read it inside callbacks.
+
+**Incorrect: subscribes to all searchParams changes**
+
+```tsx
+function ShareButton({ chatId }: { chatId: string }) {
+  const searchParams = useSearchParams()
+
+  const handleShare = () => {
+    const ref = searchParams.get('ref')
+    shareChat(chatId, { ref })
+  }
+
+  return <button onClick={handleShare}>Share</button>
+}
+```
+
+**Correct: reads on demand, no subscription**
+
+```tsx
+function ShareButton({ chatId }: { chatId: string }) {
+  const handleShare = () => {
+    const params = new URLSearchParams(window.location.search)
+    const ref = params.get('ref')
+    shareChat(chatId, { ref })
+  }
+
+  return <button onClick={handleShare}>Share</button>
+}
+```
+
+### 5.2 Do not wrap a simple expression with a primitive result type in useMemo
+
+**Impact: LOW-MEDIUM (wasted computation on every render)**
+
+When an expression is simple (few logical or arithmetical operators) and has a primitive result type (boolean, number, string), do not wrap it in `useMemo`.
+
+Calling `useMemo` and comparing hook dependencies may consume more resources than the expression itself.
+
+**Incorrect:**
+
+```tsx
+function Header({ user, notifications }: Props) {
+  const isLoading = useMemo(() => {
+    return user.isLoading || notifications.isLoading
+  }, [user.isLoading, notifications.isLoading])
+
+  if (isLoading) return <Skeleton />
+  // return some markup
+}
+```
+
+**Correct:**
+
+```tsx
+function Header({ user, notifications }: Props) {
+  const isLoading = user.isLoading || notifications.isLoading
+
+  if (isLoading) return <Skeleton />
+  // return some markup
+}
+```
+
+### 5.3 Extract Default Non-primitive Parameter Value from Memoized Component to Constant
+
+**Impact: MEDIUM (restores memoization by using a constant for default value)**
+
+When memoized component has a default value for some non-primitive optional parameter, such as an array, function, or object, calling the component without that parameter results in broken memoization. This is because new value instances are created on every rerender, and they do not pass strict equality comparison in `memo()`.
+
+To address this issue, extract the default value into a constant.
+
+**Incorrect: `onClick` has different values on every rerender**
+
+```tsx
+const UserAvatar = memo(function UserAvatar({ onClick = () => {} }: { onClick?: () => void }) {
+  // ...
+})
+
+// Used without optional onClick
+<UserAvatar />
+```
+
+**Correct: stable default value**
+
+```tsx
+const NOOP = () => {};
+
+const UserAvatar = memo(function UserAvatar({ onClick = NOOP }: { onClick?: () => void }) {
+  // ...
+})
+
+// Used without optional onClick
+<UserAvatar />
+```
+
+### 5.4 Extract to Memoized Components
+
+**Impact: MEDIUM (enables early returns)**
+
+Extract expensive work into memoized components to enable early returns before computation.
+
+**Incorrect: computes avatar even when loading**
+
+```tsx
+function Profile({ user, loading }: Props) {
+  const avatar = useMemo(() => {
+    const id = computeAvatarId(user)
+    return <Avatar id={id} />
+  }, [user])
+
+  if (loading) return <Skeleton />
+  return <div>{avatar}</div>
+}
+```
+
+**Correct: skips computation when loading**
+
+```tsx
+const UserAvatar = memo(function UserAvatar({ user }: { user: User }) {
+  const id = useMemo(() => computeAvatarId(user), [user])
+  return <Avatar id={id} />
+})
+
+function Profile({ user, loading }: Props) {
+  if (loading) return <Skeleton />
+  return (
+    <div>
+      <UserAvatar user={user} />
+    </div>
+  )
+}
+```
+
+**Note:** If your project has [React Compiler](https://react.dev/learn/react-compiler) enabled, manual memoization with `memo()` and `useMemo()` is not necessary. The compiler automatically optimizes re-renders.
+
+### 5.5 Narrow Effect Dependencies
+
+**Impact: LOW (minimizes effect re-runs)**
+
+Specify primitive dependencies instead of objects to minimize effect re-runs.
+
+**Incorrect: re-runs on any user field change**
+
+```tsx
+useEffect(() => {
+  console.log(user.id)
+}, [user])
+```
+
+**Correct: re-runs only when id changes**
+
+```tsx
+useEffect(() => {
+  console.log(user.id)
+}, [user.id])
+```
+
+**For derived state, compute outside effect:**
+
+```tsx
+// Incorrect: runs on width=767, 766, 765...
+useEffect(() => {
+  if (width < 768) {
+    enableMobileMode()
+  }
+}, [width])
+
+// Correct: runs only on boolean transition
+const isMobile = width < 768
+useEffect(() => {
+  if (isMobile) {
+    enableMobileMode()
+  }
+}, [isMobile])
+```
+
+### 5.6 Subscribe to Derived State
+
+**Impact: MEDIUM (reduces re-render frequency)**
+
+Subscribe to derived boolean state instead of continuous values to reduce re-render frequency.
+
+**Incorrect: re-renders on every pixel change**
+
+```tsx
+function Sidebar() {
+  const width = useWindowWidth()  // updates continuously
+  const isMobile = width < 768
+  return <nav className={isMobile ? 'mobile' : 'desktop'} />
+}
+```
+
+**Correct: re-renders only when boolean changes**
+
+```tsx
+function Sidebar() {
+  const isMobile = useMediaQuery('(max-width: 767px)')
+  return <nav className={isMobile ? 'mobile' : 'desktop'} />
+}
+```
+
+### 5.7 Use Functional setState Updates
+
+**Impact: MEDIUM (prevents stale closures and unnecessary callback recreations)**
+
+When updating state based on the current state value, use the functional update form of setState instead of directly referencing the state variable. This prevents stale closures, eliminates unnecessary dependencies, and creates stable callback references.
+
+**Incorrect: requires state as dependency**
+
+```tsx
+function TodoList() {
+  const [items, setItems] = useState(initialItems)
+  
+  // Callback must depend on items, recreated on every items change
+  const addItems = useCallback((newItems: Item[]) => {
+    setItems([...items, ...newItems])
+  }, [items])  // ❌ items dependency causes recreations
+  
+  // Risk of stale closure if dependency is forgotten
+  const removeItem = useCallback((id: string) => {
+    setItems(items.filter(item => item.id !== id))
+  }, [])  // ❌ Missing items dependency - will use stale items!
+  
+  return <ItemsEditor items={items} onAdd={addItems} onRemove={removeItem} />
+}
+```
+
+The first callback is recreated every time `items` changes, which can cause child components to re-render unnecessarily. The second callback has a stale closure bug—it will always reference the initial `items` value.
+
+**Correct: stable callbacks, no stale closures**
+
+```tsx
+function TodoList() {
+  const [items, setItems] = useState(initialItems)
+  
+  // Stable callback, never recreated
+  const addItems = useCallback((newItems: Item[]) => {
+    setItems(curr => [...curr, ...newItems])
+  }, [])  // ✅ No dependencies needed
+  
+  // Always uses latest state, no stale closure risk
+  const removeItem = useCallback((id: string) => {
+    setItems(curr => curr.filter(item => item.id !== id))
+  }, [])  // ✅ Safe and stable
+  
+  return <ItemsEditor items={items} onAdd={addItems} onRemove={removeItem} />
+}
+```
+
+**Benefits:**
+
+1. **Stable callback references** - Callbacks don't need to be recreated when state changes
+
+2. **No stale closures** - Always operates on the latest state value
+
+3. **Fewer dependencies** - Simplifies dependency arrays and reduces memory leaks
+
+4. **Prevents bugs** - Eliminates the most common source of React closure bugs
+
+**When to use functional updates:**
+
+- Any setState that depends on the current state value
+
+- Inside useCallback/useMemo when state is needed
+
+- Event handlers that reference state
+
+- Async operations that update state
+
+**When direct updates are fine:**
+
+- Setting state to a static value: `setCount(0)`
+
+- Setting state from props/arguments only: `setName(newName)`
+
+- State doesn't depend on previous value
+
+**Note:** If your project has [React Compiler](https://react.dev/learn/react-compiler) enabled, the compiler can automatically optimize some cases, but functional updates are still recommended for correctness and to prevent stale closure bugs.
+
+### 5.8 Use Lazy State Initialization
+
+**Impact: MEDIUM (wasted computation on every render)**
+
+Pass a function to `useState` for expensive initial values. Without the function form, the initializer runs on every render even though the value is only used once.
+
+**Incorrect: runs on every render**
+
+```tsx
+function FilteredList({ items }: { items: Item[] }) {
+  // buildSearchIndex() runs on EVERY render, even after initialization
+  const [searchIndex, setSearchIndex] = useState(buildSearchIndex(items))
+  const [query, setQuery] = useState('')
+  
+  // When query changes, buildSearchIndex runs again unnecessarily
+  return <SearchResults index={searchIndex} query={query} />
+}
+
+function UserProfile() {
+  // JSON.parse runs on every render
+  const [settings, setSettings] = useState(
+    JSON.parse(localStorage.getItem('settings') || '{}')
+  )
+  
+  return <SettingsForm settings={settings} onChange={setSettings} />
+}
+```
+
+**Correct: runs only once**
+
+```tsx
+function FilteredList({ items }: { items: Item[] }) {
+  // buildSearchIndex() runs ONLY on initial render
+  const [searchIndex, setSearchIndex] = useState(() => buildSearchIndex(items))
+  const [query, setQuery] = useState('')
+  
+  return <SearchResults index={searchIndex} query={query} />
+}
+
+function UserProfile() {
+  // JSON.parse runs only on initial render
+  const [settings, setSettings] = useState(() => {
+    const stored = localStorage.getItem('settings')
+    return stored ? JSON.parse(stored) : {}
+  })
+  
+  return <SettingsForm settings={settings} onChange={setSettings} />
+}
+```
+
+Use lazy initialization when computing initial values from localStorage/sessionStorage, building data structures (indexes, maps), reading from the DOM, or performing heavy transformations.
+
+For simple primitives (`useState(0)`), direct references (`useState(props.value)`), or cheap literals (`useState({})`), the function form is unnecessary.
+
+### 5.9 Use Transitions for Non-Urgent Updates
+
+**Impact: MEDIUM (maintains UI responsiveness)**
+
+Mark frequent, non-urgent state updates as transitions to maintain UI responsiveness.
+
+**Incorrect: blocks UI on every scroll**
+
+```tsx
+function ScrollTracker() {
+  const [scrollY, setScrollY] = useState(0)
+  useEffect(() => {
+    const handler = () => setScrollY(window.scrollY)
+    window.addEventListener('scroll', handler, { passive: true })
+    return () => window.removeEventListener('scroll', handler)
+  }, [])
+}
+```
+
+**Correct: non-blocking updates**
+
+```tsx
+import { startTransition } from 'react'
+
+function ScrollTracker() {
+  const [scrollY, setScrollY] = useState(0)
+  useEffect(() => {
+    const handler = () => {
+      startTransition(() => setScrollY(window.scrollY))
+    }
+    window.addEventListener('scroll', handler, { passive: true })
+    return () => window.removeEventListener('scroll', handler)
+  }, [])
+}
+```
+
+---
+
+## 6. Rendering Performance
+
+**Impact: MEDIUM**
+
+Optimizing the rendering process reduces the work the browser needs to do.
+
+### 6.1 Animate SVG Wrapper Instead of SVG Element
+
+**Impact: LOW (enables hardware acceleration)**
+
+Many browsers don't have hardware acceleration for CSS3 animations on SVG elements. Wrap SVG in a `<div>` and animate the wrapper instead.
+
+**Incorrect: animating SVG directly - no hardware acceleration**
+
+```tsx
+function LoadingSpinner() {
+  return (
+    <svg 
+      className="animate-spin"
+      width="24" 
+      height="24" 
+      viewBox="0 0 24 24"
+    >
+      <circle cx="12" cy="12" r="10" stroke="currentColor" />
+    </svg>
+  )
+}
+```
+
+**Correct: animating wrapper div - hardware accelerated**
+
+```tsx
+function LoadingSpinner() {
+  return (
+    <div className="animate-spin">
+      <svg 
+        width="24" 
+        height="24" 
+        viewBox="0 0 24 24"
+      >
+        <circle cx="12" cy="12" r="10" stroke="currentColor" />
+      </svg>
+    </div>
+  )
+}
+```
+
+This applies to all CSS transforms and transitions (`transform`, `opacity`, `translate`, `scale`, `rotate`). The wrapper div allows browsers to use GPU acceleration for smoother animations.
+
+### 6.2 CSS content-visibility for Long Lists
+
+**Impact: HIGH (faster initial render)**
+
+Apply `content-visibility: auto` to defer off-screen rendering.
+
+**CSS:**
+
+```css
+.message-item {
+  content-visibility: auto;
+  contain-intrinsic-size: 0 80px;
+}
+```
+
+**Example:**
+
+```tsx
+function MessageList({ messages }: { messages: Message[] }) {
+  return (
+    <div className="overflow-y-auto h-screen">
+      {messages.map(msg => (
+        <div key={msg.id} className="message-item">
+          <Avatar user={msg.author} />
+          <div>{msg.content}</div>
+        </div>
+      ))}
+    </div>
+  )
+}
+```
+
+For 1000 messages, browser skips layout/paint for ~990 off-screen items (10× faster initial render).
+
+### 6.3 Hoist Static JSX Elements
+
+**Impact: LOW (avoids re-creation)**
+
+Extract static JSX outside components to avoid re-creation.
+
+**Incorrect: recreates element every render**
+
+```tsx
+function LoadingSkeleton() {
+  return <div className="animate-pulse h-20 bg-gray-200" />
+}
+
+function Container() {
+  return (
+    <div>
+      {loading && <LoadingSkeleton />}
+    </div>
+  )
+}
+```
+
+**Correct: reuses same element**
+
+```tsx
+const loadingSkeleton = (
+  <div className="animate-pulse h-20 bg-gray-200" />
+)
+
+function Container() {
+  return (
+    <div>
+      {loading && loadingSkeleton}
+    </div>
+  )
+}
+```
+
+This is especially helpful for large and static SVG nodes, which can be expensive to recreate on every render.
+
+**Note:** If your project has [React Compiler](https://react.dev/learn/react-compiler) enabled, the compiler automatically hoists static JSX elements and optimizes component re-renders, making manual hoisting unnecessary.
+
+### 6.4 Optimize SVG Precision
+
+**Impact: LOW (reduces file size)**
+
+Reduce SVG coordinate precision to decrease file size. The optimal precision depends on the viewBox size, but in general reducing precision should be considered.
+
+**Incorrect: excessive precision**
+
+```svg
+<path d="M 10.293847 20.847362 L 30.938472 40.192837" />
+```
+
+**Correct: 1 decimal place**
+
+```svg
+<path d="M 10.3 20.8 L 30.9 40.2" />
+```
+
+**Automate with SVGO:**
+
+```bash
+npx svgo --precision=1 --multipass icon.svg
+```
+
+### 6.5 Prevent Hydration Mismatch Without Flickering
+
+**Impact: MEDIUM (avoids visual flicker and hydration errors)**
+
+When rendering content that depends on client-side storage (localStorage, cookies), avoid both SSR breakage and post-hydration flickering by injecting a synchronous script that updates the DOM before React hydrates.
+
+**Incorrect: breaks SSR**
+
+```tsx
+function ThemeWrapper({ children }: { children: ReactNode }) {
+  // localStorage is not available on server - throws error
+  const theme = localStorage.getItem('theme') || 'light'
+  
+  return (
+    <div className={theme}>
+      {children}
+    </div>
+  )
+}
+```
+
+Server-side rendering will fail because `localStorage` is undefined.
+
+**Incorrect: visual flickering**
+
+```tsx
+function ThemeWrapper({ children }: { children: ReactNode }) {
+  const [theme, setTheme] = useState('light')
+  
+  useEffect(() => {
+    // Runs after hydration - causes visible flash
+    const stored = localStorage.getItem('theme')
+    if (stored) {
+      setTheme(stored)
+    }
+  }, [])
+  
+  return (
+    <div className={theme}>
+      {children}
+    </div>
+  )
+}
+```
+
+Component first renders with default value (`light`), then updates after hydration, causing a visible flash of incorrect content.
+
+**Correct: no flicker, no hydration mismatch**
+
+```tsx
+function ThemeWrapper({ children }: { children: ReactNode }) {
+  return (
+    <>
+      <div id="theme-wrapper">
+        {children}
+      </div>
+      <script
+        dangerouslySetInnerHTML={{
+          __html: `
+            (function() {
+              try {
+                var theme = localStorage.getItem('theme') || 'light';
+                var el = document.getElementById('theme-wrapper');
+                if (el) el.className = theme;
+              } catch (e) {}
+            })();
+          `,
+        }}
+      />
+    </>
+  )
+}
+```
+
+The inline script executes synchronously before showing the element, ensuring the DOM already has the correct value. No flickering, no hydration mismatch.
+
+This pattern is especially useful for theme toggles, user preferences, authentication states, and any client-only data that should render immediately without flashing default values.
+
+### 6.6 Use Activity Component for Show/Hide
+
+**Impact: MEDIUM (preserves state/DOM)**
+
+Use React's `<Activity>` to preserve state/DOM for expensive components that frequently toggle visibility.
+
+**Usage:**
+
+```tsx
+import { Activity } from 'react'
+
+function Dropdown({ isOpen }: Props) {
+  return (
+    <Activity mode={isOpen ? 'visible' : 'hidden'}>
+      <ExpensiveMenu />
+    </Activity>
+  )
+}
+```
+
+Avoids expensive re-renders and state loss.
+
+### 6.7 Use Explicit Conditional Rendering
+
+**Impact: LOW (prevents rendering 0 or NaN)**
+
+Use explicit ternary operators (`? :`) instead of `&&` for conditional rendering when the condition can be `0`, `NaN`, or other falsy values that render.
+
+**Incorrect: renders "0" when count is 0**
+
+```tsx
+function Badge({ count }: { count: number }) {
+  return (
+    <div>
+      {count && <span className="badge">{count}</span>}
+    </div>
+  )
+}
+
+// When count = 0, renders: <div>0</div>
+// When count = 5, renders: <div><span class="badge">5</span></div>
+```
+
+**Correct: renders nothing when count is 0**
+
+```tsx
+function Badge({ count }: { count: number }) {
+  return (
+    <div>
+      {count > 0 ? <span className="badge">{count}</span> : null}
+    </div>
+  )
+}
+
+// When count = 0, renders: <div></div>
+// When count = 5, renders: <div><span class="badge">5</span></div>
+```
+
+### 6.8 Use useTransition Over Manual Loading States
+
+**Impact: LOW (reduces re-renders and improves code clarity)**
+
+Use `useTransition` instead of manual `useState` for loading states. This provides built-in `isPending` state and automatically manages transitions.
+
+**Incorrect: manual loading state**
+
+```tsx
+function SearchResults() {
+  const [query, setQuery] = useState('')
+  const [results, setResults] = useState([])
+  const [isLoading, setIsLoading] = useState(false)
+
+  const handleSearch = async (value: string) => {
+    setIsLoading(true)
+    setQuery(value)
+    const data = await fetchResults(value)
+    setResults(data)
+    setIsLoading(false)
+  }
+
+  return (
+    <>
+      <input onChange={(e) => handleSearch(e.target.value)} />
+      {isLoading && <Spinner />}
+      <ResultsList results={results} />
+    </>
+  )
+}
+```
+
+**Correct: useTransition with built-in pending state**
+
+```tsx
+import { useTransition, useState } from 'react'
+
+function SearchResults() {
+  const [query, setQuery] = useState('')
+  const [results, setResults] = useState([])
+  const [isPending, startTransition] = useTransition()
+
+  const handleSearch = (value: string) => {
+    setQuery(value) // Update input immediately
+    
+    startTransition(async () => {
+      // Fetch and update results
+      const data = await fetchResults(value)
+      setResults(data)
+    })
+  }
+
+  return (
+    <>
+      <input onChange={(e) => handleSearch(e.target.value)} />
+      {isPending && <Spinner />}
+      <ResultsList results={results} />
+    </>
+  )
+}
+```
+
+**Benefits:**
+
+- **Automatic pending state**: No need to manually manage `setIsLoading(true/false)`
+
+- **Error resilience**: Pending state correctly resets even if the transition throws
+
+- **Better responsiveness**: Keeps the UI responsive during updates
+
+- **Interrupt handling**: New transitions automatically cancel pending ones
+
+Reference: [https://react.dev/reference/react/useTransition](https://react.dev/reference/react/useTransition)
+
+---
+
+## 7. JavaScript Performance
+
+**Impact: LOW-MEDIUM**
+
+Micro-optimizations for hot paths can add up to meaningful improvements.
+
+### 7.1 Avoid Layout Thrashing
+
+**Impact: MEDIUM (prevents forced synchronous layouts and reduces performance bottlenecks)**
+
+Avoid interleaving style writes with layout reads. When you read a layout property (like `offsetWidth`, `getBoundingClientRect()`, or `getComputedStyle()`) between style changes, the browser is forced to trigger a synchronous reflow.
+
+**This is OK: browser batches style changes**
+
+```typescript
+function updateElementStyles(element: HTMLElement) {
+  // Each line invalidates style, but browser batches the recalculation
+  element.style.width = '100px'
+  element.style.height = '200px'
+  element.style.backgroundColor = 'blue'
+  element.style.border = '1px solid black'
+}
+```
+
+**Incorrect: interleaved reads and writes force reflows**
+
+```typescript
+function layoutThrashing(element: HTMLElement) {
+  element.style.width = '100px'
+  const width = element.offsetWidth  // Forces reflow
+  element.style.height = '200px'
+  const height = element.offsetHeight  // Forces another reflow
+}
+```
+
+**Correct: batch writes, then read once**
+
+```typescript
+function updateElementStyles(element: HTMLElement) {
+  // Batch all writes together
+  element.style.width = '100px'
+  element.style.height = '200px'
+  element.style.backgroundColor = 'blue'
+  element.style.border = '1px solid black'
+  
+  // Read after all writes are done (single reflow)
+  const { width, height } = element.getBoundingClientRect()
+}
+```
+
+**Correct: batch reads, then writes**
+
+```typescript
+function updateElementStyles(element: HTMLElement) {
+  element.classList.add('highlighted-box')
+  
+  const { width, height } = element.getBoundingClientRect()
+}
+```
+
+**Better: use CSS classes**
+
+**React example:**
+
+```tsx
+// Incorrect: interleaving style changes with layout queries
+function Box({ isHighlighted }: { isHighlighted: boolean }) {
+  const ref = useRef<HTMLDivElement>(null)
+  
+  useEffect(() => {
+    if (ref.current && isHighlighted) {
+      ref.current.style.width = '100px'
+      const width = ref.current.offsetWidth // Forces layout
+      ref.current.style.height = '200px'
+    }
+  }, [isHighlighted])
+  
+  return <div ref={ref}>Content</div>
+}
+
+// Correct: toggle class
+function Box({ isHighlighted }: { isHighlighted: boolean }) {
+  return (
+    <div className={isHighlighted ? 'highlighted-box' : ''}>
+      Content
+    </div>
+  )
+}
+```
+
+Prefer CSS classes over inline styles when possible. CSS files are cached by the browser, and classes provide better separation of concerns and are easier to maintain.
+
+See [this gist](https://gist.github.com/paulirish/5d52fb081b3570c81e3a) and [CSS Triggers](https://csstriggers.com/) for more information on layout-forcing operations.
+
+### 7.2 Build Index Maps for Repeated Lookups
+
+**Impact: LOW-MEDIUM (1M ops to 2K ops)**
+
+Multiple `.find()` calls by the same key should use a Map.
+
+**Incorrect (O(n) per lookup):**
+
+```typescript
+function processOrders(orders: Order[], users: User[]) {
+  return orders.map(order => ({
+    ...order,
+    user: users.find(u => u.id === order.userId)
+  }))
+}
+```
+
+**Correct (O(1) per lookup):**
+
+```typescript
+function processOrders(orders: Order[], users: User[]) {
+  const userById = new Map(users.map(u => [u.id, u]))
+
+  return orders.map(order => ({
+    ...order,
+    user: userById.get(order.userId)
+  }))
+}
+```
+
+Build map once (O(n)), then all lookups are O(1).
+
+For 1000 orders × 1000 users: 1M ops → 2K ops.
+
+### 7.3 Cache Property Access in Loops
+
+**Impact: LOW-MEDIUM (reduces lookups)**
+
+Cache object property lookups in hot paths.
+
+**Incorrect: 3 lookups × N iterations**
+
+```typescript
+for (let i = 0; i < arr.length; i++) {
+  process(obj.config.settings.value)
+}
+```
+
+**Correct: 1 lookup total**
+
+```typescript
+const value = obj.config.settings.value
+const len = arr.length
+for (let i = 0; i < len; i++) {
+  process(value)
+}
+```
+
+### 7.4 Cache Repeated Function Calls
+
+**Impact: MEDIUM (avoid redundant computation)**
+
+Use a module-level Map to cache function results when the same function is called repeatedly with the same inputs during render.
+
+**Incorrect: redundant computation**
+
+```typescript
+function ProjectList({ projects }: { projects: Project[] }) {
+  return (
+    <div>
+      {projects.map(project => {
+        // slugify() called 100+ times for same project names
+        const slug = slugify(project.name)
+        
+        return <ProjectCard key={project.id} slug={slug} />
+      })}
+    </div>
+  )
+}
+```
+
+**Correct: cached results**
+
+```typescript
+// Module-level cache
+const slugifyCache = new Map<string, string>()
+
+function cachedSlugify(text: string): string {
+  if (slugifyCache.has(text)) {
+    return slugifyCache.get(text)!
+  }
+  const result = slugify(text)
+  slugifyCache.set(text, result)
+  return result
+}
+
+function ProjectList({ projects }: { projects: Project[] }) {
+  return (
+    <div>
+      {projects.map(project => {
+        // Computed only once per unique project name
+        const slug = cachedSlugify(project.name)
+        
+        return <ProjectCard key={project.id} slug={slug} />
+      })}
+    </div>
+  )
+}
+```
+
+**Simpler pattern for single-value functions:**
+
+```typescript
+let isLoggedInCache: boolean | null = null
+
+function isLoggedIn(): boolean {
+  if (isLoggedInCache !== null) {
+    return isLoggedInCache
+  }
+  
+  isLoggedInCache = document.cookie.includes('auth=')
+  return isLoggedInCache
+}
+
+// Clear cache when auth changes
+function onAuthChange() {
+  isLoggedInCache = null
+}
+```
+
+Use a Map (not a hook) so it works everywhere: utilities, event handlers, not just React components.
+
+Reference: [https://vercel.com/blog/how-we-made-the-vercel-dashboard-twice-as-fast](https://vercel.com/blog/how-we-made-the-vercel-dashboard-twice-as-fast)
+
+### 7.5 Cache Storage API Calls
+
+**Impact: LOW-MEDIUM (reduces expensive I/O)**
+
+`localStorage`, `sessionStorage`, and `document.cookie` are synchronous and expensive. Cache reads in memory.
+
+**Incorrect: reads storage on every call**
+
+```typescript
+function getTheme() {
+  return localStorage.getItem('theme') ?? 'light'
+}
+// Called 10 times = 10 storage reads
+```
+
+**Correct: Map cache**
+
+```typescript
+const storageCache = new Map<string, string | null>()
+
+function getLocalStorage(key: string) {
+  if (!storageCache.has(key)) {
+    storageCache.set(key, localStorage.getItem(key))
+  }
+  return storageCache.get(key)
+}
+
+function setLocalStorage(key: string, value: string) {
+  localStorage.setItem(key, value)
+  storageCache.set(key, value)  // keep cache in sync
+}
+```
+
+Use a Map (not a hook) so it works everywhere: utilities, event handlers, not just React components.
+
+**Cookie caching:**
+
+```typescript
+let cookieCache: Record<string, string> | null = null
+
+function getCookie(name: string) {
+  if (!cookieCache) {
+    cookieCache = Object.fromEntries(
+      document.cookie.split('; ').map(c => c.split('='))
+    )
+  }
+  return cookieCache[name]
+}
+```
+
+**Important: invalidate on external changes**
+
+```typescript
+window.addEventListener('storage', (e) => {
+  if (e.key) storageCache.delete(e.key)
+})
+
+document.addEventListener('visibilitychange', () => {
+  if (document.visibilityState === 'visible') {
+    storageCache.clear()
+  }
+})
+```
+
+If storage can change externally (another tab, server-set cookies), invalidate cache:
+
+### 7.6 Combine Multiple Array Iterations
+
+**Impact: LOW-MEDIUM (reduces iterations)**
+
+Multiple `.filter()` or `.map()` calls iterate the array multiple times. Combine into one loop.
+
+**Incorrect: 3 iterations**
+
+```typescript
+const admins = users.filter(u => u.isAdmin)
+const testers = users.filter(u => u.isTester)
+const inactive = users.filter(u => !u.isActive)
+```
+
+**Correct: 1 iteration**
+
+```typescript
+const admins: User[] = []
+const testers: User[] = []
+const inactive: User[] = []
+
+for (const user of users) {
+  if (user.isAdmin) admins.push(user)
+  if (user.isTester) testers.push(user)
+  if (!user.isActive) inactive.push(user)
+}
+```
+
+### 7.7 Early Length Check for Array Comparisons
+
+**Impact: MEDIUM-HIGH (avoids expensive operations when lengths differ)**
+
+When comparing arrays with expensive operations (sorting, deep equality, serialization), check lengths first. If lengths differ, the arrays cannot be equal.
+
+In real-world applications, this optimization is especially valuable when the comparison runs in hot paths (event handlers, render loops).
+
+**Incorrect: always runs expensive comparison**
+
+```typescript
+function hasChanges(current: string[], original: string[]) {
+  // Always sorts and joins, even when lengths differ
+  return current.sort().join() !== original.sort().join()
+}
+```
+
+Two O(n log n) sorts run even when `current.length` is 5 and `original.length` is 100. There is also overhead of joining the arrays and comparing the strings.
+
+**Correct (O(1) length check first):**
+
+```typescript
+function hasChanges(current: string[], original: string[]) {
+  // Early return if lengths differ
+  if (current.length !== original.length) {
+    return true
+  }
+  // Only sort when lengths match
+  const currentSorted = current.toSorted()
+  const originalSorted = original.toSorted()
+  for (let i = 0; i < currentSorted.length; i++) {
+    if (currentSorted[i] !== originalSorted[i]) {
+      return true
+    }
+  }
+  return false
+}
+```
+
+This new approach is more efficient because:
+
+- It avoids the overhead of sorting and joining the arrays when lengths differ
+
+- It avoids consuming memory for the joined strings (especially important for large arrays)
+
+- It avoids mutating the original arrays
+
+- It returns early when a difference is found
+
+### 7.8 Early Return from Functions
+
+**Impact: LOW-MEDIUM (avoids unnecessary computation)**
+
+Return early when result is determined to skip unnecessary processing.
+
+**Incorrect: processes all items even after finding answer**
+
+```typescript
+function validateUsers(users: User[]) {
+  let hasError = false
+  let errorMessage = ''
+  
+  for (const user of users) {
+    if (!user.email) {
+      hasError = true
+      errorMessage = 'Email required'
+    }
+    if (!user.name) {
+      hasError = true
+      errorMessage = 'Name required'
+    }
+    // Continues checking all users even after error found
+  }
+  
+  return hasError ? { valid: false, error: errorMessage } : { valid: true }
+}
+```
+
+**Correct: returns immediately on first error**
+
+```typescript
+function validateUsers(users: User[]) {
+  for (const user of users) {
+    if (!user.email) {
+      return { valid: false, error: 'Email required' }
+    }
+    if (!user.name) {
+      return { valid: false, error: 'Name required' }
+    }
+  }
+
+  return { valid: true }
+}
+```
+
+### 7.9 Hoist RegExp Creation
+
+**Impact: LOW-MEDIUM (avoids recreation)**
+
+Don't create RegExp inside render. Hoist to module scope or memoize with `useMemo()`.
+
+**Incorrect: new RegExp every render**
+
+```tsx
+function Highlighter({ text, query }: Props) {
+  const regex = new RegExp(`(${query})`, 'gi')
+  const parts = text.split(regex)
+  return <>{parts.map((part, i) => ...)}</>
+}
+```
+
+**Correct: memoize or hoist**
+
+```tsx
+const EMAIL_REGEX = /^[^\s@]+@[^\s@]+\.[^\s@]+$/
+
+function Highlighter({ text, query }: Props) {
+  const regex = useMemo(
+    () => new RegExp(`(${escapeRegex(query)})`, 'gi'),
+    [query]
+  )
+  const parts = text.split(regex)
+  return <>{parts.map((part, i) => ...)}</>
+}
+```
+
+**Warning: global regex has mutable state**
+
+```typescript
+const regex = /foo/g
+regex.test('foo')  // true, lastIndex = 3
+regex.test('foo')  // false, lastIndex = 0
+```
+
+Global regex (`/g`) has mutable `lastIndex` state:
+
+### 7.10 Use Loop for Min/Max Instead of Sort
+
+**Impact: LOW (O(n) instead of O(n log n))**
+
+Finding the smallest or largest element only requires a single pass through the array. Sorting is wasteful and slower.
+
+**Incorrect (O(n log n) - sort to find latest):**
+
+```typescript
+interface Project {
+  id: string
+  name: string
+  updatedAt: number
+}
+
+function getLatestProject(projects: Project[]) {
+  const sorted = [...projects].sort((a, b) => b.updatedAt - a.updatedAt)
+  return sorted[0]
+}
+```
+
+Sorts the entire array just to find the maximum value.
+
+**Incorrect (O(n log n) - sort for oldest and newest):**
+
+```typescript
+function getOldestAndNewest(projects: Project[]) {
+  const sorted = [...projects].sort((a, b) => a.updatedAt - b.updatedAt)
+  return { oldest: sorted[0], newest: sorted[sorted.length - 1] }
+}
+```
+
+Still sorts unnecessarily when only min/max are needed.
+
+**Correct (O(n) - single loop):**
+
+```typescript
+function getLatestProject(projects: Project[]) {
+  if (projects.length === 0) return null
+  
+  let latest = projects[0]
+  
+  for (let i = 1; i < projects.length; i++) {
+    if (projects[i].updatedAt > latest.updatedAt) {
+      latest = projects[i]
+    }
+  }
+  
+  return latest
+}
+
+function getOldestAndNewest(projects: Project[]) {
+  if (projects.length === 0) return { oldest: null, newest: null }
+  
+  let oldest = projects[0]
+  let newest = projects[0]
+  
+  for (let i = 1; i < projects.length; i++) {
+    if (projects[i].updatedAt < oldest.updatedAt) oldest = projects[i]
+    if (projects[i].updatedAt > newest.updatedAt) newest = projects[i]
+  }
+  
+  return { oldest, newest }
+}
+```
+
+Single pass through the array, no copying, no sorting.
+
+**Alternative: Math.min/Math.max for small arrays**
+
+```typescript
+const numbers = [5, 2, 8, 1, 9]
+const min = Math.min(...numbers)
+const max = Math.max(...numbers)
+```
+
+This works for small arrays, but can be slower or just throw an error for very large arrays due to spread operator limitations. Maximal array length is approximately 124000 in Chrome 143 and 638000 in Safari 18; exact numbers may vary - see [the fiddle](https://jsfiddle.net/qw1jabsx/4/). Use the loop approach for reliability.
+
+### 7.11 Use Set/Map for O(1) Lookups
+
+**Impact: LOW-MEDIUM (O(n) to O(1))**
+
+Convert arrays to Set/Map for repeated membership checks.
+
+**Incorrect (O(n) per check):**
+
+```typescript
+const allowedIds = ['a', 'b', 'c', ...]
+items.filter(item => allowedIds.includes(item.id))
+```
+
+**Correct (O(1) per check):**
+
+```typescript
+const allowedIds = new Set(['a', 'b', 'c', ...])
+items.filter(item => allowedIds.has(item.id))
+```
+
+### 7.12 Use toSorted() Instead of sort() for Immutability
+
+**Impact: MEDIUM-HIGH (prevents mutation bugs in React state)**
+
+`.sort()` mutates the array in place, which can cause bugs with React state and props. Use `.toSorted()` to create a new sorted array without mutation.
+
+**Incorrect: mutates original array**
+
+```typescript
+function UserList({ users }: { users: User[] }) {
+  // Mutates the users prop array!
+  const sorted = useMemo(
+    () => users.sort((a, b) => a.name.localeCompare(b.name)),
+    [users]
+  )
+  return <div>{sorted.map(renderUser)}</div>
+}
+```
+
+**Correct: creates new array**
+
+```typescript
+function UserList({ users }: { users: User[] }) {
+  // Creates new sorted array, original unchanged
+  const sorted = useMemo(
+    () => users.toSorted((a, b) => a.name.localeCompare(b.name)),
+    [users]
+  )
+  return <div>{sorted.map(renderUser)}</div>
+}
+```
+
+**Why this matters in React:**
+
+1. Props/state mutations break React's immutability model - React expects props and state to be treated as read-only
+
+2. Causes stale closure bugs - Mutating arrays inside closures (callbacks, effects) can lead to unexpected behavior
+
+**Browser support: fallback for older browsers**
+
+```typescript
+// Fallback for older browsers
+const sorted = [...items].sort((a, b) => a.value - b.value)
+```
+
+`.toSorted()` is available in all modern browsers (Chrome 110+, Safari 16+, Firefox 115+, Node.js 20+). For older environments, use spread operator:
+
+**Other immutable array methods:**
+
+- `.toSorted()` - immutable sort
+
+- `.toReversed()` - immutable reverse
+
+- `.toSpliced()` - immutable splice
+
+- `.with()` - immutable element replacement
+
+---
+
+## 8. Advanced Patterns
+
+**Impact: LOW**
+
+Advanced patterns for specific cases that require careful implementation.
+
+### 8.1 Store Event Handlers in Refs
+
+**Impact: LOW (stable subscriptions)**
+
+Store callbacks in refs when used in effects that shouldn't re-subscribe on callback changes.
+
+**Incorrect: re-subscribes on every render**
+
+```tsx
+function useWindowEvent(event: string, handler: (e) => void) {
+  useEffect(() => {
+    window.addEventListener(event, handler)
+    return () => window.removeEventListener(event, handler)
+  }, [event, handler])
+}
+```
+
+**Correct: stable subscription**
+
+```tsx
+import { useEffectEvent } from 'react'
+
+function useWindowEvent(event: string, handler: (e) => void) {
+  const onEvent = useEffectEvent(handler)
+
+  useEffect(() => {
+    window.addEventListener(event, onEvent)
+    return () => window.removeEventListener(event, onEvent)
+  }, [event])
+}
+```
+
+**Alternative: use `useEffectEvent` if you're on latest React:**
+
+`useEffectEvent` provides a cleaner API for the same pattern: it creates a stable function reference that always calls the latest version of the handler.
+
+### 8.2 useEffectEvent for Stable Callback Refs
+
+**Impact: LOW (prevents effect re-runs)**
+
+Access latest values in callbacks without adding them to dependency arrays. Prevents effect re-runs while avoiding stale closures.
+
+**Incorrect: effect re-runs on every callback change**
+
+```tsx
+function SearchInput({ onSearch }: { onSearch: (q: string) => void }) {
+  const [query, setQuery] = useState('')
+
+  useEffect(() => {
+    const timeout = setTimeout(() => onSearch(query), 300)
+    return () => clearTimeout(timeout)
+  }, [query, onSearch])
+}
+```
+
+**Correct: using React's useEffectEvent**
+
+```tsx
+import { useEffectEvent } from 'react';
+
+function SearchInput({ onSearch }: { onSearch: (q: string) => void }) {
+  const [query, setQuery] = useState('')
+  const onSearchEvent = useEffectEvent(onSearch)
+
+  useEffect(() => {
+    const timeout = setTimeout(() => onSearchEvent(query), 300)
+    return () => clearTimeout(timeout)
+  }, [query])
+}
+```
+
+---
+
+## References
+
+1. [https://react.dev](https://react.dev)
+2. [https://nextjs.org](https://nextjs.org)
+3. [https://swr.vercel.app](https://swr.vercel.app)
+4. [https://github.com/shuding/better-all](https://github.com/shuding/better-all)
+5. [https://github.com/isaacs/node-lru-cache](https://github.com/isaacs/node-lru-cache)
+6. [https://vercel.com/blog/how-we-optimized-package-imports-in-next-js](https://vercel.com/blog/how-we-optimized-package-imports-in-next-js)
+7. [https://vercel.com/blog/how-we-made-the-vercel-dashboard-twice-as-fast](https://vercel.com/blog/how-we-made-the-vercel-dashboard-twice-as-fast)
diff --git a/.github/skills/vercel-react-best-practices/SKILL.md b/.github/skills/vercel-react-best-practices/SKILL.md
new file mode 100644
index 0000000..b064716
--- /dev/null
+++ b/.github/skills/vercel-react-best-practices/SKILL.md
@@ -0,0 +1,125 @@
+---
+name: vercel-react-best-practices
+description: React and Next.js performance optimization guidelines from Vercel Engineering. This skill should be used when writing, reviewing, or refactoring React/Next.js code to ensure optimal performance patterns. Triggers on tasks involving React components, Next.js pages, data fetching, bundle optimization, or performance improvements.
+license: MIT
+metadata:
+  author: vercel
+  version: "1.0.0"
+---
+
+# Vercel React Best Practices
+
+Comprehensive performance optimization guide for React and Next.js applications, maintained by Vercel. Contains 45 rules across 8 categories, prioritized by impact to guide automated refactoring and code generation.
+
+## When to Apply
+
+Reference these guidelines when:
+- Writing new React components or Next.js pages
+- Implementing data fetching (client or server-side)
+- Reviewing code for performance issues
+- Refactoring existing React/Next.js code
+- Optimizing bundle size or load times
+
+## Rule Categories by Priority
+
+| Priority | Category | Impact | Prefix |
+|----------|----------|--------|--------|
+| 1 | Eliminating Waterfalls | CRITICAL | `async-` |
+| 2 | Bundle Size Optimization | CRITICAL | `bundle-` |
+| 3 | Server-Side Performance | HIGH | `server-` |
+| 4 | Client-Side Data Fetching | MEDIUM-HIGH | `client-` |
+| 5 | Re-render Optimization | MEDIUM | `rerender-` |
+| 6 | Rendering Performance | MEDIUM | `rendering-` |
+| 7 | JavaScript Performance | LOW-MEDIUM | `js-` |
+| 8 | Advanced Patterns | LOW | `advanced-` |
+
+## Quick Reference
+
+### 1. Eliminating Waterfalls (CRITICAL)
+
+- `async-defer-await` - Move await into branches where actually used
+- `async-parallel` - Use Promise.all() for independent operations
+- `async-dependencies` - Use better-all for partial dependencies
+- `async-api-routes` - Start promises early, await late in API routes
+- `async-suspense-boundaries` - Use Suspense to stream content
+
+### 2. Bundle Size Optimization (CRITICAL)
+
+- `bundle-barrel-imports` - Import directly, avoid barrel files
+- `bundle-dynamic-imports` - Use next/dynamic for heavy components
+- `bundle-defer-third-party` - Load analytics/logging after hydration
+- `bundle-conditional` - Load modules only when feature is activated
+- `bundle-preload` - Preload on hover/focus for perceived speed
+
+### 3. Server-Side Performance (HIGH)
+
+- `server-cache-react` - Use React.cache() for per-request deduplication
+- `server-cache-lru` - Use LRU cache for cross-request caching
+- `server-serialization` - Minimize data passed to client components
+- `server-parallel-fetching` - Restructure components to parallelize fetches
+- `server-after-nonblocking` - Use after() for non-blocking operations
+
+### 4. Client-Side Data Fetching (MEDIUM-HIGH)
+
+- `client-swr-dedup` - Use SWR for automatic request deduplication
+- `client-event-listeners` - Deduplicate global event listeners
+
+### 5. Re-render Optimization (MEDIUM)
+
+- `rerender-defer-reads` - Don't subscribe to state only used in callbacks
+- `rerender-memo` - Extract expensive work into memoized components
+- `rerender-dependencies` - Use primitive dependencies in effects
+- `rerender-derived-state` - Subscribe to derived booleans, not raw values
+- `rerender-functional-setstate` - Use functional setState for stable callbacks
+- `rerender-lazy-state-init` - Pass function to useState for expensive values
+- `rerender-transitions` - Use startTransition for non-urgent updates
+
+### 6. Rendering Performance (MEDIUM)
+
+- `rendering-animate-svg-wrapper` - Animate div wrapper, not SVG element
+- `rendering-content-visibility` - Use content-visibility for long lists
+- `rendering-hoist-jsx` - Extract static JSX outside components
+- `rendering-svg-precision` - Reduce SVG coordinate precision
+- `rendering-hydration-no-flicker` - Use inline script for client-only data
+- `rendering-activity` - Use Activity component for show/hide
+- `rendering-conditional-render` - Use ternary, not && for conditionals
+
+### 7. JavaScript Performance (LOW-MEDIUM)
+
+- `js-batch-dom-css` - Group CSS changes via classes or cssText
+- `js-index-maps` - Build Map for repeated lookups
+- `js-cache-property-access` - Cache object properties in loops
+- `js-cache-function-results` - Cache function results in module-level Map
+- `js-cache-storage` - Cache localStorage/sessionStorage reads
+- `js-combine-iterations` - Combine multiple filter/map into one loop
+- `js-length-check-first` - Check array length before expensive comparison
+- `js-early-exit` - Return early from functions
+- `js-hoist-regexp` - Hoist RegExp creation outside loops
+- `js-min-max-loop` - Use loop for min/max instead of sort
+- `js-set-map-lookups` - Use Set/Map for O(1) lookups
+- `js-tosorted-immutable` - Use toSorted() for immutability
+
+### 8. Advanced Patterns (LOW)
+
+- `advanced-event-handler-refs` - Store event handlers in refs
+- `advanced-use-latest` - useLatest for stable callback refs
+
+## How to Use
+
+Read individual rule files for detailed explanations and code examples:
+
+```
+rules/async-parallel.md
+rules/bundle-barrel-imports.md
+rules/_sections.md
+```
+
+Each rule file contains:
+- Brief explanation of why it matters
+- Incorrect code example with explanation
+- Correct code example with explanation
+- Additional context and references
+
+## Full Compiled Document
+
+For the complete guide with all rules expanded: `AGENTS.md`
diff --git a/.github/skills/vercel-react-best-practices/rules/advanced-event-handler-refs.md b/.github/skills/vercel-react-best-practices/rules/advanced-event-handler-refs.md
new file mode 100644
index 0000000..97e7ade
--- /dev/null
+++ b/.github/skills/vercel-react-best-practices/rules/advanced-event-handler-refs.md
@@ -0,0 +1,55 @@
+---
+title: Store Event Handlers in Refs
+impact: LOW
+impactDescription: stable subscriptions
+tags: advanced, hooks, refs, event-handlers, optimization
+---
+
+## Store Event Handlers in Refs
+
+Store callbacks in refs when used in effects that shouldn't re-subscribe on callback changes.
+
+**Incorrect (re-subscribes on every render):**
+
+```tsx
+function useWindowEvent(event: string, handler: (e) => void) {
+  useEffect(() => {
+    window.addEventListener(event, handler)
+    return () => window.removeEventListener(event, handler)
+  }, [event, handler])
+}
+```
+
+**Correct (stable subscription):**
+
+```tsx
+function useWindowEvent(event: string, handler: (e) => void) {
+  const handlerRef = useRef(handler)
+  useEffect(() => {
+    handlerRef.current = handler
+  }, [handler])
+
+  useEffect(() => {
+    const listener = (e) => handlerRef.current(e)
+    window.addEventListener(event, listener)
+    return () => window.removeEventListener(event, listener)
+  }, [event])
+}
+```
+
+**Alternative: use `useEffectEvent` if you're on latest React:**
+
+```tsx
+import { useEffectEvent } from 'react'
+
+function useWindowEvent(event: string, handler: (e) => void) {
+  const onEvent = useEffectEvent(handler)
+
+  useEffect(() => {
+    window.addEventListener(event, onEvent)
+    return () => window.removeEventListener(event, onEvent)
+  }, [event])
+}
+```
+
+`useEffectEvent` provides a cleaner API for the same pattern: it creates a stable function reference that always calls the latest version of the handler.
diff --git a/.github/skills/vercel-react-best-practices/rules/advanced-use-latest.md b/.github/skills/vercel-react-best-practices/rules/advanced-use-latest.md
new file mode 100644
index 0000000..9c7cb50
--- /dev/null
+++ b/.github/skills/vercel-react-best-practices/rules/advanced-use-latest.md
@@ -0,0 +1,39 @@
+---
+title: useEffectEvent for Stable Callback Refs
+impact: LOW
+impactDescription: prevents effect re-runs
+tags: advanced, hooks, useEffectEvent, refs, optimization
+---
+
+## useEffectEvent for Stable Callback Refs
+
+Access latest values in callbacks without adding them to dependency arrays. Prevents effect re-runs while avoiding stale closures.
+
+**Incorrect (effect re-runs on every callback change):**
+
+```tsx
+function SearchInput({ onSearch }: { onSearch: (q: string) => void }) {
+  const [query, setQuery] = useState('')
+
+  useEffect(() => {
+    const timeout = setTimeout(() => onSearch(query), 300)
+    return () => clearTimeout(timeout)
+  }, [query, onSearch])
+}
+```
+
+**Correct (using React's useEffectEvent):**
+
+```tsx
+import { useEffectEvent } from 'react';
+
+function SearchInput({ onSearch }: { onSearch: (q: string) => void }) {
+  const [query, setQuery] = useState('')
+  const onSearchEvent = useEffectEvent(onSearch)
+
+  useEffect(() => {
+    const timeout = setTimeout(() => onSearchEvent(query), 300)
+    return () => clearTimeout(timeout)
+  }, [query])
+}
+```
diff --git a/.github/skills/vercel-react-best-practices/rules/async-api-routes.md b/.github/skills/vercel-react-best-practices/rules/async-api-routes.md
new file mode 100644
index 0000000..6feda1e
--- /dev/null
+++ b/.github/skills/vercel-react-best-practices/rules/async-api-routes.md
@@ -0,0 +1,38 @@
+---
+title: Prevent Waterfall Chains in API Routes
+impact: CRITICAL
+impactDescription: 2-10× improvement
+tags: api-routes, server-actions, waterfalls, parallelization
+---
+
+## Prevent Waterfall Chains in API Routes
+
+In API routes and Server Actions, start independent operations immediately, even if you don't await them yet.
+
+**Incorrect (config waits for auth, data waits for both):**
+
+```typescript
+export async function GET(request: Request) {
+  const session = await auth()
+  const config = await fetchConfig()
+  const data = await fetchData(session.user.id)
+  return Response.json({ data, config })
+}
+```
+
+**Correct (auth and config start immediately):**
+
+```typescript
+export async function GET(request: Request) {
+  const sessionPromise = auth()
+  const configPromise = fetchConfig()
+  const session = await sessionPromise
+  const [config, data] = await Promise.all([
+    configPromise,
+    fetchData(session.user.id)
+  ])
+  return Response.json({ data, config })
+}
+```
+
+For operations with more complex dependency chains, use `better-all` to automatically maximize parallelism (see Dependency-Based Parallelization).
diff --git a/.github/skills/vercel-react-best-practices/rules/async-defer-await.md b/.github/skills/vercel-react-best-practices/rules/async-defer-await.md
new file mode 100644
index 0000000..ea7082a
--- /dev/null
+++ b/.github/skills/vercel-react-best-practices/rules/async-defer-await.md
@@ -0,0 +1,80 @@
+---
+title: Defer Await Until Needed
+impact: HIGH
+impactDescription: avoids blocking unused code paths
+tags: async, await, conditional, optimization
+---
+
+## Defer Await Until Needed
+
+Move `await` operations into the branches where they're actually used to avoid blocking code paths that don't need them.
+
+**Incorrect (blocks both branches):**
+
+```typescript
+async function handleRequest(userId: string, skipProcessing: boolean) {
+  const userData = await fetchUserData(userId)
+  
+  if (skipProcessing) {
+    // Returns immediately but still waited for userData
+    return { skipped: true }
+  }
+  
+  // Only this branch uses userData
+  return processUserData(userData)
+}
+```
+
+**Correct (only blocks when needed):**
+
+```typescript
+async function handleRequest(userId: string, skipProcessing: boolean) {
+  if (skipProcessing) {
+    // Returns immediately without waiting
+    return { skipped: true }
+  }
+  
+  // Fetch only when needed
+  const userData = await fetchUserData(userId)
+  return processUserData(userData)
+}
+```
+
+**Another example (early return optimization):**
+
+```typescript
+// Incorrect: always fetches permissions
+async function updateResource(resourceId: string, userId: string) {
+  const permissions = await fetchPermissions(userId)
+  const resource = await getResource(resourceId)
+  
+  if (!resource) {
+    return { error: 'Not found' }
+  }
+  
+  if (!permissions.canEdit) {
+    return { error: 'Forbidden' }
+  }
+  
+  return await updateResourceData(resource, permissions)
+}
+
+// Correct: fetches only when needed
+async function updateResource(resourceId: string, userId: string) {
+  const resource = await getResource(resourceId)
+  
+  if (!resource) {
+    return { error: 'Not found' }
+  }
+  
+  const permissions = await fetchPermissions(userId)
+  
+  if (!permissions.canEdit) {
+    return { error: 'Forbidden' }
+  }
+  
+  return await updateResourceData(resource, permissions)
+}
+```
+
+This optimization is especially valuable when the skipped branch is frequently taken, or when the deferred operation is expensive.
diff --git a/.github/skills/vercel-react-best-practices/rules/async-dependencies.md b/.github/skills/vercel-react-best-practices/rules/async-dependencies.md
new file mode 100644
index 0000000..0484eba
--- /dev/null
+++ b/.github/skills/vercel-react-best-practices/rules/async-dependencies.md
@@ -0,0 +1,51 @@
+---
+title: Dependency-Based Parallelization
+impact: CRITICAL
+impactDescription: 2-10× improvement
+tags: async, parallelization, dependencies, better-all
+---
+
+## Dependency-Based Parallelization
+
+For operations with partial dependencies, use `better-all` to maximize parallelism. It automatically starts each task at the earliest possible moment.
+
+**Incorrect (profile waits for config unnecessarily):**
+
+```typescript
+const [user, config] = await Promise.all([
+  fetchUser(),
+  fetchConfig()
+])
+const profile = await fetchProfile(user.id)
+```
+
+**Correct (config and profile run in parallel):**
+
+```typescript
+import { all } from 'better-all'
+
+const { user, config, profile } = await all({
+  async user() { return fetchUser() },
+  async config() { return fetchConfig() },
+  async profile() {
+    return fetchProfile((await this.$.user).id)
+  }
+})
+```
+
+**Alternative without extra dependencies:**
+
+We can also create all the promises first, and do `Promise.all()` at the end.
+
+```typescript
+const userPromise = fetchUser()
+const profilePromise = userPromise.then(user => fetchProfile(user.id))
+
+const [user, config, profile] = await Promise.all([
+  userPromise,
+  fetchConfig(),
+  profilePromise
+])
+```
+
+Reference: [https://github.com/shuding/better-all](https://github.com/shuding/better-all)
diff --git a/.github/skills/vercel-react-best-practices/rules/async-parallel.md b/.github/skills/vercel-react-best-practices/rules/async-parallel.md
new file mode 100644
index 0000000..64133f6
--- /dev/null
+++ b/.github/skills/vercel-react-best-practices/rules/async-parallel.md
@@ -0,0 +1,28 @@
+---
+title: Promise.all() for Independent Operations
+impact: CRITICAL
+impactDescription: 2-10× improvement
+tags: async, parallelization, promises, waterfalls
+---
+
+## Promise.all() for Independent Operations
+
+When async operations have no interdependencies, execute them concurrently using `Promise.all()`.
+
+**Incorrect (sequential execution, 3 round trips):**
+
+```typescript
+const user = await fetchUser()
+const posts = await fetchPosts()
+const comments = await fetchComments()
+```
+
+**Correct (parallel execution, 1 round trip):**
+
+```typescript
+const [user, posts, comments] = await Promise.all([
+  fetchUser(),
+  fetchPosts(),
+  fetchComments()
+])
+```
diff --git a/.github/skills/vercel-react-best-practices/rules/async-suspense-boundaries.md b/.github/skills/vercel-react-best-practices/rules/async-suspense-boundaries.md
new file mode 100644
index 0000000..1fbc05b
--- /dev/null
+++ b/.github/skills/vercel-react-best-practices/rules/async-suspense-boundaries.md
@@ -0,0 +1,99 @@
+---
+title: Strategic Suspense Boundaries
+impact: HIGH
+impactDescription: faster initial paint
+tags: async, suspense, streaming, layout-shift
+---
+
+## Strategic Suspense Boundaries
+
+Instead of awaiting data in async components before returning JSX, use Suspense boundaries to show the wrapper UI faster while data loads.
+
+**Incorrect (wrapper blocked by data fetching):**
+
+```tsx
+async function Page() {
+  const data = await fetchData() // Blocks entire page
+  
+  return (
+    <div>
+      <div>Sidebar</div>
+      <div>Header</div>
+      <div>
+        <DataDisplay data={data} />
+      </div>
+      <div>Footer</div>
+    </div>
+  )
+}
+```
+
+The entire layout waits for data even though only the middle section needs it.
+
+**Correct (wrapper shows immediately, data streams in):**
+
+```tsx
+function Page() {
+  return (
+    <div>
+      <div>Sidebar</div>
+      <div>Header</div>
+      <div>
+        <Suspense fallback={<Skeleton />}>
+          <DataDisplay />
+        </Suspense>
+      </div>
+      <div>Footer</div>
+    </div>
+  )
+}
+
+async function DataDisplay() {
+  const data = await fetchData() // Only blocks this component
+  return <div>{data.content}</div>
+}
+```
+
+Sidebar, Header, and Footer render immediately. Only DataDisplay waits for data.
+
+**Alternative (share promise across components):**
+
+```tsx
+function Page() {
+  // Start fetch immediately, but don't await
+  const dataPromise = fetchData()
+  
+  return (
+    <div>
+      <div>Sidebar</div>
+      <div>Header</div>
+      <Suspense fallback={<Skeleton />}>
+        <DataDisplay dataPromise={dataPromise} />
+        <DataSummary dataPromise={dataPromise} />
+      </Suspense>
+      <div>Footer</div>
+    </div>
+  )
+}
+
+function DataDisplay({ dataPromise }: { dataPromise: Promise<Data> }) {
+  const data = use(dataPromise) // Unwraps the promise
+  return <div>{data.content}</div>
+}
+
+function DataSummary({ dataPromise }: { dataPromise: Promise<Data> }) {
+  const data = use(dataPromise) // Reuses the same promise
+  return <div>{data.summary}</div>
+}
+```
+
+Both components share the same promise, so only one fetch occurs. Layout renders immediately while both components wait together.
+
+**When NOT to use this pattern:**
+
+- Critical data needed for layout decisions (affects positioning)
+- SEO-critical content above the fold
+- Small, fast queries where suspense overhead isn't worth it
+- When you want to avoid layout shift (loading → content jump)
+
+**Trade-off:** Faster initial paint vs potential layout shift. Choose based on your UX priorities.
diff --git a/.github/skills/vercel-react-best-practices/rules/bundle-barrel-imports.md b/.github/skills/vercel-react-best-practices/rules/bundle-barrel-imports.md
new file mode 100644
index 0000000..ee48f32
--- /dev/null
+++ b/.github/skills/vercel-react-best-practices/rules/bundle-barrel-imports.md
@@ -0,0 +1,59 @@
+---
+title: Avoid Barrel File Imports
+impact: CRITICAL
+impactDescription: 200-800ms import cost, slow builds
+tags: bundle, imports, tree-shaking, barrel-files, performance
+---
+
+## Avoid Barrel File Imports
+
+Import directly from source files instead of barrel files to avoid loading thousands of unused modules. **Barrel files** are entry points that re-export multiple modules (e.g., `index.js` that does `export * from './module'`).
+
+Popular icon and component libraries can have **up to 10,000 re-exports** in their entry file. For many React packages, **it takes 200-800ms just to import them**, affecting both development speed and production cold starts.
+
+**Why tree-shaking doesn't help:** When a library is marked as external (not bundled), the bundler can't optimize it. If you bundle it to enable tree-shaking, builds become substantially slower analyzing the entire module graph.
+
+**Incorrect (imports entire library):**
+
+```tsx
+import { Check, X, Menu } from 'lucide-react'
+// Loads 1,583 modules, takes ~2.8s extra in dev
+// Runtime cost: 200-800ms on every cold start
+
+import { Button, TextField } from '@mui/material'
+// Loads 2,225 modules, takes ~4.2s extra in dev
+```
+
+**Correct (imports only what you need):**
+
+```tsx
+import Check from 'lucide-react/dist/esm/icons/check'
+import X from 'lucide-react/dist/esm/icons/x'
+import Menu from 'lucide-react/dist/esm/icons/menu'
+// Loads only 3 modules (~2KB vs ~1MB)
+
+import Button from '@mui/material/Button'
+import TextField from '@mui/material/TextField'
+// Loads only what you use
+```
+
+**Alternative (Next.js 13.5+):**
+
+```js
+// next.config.js - use optimizePackageImports
+module.exports = {
+  experimental: {
+    optimizePackageImports: ['lucide-react', '@mui/material']
+  }
+}
+
+// Then you can keep the ergonomic barrel imports:
+import { Check, X, Menu } from 'lucide-react'
+// Automatically transformed to direct imports at build time
+```
+
+Direct imports provide 15-70% faster dev boot, 28% faster builds, 40% faster cold starts, and significantly faster HMR.
+
+Libraries commonly affected: `lucide-react`, `@mui/material`, `@mui/icons-material`, `@tabler/icons-react`, `react-icons`, `@headlessui/react`, `@radix-ui/react-*`, `lodash`, `ramda`, `date-fns`, `rxjs`, `react-use`.
+
+Reference: [How we optimized package imports in Next.js](https://vercel.com/blog/how-we-optimized-package-imports-in-next-js)
diff --git a/.github/skills/vercel-react-best-practices/rules/bundle-conditional.md b/.github/skills/vercel-react-best-practices/rules/bundle-conditional.md
new file mode 100644
index 0000000..99d6fc9
--- /dev/null
+++ b/.github/skills/vercel-react-best-practices/rules/bundle-conditional.md
@@ -0,0 +1,31 @@
+---
+title: Conditional Module Loading
+impact: HIGH
+impactDescription: loads large data only when needed
+tags: bundle, conditional-loading, lazy-loading
+---
+
+## Conditional Module Loading
+
+Load large data or modules only when a feature is activated.
+
+**Example (lazy-load animation frames):**
+
+```tsx
+function AnimationPlayer({ enabled, setEnabled }: { enabled: boolean; setEnabled: React.Dispatch<React.SetStateAction<boolean>> }) {
+  const [frames, setFrames] = useState<Frame[] | null>(null)
+
+  useEffect(() => {
+    if (enabled && !frames && typeof window !== 'undefined') {
+      import('./animation-frames.js')
+        .then(mod => setFrames(mod.frames))
+        .catch(() => setEnabled(false))
+    }
+  }, [enabled, frames, setEnabled])
+
+  if (!frames) return <Skeleton />
+  return <Canvas frames={frames} />
+}
+```
+
+The `typeof window !== 'undefined'` check prevents bundling this module for SSR, optimizing server bundle size and build speed.
diff --git a/.github/skills/vercel-react-best-practices/rules/bundle-defer-third-party.md b/.github/skills/vercel-react-best-practices/rules/bundle-defer-third-party.md
new file mode 100644
index 0000000..db041d1
--- /dev/null
+++ b/.github/skills/vercel-react-best-practices/rules/bundle-defer-third-party.md
@@ -0,0 +1,49 @@
+---
+title: Defer Non-Critical Third-Party Libraries
+impact: MEDIUM
+impactDescription: loads after hydration
+tags: bundle, third-party, analytics, defer
+---
+
+## Defer Non-Critical Third-Party Libraries
+
+Analytics, logging, and error tracking don't block user interaction. Load them after hydration.
+
+**Incorrect (blocks initial bundle):**
+
+```tsx
+import { Analytics } from '@vercel/analytics/react'
+
+export default function RootLayout({ children }) {
+  return (
+    <html>
+      <body>
+        {children}
+        <Analytics />
+      </body>
+    </html>
+  )
+}
+```
+
+**Correct (loads after hydration):**
+
+```tsx
+import dynamic from 'next/dynamic'
+
+const Analytics = dynamic(
+  () => import('@vercel/analytics/react').then(m => m.Analytics),
+  { ssr: false }
+)
+
+export default function RootLayout({ children }) {
+  return (
+    <html>
+      <body>
+        {children}
+        <Analytics />
+      </body>
+    </html>
+  )
+}
+```
diff --git a/.github/skills/vercel-react-best-practices/rules/bundle-dynamic-imports.md b/.github/skills/vercel-react-best-practices/rules/bundle-dynamic-imports.md
new file mode 100644
index 0000000..60b6269
--- /dev/null
+++ b/.github/skills/vercel-react-best-practices/rules/bundle-dynamic-imports.md
@@ -0,0 +1,35 @@
+---
+title: Dynamic Imports for Heavy Components
+impact: CRITICAL
+impactDescription: directly affects TTI and LCP
+tags: bundle, dynamic-import, code-splitting, next-dynamic
+---
+
+## Dynamic Imports for Heavy Components
+
+Use `next/dynamic` to lazy-load large components not needed on initial render.
+
+**Incorrect (Monaco bundles with main chunk ~300KB):**
+
+```tsx
+import { MonacoEditor } from './monaco-editor'
+
+function CodePanel({ code }: { code: string }) {
+  return <MonacoEditor value={code} />
+}
+```
+
+**Correct (Monaco loads on demand):**
+
+```tsx
+import dynamic from 'next/dynamic'
+
+const MonacoEditor = dynamic(
+  () => import('./monaco-editor').then(m => m.MonacoEditor),
+  { ssr: false }
+)
+
+function CodePanel({ code }: { code: string }) {
+  return <MonacoEditor value={code} />
+}
+```
diff --git a/.github/skills/vercel-react-best-practices/rules/bundle-preload.md b/.github/skills/vercel-react-best-practices/rules/bundle-preload.md
new file mode 100644
index 0000000..7000504
--- /dev/null
+++ b/.github/skills/vercel-react-best-practices/rules/bundle-preload.md
@@ -0,0 +1,50 @@
+---
+title: Preload Based on User Intent
+impact: MEDIUM
+impactDescription: reduces perceived latency
+tags: bundle, preload, user-intent, hover
+---
+
+## Preload Based on User Intent
+
+Preload heavy bundles before they're needed to reduce perceived latency.
+
+**Example (preload on hover/focus):**
+
+```tsx
+function EditorButton({ onClick }: { onClick: () => void }) {
+  const preload = () => {
+    if (typeof window !== 'undefined') {
+      void import('./monaco-editor')
+    }
+  }
+
+  return (
+    <button
+      onMouseEnter={preload}
+      onFocus={preload}
+      onClick={onClick}
+    >
+      Open Editor
+    </button>
+  )
+}
+```
+
+**Example (preload when feature flag is enabled):**
+
+```tsx
+function FlagsProvider({ children, flags }: Props) {
+  useEffect(() => {
+    if (flags.editorEnabled && typeof window !== 'undefined') {
+      void import('./monaco-editor').then(mod => mod.init())
+    }
+  }, [flags.editorEnabled])
+
+  return <FlagsContext.Provider value={flags}>
+    {children}
+  </FlagsContext.Provider>
+}
+```
+
+The `typeof window !== 'undefined'` check prevents bundling preloaded modules for SSR, optimizing server bundle size and build speed.
diff --git a/.github/skills/vercel-react-best-practices/rules/client-event-listeners.md b/.github/skills/vercel-react-best-practices/rules/client-event-listeners.md
new file mode 100644
index 0000000..aad4ae9
--- /dev/null
+++ b/.github/skills/vercel-react-best-practices/rules/client-event-listeners.md
@@ -0,0 +1,74 @@
+---
+title: Deduplicate Global Event Listeners
+impact: LOW
+impactDescription: single listener for N components
+tags: client, swr, event-listeners, subscription
+---
+
+## Deduplicate Global Event Listeners
+
+Use `useSWRSubscription()` to share global event listeners across component instances.
+
+**Incorrect (N instances = N listeners):**
+
+```tsx
+function useKeyboardShortcut(key: string, callback: () => void) {
+  useEffect(() => {
+    const handler = (e: KeyboardEvent) => {
+      if (e.metaKey && e.key === key) {
+        callback()
+      }
+    }
+    window.addEventListener('keydown', handler)
+    return () => window.removeEventListener('keydown', handler)
+  }, [key, callback])
+}
+```
+
+When using the `useKeyboardShortcut` hook multiple times, each instance will register a new listener.
+
+**Correct (N instances = 1 listener):**
+
+```tsx
+import useSWRSubscription from 'swr/subscription'
+
+// Module-level Map to track callbacks per key
+const keyCallbacks = new Map<string, Set<() => void>>()
+
+function useKeyboardShortcut(key: string, callback: () => void) {
+  // Register this callback in the Map
+  useEffect(() => {
+    if (!keyCallbacks.has(key)) {
+      keyCallbacks.set(key, new Set())
+    }
+    keyCallbacks.get(key)!.add(callback)
+
+    return () => {
+      const set = keyCallbacks.get(key)
+      if (set) {
+        set.delete(callback)
+        if (set.size === 0) {
+          keyCallbacks.delete(key)
+        }
+      }
+    }
+  }, [key, callback])
+
+  useSWRSubscription('global-keydown', () => {
+    const handler = (e: KeyboardEvent) => {
+      if (e.metaKey && keyCallbacks.has(e.key)) {
+        keyCallbacks.get(e.key)!.forEach(cb => cb())
+      }
+    }
+    window.addEventListener('keydown', handler)
+    return () => window.removeEventListener('keydown', handler)
+  })
+}
+
+function Profile() {
+  // Multiple shortcuts will share the same listener
+  useKeyboardShortcut('p', () => { /* ... */ }) 
+  useKeyboardShortcut('k', () => { /* ... */ })
+  // ...
+}
+```
diff --git a/.github/skills/vercel-react-best-practices/rules/client-localstorage-schema.md b/.github/skills/vercel-react-best-practices/rules/client-localstorage-schema.md
new file mode 100644
index 0000000..d30a1a7
--- /dev/null
+++ b/.github/skills/vercel-react-best-practices/rules/client-localstorage-schema.md
@@ -0,0 +1,71 @@
+---
+title: Version and Minimize localStorage Data
+impact: MEDIUM
+impactDescription: prevents schema conflicts, reduces storage size
+tags: client, localStorage, storage, versioning, data-minimization
+---
+
+## Version and Minimize localStorage Data
+
+Add version prefix to keys and store only needed fields. Prevents schema conflicts and accidental storage of sensitive data.
+
+**Incorrect:**
+
+```typescript
+// No version, stores everything, no error handling
+localStorage.setItem('userConfig', JSON.stringify(fullUserObject))
+const data = localStorage.getItem('userConfig')
+```
+
+**Correct:**
+
+```typescript
+const VERSION = 'v2'
+
+function saveConfig(config: { theme: string; language: string }) {
+  try {
+    localStorage.setItem(`userConfig:${VERSION}`, JSON.stringify(config))
+  } catch {
+    // Throws in incognito/private browsing, quota exceeded, or disabled
+  }
+}
+
+function loadConfig() {
+  try {
+    const data = localStorage.getItem(`userConfig:${VERSION}`)
+    return data ? JSON.parse(data) : null
+  } catch {
+    return null
+  }
+}
+
+// Migration from v1 to v2
+function migrate() {
+  try {
+    const v1 = localStorage.getItem('userConfig:v1')
+    if (v1) {
+      const old = JSON.parse(v1)
+      saveConfig({ theme: old.darkMode ? 'dark' : 'light', language: old.lang })
+      localStorage.removeItem('userConfig:v1')
+    }
+  } catch {}
+}
+```
+
+**Store minimal fields from server responses:**
+
+```typescript
+// User object has 20+ fields, only store what UI needs
+function cachePrefs(user: FullUser) {
+  try {
+    localStorage.setItem('prefs:v1', JSON.stringify({
+      theme: user.preferences.theme,
+      notifications: user.preferences.notifications
+    }))
+  } catch {}
+}
+```
+
+**Always wrap in try-catch:** `getItem()` and `setItem()` throw in incognito/private browsing (Safari, Firefox), when quota exceeded, or when disabled.
+
+**Benefits:** Schema evolution via versioning, reduced storage size, prevents storing tokens/PII/internal flags.
diff --git a/.github/skills/vercel-react-best-practices/rules/client-passive-event-listeners.md b/.github/skills/vercel-react-best-practices/rules/client-passive-event-listeners.md
new file mode 100644
index 0000000..ce39a88
--- /dev/null
+++ b/.github/skills/vercel-react-best-practices/rules/client-passive-event-listeners.md
@@ -0,0 +1,48 @@
+---
+title: Use Passive Event Listeners for Scrolling Performance
+impact: MEDIUM
+impactDescription: eliminates scroll delay caused by event listeners
+tags: client, event-listeners, scrolling, performance, touch, wheel
+---
+
+## Use Passive Event Listeners for Scrolling Performance
+
+Add `{ passive: true }` to touch and wheel event listeners to enable immediate scrolling. Browsers normally wait for listeners to finish to check if `preventDefault()` is called, causing scroll delay.
+
+**Incorrect:**
+
+```typescript
+useEffect(() => {
+  const handleTouch = (e: TouchEvent) => console.log(e.touches[0].clientX)
+  const handleWheel = (e: WheelEvent) => console.log(e.deltaY)
+  
+  document.addEventListener('touchstart', handleTouch)
+  document.addEventListener('wheel', handleWheel)
+  
+  return () => {
+    document.removeEventListener('touchstart', handleTouch)
+    document.removeEventListener('wheel', handleWheel)
+  }
+}, [])
+```
+
+**Correct:**
+
+```typescript
+useEffect(() => {
+  const handleTouch = (e: TouchEvent) => console.log(e.touches[0].clientX)
+  const handleWheel = (e: WheelEvent) => console.log(e.deltaY)
+  
+  document.addEventListener('touchstart', handleTouch, { passive: true })
+  document.addEventListener('wheel', handleWheel, { passive: true })
+  
+  return () => {
+    document.removeEventListener('touchstart', handleTouch)
+    document.removeEventListener('wheel', handleWheel)
+  }
+}, [])
+```
+
+**Use passive when:** tracking/analytics, logging, any listener that doesn't call `preventDefault()`.
+
+**Don't use passive when:** implementing custom swipe gestures, custom zoom controls, or any listener that needs `preventDefault()`.
diff --git a/.github/skills/vercel-react-best-practices/rules/client-swr-dedup.md b/.github/skills/vercel-react-best-practices/rules/client-swr-dedup.md
new file mode 100644
index 0000000..2a430f2
--- /dev/null
+++ b/.github/skills/vercel-react-best-practices/rules/client-swr-dedup.md
@@ -0,0 +1,56 @@
+---
+title: Use SWR for Automatic Deduplication
+impact: MEDIUM-HIGH
+impactDescription: automatic deduplication
+tags: client, swr, deduplication, data-fetching
+---
+
+## Use SWR for Automatic Deduplication
+
+SWR enables request deduplication, caching, and revalidation across component instances.
+
+**Incorrect (no deduplication, each instance fetches):**
+
+```tsx
+function UserList() {
+  const [users, setUsers] = useState([])
+  useEffect(() => {
+    fetch('/api/users')
+      .then(r => r.json())
+      .then(setUsers)
+  }, [])
+}
+```
+
+**Correct (multiple instances share one request):**
+
+```tsx
+import useSWR from 'swr'
+
+function UserList() {
+  const { data: users } = useSWR('/api/users', fetcher)
+}
+```
+
+**For immutable data:**
+
+```tsx
+import { useImmutableSWR } from '@/lib/swr'
+
+function StaticContent() {
+  const { data } = useImmutableSWR('/api/config', fetcher)
+}
+```
+
+**For mutations:**
+
+```tsx
+import { useSWRMutation } from 'swr/mutation'
+
+function UpdateButton() {
+  const { trigger } = useSWRMutation('/api/user', updateUser)
+  return <button onClick={() => trigger()}>Update</button>
+}
+```
+
+Reference: [https://swr.vercel.app](https://swr.vercel.app)
diff --git a/.github/skills/vercel-react-best-practices/rules/js-batch-dom-css.md b/.github/skills/vercel-react-best-practices/rules/js-batch-dom-css.md
new file mode 100644
index 0000000..a62d84e
--- /dev/null
+++ b/.github/skills/vercel-react-best-practices/rules/js-batch-dom-css.md
@@ -0,0 +1,107 @@
+---
+title: Avoid Layout Thrashing
+impact: MEDIUM
+impactDescription: prevents forced synchronous layouts and reduces performance bottlenecks
+tags: javascript, dom, css, performance, reflow, layout-thrashing
+---
+
+## Avoid Layout Thrashing
+
+Avoid interleaving style writes with layout reads. When you read a layout property (like `offsetWidth`, `getBoundingClientRect()`, or `getComputedStyle()`) between style changes, the browser is forced to trigger a synchronous reflow.
+
+**This is OK (browser batches style changes):**
+```typescript
+function updateElementStyles(element: HTMLElement) {
+  // Each line invalidates style, but browser batches the recalculation
+  element.style.width = '100px'
+  element.style.height = '200px'
+  element.style.backgroundColor = 'blue'
+  element.style.border = '1px solid black'
+}
+```
+
+**Incorrect (interleaved reads and writes force reflows):**
+```typescript
+function layoutThrashing(element: HTMLElement) {
+  element.style.width = '100px'
+  const width = element.offsetWidth  // Forces reflow
+  element.style.height = '200px'
+  const height = element.offsetHeight  // Forces another reflow
+}
+```
+
+**Correct (batch writes, then read once):**
+```typescript
+function updateElementStyles(element: HTMLElement) {
+  // Batch all writes together
+  element.style.width = '100px'
+  element.style.height = '200px'
+  element.style.backgroundColor = 'blue'
+  element.style.border = '1px solid black'
+  
+  // Read after all writes are done (single reflow)
+  const { width, height } = element.getBoundingClientRect()
+}
+```
+
+**Correct (batch reads, then writes):**
+```typescript
+function avoidThrashing(element: HTMLElement) {
+  // Read phase - all layout queries first
+  const rect1 = element.getBoundingClientRect()
+  const offsetWidth = element.offsetWidth
+  const offsetHeight = element.offsetHeight
+  
+  // Write phase - all style changes after
+  element.style.width = '100px'
+  element.style.height = '200px'
+}
+```
+
+**Better: use CSS classes**
+```css
+.highlighted-box {
+  width: 100px;
+  height: 200px;
+  background-color: blue;
+  border: 1px solid black;
+}
+```
+```typescript
+function updateElementStyles(element: HTMLElement) {
+  element.classList.add('highlighted-box')
+  
+  const { width, height } = element.getBoundingClientRect()
+}
+```
+
+**React example:**
+```tsx
+// Incorrect: interleaving style changes with layout queries
+function Box({ isHighlighted }: { isHighlighted: boolean }) {
+  const ref = useRef<HTMLDivElement>(null)
+  
+  useEffect(() => {
+    if (ref.current && isHighlighted) {
+      ref.current.style.width = '100px'
+      const width = ref.current.offsetWidth // Forces layout
+      ref.current.style.height = '200px'
+    }
+  }, [isHighlighted])
+  
+  return <div ref={ref}>Content</div>
+}
+
+// Correct: toggle class
+function Box({ isHighlighted }: { isHighlighted: boolean }) {
+  return (
+    <div className={isHighlighted ? 'highlighted-box' : ''}>
+      Content
+    </div>
+  )
+}
+```
+
+Prefer CSS classes over inline styles when possible. CSS files are cached by the browser, and classes provide better separation of concerns and are easier to maintain.
+
+See [this gist](https://gist.github.com/paulirish/5d52fb081b3570c81e3a) and [CSS Triggers](https://csstriggers.com/) for more information on layout-forcing operations.
diff --git a/.github/skills/vercel-react-best-practices/rules/js-cache-function-results.md b/.github/skills/vercel-react-best-practices/rules/js-cache-function-results.md
new file mode 100644
index 0000000..180f8ac
--- /dev/null
+++ b/.github/skills/vercel-react-best-practices/rules/js-cache-function-results.md
@@ -0,0 +1,80 @@
+---
+title: Cache Repeated Function Calls
+impact: MEDIUM
+impactDescription: avoid redundant computation
+tags: javascript, cache, memoization, performance
+---
+
+## Cache Repeated Function Calls
+
+Use a module-level Map to cache function results when the same function is called repeatedly with the same inputs during render.
+
+**Incorrect (redundant computation):**
+
+```typescript
+function ProjectList({ projects }: { projects: Project[] }) {
+  return (
+    <div>
+      {projects.map(project => {
+        // slugify() called 100+ times for same project names
+        const slug = slugify(project.name)
+        
+        return <ProjectCard key={project.id} slug={slug} />
+      })}
+    </div>
+  )
+}
+```
+
+**Correct (cached results):**
+
+```typescript
+// Module-level cache
+const slugifyCache = new Map<string, string>()
+
+function cachedSlugify(text: string): string {
+  if (slugifyCache.has(text)) {
+    return slugifyCache.get(text)!
+  }
+  const result = slugify(text)
+  slugifyCache.set(text, result)
+  return result
+}
+
+function ProjectList({ projects }: { projects: Project[] }) {
+  return (
+    <div>
+      {projects.map(project => {
+        // Computed only once per unique project name
+        const slug = cachedSlugify(project.name)
+        
+        return <ProjectCard key={project.id} slug={slug} />
+      })}
+    </div>
+  )
+}
+```
+
+**Simpler pattern for single-value functions:**
+
+```typescript
+let isLoggedInCache: boolean | null = null
+
+function isLoggedIn(): boolean {
+  if (isLoggedInCache !== null) {
+    return isLoggedInCache
+  }
+  
+  isLoggedInCache = document.cookie.includes('auth=')
+  return isLoggedInCache
+}
+
+// Clear cache when auth changes
+function onAuthChange() {
+  isLoggedInCache = null
+}
+```
+
+Use a Map (not a hook) so it works everywhere: utilities, event handlers, not just React components.
+
+Reference: [How we made the Vercel Dashboard twice as fast](https://vercel.com/blog/how-we-made-the-vercel-dashboard-twice-as-fast)
diff --git a/.github/skills/vercel-react-best-practices/rules/js-cache-property-access.md b/.github/skills/vercel-react-best-practices/rules/js-cache-property-access.md
new file mode 100644
index 0000000..39eec90
--- /dev/null
+++ b/.github/skills/vercel-react-best-practices/rules/js-cache-property-access.md
@@ -0,0 +1,28 @@
+---
+title: Cache Property Access in Loops
+impact: LOW-MEDIUM
+impactDescription: reduces lookups
+tags: javascript, loops, optimization, caching
+---
+
+## Cache Property Access in Loops
+
+Cache object property lookups in hot paths.
+
+**Incorrect (3 lookups × N iterations):**
+
+```typescript
+for (let i = 0; i < arr.length; i++) {
+  process(obj.config.settings.value)
+}
+```
+
+**Correct (1 lookup total):**
+
+```typescript
+const value = obj.config.settings.value
+const len = arr.length
+for (let i = 0; i < len; i++) {
+  process(value)
+}
+```
diff --git a/.github/skills/vercel-react-best-practices/rules/js-cache-storage.md b/.github/skills/vercel-react-best-practices/rules/js-cache-storage.md
new file mode 100644
index 0000000..aa4a30c
--- /dev/null
+++ b/.github/skills/vercel-react-best-practices/rules/js-cache-storage.md
@@ -0,0 +1,70 @@
+---
+title: Cache Storage API Calls
+impact: LOW-MEDIUM
+impactDescription: reduces expensive I/O
+tags: javascript, localStorage, storage, caching, performance
+---
+
+## Cache Storage API Calls
+
+`localStorage`, `sessionStorage`, and `document.cookie` are synchronous and expensive. Cache reads in memory.
+
+**Incorrect (reads storage on every call):**
+
+```typescript
+function getTheme() {
+  return localStorage.getItem('theme') ?? 'light'
+}
+// Called 10 times = 10 storage reads
+```
+
+**Correct (Map cache):**
+
+```typescript
+const storageCache = new Map<string, string | null>()
+
+function getLocalStorage(key: string) {
+  if (!storageCache.has(key)) {
+    storageCache.set(key, localStorage.getItem(key))
+  }
+  return storageCache.get(key)
+}
+
+function setLocalStorage(key: string, value: string) {
+  localStorage.setItem(key, value)
+  storageCache.set(key, value)  // keep cache in sync
+}
+```
+
+Use a Map (not a hook) so it works everywhere: utilities, event handlers, not just React components.
+
+**Cookie caching:**
+
+```typescript
+let cookieCache: Record<string, string> | null = null
+
+function getCookie(name: string) {
+  if (!cookieCache) {
+    cookieCache = Object.fromEntries(
+      document.cookie.split('; ').map(c => c.split('='))
+    )
+  }
+  return cookieCache[name]
+}
+```
+
+**Important (invalidate on external changes):**
+
+If storage can change externally (another tab, server-set cookies), invalidate cache:
+
+```typescript
+window.addEventListener('storage', (e) => {
+  if (e.key) storageCache.delete(e.key)
+})
+
+document.addEventListener('visibilitychange', () => {
+  if (document.visibilityState === 'visible') {
+    storageCache.clear()
+  }
+})
+```
diff --git a/.github/skills/vercel-react-best-practices/rules/js-combine-iterations.md b/.github/skills/vercel-react-best-practices/rules/js-combine-iterations.md
new file mode 100644
index 0000000..044d017
--- /dev/null
+++ b/.github/skills/vercel-react-best-practices/rules/js-combine-iterations.md
@@ -0,0 +1,32 @@
+---
+title: Combine Multiple Array Iterations
+impact: LOW-MEDIUM
+impactDescription: reduces iterations
+tags: javascript, arrays, loops, performance
+---
+
+## Combine Multiple Array Iterations
+
+Multiple `.filter()` or `.map()` calls iterate the array multiple times. Combine into one loop.
+
+**Incorrect (3 iterations):**
+
+```typescript
+const admins = users.filter(u => u.isAdmin)
+const testers = users.filter(u => u.isTester)
+const inactive = users.filter(u => !u.isActive)
+```
+
+**Correct (1 iteration):**
+
+```typescript
+const admins: User[] = []
+const testers: User[] = []
+const inactive: User[] = []
+
+for (const user of users) {
+  if (user.isAdmin) admins.push(user)
+  if (user.isTester) testers.push(user)
+  if (!user.isActive) inactive.push(user)
+}
+```
diff --git a/.github/skills/vercel-react-best-practices/rules/js-early-exit.md b/.github/skills/vercel-react-best-practices/rules/js-early-exit.md
new file mode 100644
index 0000000..f46cb89
--- /dev/null
+++ b/.github/skills/vercel-react-best-practices/rules/js-early-exit.md
@@ -0,0 +1,50 @@
+---
+title: Early Return from Functions
+impact: LOW-MEDIUM
+impactDescription: avoids unnecessary computation
+tags: javascript, functions, optimization, early-return
+---
+
+## Early Return from Functions
+
+Return early when result is determined to skip unnecessary processing.
+
+**Incorrect (processes all items even after finding answer):**
+
+```typescript
+function validateUsers(users: User[]) {
+  let hasError = false
+  let errorMessage = ''
+  
+  for (const user of users) {
+    if (!user.email) {
+      hasError = true
+      errorMessage = 'Email required'
+    }
+    if (!user.name) {
+      hasError = true
+      errorMessage = 'Name required'
+    }
+    // Continues checking all users even after error found
+  }
+  
+  return hasError ? { valid: false, error: errorMessage } : { valid: true }
+}
+```
+
+**Correct (returns immediately on first error):**
+
+```typescript
+function validateUsers(users: User[]) {
+  for (const user of users) {
+    if (!user.email) {
+      return { valid: false, error: 'Email required' }
+    }
+    if (!user.name) {
+      return { valid: false, error: 'Name required' }
+    }
+  }
+
+  return { valid: true }
+}
+```
diff --git a/.github/skills/vercel-react-best-practices/rules/js-hoist-regexp.md b/.github/skills/vercel-react-best-practices/rules/js-hoist-regexp.md
new file mode 100644
index 0000000..dae3fef
--- /dev/null
+++ b/.github/skills/vercel-react-best-practices/rules/js-hoist-regexp.md
@@ -0,0 +1,45 @@
+---
+title: Hoist RegExp Creation
+impact: LOW-MEDIUM
+impactDescription: avoids recreation
+tags: javascript, regexp, optimization, memoization
+---
+
+## Hoist RegExp Creation
+
+Don't create RegExp inside render. Hoist to module scope or memoize with `useMemo()`.
+
+**Incorrect (new RegExp every render):**
+
+```tsx
+function Highlighter({ text, query }: Props) {
+  const regex = new RegExp(`(${query})`, 'gi')
+  const parts = text.split(regex)
+  return <>{parts.map((part, i) => ...)}</>
+}
+```
+
+**Correct (memoize or hoist):**
+
+```tsx
+const EMAIL_REGEX = /^[^\s@]+@[^\s@]+\.[^\s@]+$/
+
+function Highlighter({ text, query }: Props) {
+  const regex = useMemo(
+    () => new RegExp(`(${escapeRegex(query)})`, 'gi'),
+    [query]
+  )
+  const parts = text.split(regex)
+  return <>{parts.map((part, i) => ...)}</>
+}
+```
+
+**Warning (global regex has mutable state):**
+
+Global regex (`/g`) has mutable `lastIndex` state:
+
+```typescript
+const regex = /foo/g
+regex.test('foo')  // true, lastIndex = 3
+regex.test('foo')  // false, lastIndex = 0
+```
diff --git a/.github/skills/vercel-react-best-practices/rules/js-index-maps.md b/.github/skills/vercel-react-best-practices/rules/js-index-maps.md
new file mode 100644
index 0000000..9d357a0
--- /dev/null
+++ b/.github/skills/vercel-react-best-practices/rules/js-index-maps.md
@@ -0,0 +1,37 @@
+---
+title: Build Index Maps for Repeated Lookups
+impact: LOW-MEDIUM
+impactDescription: 1M ops to 2K ops
+tags: javascript, map, indexing, optimization, performance
+---
+
+## Build Index Maps for Repeated Lookups
+
+Multiple `.find()` calls by the same key should use a Map.
+
+**Incorrect (O(n) per lookup):**
+
+```typescript
+function processOrders(orders: Order[], users: User[]) {
+  return orders.map(order => ({
+    ...order,
+    user: users.find(u => u.id === order.userId)
+  }))
+}
+```
+
+**Correct (O(1) per lookup):**
+
+```typescript
+function processOrders(orders: Order[], users: User[]) {
+  const userById = new Map(users.map(u => [u.id, u]))
+
+  return orders.map(order => ({
+    ...order,
+    user: userById.get(order.userId)
+  }))
+}
+```
+
+Build map once (O(n)), then all lookups are O(1).
+For 1000 orders × 1000 users: 1M ops → 2K ops.
diff --git a/.github/skills/vercel-react-best-practices/rules/js-length-check-first.md b/.github/skills/vercel-react-best-practices/rules/js-length-check-first.md
new file mode 100644
index 0000000..8b89573
--- /dev/null
+++ b/.github/skills/vercel-react-best-practices/rules/js-length-check-first.md
@@ -0,0 +1,49 @@
+---
+title: Early Length Check for Array Comparisons
+impact: MEDIUM-HIGH
+impactDescription: avoids expensive operations when lengths differ
+tags: javascript, arrays, performance, optimization, comparison
+---
+
+## Early Length Check for Array Comparisons
+
+When comparing arrays with expensive operations (sorting, deep equality, serialization), check lengths first. If lengths differ, the arrays cannot be equal.
+
+In real-world applications, this optimization is especially valuable when the comparison runs in hot paths (event handlers, render loops).
+
+**Incorrect (always runs expensive comparison):**
+
+```typescript
+function hasChanges(current: string[], original: string[]) {
+  // Always sorts and joins, even when lengths differ
+  return current.sort().join() !== original.sort().join()
+}
+```
+
+Two O(n log n) sorts run even when `current.length` is 5 and `original.length` is 100. There is also overhead of joining the arrays and comparing the strings.
+
+**Correct (O(1) length check first):**
+
+```typescript
+function hasChanges(current: string[], original: string[]) {
+  // Early return if lengths differ
+  if (current.length !== original.length) {
+    return true
+  }
+  // Only sort when lengths match
+  const currentSorted = current.toSorted()
+  const originalSorted = original.toSorted()
+  for (let i = 0; i < currentSorted.length; i++) {
+    if (currentSorted[i] !== originalSorted[i]) {
+      return true
+    }
+  }
+  return false
+}
+```
+
+This new approach is more efficient because:
+- It avoids the overhead of sorting and joining the arrays when lengths differ
+- It avoids consuming memory for the joined strings (especially important for large arrays)
+- It avoids mutating the original arrays
+- It returns early when a difference is found
diff --git a/.github/skills/vercel-react-best-practices/rules/js-min-max-loop.md b/.github/skills/vercel-react-best-practices/rules/js-min-max-loop.md
new file mode 100644
index 0000000..4b6656e
--- /dev/null
+++ b/.github/skills/vercel-react-best-practices/rules/js-min-max-loop.md
@@ -0,0 +1,82 @@
+---
+title: Use Loop for Min/Max Instead of Sort
+impact: LOW
+impactDescription: O(n) instead of O(n log n)
+tags: javascript, arrays, performance, sorting, algorithms
+---
+
+## Use Loop for Min/Max Instead of Sort
+
+Finding the smallest or largest element only requires a single pass through the array. Sorting is wasteful and slower.
+
+**Incorrect (O(n log n) - sort to find latest):**
+
+```typescript
+interface Project {
+  id: string
+  name: string
+  updatedAt: number
+}
+
+function getLatestProject(projects: Project[]) {
+  const sorted = [...projects].sort((a, b) => b.updatedAt - a.updatedAt)
+  return sorted[0]
+}
+```
+
+Sorts the entire array just to find the maximum value.
+
+**Incorrect (O(n log n) - sort for oldest and newest):**
+
+```typescript
+function getOldestAndNewest(projects: Project[]) {
+  const sorted = [...projects].sort((a, b) => a.updatedAt - b.updatedAt)
+  return { oldest: sorted[0], newest: sorted[sorted.length - 1] }
+}
+```
+
+Still sorts unnecessarily when only min/max are needed.
+
+**Correct (O(n) - single loop):**
+
+```typescript
+function getLatestProject(projects: Project[]) {
+  if (projects.length === 0) return null
+  
+  let latest = projects[0]
+  
+  for (let i = 1; i < projects.length; i++) {
+    if (projects[i].updatedAt > latest.updatedAt) {
+      latest = projects[i]
+    }
+  }
+  
+  return latest
+}
+
+function getOldestAndNewest(projects: Project[]) {
+  if (projects.length === 0) return { oldest: null, newest: null }
+  
+  let oldest = projects[0]
+  let newest = projects[0]
+  
+  for (let i = 1; i < projects.length; i++) {
+    if (projects[i].updatedAt < oldest.updatedAt) oldest = projects[i]
+    if (projects[i].updatedAt > newest.updatedAt) newest = projects[i]
+  }
+  
+  return { oldest, newest }
+}
+```
+
+Single pass through the array, no copying, no sorting.
+
+**Alternative (Math.min/Math.max for small arrays):**
+
+```typescript
+const numbers = [5, 2, 8, 1, 9]
+const min = Math.min(...numbers)
+const max = Math.max(...numbers)
+```
+
+This works for small arrays, but can be slower or just throw an error for very large arrays due to spread operator limitations. Maximal array length is approximately 124000 in Chrome 143 and 638000 in Safari 18; exact numbers may vary - see [the fiddle](https://jsfiddle.net/qw1jabsx/4/). Use the loop approach for reliability.
diff --git a/.github/skills/vercel-react-best-practices/rules/js-set-map-lookups.md b/.github/skills/vercel-react-best-practices/rules/js-set-map-lookups.md
new file mode 100644
index 0000000..680a489
--- /dev/null
+++ b/.github/skills/vercel-react-best-practices/rules/js-set-map-lookups.md
@@ -0,0 +1,24 @@
+---
+title: Use Set/Map for O(1) Lookups
+impact: LOW-MEDIUM
+impactDescription: O(n) to O(1)
+tags: javascript, set, map, data-structures, performance
+---
+
+## Use Set/Map for O(1) Lookups
+
+Convert arrays to Set/Map for repeated membership checks.
+
+**Incorrect (O(n) per check):**
+
+```typescript
+const allowedIds = ['a', 'b', 'c', ...]
+items.filter(item => allowedIds.includes(item.id))
+```
+
+**Correct (O(1) per check):**
+
+```typescript
+const allowedIds = new Set(['a', 'b', 'c', ...])
+items.filter(item => allowedIds.has(item.id))
+```
diff --git a/.github/skills/vercel-react-best-practices/rules/js-tosorted-immutable.md b/.github/skills/vercel-react-best-practices/rules/js-tosorted-immutable.md
new file mode 100644
index 0000000..eae8b3f
--- /dev/null
+++ b/.github/skills/vercel-react-best-practices/rules/js-tosorted-immutable.md
@@ -0,0 +1,57 @@
+---
+title: Use toSorted() Instead of sort() for Immutability
+impact: MEDIUM-HIGH
+impactDescription: prevents mutation bugs in React state
+tags: javascript, arrays, immutability, react, state, mutation
+---
+
+## Use toSorted() Instead of sort() for Immutability
+
+`.sort()` mutates the array in place, which can cause bugs with React state and props. Use `.toSorted()` to create a new sorted array without mutation.
+
+**Incorrect (mutates original array):**
+
+```typescript
+function UserList({ users }: { users: User[] }) {
+  // Mutates the users prop array!
+  const sorted = useMemo(
+    () => users.sort((a, b) => a.name.localeCompare(b.name)),
+    [users]
+  )
+  return <div>{sorted.map(renderUser)}</div>
+}
+```
+
+**Correct (creates new array):**
+
+```typescript
+function UserList({ users }: { users: User[] }) {
+  // Creates new sorted array, original unchanged
+  const sorted = useMemo(
+    () => users.toSorted((a, b) => a.name.localeCompare(b.name)),
+    [users]
+  )
+  return <div>{sorted.map(renderUser)}</div>
+}
+```
+
+**Why this matters in React:**
+
+1. Props/state mutations break React's immutability model - React expects props and state to be treated as read-only
+2. Causes stale closure bugs - Mutating arrays inside closures (callbacks, effects) can lead to unexpected behavior
+
+**Browser support (fallback for older browsers):**
+
+`.toSorted()` is available in all modern browsers (Chrome 110+, Safari 16+, Firefox 115+, Node.js 20+). For older environments, use spread operator:
+
+```typescript
+// Fallback for older browsers
+const sorted = [...items].sort((a, b) => a.value - b.value)
+```
+
+**Other immutable array methods:**
+
+- `.toSorted()` - immutable sort
+- `.toReversed()` - immutable reverse
+- `.toSpliced()` - immutable splice
+- `.with()` - immutable element replacement
diff --git a/.github/skills/vercel-react-best-practices/rules/rendering-activity.md b/.github/skills/vercel-react-best-practices/rules/rendering-activity.md
new file mode 100644
index 0000000..c957a49
--- /dev/null
+++ b/.github/skills/vercel-react-best-practices/rules/rendering-activity.md
@@ -0,0 +1,26 @@
+---
+title: Use Activity Component for Show/Hide
+impact: MEDIUM
+impactDescription: preserves state/DOM
+tags: rendering, activity, visibility, state-preservation
+---
+
+## Use Activity Component for Show/Hide
+
+Use React's `<Activity>` to preserve state/DOM for expensive components that frequently toggle visibility.
+
+**Usage:**
+
+```tsx
+import { Activity } from 'react'
+
+function Dropdown({ isOpen }: Props) {
+  return (
+    <Activity mode={isOpen ? 'visible' : 'hidden'}>
+      <ExpensiveMenu />
+    </Activity>
+  )
+}
+```
+
+Avoids expensive re-renders and state loss.
diff --git a/.github/skills/vercel-react-best-practices/rules/rendering-animate-svg-wrapper.md b/.github/skills/vercel-react-best-practices/rules/rendering-animate-svg-wrapper.md
new file mode 100644
index 0000000..646744c
--- /dev/null
+++ b/.github/skills/vercel-react-best-practices/rules/rendering-animate-svg-wrapper.md
@@ -0,0 +1,47 @@
+---
+title: Animate SVG Wrapper Instead of SVG Element
+impact: LOW
+impactDescription: enables hardware acceleration
+tags: rendering, svg, css, animation, performance
+---
+
+## Animate SVG Wrapper Instead of SVG Element
+
+Many browsers don't have hardware acceleration for CSS3 animations on SVG elements. Wrap SVG in a `<div>` and animate the wrapper instead.
+
+**Incorrect (animating SVG directly - no hardware acceleration):**
+
+```tsx
+function LoadingSpinner() {
+  return (
+    <svg 
+      className="animate-spin"
+      width="24" 
+      height="24" 
+      viewBox="0 0 24 24"
+    >
+      <circle cx="12" cy="12" r="10" stroke="currentColor" />
+    </svg>
+  )
+}
+```
+
+**Correct (animating wrapper div - hardware accelerated):**
+
+```tsx
+function LoadingSpinner() {
+  return (
+    <div className="animate-spin">
+      <svg 
+        width="24" 
+        height="24" 
+        viewBox="0 0 24 24"
+      >
+        <circle cx="12" cy="12" r="10" stroke="currentColor" />
+      </svg>
+    </div>
+  )
+}
+```
+
+This applies to all CSS transforms and transitions (`transform`, `opacity`, `translate`, `scale`, `rotate`). The wrapper div allows browsers to use GPU acceleration for smoother animations.
diff --git a/.github/skills/vercel-react-best-practices/rules/rendering-conditional-render.md b/.github/skills/vercel-react-best-practices/rules/rendering-conditional-render.md
new file mode 100644
index 0000000..7e866f5
--- /dev/null
+++ b/.github/skills/vercel-react-best-practices/rules/rendering-conditional-render.md
@@ -0,0 +1,40 @@
+---
+title: Use Explicit Conditional Rendering
+impact: LOW
+impactDescription: prevents rendering 0 or NaN
+tags: rendering, conditional, jsx, falsy-values
+---
+
+## Use Explicit Conditional Rendering
+
+Use explicit ternary operators (`? :`) instead of `&&` for conditional rendering when the condition can be `0`, `NaN`, or other falsy values that render.
+
+**Incorrect (renders "0" when count is 0):**
+
+```tsx
+function Badge({ count }: { count: number }) {
+  return (
+    <div>
+      {count && <span className="badge">{count}</span>}
+    </div>
+  )
+}
+
+// When count = 0, renders: <div>0</div>
+// When count = 5, renders: <div><span class="badge">5</span></div>
+```
+
+**Correct (renders nothing when count is 0):**
+
+```tsx
+function Badge({ count }: { count: number }) {
+  return (
+    <div>
+      {count > 0 ? <span className="badge">{count}</span> : null}
+    </div>
+  )
+}
+
+// When count = 0, renders: <div></div>
+// When count = 5, renders: <div><span class="badge">5</span></div>
+```
diff --git a/.github/skills/vercel-react-best-practices/rules/rendering-content-visibility.md b/.github/skills/vercel-react-best-practices/rules/rendering-content-visibility.md
new file mode 100644
index 0000000..aa66563
--- /dev/null
+++ b/.github/skills/vercel-react-best-practices/rules/rendering-content-visibility.md
@@ -0,0 +1,38 @@
+---
+title: CSS content-visibility for Long Lists
+impact: HIGH
+impactDescription: faster initial render
+tags: rendering, css, content-visibility, long-lists
+---
+
+## CSS content-visibility for Long Lists
+
+Apply `content-visibility: auto` to defer off-screen rendering.
+
+**CSS:**
+
+```css
+.message-item {
+  content-visibility: auto;
+  contain-intrinsic-size: 0 80px;
+}
+```
+
+**Example:**
+
+```tsx
+function MessageList({ messages }: { messages: Message[] }) {
+  return (
+    <div className="overflow-y-auto h-screen">
+      {messages.map(msg => (
+        <div key={msg.id} className="message-item">
+          <Avatar user={msg.author} />
+          <div>{msg.content}</div>
+        </div>
+      ))}
+    </div>
+  )
+}
+```
+
+For 1000 messages, browser skips layout/paint for ~990 off-screen items (10× faster initial render).
diff --git a/.github/skills/vercel-react-best-practices/rules/rendering-hoist-jsx.md b/.github/skills/vercel-react-best-practices/rules/rendering-hoist-jsx.md
new file mode 100644
index 0000000..32d2f3f
--- /dev/null
+++ b/.github/skills/vercel-react-best-practices/rules/rendering-hoist-jsx.md
@@ -0,0 +1,46 @@
+---
+title: Hoist Static JSX Elements
+impact: LOW
+impactDescription: avoids re-creation
+tags: rendering, jsx, static, optimization
+---
+
+## Hoist Static JSX Elements
+
+Extract static JSX outside components to avoid re-creation.
+
+**Incorrect (recreates element every render):**
+
+```tsx
+function LoadingSkeleton() {
+  return <div className="animate-pulse h-20 bg-gray-200" />
+}
+
+function Container() {
+  return (
+    <div>
+      {loading && <LoadingSkeleton />}
+    </div>
+  )
+}
+```
+
+**Correct (reuses same element):**
+
+```tsx
+const loadingSkeleton = (
+  <div className="animate-pulse h-20 bg-gray-200" />
+)
+
+function Container() {
+  return (
+    <div>
+      {loading && loadingSkeleton}
+    </div>
+  )
+}
+```
+
+This is especially helpful for large and static SVG nodes, which can be expensive to recreate on every render.
+
+**Note:** If your project has [React Compiler](https://react.dev/learn/react-compiler) enabled, the compiler automatically hoists static JSX elements and optimizes component re-renders, making manual hoisting unnecessary.
diff --git a/.github/skills/vercel-react-best-practices/rules/rendering-hydration-no-flicker.md b/.github/skills/vercel-react-best-practices/rules/rendering-hydration-no-flicker.md
new file mode 100644
index 0000000..5cf0e79
--- /dev/null
+++ b/.github/skills/vercel-react-best-practices/rules/rendering-hydration-no-flicker.md
@@ -0,0 +1,82 @@
+---
+title: Prevent Hydration Mismatch Without Flickering
+impact: MEDIUM
+impactDescription: avoids visual flicker and hydration errors
+tags: rendering, ssr, hydration, localStorage, flicker
+---
+
+## Prevent Hydration Mismatch Without Flickering
+
+When rendering content that depends on client-side storage (localStorage, cookies), avoid both SSR breakage and post-hydration flickering by injecting a synchronous script that updates the DOM before React hydrates.
+
+**Incorrect (breaks SSR):**
+
+```tsx
+function ThemeWrapper({ children }: { children: ReactNode }) {
+  // localStorage is not available on server - throws error
+  const theme = localStorage.getItem('theme') || 'light'
+  
+  return (
+    <div className={theme}>
+      {children}
+    </div>
+  )
+}
+```
+
+Server-side rendering will fail because `localStorage` is undefined.
+
+**Incorrect (visual flickering):**
+
+```tsx
+function ThemeWrapper({ children }: { children: ReactNode }) {
+  const [theme, setTheme] = useState('light')
+  
+  useEffect(() => {
+    // Runs after hydration - causes visible flash
+    const stored = localStorage.getItem('theme')
+    if (stored) {
+      setTheme(stored)
+    }
+  }, [])
+  
+  return (
+    <div className={theme}>
+      {children}
+    </div>
+  )
+}
+```
+
+Component first renders with default value (`light`), then updates after hydration, causing a visible flash of incorrect content.
+
+**Correct (no flicker, no hydration mismatch):**
+
+```tsx
+function ThemeWrapper({ children }: { children: ReactNode }) {
+  return (
+    <>
+      <div id="theme-wrapper">
+        {children}
+      </div>
+      <script
+        dangerouslySetInnerHTML={{
+          __html: `
+            (function() {
+              try {
+                var theme = localStorage.getItem('theme') || 'light';
+                var el = document.getElementById('theme-wrapper');
+                if (el) el.className = theme;
+              } catch (e) {}
+            })();
+          `,
+        }}
+      />
+    </>
+  )
+}
+```
+
+The inline script executes synchronously before showing the element, ensuring the DOM already has the correct value. No flickering, no hydration mismatch.
+
+This pattern is especially useful for theme toggles, user preferences, authentication states, and any client-only data that should render immediately without flashing default values.
diff --git a/.github/skills/vercel-react-best-practices/rules/rendering-svg-precision.md b/.github/skills/vercel-react-best-practices/rules/rendering-svg-precision.md
new file mode 100644
index 0000000..6d77128
--- /dev/null
+++ b/.github/skills/vercel-react-best-practices/rules/rendering-svg-precision.md
@@ -0,0 +1,28 @@
+---
+title: Optimize SVG Precision
+impact: LOW
+impactDescription: reduces file size
+tags: rendering, svg, optimization, svgo
+---
+
+## Optimize SVG Precision
+
+Reduce SVG coordinate precision to decrease file size. The optimal precision depends on the viewBox size, but in general reducing precision should be considered.
+
+**Incorrect (excessive precision):**
+
+```svg
+<path d="M 10.293847 20.847362 L 30.938472 40.192837" />
+```
+
+**Correct (1 decimal place):**
+
+```svg
+<path d="M 10.3 20.8 L 30.9 40.2" />
+```
+
+**Automate with SVGO:**
+
+```bash
+npx svgo --precision=1 --multipass icon.svg
+```
diff --git a/.github/skills/vercel-react-best-practices/rules/rendering-usetransition-loading.md b/.github/skills/vercel-react-best-practices/rules/rendering-usetransition-loading.md
new file mode 100644
index 0000000..0c1b0b9
--- /dev/null
+++ b/.github/skills/vercel-react-best-practices/rules/rendering-usetransition-loading.md
@@ -0,0 +1,75 @@
+---
+title: Use useTransition Over Manual Loading States
+impact: LOW
+impactDescription: reduces re-renders and improves code clarity
+tags: rendering, transitions, useTransition, loading, state
+---
+
+## Use useTransition Over Manual Loading States
+
+Use `useTransition` instead of manual `useState` for loading states. This provides built-in `isPending` state and automatically manages transitions.
+
+**Incorrect (manual loading state):**
+
+```tsx
+function SearchResults() {
+  const [query, setQuery] = useState('')
+  const [results, setResults] = useState([])
+  const [isLoading, setIsLoading] = useState(false)
+
+  const handleSearch = async (value: string) => {
+    setIsLoading(true)
+    setQuery(value)
+    const data = await fetchResults(value)
+    setResults(data)
+    setIsLoading(false)
+  }
+
+  return (
+    <>
+      <input onChange={(e) => handleSearch(e.target.value)} />
+      {isLoading && <Spinner />}
+      <ResultsList results={results} />
+    </>
+  )
+}
+```
+
+**Correct (useTransition with built-in pending state):**
+
+```tsx
+import { useTransition, useState } from 'react'
+
+function SearchResults() {
+  const [query, setQuery] = useState('')
+  const [results, setResults] = useState([])
+  const [isPending, startTransition] = useTransition()
+
+  const handleSearch = (value: string) => {
+    setQuery(value) // Update input immediately
+    
+    startTransition(async () => {
+      // Fetch and update results
+      const data = await fetchResults(value)
+      setResults(data)
+    })
+  }
+
+  return (
+    <>
+      <input onChange={(e) => handleSearch(e.target.value)} />
+      {isPending && <Spinner />}
+      <ResultsList results={results} />
+    </>
+  )
+}
+```
+
+**Benefits:**
+
+- **Automatic pending state**: No need to manually manage `setIsLoading(true/false)`
+- **Error resilience**: Pending state correctly resets even if the transition throws
+- **Better responsiveness**: Keeps the UI responsive during updates
+- **Interrupt handling**: New transitions automatically cancel pending ones
+
+Reference: [useTransition](https://react.dev/reference/react/useTransition)
diff --git a/.github/skills/vercel-react-best-practices/rules/rerender-defer-reads.md b/.github/skills/vercel-react-best-practices/rules/rerender-defer-reads.md
new file mode 100644
index 0000000..e867c95
--- /dev/null
+++ b/.github/skills/vercel-react-best-practices/rules/rerender-defer-reads.md
@@ -0,0 +1,39 @@
+---
+title: Defer State Reads to Usage Point
+impact: MEDIUM
+impactDescription: avoids unnecessary subscriptions
+tags: rerender, searchParams, localStorage, optimization
+---
+
+## Defer State Reads to Usage Point
+
+Don't subscribe to dynamic state (searchParams, localStorage) if you only read it inside callbacks.
+
+**Incorrect (subscribes to all searchParams changes):**
+
+```tsx
+function ShareButton({ chatId }: { chatId: string }) {
+  const searchParams = useSearchParams()
+
+  const handleShare = () => {
+    const ref = searchParams.get('ref')
+    shareChat(chatId, { ref })
+  }
+
+  return <button onClick={handleShare}>Share</button>
+}
+```
+
+**Correct (reads on demand, no subscription):**
+
+```tsx
+function ShareButton({ chatId }: { chatId: string }) {
+  const handleShare = () => {
+    const params = new URLSearchParams(window.location.search)
+    const ref = params.get('ref')
+    shareChat(chatId, { ref })
+  }
+
+  return <button onClick={handleShare}>Share</button>
+}
+```
diff --git a/.github/skills/vercel-react-best-practices/rules/rerender-dependencies.md b/.github/skills/vercel-react-best-practices/rules/rerender-dependencies.md
new file mode 100644
index 0000000..47a4d92
--- /dev/null
+++ b/.github/skills/vercel-react-best-practices/rules/rerender-dependencies.md
@@ -0,0 +1,45 @@
+---
+title: Narrow Effect Dependencies
+impact: LOW
+impactDescription: minimizes effect re-runs
+tags: rerender, useEffect, dependencies, optimization
+---
+
+## Narrow Effect Dependencies
+
+Specify primitive dependencies instead of objects to minimize effect re-runs.
+
+**Incorrect (re-runs on any user field change):**
+
+```tsx
+useEffect(() => {
+  console.log(user.id)
+}, [user])
+```
+
+**Correct (re-runs only when id changes):**
+
+```tsx
+useEffect(() => {
+  console.log(user.id)
+}, [user.id])
+```
+
+**For derived state, compute outside effect:**
+
+```tsx
+// Incorrect: runs on width=767, 766, 765...
+useEffect(() => {
+  if (width < 768) {
+    enableMobileMode()
+  }
+}, [width])
+
+// Correct: runs only on boolean transition
+const isMobile = width < 768
+useEffect(() => {
+  if (isMobile) {
+    enableMobileMode()
+  }
+}, [isMobile])
+```
diff --git a/.github/skills/vercel-react-best-practices/rules/rerender-derived-state.md b/.github/skills/vercel-react-best-practices/rules/rerender-derived-state.md
new file mode 100644
index 0000000..e5c899f
--- /dev/null
+++ b/.github/skills/vercel-react-best-practices/rules/rerender-derived-state.md
@@ -0,0 +1,29 @@
+---
+title: Subscribe to Derived State
+impact: MEDIUM
+impactDescription: reduces re-render frequency
+tags: rerender, derived-state, media-query, optimization
+---
+
+## Subscribe to Derived State
+
+Subscribe to derived boolean state instead of continuous values to reduce re-render frequency.
+
+**Incorrect (re-renders on every pixel change):**
+
+```tsx
+function Sidebar() {
+  const width = useWindowWidth()  // updates continuously
+  const isMobile = width < 768
+  return <nav className={isMobile ? 'mobile' : 'desktop'} />
+}
+```
+
+**Correct (re-renders only when boolean changes):**
+
+```tsx
+function Sidebar() {
+  const isMobile = useMediaQuery('(max-width: 767px)')
+  return <nav className={isMobile ? 'mobile' : 'desktop'} />
+}
+```
diff --git a/.github/skills/vercel-react-best-practices/rules/rerender-functional-setstate.md b/.github/skills/vercel-react-best-practices/rules/rerender-functional-setstate.md
new file mode 100644
index 0000000..b004ef4
--- /dev/null
+++ b/.github/skills/vercel-react-best-practices/rules/rerender-functional-setstate.md
@@ -0,0 +1,74 @@
+---
+title: Use Functional setState Updates
+impact: MEDIUM
+impactDescription: prevents stale closures and unnecessary callback recreations
+tags: react, hooks, useState, useCallback, callbacks, closures
+---
+
+## Use Functional setState Updates
+
+When updating state based on the current state value, use the functional update form of setState instead of directly referencing the state variable. This prevents stale closures, eliminates unnecessary dependencies, and creates stable callback references.
+
+**Incorrect (requires state as dependency):**
+
+```tsx
+function TodoList() {
+  const [items, setItems] = useState(initialItems)
+  
+  // Callback must depend on items, recreated on every items change
+  const addItems = useCallback((newItems: Item[]) => {
+    setItems([...items, ...newItems])
+  }, [items])  // ❌ items dependency causes recreations
+  
+  // Risk of stale closure if dependency is forgotten
+  const removeItem = useCallback((id: string) => {
+    setItems(items.filter(item => item.id !== id))
+  }, [])  // ❌ Missing items dependency - will use stale items!
+  
+  return <ItemsEditor items={items} onAdd={addItems} onRemove={removeItem} />
+}
+```
+
+The first callback is recreated every time `items` changes, which can cause child components to re-render unnecessarily. The second callback has a stale closure bug—it will always reference the initial `items` value.
+
+**Correct (stable callbacks, no stale closures):**
+
+```tsx
+function TodoList() {
+  const [items, setItems] = useState(initialItems)
+  
+  // Stable callback, never recreated
+  const addItems = useCallback((newItems: Item[]) => {
+    setItems(curr => [...curr, ...newItems])
+  }, [])  // ✅ No dependencies needed
+  
+  // Always uses latest state, no stale closure risk
+  const removeItem = useCallback((id: string) => {
+    setItems(curr => curr.filter(item => item.id !== id))
+  }, [])  // ✅ Safe and stable
+  
+  return <ItemsEditor items={items} onAdd={addItems} onRemove={removeItem} />
+}
+```
+
+**Benefits:**
+
+1. **Stable callback references** - Callbacks don't need to be recreated when state changes
+2. **No stale closures** - Always operates on the latest state value
+3. **Fewer dependencies** - Simplifies dependency arrays and reduces memory leaks
+4. **Prevents bugs** - Eliminates the most common source of React closure bugs
+
+**When to use functional updates:**
+
+- Any setState that depends on the current state value
+- Inside useCallback/useMemo when state is needed
+- Event handlers that reference state
+- Async operations that update state
+
+**When direct updates are fine:**
+
+- Setting state to a static value: `setCount(0)`
+- Setting state from props/arguments only: `setName(newName)`
+- State doesn't depend on previous value
+
+**Note:** If your project has [React Compiler](https://react.dev/learn/react-compiler) enabled, the compiler can automatically optimize some cases, but functional updates are still recommended for correctness and to prevent stale closure bugs.
diff --git a/.github/skills/vercel-react-best-practices/rules/rerender-lazy-state-init.md b/.github/skills/vercel-react-best-practices/rules/rerender-lazy-state-init.md
new file mode 100644
index 0000000..4ecb350
--- /dev/null
+++ b/.github/skills/vercel-react-best-practices/rules/rerender-lazy-state-init.md
@@ -0,0 +1,58 @@
+---
+title: Use Lazy State Initialization
+impact: MEDIUM
+impactDescription: wasted computation on every render
+tags: react, hooks, useState, performance, initialization
+---
+
+## Use Lazy State Initialization
+
+Pass a function to `useState` for expensive initial values. Without the function form, the initializer runs on every render even though the value is only used once.
+
+**Incorrect (runs on every render):**
+
+```tsx
+function FilteredList({ items }: { items: Item[] }) {
+  // buildSearchIndex() runs on EVERY render, even after initialization
+  const [searchIndex, setSearchIndex] = useState(buildSearchIndex(items))
+  const [query, setQuery] = useState('')
+  
+  // When query changes, buildSearchIndex runs again unnecessarily
+  return <SearchResults index={searchIndex} query={query} />
+}
+
+function UserProfile() {
+  // JSON.parse runs on every render
+  const [settings, setSettings] = useState(
+    JSON.parse(localStorage.getItem('settings') || '{}')
+  )
+  
+  return <SettingsForm settings={settings} onChange={setSettings} />
+}
+```
+
+**Correct (runs only once):**
+
+```tsx
+function FilteredList({ items }: { items: Item[] }) {
+  // buildSearchIndex() runs ONLY on initial render
+  const [searchIndex, setSearchIndex] = useState(() => buildSearchIndex(items))
+  const [query, setQuery] = useState('')
+  
+  return <SearchResults index={searchIndex} query={query} />
+}
+
+function UserProfile() {
+  // JSON.parse runs only on initial render
+  const [settings, setSettings] = useState(() => {
+    const stored = localStorage.getItem('settings')
+    return stored ? JSON.parse(stored) : {}
+  })
+  
+  return <SettingsForm settings={settings} onChange={setSettings} />
+}
+```
+
+Use lazy initialization when computing initial values from localStorage/sessionStorage, building data structures (indexes, maps), reading from the DOM, or performing heavy transformations.
+
+For simple primitives (`useState(0)`), direct references (`useState(props.value)`), or cheap literals (`useState({})`), the function form is unnecessary.
diff --git a/.github/skills/vercel-react-best-practices/rules/rerender-memo-with-default-value.md b/.github/skills/vercel-react-best-practices/rules/rerender-memo-with-default-value.md
new file mode 100644
index 0000000..6357049
--- /dev/null
+++ b/.github/skills/vercel-react-best-practices/rules/rerender-memo-with-default-value.md
@@ -0,0 +1,38 @@
+---
+
+title: Extract Default Non-primitive Parameter Value from Memoized Component to Constant
+impact: MEDIUM
+impactDescription: restores memoization by using a constant for default value
+tags: rerender, memo, optimization
+
+---
+
+## Extract Default Non-primitive Parameter Value from Memoized Component to Constant
+
+When memoized component has a default value for some non-primitive optional parameter, such as an array, function, or object, calling the component without that parameter results in broken memoization. This is because new value instances are created on every rerender, and they do not pass strict equality comparison in `memo()`.
+
+To address this issue, extract the default value into a constant.
+
+**Incorrect (`onClick` has different values on every rerender):**
+
+```tsx
+const UserAvatar = memo(function UserAvatar({ onClick = () => {} }: { onClick?: () => void }) {
+  // ...
+})
+
+// Used without optional onClick
+<UserAvatar />
+```
+
+**Correct (stable default value):**
+
+```tsx
+const NOOP = () => {};
+
+const UserAvatar = memo(function UserAvatar({ onClick = NOOP }: { onClick?: () => void }) {
+  // ...
+})
+
+// Used without optional onClick
+<UserAvatar />
+```
diff --git a/.github/skills/vercel-react-best-practices/rules/rerender-memo.md b/.github/skills/vercel-react-best-practices/rules/rerender-memo.md
new file mode 100644
index 0000000..f8982ab
--- /dev/null
+++ b/.github/skills/vercel-react-best-practices/rules/rerender-memo.md
@@ -0,0 +1,44 @@
+---
+title: Extract to Memoized Components
+impact: MEDIUM
+impactDescription: enables early returns
+tags: rerender, memo, useMemo, optimization
+---
+
+## Extract to Memoized Components
+
+Extract expensive work into memoized components to enable early returns before computation.
+
+**Incorrect (computes avatar even when loading):**
+
+```tsx
+function Profile({ user, loading }: Props) {
+  const avatar = useMemo(() => {
+    const id = computeAvatarId(user)
+    return <Avatar id={id} />
+  }, [user])
+
+  if (loading) return <Skeleton />
+  return <div>{avatar}</div>
+}
+```
+
+**Correct (skips computation when loading):**
+
+```tsx
+const UserAvatar = memo(function UserAvatar({ user }: { user: User }) {
+  const id = useMemo(() => computeAvatarId(user), [user])
+  return <Avatar id={id} />
+})
+
+function Profile({ user, loading }: Props) {
+  if (loading) return <Skeleton />
+  return (
+    <div>
+      <UserAvatar user={user} />
+    </div>
+  )
+}
+```
+
+**Note:** If your project has [React Compiler](https://react.dev/learn/react-compiler) enabled, manual memoization with `memo()` and `useMemo()` is not necessary. The compiler automatically optimizes re-renders.
diff --git a/.github/skills/vercel-react-best-practices/rules/rerender-simple-expression-in-memo.md b/.github/skills/vercel-react-best-practices/rules/rerender-simple-expression-in-memo.md
new file mode 100644
index 0000000..59dfab0
--- /dev/null
+++ b/.github/skills/vercel-react-best-practices/rules/rerender-simple-expression-in-memo.md
@@ -0,0 +1,35 @@
+---
+title: Do not wrap a simple expression with a primitive result type in useMemo
+impact: LOW-MEDIUM
+impactDescription: wasted computation on every render
+tags: rerender, useMemo, optimization
+---
+
+## Do not wrap a simple expression with a primitive result type in useMemo
+
+When an expression is simple (few logical or arithmetical operators) and has a primitive result type (boolean, number, string), do not wrap it in `useMemo`.
+Calling `useMemo` and comparing hook dependencies may consume more resources than the expression itself.
+
+**Incorrect:**
+
+```tsx
+function Header({ user, notifications }: Props) {
+  const isLoading = useMemo(() => {
+    return user.isLoading || notifications.isLoading
+  }, [user.isLoading, notifications.isLoading])
+
+  if (isLoading) return <Skeleton />
+  // return some markup
+}
+```
+
+**Correct:**
+
+```tsx
+function Header({ user, notifications }: Props) {
+  const isLoading = user.isLoading || notifications.isLoading
+
+  if (isLoading) return <Skeleton />
+  // return some markup
+}
+```
diff --git a/.github/skills/vercel-react-best-practices/rules/rerender-transitions.md b/.github/skills/vercel-react-best-practices/rules/rerender-transitions.md
new file mode 100644
index 0000000..d99f43f
--- /dev/null
+++ b/.github/skills/vercel-react-best-practices/rules/rerender-transitions.md
@@ -0,0 +1,40 @@
+---
+title: Use Transitions for Non-Urgent Updates
+impact: MEDIUM
+impactDescription: maintains UI responsiveness
+tags: rerender, transitions, startTransition, performance
+---
+
+## Use Transitions for Non-Urgent Updates
+
+Mark frequent, non-urgent state updates as transitions to maintain UI responsiveness.
+
+**Incorrect (blocks UI on every scroll):**
+
+```tsx
+function ScrollTracker() {
+  const [scrollY, setScrollY] = useState(0)
+  useEffect(() => {
+    const handler = () => setScrollY(window.scrollY)
+    window.addEventListener('scroll', handler, { passive: true })
+    return () => window.removeEventListener('scroll', handler)
+  }, [])
+}
+```
+
+**Correct (non-blocking updates):**
+
+```tsx
+import { startTransition } from 'react'
+
+function ScrollTracker() {
+  const [scrollY, setScrollY] = useState(0)
+  useEffect(() => {
+    const handler = () => {
+      startTransition(() => setScrollY(window.scrollY))
+    }
+    window.addEventListener('scroll', handler, { passive: true })
+    return () => window.removeEventListener('scroll', handler)
+  }, [])
+}
+```
diff --git a/.github/skills/vercel-react-best-practices/rules/server-after-nonblocking.md b/.github/skills/vercel-react-best-practices/rules/server-after-nonblocking.md
new file mode 100644
index 0000000..e8f5b26
--- /dev/null
+++ b/.github/skills/vercel-react-best-practices/rules/server-after-nonblocking.md
@@ -0,0 +1,73 @@
+---
+title: Use after() for Non-Blocking Operations
+impact: MEDIUM
+impactDescription: faster response times
+tags: server, async, logging, analytics, side-effects
+---
+
+## Use after() for Non-Blocking Operations
+
+Use Next.js's `after()` to schedule work that should execute after a response is sent. This prevents logging, analytics, and other side effects from blocking the response.
+
+**Incorrect (blocks response):**
+
+```tsx
+import { logUserAction } from '@/app/utils'
+
+export async function POST(request: Request) {
+  // Perform mutation
+  await updateDatabase(request)
+  
+  // Logging blocks the response
+  const userAgent = request.headers.get('user-agent') || 'unknown'
+  await logUserAction({ userAgent })
+  
+  return new Response(JSON.stringify({ status: 'success' }), {
+    status: 200,
+    headers: { 'Content-Type': 'application/json' }
+  })
+}
+```
+
+**Correct (non-blocking):**
+
+```tsx
+import { after } from 'next/server'
+import { headers, cookies } from 'next/headers'
+import { logUserAction } from '@/app/utils'
+
+export async function POST(request: Request) {
+  // Perform mutation
+  await updateDatabase(request)
+  
+  // Log after response is sent
+  after(async () => {
+    const userAgent = (await headers()).get('user-agent') || 'unknown'
+    const sessionCookie = (await cookies()).get('session-id')?.value || 'anonymous'
+    
+    logUserAction({ sessionCookie, userAgent })
+  })
+  
+  return new Response(JSON.stringify({ status: 'success' }), {
+    status: 200,
+    headers: { 'Content-Type': 'application/json' }
+  })
+}
+```
+
+The response is sent immediately while logging happens in the background.
+
+**Common use cases:**
+
+- Analytics tracking
+- Audit logging
+- Sending notifications
+- Cache invalidation
+- Cleanup tasks
+
+**Important notes:**
+
+- `after()` runs even if the response fails or redirects
+- Works in Server Actions, Route Handlers, and Server Components
+
+Reference: [https://nextjs.org/docs/app/api-reference/functions/after](https://nextjs.org/docs/app/api-reference/functions/after)
diff --git a/.github/skills/vercel-react-best-practices/rules/server-auth-actions.md b/.github/skills/vercel-react-best-practices/rules/server-auth-actions.md
new file mode 100644
index 0000000..ee82c04
--- /dev/null
+++ b/.github/skills/vercel-react-best-practices/rules/server-auth-actions.md
@@ -0,0 +1,96 @@
+---
+title: Authenticate Server Actions Like API Routes
+impact: CRITICAL
+impactDescription: prevents unauthorized access to server mutations
+tags: server, server-actions, authentication, security, authorization
+---
+
+## Authenticate Server Actions Like API Routes
+
+**Impact: CRITICAL (prevents unauthorized access to server mutations)**
+
+Server Actions (functions with `"use server"`) are exposed as public endpoints, just like API routes. Always verify authentication and authorization **inside** each Server Action—do not rely solely on middleware, layout guards, or page-level checks, as Server Actions can be invoked directly.
+
+Next.js documentation explicitly states: "Treat Server Actions with the same security considerations as public-facing API endpoints, and verify if the user is allowed to perform a mutation."
+
+**Incorrect (no authentication check):**
+
+```typescript
+'use server'
+
+export async function deleteUser(userId: string) {
+  // Anyone can call this! No auth check
+  await db.user.delete({ where: { id: userId } })
+  return { success: true }
+}
+```
+
+**Correct (authentication inside the action):**
+
+```typescript
+'use server'
+
+import { verifySession } from '@/lib/auth'
+import { unauthorized } from '@/lib/errors'
+
+export async function deleteUser(userId: string) {
+  // Always check auth inside the action
+  const session = await verifySession()
+  
+  if (!session) {
+    throw unauthorized('Must be logged in')
+  }
+  
+  // Check authorization too
+  if (session.user.role !== 'admin' && session.user.id !== userId) {
+    throw unauthorized('Cannot delete other users')
+  }
+  
+  await db.user.delete({ where: { id: userId } })
+  return { success: true }
+}
+```
+
+**With input validation:**
+
+```typescript
+'use server'
+
+import { verifySession } from '@/lib/auth'
+import { z } from 'zod'
+
+const updateProfileSchema = z.object({
+  userId: z.string().uuid(),
+  name: z.string().min(1).max(100),
+  email: z.string().email()
+})
+
+export async function updateProfile(data: unknown) {
+  // Validate input first
+  const validated = updateProfileSchema.parse(data)
+  
+  // Then authenticate
+  const session = await verifySession()
+  if (!session) {
+    throw new Error('Unauthorized')
+  }
+  
+  // Then authorize
+  if (session.user.id !== validated.userId) {
+    throw new Error('Can only update own profile')
+  }
+  
+  // Finally perform the mutation
+  await db.user.update({
+    where: { id: validated.userId },
+    data: {
+      name: validated.name,
+      email: validated.email
+    }
+  })
+  
+  return { success: true }
+}
+```
+
+Reference: [https://nextjs.org/docs/app/guides/authentication](https://nextjs.org/docs/app/guides/authentication)
diff --git a/.github/skills/vercel-react-best-practices/rules/server-cache-lru.md b/.github/skills/vercel-react-best-practices/rules/server-cache-lru.md
new file mode 100644
index 0000000..ef6938a
--- /dev/null
+++ b/.github/skills/vercel-react-best-practices/rules/server-cache-lru.md
@@ -0,0 +1,41 @@
+---
+title: Cross-Request LRU Caching
+impact: HIGH
+impactDescription: caches across requests
+tags: server, cache, lru, cross-request
+---
+
+## Cross-Request LRU Caching
+
+`React.cache()` only works within one request. For data shared across sequential requests (user clicks button A then button B), use an LRU cache.
+
+**Implementation:**
+
+```typescript
+import { LRUCache } from 'lru-cache'
+
+const cache = new LRUCache<string, any>({
+  max: 1000,
+  ttl: 5 * 60 * 1000  // 5 minutes
+})
+
+export async function getUser(id: string) {
+  const cached = cache.get(id)
+  if (cached) return cached
+
+  const user = await db.user.findUnique({ where: { id } })
+  cache.set(id, user)
+  return user
+}
+
+// Request 1: DB query, result cached
+// Request 2: cache hit, no DB query
+```
+
+Use when sequential user actions hit multiple endpoints needing the same data within seconds.
+
+**With Vercel's [Fluid Compute](https://vercel.com/docs/fluid-compute):** LRU caching is especially effective because multiple concurrent requests can share the same function instance and cache. This means the cache persists across requests without needing external storage like Redis.
+
+**In traditional serverless:** Each invocation runs in isolation, so consider Redis for cross-process caching.
+
+Reference: [https://github.com/isaacs/node-lru-cache](https://github.com/isaacs/node-lru-cache)
diff --git a/.github/skills/vercel-react-best-practices/rules/server-cache-react.md b/.github/skills/vercel-react-best-practices/rules/server-cache-react.md
new file mode 100644
index 0000000..87c9ca3
--- /dev/null
+++ b/.github/skills/vercel-react-best-practices/rules/server-cache-react.md
@@ -0,0 +1,76 @@
+---
+title: Per-Request Deduplication with React.cache()
+impact: MEDIUM
+impactDescription: deduplicates within request
+tags: server, cache, react-cache, deduplication
+---
+
+## Per-Request Deduplication with React.cache()
+
+Use `React.cache()` for server-side request deduplication. Authentication and database queries benefit most.
+
+**Usage:**
+
+```typescript
+import { cache } from 'react'
+
+export const getCurrentUser = cache(async () => {
+  const session = await auth()
+  if (!session?.user?.id) return null
+  return await db.user.findUnique({
+    where: { id: session.user.id }
+  })
+})
+```
+
+Within a single request, multiple calls to `getCurrentUser()` execute the query only once.
+
+**Avoid inline objects as arguments:**
+
+`React.cache()` uses shallow equality (`Object.is`) to determine cache hits. Inline objects create new references each call, preventing cache hits.
+
+**Incorrect (always cache miss):**
+
+```typescript
+const getUser = cache(async (params: { uid: number }) => {
+  return await db.user.findUnique({ where: { id: params.uid } })
+})
+
+// Each call creates new object, never hits cache
+getUser({ uid: 1 })
+getUser({ uid: 1 })  // Cache miss, runs query again
+```
+
+**Correct (cache hit):**
+
+```typescript
+const getUser = cache(async (uid: number) => {
+  return await db.user.findUnique({ where: { id: uid } })
+})
+
+// Primitive args use value equality
+getUser(1)
+getUser(1)  // Cache hit, returns cached result
+```
+
+If you must pass objects, pass the same reference:
+
+```typescript
+const params = { uid: 1 }
+getUser(params)  // Query runs
+getUser(params)  // Cache hit (same reference)
+```
+
+**Next.js-Specific Note:**
+
+In Next.js, the `fetch` API is automatically extended with request memoization. Requests with the same URL and options are automatically deduplicated within a single request, so you don't need `React.cache()` for `fetch` calls. However, `React.cache()` is still essential for other async tasks:
+
+- Database queries (Prisma, Drizzle, etc.)
+- Heavy computations
+- Authentication checks
+- File system operations
+- Any non-fetch async work
+
+Use `React.cache()` to deduplicate these operations across your component tree.
+
+Reference: [React.cache documentation](https://react.dev/reference/react/cache)
diff --git a/.github/skills/vercel-react-best-practices/rules/server-dedup-props.md b/.github/skills/vercel-react-best-practices/rules/server-dedup-props.md
new file mode 100644
index 0000000..fb24a25
--- /dev/null
+++ b/.github/skills/vercel-react-best-practices/rules/server-dedup-props.md
@@ -0,0 +1,65 @@
+---
+title: Avoid Duplicate Serialization in RSC Props
+impact: LOW
+impactDescription: reduces network payload by avoiding duplicate serialization
+tags: server, rsc, serialization, props, client-components
+---
+
+## Avoid Duplicate Serialization in RSC Props
+
+**Impact: LOW (reduces network payload by avoiding duplicate serialization)**
+
+RSC→client serialization deduplicates by object reference, not value. Same reference = serialized once; new reference = serialized again. Do transformations (`.toSorted()`, `.filter()`, `.map()`) in client, not server.
+
+**Incorrect (duplicates array):**
+
+```tsx
+// RSC: sends 6 strings (2 arrays × 3 items)
+<ClientList usernames={usernames} usernamesOrdered={usernames.toSorted()} />
+```
+
+**Correct (sends 3 strings):**
+
+```tsx
+// RSC: send once
+<ClientList usernames={usernames} />
+
+// Client: transform there
+'use client'
+const sorted = useMemo(() => [...usernames].sort(), [usernames])
+```
+
+**Nested deduplication behavior:**
+
+Deduplication works recursively. Impact varies by data type:
+
+- `string[]`, `number[]`, `boolean[]`: **HIGH impact** - array + all primitives fully duplicated
+- `object[]`: **LOW impact** - array duplicated, but nested objects deduplicated by reference
+
+```tsx
+// string[] - duplicates everything
+usernames={['a','b']} sorted={usernames.toSorted()} // sends 4 strings
+
+// object[] - duplicates array structure only
+users={[{id:1},{id:2}]} sorted={users.toSorted()} // sends 2 arrays + 2 unique objects (not 4)
+```
+
+**Operations breaking deduplication (create new references):**
+
+- Arrays: `.toSorted()`, `.filter()`, `.map()`, `.slice()`, `[...arr]`
+- Objects: `{...obj}`, `Object.assign()`, `structuredClone()`, `JSON.parse(JSON.stringify())`
+
+**More examples:**
+
+```tsx
+// ❌ Bad
+<C users={users} active={users.filter(u => u.active)} />
+<C product={product} productName={product.name} />
+
+// ✅ Good
+<C users={users} />
+<C product={product} />
+// Do filtering/destructuring in client
+```
+
+**Exception:** Pass derived data when transformation is expensive or client doesn't need original.
diff --git a/.github/skills/vercel-react-best-practices/rules/server-parallel-fetching.md b/.github/skills/vercel-react-best-practices/rules/server-parallel-fetching.md
new file mode 100644
index 0000000..1affc83
--- /dev/null
+++ b/.github/skills/vercel-react-best-practices/rules/server-parallel-fetching.md
@@ -0,0 +1,83 @@
+---
+title: Parallel Data Fetching with Component Composition
+impact: CRITICAL
+impactDescription: eliminates server-side waterfalls
+tags: server, rsc, parallel-fetching, composition
+---
+
+## Parallel Data Fetching with Component Composition
+
+React Server Components execute sequentially within a tree. Restructure with composition to parallelize data fetching.
+
+**Incorrect (Sidebar waits for Page's fetch to complete):**
+
+```tsx
+export default async function Page() {
+  const header = await fetchHeader()
+  return (
+    <div>
+      <div>{header}</div>
+      <Sidebar />
+    </div>
+  )
+}
+
+async function Sidebar() {
+  const items = await fetchSidebarItems()
+  return <nav>{items.map(renderItem)}</nav>
+}
+```
+
+**Correct (both fetch simultaneously):**
+
+```tsx
+async function Header() {
+  const data = await fetchHeader()
+  return <div>{data}</div>
+}
+
+async function Sidebar() {
+  const items = await fetchSidebarItems()
+  return <nav>{items.map(renderItem)}</nav>
+}
+
+export default function Page() {
+  return (
+    <div>
+      <Header />
+      <Sidebar />
+    </div>
+  )
+}
+```
+
+**Alternative with children prop:**
+
+```tsx
+async function Header() {
+  const data = await fetchHeader()
+  return <div>{data}</div>
+}
+
+async function Sidebar() {
+  const items = await fetchSidebarItems()
+  return <nav>{items.map(renderItem)}</nav>
+}
+
+function Layout({ children }: { children: ReactNode }) {
+  return (
+    <div>
+      <Header />
+      {children}
+    </div>
+  )
+}
+
+export default function Page() {
+  return (
+    <Layout>
+      <Sidebar />
+    </Layout>
+  )
+}
+```
diff --git a/.github/skills/vercel-react-best-practices/rules/server-serialization.md b/.github/skills/vercel-react-best-practices/rules/server-serialization.md
new file mode 100644
index 0000000..39c5c41
--- /dev/null
+++ b/.github/skills/vercel-react-best-practices/rules/server-serialization.md
@@ -0,0 +1,38 @@
+---
+title: Minimize Serialization at RSC Boundaries
+impact: HIGH
+impactDescription: reduces data transfer size
+tags: server, rsc, serialization, props
+---
+
+## Minimize Serialization at RSC Boundaries
+
+The React Server/Client boundary serializes all object properties into strings and embeds them in the HTML response and subsequent RSC requests. This serialized data directly impacts page weight and load time, so **size matters a lot**. Only pass fields that the client actually uses.
+
+**Incorrect (serializes all 50 fields):**
+
+```tsx
+async function Page() {
+  const user = await fetchUser()  // 50 fields
+  return <Profile user={user} />
+}
+
+'use client'
+function Profile({ user }: { user: User }) {
+  return <div>{user.name}</div>  // uses 1 field
+}
+```
+
+**Correct (serializes only 1 field):**
+
+```tsx
+async function Page() {
+  const user = await fetchUser()
+  return <Profile name={user.name} />
+}
+
+'use client'
+function Profile({ name }: { name: string }) {
+  return <div>{name}</div>
+}
+```
diff --git a/.github/skills/workflows/sdd-workflow.md b/.github/skills/workflows/sdd-workflow.md
new file mode 100644
index 0000000..af33dff
--- /dev/null
+++ b/.github/skills/workflows/sdd-workflow.md
@@ -0,0 +1,49 @@
+---
+description: Template for creating a product and technical specification for a new component or feature.
+---
+
+# SPEC: [Component Name]
+
+## 1. Goal & Intent
+> Provide a brief description of what this component does and why we are building it.
+
+## 2. Usage & Interface
+> Show how this component will be called in code. Include prop definitions.
+
+```tsx
+<ComponentName 
+  prop1="value"
+  prop2={true}
+/>
+```
+
+## 3. Technical Implementation
+- **State Management**: (e.g., Local React state, Zustand, etc.)
+- **Logic**: (e.g., Use cases for specific hooks like `useEffect` or `useMemo`)
+- **Dependencies**: (e.g., Three.js, Lucide icons, etc.)
+
+## 4. Visuals & Interaction
+- **Aesthetics**: (e.g., "Glassmorphic," "High-contrast dark mode")
+- **Animations**: (e.g., "Fades in using Framer Motion," "Parallax scrolling")
+- **Container Queries**: How does it respond to its parent container?
+
+## 5. Accessibility (WCAG 2.1)
+- [ ] ARIA Labels defined
+- [ ] Keyboard navigation (Tab index, Enter key)
+- [ ] Reduced Motion compatibility
+- [ ] Sufficient color contrast
+
+## 6. Performance
+- [ ] Soft asset limit (e.g., < 500kb textures)
+- [ ] Component-level optimization (Render loops capped)
+- [ ] Critical CSS inlined
+
+## 7. Implementation Checklist
+- [ ] Initial scaffolding
+- [ ] Core logic / State
+- [ ] Visual styling (Tailwind v4)
+- [ ] Interaction / Animation
+- [ ] Final Accessibility audit
+
+## 8. Changelog
+- **[TIMESTAMP]**: Initial spec creation.
diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 0000000..732c927
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,179 @@
+**OBJECTIVE:**
+Building production-ready React applications with TypeScript and Google Gemini AI integration.
+
+**REASON:**
+Enables rapid prototyping and design collaboration with AI-powered assistance while delivering production-quality, maintainable code for development teams.
+
+**DESCRIPTION:**
+Use these instructions when building React applications in TypeScript that integrate with Google Gemini APIs, independent of specific UI frameworks.
+
+**QUICK START:**
+- See [CONTRIBUTING.md](CONTRIBUTING.md) for development workflow and standards
+- See [.github/README.md](.github/README.md) for AI guidance system documentation
+- See [.github/GITHUB_AUTH_SETUP.md](.github/GITHUB_AUTH_SETUP.md) for GitHub authentication setup
+
+**INSTRUCTIONS:**
+Create responsive, accessible React applications with TypeScript using strict configuration and Gemini API integration.
+
+**IMPORTANT!** Before you start a task, or make a new change, follow these _rules_:
+
+- DO NOT change the visual design, theme styling, or composition of the UI once a `checkpoint`, and/or a component or pattern has been established. 
+
+- DO NOT revert any "styling" (CSS/Layout) or "scripting" (TS/JSX) change intentionally by me.
+
+- DO NOT make changes outside the scope of the requested feature, i.e., don't modify the main navigation when asked to build a data table.
+
+- ALWAYS break out code into reusable components ready for export via ES module
+
+- ALWAYS follow the [Component Architecture](.github/rules/component-architecture.md) folder-per-component pattern
+
+- ALWAYS create SPEC.md before coding new features (see [Spec-Driven Development](.github/rules/spec-driven-development.md))
+
+Include the following specifications:
+
+1. **Accessibility & Performance**: Prioritize as first-class features. Follow [Web Interface Guidelines](.github/instructions/web-interface-guidelines.instructions.md):
+   - Semantic HTML (`<button>`, `<a>`, `<label>`, `<form>`)
+   - ARIA labels for icon-only buttons and form controls
+   - Keyboard navigation and visible focus states
+   - Screen reader support with `aria-live` for async updates
+   - No paste-blocking or zoom-disabling
+   - Images with explicit dimensions
+
+2. **Adaptive Layout & Mobile-First UX**: Use CSS custom properties, Container Queries, and dynamic viewport units (`cqw`, `dvh`) for responsive design. Implement touch-friendly interactions.
+
+3. **TypeScript**: Use strict typing throughout. Define interfaces for component props. Avoid `any`.
+
+4. **Component Structure**:
+   - One component per file with PascalCase filename (`.tsx`)
+   - Functional components with hooks
+   - Explicit prop types via interfaces
+   - `defaultProps` for optional props
+   - Named exports or single default export
+
+5. **State Management**: 
+   - Use `useState` and `useContext` for local/shared state
+   - Consider Context API for multi-level prop passing (2-3+ levels)
+   - URL state for filters, tabs, pagination, expanded panels (use libraries like `nuqs`)
+   - Manage Gemini API response state separately from UI state
+
+6. **Styling**: 
+   - Use a consistent CSS-in-JS solution (Emotion, styled-components) or utility-based CSS
+   - Create reusable design tokens (colors, typography, spacing)
+   - Support light/dark modes for (Tailwind)[https://tailwindcss.com/docs/dark-mode#with-system-theme-support] & (MUI)[https://mui.com/material-ui/customization/dark-mode/#the-solution-css-variables]; persist user preference
+   - Avoid `transition: all`; list properties explicitly
+   - Honor `prefers-reduced-motion`
+
+7. **Forms & Inputs**:
+   - Inputs require `<label>` or `aria-label`
+   - Use correct `type` and `inputmode`
+   - Include validation inline near fields
+   - Disable submit button during Gemini API requests; show loading state
+   - Focus first error on submit
+   - No paste-blocking; allow autocomplete
+   - Show streaming indicator when receiving Gemini responses
+
+8. **Icons**: Use inline SVG or icon libraries (e.g., Lucide). No webfont icons.
+
+9. **Images**: 
+   - Explicit `width` and `height` to prevent layout shift
+   - Lazy load below-fold images
+   - Preload critical above-fold images
+   - Handle Gemini-generated images with proper error states
+
+10. **Performance**:
+    - Virtualize large lists (>50 items)
+    - Avoid layout reads in render (`getBoundingClientRect`, `offsetHeight`)
+    - Batch DOM operations
+    - Use uncontrolled inputs where possible
+    - Memoize expensive computations (`useMemo`, `useCallback`)
+    - Debounce Gemini API calls to prevent rate limiting
+
+11. **Gemini API Integration**:
+    - Use official Google Generative AI client library (`@google/generative-ai`)
+    - Implement proper error handling for API failures with user-friendly messages
+    - Show loading states during API requests; support request cancellation
+    - Stream responses when available for better perceived performance
+    - Implement rate limiting and retry logic with exponential backoff
+    - Validate and sanitize API responses before rendering
+    - Store API keys securely (never in client code; use environment variables or backend proxy)
+    - Display clear attribution/disclosure that content is AI-generated
+
+12. **Navigation & Deep Linking**: 
+    - Use `<a>` or router `<Link>` (support Cmd/Ctrl+click)
+    - Sync URL with component state
+    - Support deep linking for all interactive features
+    - Persist AI-generated content state appropriately
+
+13. **Destructive Actions**: Require confirmation modal or undo window. Never immediate.
+
+14. **Chat/Conversation UI** (if applicable):
+    - Display clear visual distinction between user and AI messages
+    - Show typing/streaming indicators during Gemini response generation
+    - Support message editing and regeneration
+    - Implement message history with scroll-to-latest functionality
+    - Include copy-to-clipboard for AI responses
+    - Add feedback mechanism (thumbs up/down) for response quality
+
+15. **Content Generation** (if applicable):
+    - Provide context/prompt templates for consistent results
+    - Show token usage or cost estimates if applicable
+    - Allow users to adjust generation parameters (temperature, length)
+    - Display content source/attribution clearly
+    - Implement review/edit workflow before publishing generated content
+
+16. **Testing & Documentation**: 
+    - Unit tests for core components and utilities
+    - Mock Gemini API responses for testing
+    - Visual regression tests when possible
+    - Storybook or equivalent for documentation
+    - Accessibility audits (APAC/WCAG)
+    - Test error scenarios and API failures
+
+17. **Web Standards Compliance**: Follow all guidelines in [Web Interface Guidelines](.github/instructions/web-interface-guidelines.instructions.md) for forms, focus, animations, content handling, hydration, and copy.
+
+## Development Workflow
+
+### Creating Pull Requests
+
+**Using GitHub CLI (Recommended):**
+```bash
+# Ensure you're authenticated
+gh auth status
+
+# Create PR from current branch
+gh pr create --base main --head $(git branch --show-current)
+
+# Or with template
+gh pr create \
+  --title "$(git log -1 --pretty=format:'%s')" \
+  --body "$(cat .github/pr-template-commits.md)" \
+  --base main
+```
+
+See [.github/GITHUB_AUTH_SETUP.md](.github/GITHUB_AUTH_SETUP.md) for setup instructions.
+
+**Using Prompts:**
+Use [.github/prompts/create-pr.prompt.md](.github/prompts/create-pr.prompt.md) to analyze commits and generate PR descriptions automatically.
+
+### Referencing Guidance Files
+
+When working with AI assistants, reference specific guidance files:
+
+```
+# Before creating a component
+Read .github/rules/component-architecture.md
+Read .github/instructions/web-interface-guidelines.instructions.md
+
+# For performance optimization
+Read .github/skills/vercel-react-best-practices/SKILL.md
+
+# For accessibility
+Read .github/skills/accessibility_audit/SKILL.md
+```
+
+## Additional Resources
+
+- **[.github/copilot-instructions.md](.github/copilot-instructions.md)** - Complete architecture guide
+- **[.github/README.md](.github/README.md)** - AI guidance system overview
+- **[DEPLOYMENT.md](DEPLOYMENT.md)** - Deployment instructions
+- **[README.md](README.md)** - Project setup and overview
\ No newline at end of file
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
new file mode 100644
index 0000000..a6343ad
--- /dev/null
+++ b/CONTRIBUTING.md
@@ -0,0 +1,320 @@
+# Contributing to DevLog
+
+Thank you for your interest in contributing to DevLog! This guide will help you understand our development workflow and standards.
+
+## Table of Contents
+
+- [Getting Started](#getting-started)
+- [Development Workflow](#development-workflow)
+- [AI Guidance System](#ai-guidance-system)
+- [Code Standards](#code-standards)
+- [Testing](#testing)
+- [Pull Requests](#pull-requests)
+- [Commit Conventions](#commit-conventions)
+
+## Getting Started
+
+### Prerequisites
+
+- Node.js v18+
+- Git
+- GitHub account
+- GitHub CLI (`gh`) recommended for PR creation
+
+### Initial Setup
+
+1. **Clone the repository**
+   ```bash
+   git clone https://github.com/ericthayer/devlog.git
+   cd devlog
+   ```
+
+2. **Install dependencies**
+   ```bash
+   npm install
+   ```
+
+3. **Set up environment variables**
+   ```bash
+   cp .env.example .env
+   # Edit .env with your API keys:
+   # - VITE_API_KEY (Google Gemini)
+   # - VITE_SUPABASE_URL
+   # - VITE_SUPABASE_ANON_KEY
+   ```
+
+4. **Run database migrations**
+   - See [README.md](README.md#supabase-configuration) for Supabase setup
+
+5. **Start development server**
+   ```bash
+   npm run dev
+   ```
+
+## Development Workflow
+
+### Branch Strategy
+
+We use feature branches for all development:
+
+```bash
+# Create a feature branch
+git checkout -b feat/your-feature-name
+
+# Or for bug fixes
+git checkout -b fix/issue-description
+
+# Or for documentation
+git checkout -b docs/what-youre-documenting
+```
+
+**Branch naming conventions:**
+- `feat/` - New features
+- `fix/` - Bug fixes
+- `refactor/` - Code refactoring
+- `docs/` - Documentation updates
+- `test/` - Test additions or updates
+- `perf/` - Performance improvements
+
+### Making Changes
+
+1. **Before coding**: Check the [AI Guidance System](#ai-guidance-system)
+2. **Write code**: Follow [Code Standards](#code-standards)
+3. **Add tests**: All features should have tests
+4. **Run tests**: `npm test`
+5. **Build**: Verify with `npm run build`
+6. **Commit**: Follow [Commit Conventions](#commit-conventions)
+
+### Submitting Changes
+
+1. **Push your branch**
+   ```bash
+   git push origin your-branch-name
+   ```
+
+2. **Create a Pull Request**
+   
+   **Option A: GitHub CLI (Recommended)**
+   ```bash
+   gh pr create --base main --head your-branch-name
+   ```
+   
+   **Option B: Manual**
+   - Go to https://github.com/ericthayer/devlog/pulls
+   - Click "New Pull Request"
+   - Select your branch
+   - Fill in the PR template
+   
+   See [.github/GITHUB_AUTH_SETUP.md](.github/GITHUB_AUTH_SETUP.md) for authentication setup.
+
+3. **Wait for review**
+   - Address any feedback
+   - Make requested changes
+   - Push updates to the same branch
+
+## AI Guidance System
+
+DevLog uses a comprehensive AI guidance framework in the `.github/` directory. This helps maintain consistency and quality when working with AI assistants like GitHub Copilot.
+
+### Three-Layer Structure
+
+#### 1. **Instructions** (`.github/instructions/`)
+Scope-specific rules that apply to certain file types:
+
+- `development-standards.instructions.md` - TypeScript/React standards, APCA contrast
+- `web-interface-guidelines.instructions.md` - UI/UX requirements (24px hit targets, keyboard support)
+- `github-issue.instructions.md` - Issue creation format
+- `storybook.instructions.md` - Storybook usage
+
+**When to use**: Reference before creating components or UI elements.
+
+#### 2. **Rules** (`.github/rules/`)
+Architectural principles that govern the codebase:
+
+- `component-architecture.md` - Folder-per-component pattern
+- `spec-driven-development.md` - SDD methodology (create SPEC.md before coding)
+- `supabase.md` - Database, auth, RLS best practices
+- `accessibility.md` - WCAG compliance
+- `web-performance.md` - Performance optimization
+
+**When to use**: Reference when making architectural decisions.
+
+#### 3. **Skills** (`.github/skills/`)
+Executable workflows and templates:
+
+- `scaffold_component/` - Component creation workflow
+- `accessibility_audit/` - Testing checklist
+- `vercel-react-best-practices/` - 45 performance rules
+
+**When to use**: Follow when building new features.
+
+### Using the Guidance System
+
+1. **Before starting work**: Check relevant instructions and rules
+2. **During development**: Reference skills for workflows
+3. **In PR reviews**: Cite rules when suggesting changes
+4. **With AI assistants**: The system is attached to Copilot instructions automatically
+
+See [.github/README.md](.github/README.md) for detailed guidance system documentation.
+
+## Code Standards
+
+### TypeScript/React Standards
+
+- Follow the [Airbnb JavaScript Style Guide](https://airbnb.io/javascript/)
+- Use TypeScript for all new code
+- Use functional components with hooks
+- Define prop types with TypeScript interfaces
+- Avoid `any` types
+
+See [.github/instructions/development-standards.instructions.md](.github/instructions/development-standards.instructions.md) for complete standards.
+
+### Project Structure
+
+```
+src/
+├── components/       # React components (one per folder)
+├── contexts/         # React contexts
+├── services/         # Business logic (API calls, external services)
+├── utils/           # Pure utility functions
+├── tests/           # Test files
+└── types.ts         # Shared TypeScript types
+```
+
+### Component Architecture
+
+Follow the **Folder-per-Component** pattern:
+
+```
+src/components/MyComponent/
+├── MyComponent.tsx       # Component implementation
+├── MyComponent.test.tsx  # Tests
+├── index.ts             # Named export: export { MyComponent } from './MyComponent'
+└── SPEC.md              # Component specification (optional)
+```
+
+See [.github/rules/component-architecture.md](.github/rules/component-architecture.md) for details.
+
+### Styling
+
+- Use Tailwind CSS utility classes
+- Follow brutalist theme (yellow/black, hard borders, no smooth animations)
+- APCA contrast minimum: 60 for normal text, 45 for large text
+- Hit targets: minimum 24px × 24px
+
+## Testing
+
+### Running Tests
+
+```bash
+npm test              # Watch mode
+npm run test:ui       # Interactive UI
+npm run test:coverage # Coverage report
+```
+
+### Writing Tests
+
+- Place tests in `src/tests/` directory
+- Name tests `*.test.tsx` or `*.test.ts`
+- Use Vitest + React Testing Library
+- Follow existing test patterns in `src/tests/`
+
+Example:
+```typescript
+import { describe, it, expect } from 'vitest';
+import { render, screen } from '@testing-library/react';
+import { MyComponent } from '../components/MyComponent';
+
+describe('MyComponent', () => {
+  it('renders correctly', () => {
+    render(<MyComponent />);
+    expect(screen.getByText('Expected Text')).toBeInTheDocument();
+  });
+});
+```
+
+### Test Coverage Goals
+
+- Aim for 80%+ coverage on new code
+- All exported functions should have tests
+- All components should have basic render tests
+
+## Pull Requests
+
+### PR Template
+
+Use the template in [.github/pr-template-commits.md](.github/pr-template-commits.md) or let `gh pr create` auto-fill.
+
+### PR Checklist
+
+Before submitting:
+
+- [ ] Code follows project style guidelines
+- [ ] All tests pass (`npm test`)
+- [ ] Build succeeds (`npm run build`)
+- [ ] No TypeScript errors
+- [ ] Documentation updated (if needed)
+- [ ] Accessibility requirements met (24px targets, keyboard support)
+- [ ] APCA contrast verified for UI changes
+
+### Review Process
+
+1. PRs require at least one approval
+2. All CI checks must pass
+3. Address reviewer feedback promptly
+4. Squash commits before merging (if requested)
+
+## Commit Conventions
+
+We follow [Conventional Commits](https://www.conventionalcommits.org/):
+
+### Format
+
+```
+<type>(<scope>): <subject>
+
+[optional body]
+
+[optional footer]
+```
+
+### Types
+
+- `feat:` - New feature
+- `fix:` - Bug fix
+- `docs:` - Documentation changes
+- `refactor:` - Code refactoring (no functional changes)
+- `test:` - Adding or updating tests
+- `perf:` - Performance improvements
+- `build:` - Build system or dependencies
+- `ci:` - CI configuration changes
+
+### Examples
+
+```bash
+feat(auth): add OAuth login support
+
+fix(upload): resolve file size calculation error
+
+docs(readme): update Supabase setup instructions
+
+refactor(components): move all files to src/ directory
+```
+
+## Need Help?
+
+- **Questions**: Open a [GitHub Discussion](https://github.com/ericthayer/devlog/discussions)
+- **Bugs**: Open an [Issue](https://github.com/ericthayer/devlog/issues)
+- **Security**: Email [maintainer contact info]
+- **AI Agents**: See [AGENTS.md](AGENTS.md) for AI-specific guidelines
+
+## Additional Resources
+
+- [README.md](README.md) - Project overview and setup
+- [DEPLOYMENT.md](DEPLOYMENT.md) - Deployment guide
+- [.github/copilot-instructions.md](.github/copilot-instructions.md) - AI agent architecture guide
+- [.github/GITHUB_AUTH_SETUP.md](.github/GITHUB_AUTH_SETUP.md) - GitHub authentication setup
+
+---
+
+**Thank you for contributing to DevLog!** 🎉
diff --git a/DEPLOYMENT.md b/DEPLOYMENT.md
new file mode 100644
index 0000000..be2e09b
--- /dev/null
+++ b/DEPLOYMENT.md
@@ -0,0 +1,231 @@
+# Deployment Guide
+
+## Prerequisites
+
+Before deploying, ensure you have:
+- Google Gemini API key
+- Supabase project (with database and storage configured)
+- Node.js 18+ installed locally
+
+## Environment Variables
+
+Set these variables in your deployment platform:
+
+```env
+VITE_API_KEY=your_google_gemini_api_key
+VITE_SUPABASE_URL=https://your-project.supabase.co
+VITE_SUPABASE_ANON_KEY=your_supabase_anon_key
+```
+
+## Supabase Setup
+
+### 1. Database Tables
+
+Create the required tables (if not already exists):
+
+```sql
+CREATE TABLE case_studies (
+  id UUID DEFAULT gen_random_uuid() PRIMARY KEY,
+  title TEXT NOT NULL,
+  status TEXT NOT NULL CHECK (status IN ('draft', 'published', 'archived')),
+  problem TEXT,
+  approach TEXT,
+  outcome TEXT,
+  next_steps TEXT,
+  tags TEXT[],
+  seo_metadata JSONB,
+  created_at TIMESTAMP WITH TIME ZONE DEFAULT NOW()
+);
+
+CREATE TABLE assets (
+  id UUID DEFAULT gen_random_uuid() PRIMARY KEY,
+  case_study_id UUID REFERENCES case_studies(id) ON DELETE CASCADE,
+  original_name TEXT NOT NULL,
+  ai_name TEXT NOT NULL,
+  type TEXT,
+  topic TEXT,
+  context TEXT,
+  variant TEXT,
+  version TEXT,
+  file_type TEXT,
+  url TEXT NOT NULL,
+  size INTEGER,
+  created_at TIMESTAMP WITH TIME ZONE DEFAULT NOW()
+);
+```
+
+### 2. Run Authentication Migration
+
+Execute the migration file to set up authentication and RLS policies:
+
+```bash
+# From your local machine
+psql your_supabase_connection_string < supabase/migrations/001_auth_and_rls.sql
+```
+
+Or use Supabase Dashboard → SQL Editor and paste the contents of `supabase/migrations/001_auth_and_rls.sql`.
+
+### 3. Storage Bucket
+
+Create a bucket named `assets` in Supabase Storage. The RLS policies from the migration will handle permissions.
+
+### 4. Configure Email Auth
+
+In Supabase Dashboard:
+1. Go to Authentication → Providers
+2. Enable Email provider
+3. Configure email templates (optional)
+4. Set site URL to your deployment URL
+
+## Deploy to Vercel
+
+### One-Click Deploy
+
+[![Deploy with Vercel](https://vercel.com/button)](https://vercel.com/new/clone?repository-url=https://github.com/YOUR_USERNAME/devlog)
+
+### Manual Deployment
+
+1. Install Vercel CLI:
+```bash
+npm install -g vercel
+```
+
+2. Login to Vercel:
+```bash
+vercel login
+```
+
+3. Deploy:
+```bash
+vercel
+```
+
+4. Add environment variables in Vercel Dashboard:
+   - Go to your project → Settings → Environment Variables
+   - Add `VITE_API_KEY`, `VITE_SUPABASE_URL`, `VITE_SUPABASE_ANON_KEY`
+
+5. Redeploy to apply environment variables:
+```bash
+vercel --prod
+```
+
+### Build Configuration
+
+Vercel will auto-detect Vite. If needed, configure:
+
+**Build Command**: `npm run build`
+**Output Directory**: `dist`
+**Install Command**: `npm install`
+
+## Deploy to Netlify
+
+1. Install Netlify CLI:
+```bash
+npm install -g netlify-cli
+```
+
+2. Build the app:
+```bash
+npm run build
+```
+
+3. Deploy:
+```bash
+netlify deploy --prod
+```
+
+4. Set environment variables in Netlify Dashboard:
+   - Go to Site Settings → Build & Deploy → Environment
+   - Add the three environment variables
+
+### netlify.toml Configuration
+
+Create `netlify.toml` in the project root:
+
+```toml
+[build]
+  command = "npm run build"
+  publish = "dist"
+
+[[redirects]]
+  from = "/*"
+  to = "/index.html"
+  status = 200
+```
+
+## Post-Deployment
+
+### 1. Create First User
+
+Visit your deployed app and sign up with an email and password. Choose the "publisher" role for admin access.
+
+### 2. Update Supabase Redirect URLs
+
+In Supabase Dashboard → Authentication → URL Configuration:
+- Add your deployment URL to the list of redirect URLs
+- Example: `https://your-app.vercel.app`
+
+### 3. Test Authentication
+
+1. Sign up a new user
+2. Check that the user appears in Supabase Dashboard → Authentication → Users
+3. Verify the `user_roles` table has the correct role
+
+### 4. Upload a Case Study
+
+Test the full flow:
+1. Upload design files
+2. Generate a case study
+3. Verify files appear in Supabase Storage
+4. Check database records in `case_studies` and `assets` tables
+
+## Troubleshooting
+
+### Authentication Errors
+
+**Error**: "User not found" or "Invalid login credentials"
+- Verify email confirmation settings in Supabase
+- Check that email provider is enabled
+
+**Error**: "Access denied" or "Row level security"
+- Ensure RLS policies are properly configured
+- Verify user has a role in `user_roles` table
+
+### Storage Upload Errors
+
+**Error**: "StorageApiError: headers must have required property 'authorization'"
+- Check that storage RLS policies allow authenticated uploads
+- Verify user is logged in before uploading
+
+### Build Errors
+
+**Error**: Missing environment variables
+- Ensure all `VITE_*` variables are set in deployment platform
+- Restart the build after adding variables
+
+**Error**: Type errors during build
+- Run `npm run build` locally first to catch issues
+- Check TypeScript configuration in `tsconfig.json`
+
+## Monitoring & Maintenance
+
+### Check Supabase Logs
+
+Monitor your deployment:
+- Database logs: Supabase Dashboard → Database → Logs
+- Storage logs: Supabase Dashboard → Storage → Logs
+- Auth logs: Supabase Dashboard → Authentication → Logs
+
+### Update Dependencies
+
+```bash
+npm update
+npm audit fix
+```
+
+### Database Backups
+
+Supabase provides automatic backups. For manual backups:
+```bash
+pg_dump your_supabase_connection_string > backup.sql
+```
diff --git a/IMPLEMENTATION_SUMMARY.md b/IMPLEMENTATION_SUMMARY.md
new file mode 100644
index 0000000..a84e0fd
--- /dev/null
+++ b/IMPLEMENTATION_SUMMARY.md
@@ -0,0 +1,157 @@
+# Implementation Summary
+
+## ✅ Completed Tasks
+
+### 1. Authentication & Authorization
+
+**Files Created:**
+- `src/contexts/AuthContext.tsx` - Auth state management with Supabase
+- `src/components/LoginView.tsx` - Login/signup UI with role selection
+- `supabase/migrations/001_auth_and_rls.sql` - Database migration for auth + RLS
+
+**Files Modified:**
+- `src/types.ts` - Added User, UserRole types, updated AppView
+- `src/index.tsx` - Wrapped app with AuthProvider
+- `src/App.tsx` - Added auth checks, canEdit permission logic
+- `src/components/AppHeader.tsx` - Added user info display and logout button
+- `src/components/UploadView.tsx` - Added canEdit prop to restrict publisher-only actions
+
+**Features:**
+- Two roles: `publisher` (full CRUD) and `reader` (read-only published content)
+- Row-level security on case_studies, assets, and storage
+- User roles table links auth.users to roles
+- Protected routes based on authentication state
+
+### 2. Testing Infrastructure
+
+**Files Created:**
+- `vitest.config.ts` - Vitest configuration
+- `src/tests/setup.ts` - Test setup with jest-dom matchers
+- `src/tests/BrutalistButton.test.tsx` - Example component test
+- `src/tests/geminiService.test.ts` - Example service test with mocking
+
+**Files Modified:**
+- `package.json` - Added test scripts (test, test:ui, test:coverage)
+
+**Dependencies Added:**
+- vitest
+- @testing-library/react
+- @testing-library/jest-dom
+- @testing-library/user-event
+- jsdom
+- @vitest/ui
+
+### 3. Deployment Documentation
+
+**Files Created:**
+- `DEPLOYMENT.md` - Comprehensive deployment guide covering:
+  - Vercel deployment (one-click + manual)
+  - Netlify deployment
+  - Supabase setup (database, auth, storage)
+  - Environment variables
+  - Post-deployment checklist
+  - Troubleshooting guide
+
+### 4. Documentation Updates
+
+**Files Modified:**
+- `.github/copilot-instructions.md` - Updated with:
+  - Authentication patterns
+  - Error handling patterns (Toast, try-catch, optimistic updates)
+  - Testing strategy
+  - Permission checks (canEdit pattern)
+  - Storage bucket policies for authenticated access
+  
+- `README.md` - Major updates:
+  - Added authentication section
+  - Added testing section with examples
+  - Added deployment quick-start
+  - Updated architecture overview
+  - Added project structure tree
+  - Expanded tech stack
+  - Added role descriptions
+
+## 🔑 Key Changes
+
+### Authentication Flow
+1. User visits app → AuthProvider checks session
+2. If no session → Shows LoginView
+3. User signs up/in → Creates/retrieves role from user_roles table
+4. App loads with canEdit = (user.role === 'publisher')
+5. UI conditionally shows create/edit/delete based on canEdit
+
+### RLS Security
+- Publishers can CRUD all case studies (including drafts)
+- Readers can only SELECT published case studies
+- Publishers can upload/modify/delete storage objects
+- All authenticated users can view storage objects
+
+### Testing Approach
+- Vitest for fast test execution
+- React Testing Library for component testing
+- Service mocking with vi.mock()
+- Tests in src/tests/ directory
+
+### Deployment
+- One-click Vercel deployment supported
+- Environment variables configured via dashboard
+- Supabase migration must be run before first use
+- Email confirmation can be disabled in Supabase for dev
+
+## 📋 Next Steps for User
+
+1. **Run Database Migration**
+   ```bash
+   # In Supabase Dashboard → SQL Editor, paste and run:
+   # supabase/migrations/001_auth_and_rls.sql
+   ```
+
+2. **Create First User**
+   - Start app with `npm run dev`
+   - Sign up with email/password
+   - Choose "Publisher" role
+   - Verify user appears in Supabase Dashboard → Authentication → Users
+
+3. **Test Authentication**
+   - Upload files
+   - Create case study
+   - Log out
+   - Sign up as Reader
+   - Verify restricted access
+
+4. **Run Tests**
+   ```bash
+   npm test           # Watch mode
+   npm run test:ui    # Interactive UI
+   ```
+
+5. **Deploy**
+   - Follow DEPLOYMENT.md for Vercel or Netlify
+   - Set environment variables in platform dashboard
+   - Update Supabase redirect URLs
+
+## 🐛 Potential Issues
+
+1. **Storage Authorization Errors**
+   - Ensure migration was run completely
+   - Check user has role in user_roles table
+   - Verify storage policies exist (Dashboard → Storage → assets → Policies)
+
+2. **Test Import Errors**
+   - If tests fail to import React components, check vitest.config.ts
+   - Ensure @vitejs/plugin-react is loaded
+
+3. **Authentication Redirect Loop**
+   - Check VITE_SUPABASE_URL is set correctly
+   - Verify email confirmation settings in Supabase
+
+## 📊 Statistics
+
+- **Files Created**: 9
+- **Files Modified**: 8
+- **Lines of Code Added**: ~1,200
+- **Dependencies Added**: 6
+- **Test Files Created**: 3
+- **Documentation Files**: 3
+
+All requested features have been implemented successfully! 🎉
diff --git a/LOGIN_UX_IMPROVEMENTS.md b/LOGIN_UX_IMPROVEMENTS.md
new file mode 100644
index 0000000..9ba43d0
--- /dev/null
+++ b/LOGIN_UX_IMPROVEMENTS.md
@@ -0,0 +1,147 @@
+# LoginView UX Improvements
+
+## Changes Made
+
+### 1. Password Visibility Toggle ✅
+- Added eye/eye-off icon button in password field
+- Toggle between password obfuscation and plain text
+- Uses lucide-react `Eye` and `EyeOff` icons
+- Positioned absolutely in input field (right side)
+
+**Implementation:**
+```tsx
+const [showPassword, setShowPassword] = useState(false);
+
+<input type={showPassword ? 'text' : 'password'} ... />
+<button onClick={() => setShowPassword(!showPassword)}>
+  <Icon name={showPassword ? 'EyeOff' : 'Eye'} />
+</button>
+```
+
+### 2. Publisher Role by Request Only ✅
+- All new sign-ups default to `reader` role
+- Added checkbox to request publisher access during sign-up
+- Publisher requests tracked in `user_roles.publisher_requested` column
+- Success message shown when publisher access requested
+- Admin must manually approve via SQL query
+
+**Implementation:**
+```tsx
+const [requestPublisher, setRequestPublisher] = useState(false);
+
+// On sign-up
+await signUp(email, password, 'reader', requestPublisher);
+```
+
+**Database:**
+```sql
+ALTER TABLE user_roles ADD COLUMN publisher_requested BOOLEAN DEFAULT FALSE;
+```
+
+**Admin Approval Process:**
+```sql
+-- Check pending requests
+SELECT * FROM user_roles WHERE publisher_requested = true;
+
+-- Approve user
+UPDATE user_roles 
+SET role = 'publisher', publisher_requested = false 
+WHERE user_id = 'xxx-xxx-xxx';
+```
+
+### 3. OAuth Provider Login (Google & GitHub) ✅
+- Added "OR CONTINUE WITH" section below email/password form
+- Google and GitHub OAuth buttons with provider icons
+- Uses Supabase Auth's `signInWithOAuth()` method
+- OAuth users auto-assigned reader role on first login
+- Redirect handled automatically by Supabase
+
+**Implementation:**
+```tsx
+const signInWithProvider = async (provider: 'google' | 'github') => {
+  await supabase.auth.signInWithOAuth({
+    provider,
+    options: { redirectTo: window.location.origin }
+  });
+};
+```
+
+**OAuth First-Time Login Flow:**
+1. User clicks Google/GitHub button
+2. Redirects to provider for authentication
+3. Provider redirects back to app
+4. `getUserRole()` checks if user has role
+5. If no role exists, creates reader role automatically
+6. User is logged in with reader access
+
+## UI/UX Design
+
+### Sign-Up Form
+- Reader access highlighted in yellow box (default)
+- Publisher request shown as checkbox option
+- Clear iconography (BookOpen for reader, Crown for publisher)
+- Helpful descriptions under each option
+- Success banner if publisher access requested
+
+### OAuth Buttons
+- Consistent brutalist styling
+- Provider icons (Chrome for Google, Github for GitHub)
+- Disabled state during loading
+- Secondary variant for non-primary action
+
+### Visual Hierarchy
+1. Email/Password form (primary)
+2. Divider line
+3. OAuth options (secondary)
+4. Role permissions info (footer)
+
+## Updated Files
+
+**Components:**
+- `src/components/LoginView.tsx` - Complete redesign with all 3 features
+
+**Contexts:**
+- `src/contexts/AuthContext.tsx` - Added `signInWithProvider()` and `requestPublisher` param
+
+**Database:**
+- `supabase/migrations/001_auth_and_rls.sql` - Added `publisher_requested` column
+
+**Documentation:**
+- `.github/copilot-instructions.md` - Updated OAuth and approval workflow docs
+
+## Next Steps for Setup
+
+1. **Enable OAuth Providers in Supabase:**
+   - Dashboard → Authentication → Providers
+   - Enable Google OAuth
+   - Enable GitHub OAuth
+   - Configure redirect URLs
+
+2. **Google OAuth Setup:**
+   - Go to Google Cloud Console
+   - Create OAuth 2.0 Client ID
+   - Add authorized redirect URI: `https://<your-project>.supabase.co/auth/v1/callback`
+   - Copy Client ID and Secret to Supabase
+
+3. **GitHub OAuth Setup:**
+   - Go to GitHub Developer Settings
+   - Create OAuth App
+   - Authorization callback URL: `https://<your-project>.supabase.co/auth/v1/callback`
+   - Copy Client ID and Secret to Supabase
+
+4. **Test Flow:**
+   - Sign up with email (request publisher access)
+   - Check database for `publisher_requested = true`
+   - Approve via SQL
+   - Sign out and sign in again to see publisher role
+   - Test Google OAuth sign-in
+   - Test GitHub OAuth sign-in
+
+## Security Considerations
+
+- OAuth users cannot request publisher access during first login (by design)
+- They must contact admin separately or feature can be added later
+- All role checks happen server-side via RLS policies
+- Publisher approval requires database access (admin-only)
+
+All features are complete and ready for testing! 🎉
diff --git a/README.md b/README.md
index ca4b987..75f71cf 100644
--- a/README.md
+++ b/README.md
@@ -1,20 +1,231 @@
-<div align="center">
-   <img width="1178" height="869" alt="devlog-md-v1 0 0-alpha" src="https://github.com/user-attachments/assets/d69ffcac-5486-4d54-8544-61c0c7d04e6e" />
-</div>
+# DevLog - Brutalist Case Study Engine
 
-# Run and deploy your AI Studio app
+A React + TypeScript application for generating UX/Front-end case studies from design artifacts using AI. Features a brutalist UI aesthetic with a distinctive yellow/black theme and role-based authentication.
 
-This contains everything you need to run your app locally.
+## Purpose
 
-View your app in AI Studio: https://ai.studio/apps/drive/1q-W5TKWzSEGZ9Judc6ubqhYuuvk6-l57
+DevLog analyzes design assets (wireframes, mockups, prototypes) and automatically generates professional case studies. Upload your work files, and the AI synthesizes them into structured documentation with timeline views, detailed breakdowns, and exportable articles.
 
-## Run Locally
+Supports two user roles:
+- **Publisher**: Full access to create, edit, and delete case studies
+- **Reader**: View published case studies only
 
-**Prerequisites:**  Node.js
+## Contributing
 
+We welcome contributions! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for:
+- Development workflow and branch strategy
+- Code standards and testing requirements
+- Pull request process
+- AI guidance system overview
 
-1. Install dependencies:
-   `npm install`
-2. Set the `GEMINI_API_KEY` in [.env.local](.env.local) to your Gemini API key
-3. Run the app:
-   `npm run dev`
+## AI Guidance System
+
+DevLog includes a comprehensive AI development framework in [.github/](.github/README.md) with three layers:
+
+1. **Instructions** - Scope-specific guidelines (TypeScript standards, UI requirements, accessibility)
+2. **Rules** - Architectural principles (component structure, SDD, Supabase patterns)
+3. **Skills** - Executable workflows (scaffolding, audits, performance best practices)
+
+This system helps maintain consistency and quality across the codebase. See [.github/README.md](.github/README.md) for details.
+
+## Tech Stack
+
+- **Frontend**: React 19 + TypeScript + Vite
+- **Styling**: Tailwind CSS (brutalist theme)
+- **AI**: Google Gemini API (2.5-flash with thinking mode)
+- **Database**: Supabase (PostgreSQL + Storage)
+- **Authentication**: Supabase Auth with RLS
+- **Testing**: Vitest + React Testing Library
+- **Fallback**: LocalStorage persistence
+- **Icons**: lucide-react
+
+## Setup
+
+### Prerequisites
+- Node.js (v18+)
+- Google Gemini API key
+- Supabase project
+
+### Installation
+
+```bash
+npm install
+```
+
+### Environment Variables
+
+Create `.env` with:
+
+```env
+VITE_API_KEY=your_google_gemini_api_key
+VITE_SUPABASE_URL=your_supabase_project_url
+VITE_SUPABASE_ANON_KEY=your_supabase_anon_key
+```
+
+### Supabase Configuration
+
+#### 1. Create Storage Bucket
+
+1. Go to Supabase Dashboard → Storage
+2. Create a new bucket named `assets`
+3. Make it public or configure RLS policies (see migration file)
+
+#### 2. Run Database Migration
+
+Apply the authentication and RLS policies:
+
+1. Go to Supabase Dashboard → SQL Editor
+2. Copy the contents of `supabase/migrations/001_auth_and_rls.sql`
+3. Paste and run the SQL
+
+This will:
+- Create `user_roles` table for role management
+- Set up RLS policies for `case_studies` and `assets` tables
+- Configure storage policies for authenticated access
+
+#### 3. Enable Email Authentication
+
+1. Go to Supabase Dashboard → Authentication → Providers
+2. Enable the Email provider
+3. Configure email templates (optional)
+4. Set your site URL in Authentication → URL Configuration
+
+### Alternative: Quick Setup (Public Storage)
+
+For development/testing without authentication, apply these simpler storage policies:
+
+```sql
+-- Insert policy
+CREATE POLICY "Upload" ON storage.objects FOR INSERT TO public 
+WITH CHECK (bucket_id = 'assets');
+
+-- Read policy  
+CREATE POLICY "Public Access" ON storage.objects FOR SELECT TO public 
+USING (bucket_id = 'assets');
+
+-- Update policy
+CREATE POLICY "Update" ON storage.objects FOR UPDATE TO public 
+USING (bucket_id = 'assets') WITH CHECK (bucket_id = 'assets');
+```
+
+**Note**: This bypasses authentication. Use only for local development.
+
+## Development
+
+```bash
+npm run dev          # Start dev server on port 3000
+npm run build        # Production build
+npm test             # Run tests in watch mode
+npm run test:ui      # Interactive test UI
+npm run test:coverage # Test coverage report
+```
+
+## Testing
+
+Tests are written using Vitest and React Testing Library.
+
+### Running Tests
+
+```bash
+# Watch mode (re-runs on file changes)
+npm test
+
+# Interactive UI
+npm run test:ui
+
+# Coverage report
+npm run test:coverage
+```
+
+### Test Files
+
+- Component tests: `src/tests/*.test.tsx`
+- Service tests: `src/tests/*.test.ts`
+- Test setup: `src/tests/setup.ts`
+
+### Example Tests
+
+See existing examples:
+- [BrutalistButton.test.tsx](src/tests/BrutalistButton.test.tsx) - Component testing
+- [geminiService.test.ts](src/tests/geminiService.test.ts) - Service mocking
+
+## Deployment
+
+See [DEPLOYMENT.md](DEPLOYMENT.md) for complete deployment instructions covering:
+- Vercel deployment
+- Netlify deployment  
+- Supabase configuration
+- Environment variables
+- Post-deployment checklist
+
+Quick deploy to Vercel:
+
+```bash
+npm install -g vercel
+vercel
+```
+
+Then add environment variables in Vercel Dashboard and redeploy.
+
+## Key Features
+
+- **AI-Powered Analysis**: Automatic asset naming and case study generation
+- **Role-Based Access**: Publisher (admin) and Reader roles with RLS
+- **ZIP Support**: Auto-extract design files from archives
+- **Three-Layer Persistence**: Supabase → LocalStorage → Demo data
+- **Brutalist UI**: Bold yellow/black aesthetic with hard transitions
+- **Export Ready**: Generate shareable case study articles
+- **Testing Suite**: Comprehensive tests with Vitest
+- **Type Safety**: Full TypeScript coverage
+
+## Architecture
+
+- **Authentication**: Supabase Auth with custom roles (publisher/reader)
+- **Authorization**: Row-level security policies in PostgreSQL
+- **Data Flow**: Database-first with localStorage overlay
+- **State Management**: Single root state with AuthContext
+- **File Handling**: Blob URLs for small files, direct storage for >30MB
+- **Naming Convention**: AI generates `[topic]-[type]-[context]-[variant]-[version]` filenames
+- **Error Handling**: Optimistic updates with toast notifications
+
+## Project Structure
+
+```
+devlog/
+├── src/
+│   ├── components/       # React components
+│   │   ├── LoginView.tsx # Authentication UI
+│   │   ├── TimelineView.tsx
+│   │   ├── EditorView.tsx
+│   │   └── ...
+│   ├── contexts/         # React contexts
+│   │   └── AuthContext.tsx
+│   ├── services/         # Business logic
+│   │   ├── geminiService.ts # AI integration
+│   │   └── dbService.ts     # Supabase operations
+│   ├── tests/            # Test files
+│   │   ├── setup.ts
+│   │   └── *.test.tsx
+│   └── utils/            # Utilities
+│       ├── supabase.ts   # Supabase client
+│       └── demoData.ts   # Fallback data
+├── supabase/
+│   └── migrations/       # SQL migrations
+│       └── 001_auth_and_rls.sql
+├── .github/              # AI guidance system
+│   ├── instructions/     # Scope-specific guidelines
+│   ├── rules/           # Architectural principles
+│   └── skills/          # Executable workflows
+├── CONTRIBUTING.md       # Developer guide
+├── DEPLOYMENT.md         # Deployment guide
+└── README.md             # This file
+```
+
+See [.github/copilot-instructions.md](.github/copilot-instructions.md) for detailed architecture documentation.
+
+## Resources
+
+- **[CONTRIBUTING.md](CONTRIBUTING.md)** - How to contribute
+- **[DEPLOYMENT.md](DEPLOYMENT.md)** - Deployment guide (Vercel, Netlify, Supabase)
+- **[.github/README.md](.github/README.md)** - AI guidance system documentation
+- **[AGENTS.md](AGENTS.md)** - AI agent development guidelines
diff --git a/index.html b/index.html
index af45317..e15c604 100644
--- a/index.html
+++ b/index.html
@@ -65,6 +65,6 @@
 </head>
 <body class="bg-gray-50">
     <div id="root"></div>
-    <script type="module" src="/index.tsx"></script>
+    <script type="module" src="/src/index.tsx"></script>
 </body>
 </html>
diff --git a/package-lock.json b/package-lock.json
index 77719f5..f9442bf 100644
--- a/package-lock.json
+++ b/package-lock.json
@@ -20,17 +20,37 @@
         "@tailwindcss/container-queries": "^0.1.1",
         "@tailwindcss/forms": "^0.5.11",
         "@tailwindcss/typography": "^0.5.19",
+        "@testing-library/jest-dom": "^6.9.1",
+        "@testing-library/react": "^16.3.2",
+        "@testing-library/user-event": "^14.6.1",
         "@types/node": "^22.14.0",
         "@vitejs/plugin-react": "^5.0.0",
+        "@vitest/ui": "^4.0.18",
         "autoprefixer": "^10.4.23",
         "dotenv": "^17.2.3",
+        "jsdom": "^27.4.0",
         "postcss": "^8.5.6",
         "tailwindcss": "^3.4.17",
         "tsx": "^4.21.0",
         "typescript": "~5.8.2",
-        "vite": "^6.2.0"
+        "vite": "^6.2.0",
+        "vitest": "^4.0.18"
       }
     },
+    "node_modules/@acemir/cssom": {
+      "version": "0.9.31",
+      "resolved": "https://registry.npmjs.org/@acemir/cssom/-/cssom-0.9.31.tgz",
+      "integrity": "sha512-ZnR3GSaH+/vJ0YlHau21FjfLYjMpYVIzTD8M8vIEQvIGxeOXyXdzCI140rrCY862p/C/BbzWsjc1dgnM9mkoTA==",
+      "dev": true,
+      "license": "MIT"
+    },
+    "node_modules/@adobe/css-tools": {
+      "version": "4.4.4",
+      "resolved": "https://registry.npmjs.org/@adobe/css-tools/-/css-tools-4.4.4.tgz",
+      "integrity": "sha512-Elp+iwUx5rN5+Y8xLt5/GRoG20WGoDCQ/1Fb+1LiGtvwbDavuSk0jhD/eZdckHAuzcDzccnkv+rEjyWfRx18gg==",
+      "dev": true,
+      "license": "MIT"
+    },
     "node_modules/@alloc/quick-lru": {
       "version": "5.2.0",
       "resolved": "https://registry.npmjs.org/@alloc/quick-lru/-/quick-lru-5.2.0.tgz",
@@ -44,6 +64,61 @@
         "url": "https://github.com/sponsors/sindresorhus"
       }
     },
+    "node_modules/@asamuzakjp/css-color": {
+      "version": "4.1.1",
+      "resolved": "https://registry.npmjs.org/@asamuzakjp/css-color/-/css-color-4.1.1.tgz",
+      "integrity": "sha512-B0Hv6G3gWGMn0xKJ0txEi/jM5iFpT3MfDxmhZFb4W047GvytCf1DHQ1D69W3zHI4yWe2aTZAA0JnbMZ7Xc8DuQ==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@csstools/css-calc": "^2.1.4",
+        "@csstools/css-color-parser": "^3.1.0",
+        "@csstools/css-parser-algorithms": "^3.0.5",
+        "@csstools/css-tokenizer": "^3.0.4",
+        "lru-cache": "^11.2.4"
+      }
+    },
+    "node_modules/@asamuzakjp/css-color/node_modules/lru-cache": {
+      "version": "11.2.5",
+      "resolved": "https://registry.npmjs.org/lru-cache/-/lru-cache-11.2.5.tgz",
+      "integrity": "sha512-vFrFJkWtJvJnD5hg+hJvVE8Lh/TcMzKnTgCWmtBipwI5yLX/iX+5UB2tfuyODF5E7k9xEzMdYgGqaSb1c0c5Yw==",
+      "dev": true,
+      "license": "BlueOak-1.0.0",
+      "engines": {
+        "node": "20 || >=22"
+      }
+    },
+    "node_modules/@asamuzakjp/dom-selector": {
+      "version": "6.7.6",
+      "resolved": "https://registry.npmjs.org/@asamuzakjp/dom-selector/-/dom-selector-6.7.6.tgz",
+      "integrity": "sha512-hBaJER6A9MpdG3WgdlOolHmbOYvSk46y7IQN/1+iqiCuUu6iWdQrs9DGKF8ocqsEqWujWf/V7b7vaDgiUmIvUg==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@asamuzakjp/nwsapi": "^2.3.9",
+        "bidi-js": "^1.0.3",
+        "css-tree": "^3.1.0",
+        "is-potential-custom-element-name": "^1.0.1",
+        "lru-cache": "^11.2.4"
+      }
+    },
+    "node_modules/@asamuzakjp/dom-selector/node_modules/lru-cache": {
+      "version": "11.2.5",
+      "resolved": "https://registry.npmjs.org/lru-cache/-/lru-cache-11.2.5.tgz",
+      "integrity": "sha512-vFrFJkWtJvJnD5hg+hJvVE8Lh/TcMzKnTgCWmtBipwI5yLX/iX+5UB2tfuyODF5E7k9xEzMdYgGqaSb1c0c5Yw==",
+      "dev": true,
+      "license": "BlueOak-1.0.0",
+      "engines": {
+        "node": "20 || >=22"
+      }
+    },
+    "node_modules/@asamuzakjp/nwsapi": {
+      "version": "2.3.9",
+      "resolved": "https://registry.npmjs.org/@asamuzakjp/nwsapi/-/nwsapi-2.3.9.tgz",
+      "integrity": "sha512-n8GuYSrI9bF7FFZ/SjhwevlHc8xaVlb/7HmHelnc/PZXBD2ZR49NnN9sMMuDdEGPeeRQ5d0hqlSlEpgCX3Wl0Q==",
+      "dev": true,
+      "license": "MIT"
+    },
     "node_modules/@babel/code-frame": {
       "version": "7.28.6",
       "resolved": "https://registry.npmjs.org/@babel/code-frame/-/code-frame-7.28.6.tgz",
@@ -278,6 +353,16 @@
         "@babel/core": "^7.0.0-0"
       }
     },
+    "node_modules/@babel/runtime": {
+      "version": "7.28.6",
+      "resolved": "https://registry.npmjs.org/@babel/runtime/-/runtime-7.28.6.tgz",
+      "integrity": "sha512-05WQkdpL9COIMz4LjTxGpPNCdlpyimKppYNoJ5Di5EUObifl8t4tuLuUBBZEpoLYOmfvIWrsp9fCl0HoPRVTdA==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": ">=6.9.0"
+      }
+    },
     "node_modules/@babel/template": {
       "version": "7.28.6",
       "resolved": "https://registry.npmjs.org/@babel/template/-/template-7.28.6.tgz",
@@ -326,6 +411,138 @@
         "node": ">=6.9.0"
       }
     },
+    "node_modules/@csstools/color-helpers": {
+      "version": "5.1.0",
+      "resolved": "https://registry.npmjs.org/@csstools/color-helpers/-/color-helpers-5.1.0.tgz",
+      "integrity": "sha512-S11EXWJyy0Mz5SYvRmY8nJYTFFd1LCNV+7cXyAgQtOOuzb4EsgfqDufL+9esx72/eLhsRdGZwaldu/h+E4t4BA==",
+      "dev": true,
+      "funding": [
+        {
+          "type": "github",
+          "url": "https://github.com/sponsors/csstools"
+        },
+        {
+          "type": "opencollective",
+          "url": "https://opencollective.com/csstools"
+        }
+      ],
+      "license": "MIT-0",
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@csstools/css-calc": {
+      "version": "2.1.4",
+      "resolved": "https://registry.npmjs.org/@csstools/css-calc/-/css-calc-2.1.4.tgz",
+      "integrity": "sha512-3N8oaj+0juUw/1H3YwmDDJXCgTB1gKU6Hc/bB502u9zR0q2vd786XJH9QfrKIEgFlZmhZiq6epXl4rHqhzsIgQ==",
+      "dev": true,
+      "funding": [
+        {
+          "type": "github",
+          "url": "https://github.com/sponsors/csstools"
+        },
+        {
+          "type": "opencollective",
+          "url": "https://opencollective.com/csstools"
+        }
+      ],
+      "license": "MIT",
+      "engines": {
+        "node": ">=18"
+      },
+      "peerDependencies": {
+        "@csstools/css-parser-algorithms": "^3.0.5",
+        "@csstools/css-tokenizer": "^3.0.4"
+      }
+    },
+    "node_modules/@csstools/css-color-parser": {
+      "version": "3.1.0",
+      "resolved": "https://registry.npmjs.org/@csstools/css-color-parser/-/css-color-parser-3.1.0.tgz",
+      "integrity": "sha512-nbtKwh3a6xNVIp/VRuXV64yTKnb1IjTAEEh3irzS+HkKjAOYLTGNb9pmVNntZ8iVBHcWDA2Dof0QtPgFI1BaTA==",
+      "dev": true,
+      "funding": [
+        {
+          "type": "github",
+          "url": "https://github.com/sponsors/csstools"
+        },
+        {
+          "type": "opencollective",
+          "url": "https://opencollective.com/csstools"
+        }
+      ],
+      "license": "MIT",
+      "dependencies": {
+        "@csstools/color-helpers": "^5.1.0",
+        "@csstools/css-calc": "^2.1.4"
+      },
+      "engines": {
+        "node": ">=18"
+      },
+      "peerDependencies": {
+        "@csstools/css-parser-algorithms": "^3.0.5",
+        "@csstools/css-tokenizer": "^3.0.4"
+      }
+    },
+    "node_modules/@csstools/css-parser-algorithms": {
+      "version": "3.0.5",
+      "resolved": "https://registry.npmjs.org/@csstools/css-parser-algorithms/-/css-parser-algorithms-3.0.5.tgz",
+      "integrity": "sha512-DaDeUkXZKjdGhgYaHNJTV9pV7Y9B3b644jCLs9Upc3VeNGg6LWARAT6O+Q+/COo+2gg/bM5rhpMAtf70WqfBdQ==",
+      "dev": true,
+      "funding": [
+        {
+          "type": "github",
+          "url": "https://github.com/sponsors/csstools"
+        },
+        {
+          "type": "opencollective",
+          "url": "https://opencollective.com/csstools"
+        }
+      ],
+      "license": "MIT",
+      "engines": {
+        "node": ">=18"
+      },
+      "peerDependencies": {
+        "@csstools/css-tokenizer": "^3.0.4"
+      }
+    },
+    "node_modules/@csstools/css-syntax-patches-for-csstree": {
+      "version": "1.0.26",
+      "resolved": "https://registry.npmjs.org/@csstools/css-syntax-patches-for-csstree/-/css-syntax-patches-for-csstree-1.0.26.tgz",
+      "integrity": "sha512-6boXK0KkzT5u5xOgF6TKB+CLq9SOpEGmkZw0g5n9/7yg85wab3UzSxB8TxhLJ31L4SGJ6BCFRw/iftTha1CJXA==",
+      "dev": true,
+      "funding": [
+        {
+          "type": "github",
+          "url": "https://github.com/sponsors/csstools"
+        },
+        {
+          "type": "opencollective",
+          "url": "https://opencollective.com/csstools"
+        }
+      ],
+      "license": "MIT-0"
+    },
+    "node_modules/@csstools/css-tokenizer": {
+      "version": "3.0.4",
+      "resolved": "https://registry.npmjs.org/@csstools/css-tokenizer/-/css-tokenizer-3.0.4.tgz",
+      "integrity": "sha512-Vd/9EVDiu6PPJt9yAh6roZP6El1xHrdvIVGjyBsHR0RYwNHgL7FJPyIIW4fANJNG6FtyZfvlRPpFI4ZM/lubvw==",
+      "dev": true,
+      "funding": [
+        {
+          "type": "github",
+          "url": "https://github.com/sponsors/csstools"
+        },
+        {
+          "type": "opencollective",
+          "url": "https://opencollective.com/csstools"
+        }
+      ],
+      "license": "MIT",
+      "engines": {
+        "node": ">=18"
+      }
+    },
     "node_modules/@esbuild/aix-ppc64": {
       "version": "0.25.12",
       "resolved": "https://registry.npmjs.org/@esbuild/aix-ppc64/-/aix-ppc64-0.25.12.tgz",
@@ -768,6 +985,24 @@
         "node": ">=18"
       }
     },
+    "node_modules/@exodus/bytes": {
+      "version": "1.10.0",
+      "resolved": "https://registry.npmjs.org/@exodus/bytes/-/bytes-1.10.0.tgz",
+      "integrity": "sha512-tf8YdcbirXdPnJ+Nd4UN1EXnz+IP2DI45YVEr3vvzcVTOyrApkmIB4zvOQVd3XPr7RXnfBtAx+PXImXOIU0Ajg==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": "^20.19.0 || ^22.12.0 || >=24.0.0"
+      },
+      "peerDependencies": {
+        "@noble/hashes": "^1.8.0 || ^2.0.0"
+      },
+      "peerDependenciesMeta": {
+        "@noble/hashes": {
+          "optional": true
+        }
+      }
+    },
     "node_modules/@google/genai": {
       "version": "1.38.0",
       "resolved": "https://registry.npmjs.org/@google/genai/-/genai-1.38.0.tgz",
@@ -905,6 +1140,13 @@
         "node": ">=14"
       }
     },
+    "node_modules/@polka/url": {
+      "version": "1.0.0-next.29",
+      "resolved": "https://registry.npmjs.org/@polka/url/-/url-1.0.0-next.29.tgz",
+      "integrity": "sha512-wwQAWhWSuHaag8c4q/KN/vCoeOJYshAIvMQwD4GpSb3OiZklFfvAgmj0VCBBImRpuF/aFgIRzllXlVX93Jevww==",
+      "dev": true,
+      "license": "MIT"
+    },
     "node_modules/@protobufjs/aspromise": {
       "version": "1.1.2",
       "resolved": "https://registry.npmjs.org/@protobufjs/aspromise/-/aspromise-1.1.2.tgz",
@@ -1326,6 +1568,13 @@
         "win32"
       ]
     },
+    "node_modules/@standard-schema/spec": {
+      "version": "1.1.0",
+      "resolved": "https://registry.npmjs.org/@standard-schema/spec/-/spec-1.1.0.tgz",
+      "integrity": "sha512-l2aFy5jALhniG5HgqrD6jXLi/rUWrKvqN/qJx6yoJsgKhblVd+iqqU4RCXavm/jPityDo5TCvKMnpjKnOriy0w==",
+      "dev": true,
+      "license": "MIT"
+    },
     "node_modules/@supabase/auth-js": {
       "version": "2.91.0",
       "resolved": "https://registry.npmjs.org/@supabase/auth-js/-/auth-js-2.91.0.tgz",
@@ -1452,6 +1701,104 @@
         "tailwindcss": ">=3.0.0 || insiders || >=4.0.0-alpha.20 || >=4.0.0-beta.1"
       }
     },
+    "node_modules/@testing-library/dom": {
+      "version": "10.4.1",
+      "resolved": "https://registry.npmjs.org/@testing-library/dom/-/dom-10.4.1.tgz",
+      "integrity": "sha512-o4PXJQidqJl82ckFaXUeoAW+XysPLauYI43Abki5hABd853iMhitooc6znOnczgbTYmEP6U6/y1ZyKAIsvMKGg==",
+      "dev": true,
+      "license": "MIT",
+      "peer": true,
+      "dependencies": {
+        "@babel/code-frame": "^7.10.4",
+        "@babel/runtime": "^7.12.5",
+        "@types/aria-query": "^5.0.1",
+        "aria-query": "5.3.0",
+        "dom-accessibility-api": "^0.5.9",
+        "lz-string": "^1.5.0",
+        "picocolors": "1.1.1",
+        "pretty-format": "^27.0.2"
+      },
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@testing-library/jest-dom": {
+      "version": "6.9.1",
+      "resolved": "https://registry.npmjs.org/@testing-library/jest-dom/-/jest-dom-6.9.1.tgz",
+      "integrity": "sha512-zIcONa+hVtVSSep9UT3jZ5rizo2BsxgyDYU7WFD5eICBE7no3881HGeb/QkGfsJs6JTkY1aQhT7rIPC7e+0nnA==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@adobe/css-tools": "^4.4.0",
+        "aria-query": "^5.0.0",
+        "css.escape": "^1.5.1",
+        "dom-accessibility-api": "^0.6.3",
+        "picocolors": "^1.1.1",
+        "redent": "^3.0.0"
+      },
+      "engines": {
+        "node": ">=14",
+        "npm": ">=6",
+        "yarn": ">=1"
+      }
+    },
+    "node_modules/@testing-library/jest-dom/node_modules/dom-accessibility-api": {
+      "version": "0.6.3",
+      "resolved": "https://registry.npmjs.org/dom-accessibility-api/-/dom-accessibility-api-0.6.3.tgz",
+      "integrity": "sha512-7ZgogeTnjuHbo+ct10G9Ffp0mif17idi0IyWNVA/wcwcm7NPOD/WEHVP3n7n3MhXqxoIYm8d6MuZohYWIZ4T3w==",
+      "dev": true,
+      "license": "MIT"
+    },
+    "node_modules/@testing-library/react": {
+      "version": "16.3.2",
+      "resolved": "https://registry.npmjs.org/@testing-library/react/-/react-16.3.2.tgz",
+      "integrity": "sha512-XU5/SytQM+ykqMnAnvB2umaJNIOsLF3PVv//1Ew4CTcpz0/BRyy/af40qqrt7SjKpDdT1saBMc42CUok5gaw+g==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@babel/runtime": "^7.12.5"
+      },
+      "engines": {
+        "node": ">=18"
+      },
+      "peerDependencies": {
+        "@testing-library/dom": "^10.0.0",
+        "@types/react": "^18.0.0 || ^19.0.0",
+        "@types/react-dom": "^18.0.0 || ^19.0.0",
+        "react": "^18.0.0 || ^19.0.0",
+        "react-dom": "^18.0.0 || ^19.0.0"
+      },
+      "peerDependenciesMeta": {
+        "@types/react": {
+          "optional": true
+        },
+        "@types/react-dom": {
+          "optional": true
+        }
+      }
+    },
+    "node_modules/@testing-library/user-event": {
+      "version": "14.6.1",
+      "resolved": "https://registry.npmjs.org/@testing-library/user-event/-/user-event-14.6.1.tgz",
+      "integrity": "sha512-vq7fv0rnt+QTXgPxr5Hjc210p6YKq2kmdziLgnsZGgLJ9e6VAShx1pACLuRjd/AS/sr7phAR58OIIpf0LlmQNw==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": ">=12",
+        "npm": ">=6"
+      },
+      "peerDependencies": {
+        "@testing-library/dom": ">=7.21.4"
+      }
+    },
+    "node_modules/@types/aria-query": {
+      "version": "5.0.4",
+      "resolved": "https://registry.npmjs.org/@types/aria-query/-/aria-query-5.0.4.tgz",
+      "integrity": "sha512-rfT93uj5s0PRL7EzccGMs3brplhcrghnDoV26NqKhCAS1hVo+WdNsPvE/yb6ilfr5hi2MEk6d5EWJTKdxg8jVw==",
+      "dev": true,
+      "license": "MIT",
+      "peer": true
+    },
     "node_modules/@types/babel__core": {
       "version": "7.20.5",
       "resolved": "https://registry.npmjs.org/@types/babel__core/-/babel__core-7.20.5.tgz",
@@ -1497,6 +1844,24 @@
         "@babel/types": "^7.28.2"
       }
     },
+    "node_modules/@types/chai": {
+      "version": "5.2.3",
+      "resolved": "https://registry.npmjs.org/@types/chai/-/chai-5.2.3.tgz",
+      "integrity": "sha512-Mw558oeA9fFbv65/y4mHtXDs9bPnFMZAL/jxdPFUpOHHIXX91mcgEHbS5Lahr+pwZFR8A7GQleRWeI6cGFC2UA==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@types/deep-eql": "*",
+        "assertion-error": "^2.0.1"
+      }
+    },
+    "node_modules/@types/deep-eql": {
+      "version": "4.0.2",
+      "resolved": "https://registry.npmjs.org/@types/deep-eql/-/deep-eql-4.0.2.tgz",
+      "integrity": "sha512-c9h9dVVMigMPc4bwTvC5dxqtqJZwQPePsWjPlpSOnojbor6pGqdk541lfA7AqFQr5pB1BRdq0juY9db81BwyFw==",
+      "dev": true,
+      "license": "MIT"
+    },
     "node_modules/@types/estree": {
       "version": "1.0.8",
       "resolved": "https://registry.npmjs.org/@types/estree/-/estree-1.0.8.tgz",
@@ -1549,6 +1914,139 @@
         "vite": "^4.2.0 || ^5.0.0 || ^6.0.0 || ^7.0.0"
       }
     },
+    "node_modules/@vitest/expect": {
+      "version": "4.0.18",
+      "resolved": "https://registry.npmjs.org/@vitest/expect/-/expect-4.0.18.tgz",
+      "integrity": "sha512-8sCWUyckXXYvx4opfzVY03EOiYVxyNrHS5QxX3DAIi5dpJAAkyJezHCP77VMX4HKA2LDT/Jpfo8i2r5BE3GnQQ==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@standard-schema/spec": "^1.0.0",
+        "@types/chai": "^5.2.2",
+        "@vitest/spy": "4.0.18",
+        "@vitest/utils": "4.0.18",
+        "chai": "^6.2.1",
+        "tinyrainbow": "^3.0.3"
+      },
+      "funding": {
+        "url": "https://opencollective.com/vitest"
+      }
+    },
+    "node_modules/@vitest/mocker": {
+      "version": "4.0.18",
+      "resolved": "https://registry.npmjs.org/@vitest/mocker/-/mocker-4.0.18.tgz",
+      "integrity": "sha512-HhVd0MDnzzsgevnOWCBj5Otnzobjy5wLBe4EdeeFGv8luMsGcYqDuFRMcttKWZA5vVO8RFjexVovXvAM4JoJDQ==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@vitest/spy": "4.0.18",
+        "estree-walker": "^3.0.3",
+        "magic-string": "^0.30.21"
+      },
+      "funding": {
+        "url": "https://opencollective.com/vitest"
+      },
+      "peerDependencies": {
+        "msw": "^2.4.9",
+        "vite": "^6.0.0 || ^7.0.0-0"
+      },
+      "peerDependenciesMeta": {
+        "msw": {
+          "optional": true
+        },
+        "vite": {
+          "optional": true
+        }
+      }
+    },
+    "node_modules/@vitest/pretty-format": {
+      "version": "4.0.18",
+      "resolved": "https://registry.npmjs.org/@vitest/pretty-format/-/pretty-format-4.0.18.tgz",
+      "integrity": "sha512-P24GK3GulZWC5tz87ux0m8OADrQIUVDPIjjj65vBXYG17ZeU3qD7r+MNZ1RNv4l8CGU2vtTRqixrOi9fYk/yKw==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "tinyrainbow": "^3.0.3"
+      },
+      "funding": {
+        "url": "https://opencollective.com/vitest"
+      }
+    },
+    "node_modules/@vitest/runner": {
+      "version": "4.0.18",
+      "resolved": "https://registry.npmjs.org/@vitest/runner/-/runner-4.0.18.tgz",
+      "integrity": "sha512-rpk9y12PGa22Jg6g5M3UVVnTS7+zycIGk9ZNGN+m6tZHKQb7jrP7/77WfZy13Y/EUDd52NDsLRQhYKtv7XfPQw==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@vitest/utils": "4.0.18",
+        "pathe": "^2.0.3"
+      },
+      "funding": {
+        "url": "https://opencollective.com/vitest"
+      }
+    },
+    "node_modules/@vitest/snapshot": {
+      "version": "4.0.18",
+      "resolved": "https://registry.npmjs.org/@vitest/snapshot/-/snapshot-4.0.18.tgz",
+      "integrity": "sha512-PCiV0rcl7jKQjbgYqjtakly6T1uwv/5BQ9SwBLekVg/EaYeQFPiXcgrC2Y7vDMA8dM1SUEAEV82kgSQIlXNMvA==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@vitest/pretty-format": "4.0.18",
+        "magic-string": "^0.30.21",
+        "pathe": "^2.0.3"
+      },
+      "funding": {
+        "url": "https://opencollective.com/vitest"
+      }
+    },
+    "node_modules/@vitest/spy": {
+      "version": "4.0.18",
+      "resolved": "https://registry.npmjs.org/@vitest/spy/-/spy-4.0.18.tgz",
+      "integrity": "sha512-cbQt3PTSD7P2OARdVW3qWER5EGq7PHlvE+QfzSC0lbwO+xnt7+XH06ZzFjFRgzUX//JmpxrCu92VdwvEPlWSNw==",
+      "dev": true,
+      "license": "MIT",
+      "funding": {
+        "url": "https://opencollective.com/vitest"
+      }
+    },
+    "node_modules/@vitest/ui": {
+      "version": "4.0.18",
+      "resolved": "https://registry.npmjs.org/@vitest/ui/-/ui-4.0.18.tgz",
+      "integrity": "sha512-CGJ25bc8fRi8Lod/3GHSvXRKi7nBo3kxh0ApW4yCjmrWmRmlT53B5E08XRSZRliygG0aVNxLrBEqPYdz/KcCtQ==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@vitest/utils": "4.0.18",
+        "fflate": "^0.8.2",
+        "flatted": "^3.3.3",
+        "pathe": "^2.0.3",
+        "sirv": "^3.0.2",
+        "tinyglobby": "^0.2.15",
+        "tinyrainbow": "^3.0.3"
+      },
+      "funding": {
+        "url": "https://opencollective.com/vitest"
+      },
+      "peerDependencies": {
+        "vitest": "4.0.18"
+      }
+    },
+    "node_modules/@vitest/utils": {
+      "version": "4.0.18",
+      "resolved": "https://registry.npmjs.org/@vitest/utils/-/utils-4.0.18.tgz",
+      "integrity": "sha512-msMRKLMVLWygpK3u2Hybgi4MNjcYJvwTb0Ru09+fOyCXIgT5raYP041DRRdiJiI3k/2U6SEbAETB3YtBrUkCFA==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@vitest/pretty-format": "4.0.18",
+        "tinyrainbow": "^3.0.3"
+      },
+      "funding": {
+        "url": "https://opencollective.com/vitest"
+      }
+    },
     "node_modules/agent-base": {
       "version": "7.1.4",
       "resolved": "https://registry.npmjs.org/agent-base/-/agent-base-7.1.4.tgz",
@@ -1623,6 +2121,26 @@
       "dev": true,
       "license": "MIT"
     },
+    "node_modules/aria-query": {
+      "version": "5.3.0",
+      "resolved": "https://registry.npmjs.org/aria-query/-/aria-query-5.3.0.tgz",
+      "integrity": "sha512-b0P0sZPKtyu8HkeRAfCq0IfURZK+SuwMjY1UXGBU27wpAiTwQAIlq56IbIO+ytk/JjS1fMR14ee5WBBfKi5J6A==",
+      "dev": true,
+      "license": "Apache-2.0",
+      "dependencies": {
+        "dequal": "^2.0.3"
+      }
+    },
+    "node_modules/assertion-error": {
+      "version": "2.0.1",
+      "resolved": "https://registry.npmjs.org/assertion-error/-/assertion-error-2.0.1.tgz",
+      "integrity": "sha512-Izi8RQcffqCeNVgFigKli1ssklIbpHnCYc6AknXGYoB6grJqyeby7jv12JUQgmTAnIDnbck1uxksT4dzN3PWBA==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": ">=12"
+      }
+    },
     "node_modules/autoprefixer": {
       "version": "10.4.23",
       "resolved": "https://registry.npmjs.org/autoprefixer/-/autoprefixer-10.4.23.tgz",
@@ -1696,6 +2214,16 @@
         "baseline-browser-mapping": "dist/cli.js"
       }
     },
+    "node_modules/bidi-js": {
+      "version": "1.0.3",
+      "resolved": "https://registry.npmjs.org/bidi-js/-/bidi-js-1.0.3.tgz",
+      "integrity": "sha512-RKshQI1R3YQ+n9YJz2QQ147P66ELpa1FQEg20Dk8oW9t2KgLbpDLLp9aGZ7y8WHSshDknG0bknqGw5/tyCs5tw==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "require-from-string": "^2.0.2"
+      }
+    },
     "node_modules/bignumber.js": {
       "version": "9.3.1",
       "resolved": "https://registry.npmjs.org/bignumber.js/-/bignumber.js-9.3.1.tgz",
@@ -1811,6 +2339,16 @@
       ],
       "license": "CC-BY-4.0"
     },
+    "node_modules/chai": {
+      "version": "6.2.2",
+      "resolved": "https://registry.npmjs.org/chai/-/chai-6.2.2.tgz",
+      "integrity": "sha512-NUPRluOfOiTKBKvWPtSD4PhFvWCqOi0BGStNWs57X9js7XGTprSmFoz5F0tWhR4WPjNeR9jXqdC7/UpSJTnlRg==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": ">=18"
+      }
+    },
     "node_modules/chokidar": {
       "version": "3.6.0",
       "resolved": "https://registry.npmjs.org/chokidar/-/chokidar-3.6.0.tgz",
@@ -1904,6 +2442,27 @@
         "node": ">= 8"
       }
     },
+    "node_modules/css-tree": {
+      "version": "3.1.0",
+      "resolved": "https://registry.npmjs.org/css-tree/-/css-tree-3.1.0.tgz",
+      "integrity": "sha512-0eW44TGN5SQXU1mWSkKwFstI/22X2bG1nYzZTYMAWjylYURhse752YgbE4Cx46AC+bAvI+/dYTPRk1LqSUnu6w==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "mdn-data": "2.12.2",
+        "source-map-js": "^1.0.1"
+      },
+      "engines": {
+        "node": "^10 || ^12.20.0 || ^14.13.0 || >=15.0.0"
+      }
+    },
+    "node_modules/css.escape": {
+      "version": "1.5.1",
+      "resolved": "https://registry.npmjs.org/css.escape/-/css.escape-1.5.1.tgz",
+      "integrity": "sha512-YUifsXXuknHlUsmlgyY0PKzgPOr7/FjCePfHNt0jxm83wHZi44VDMQ7/fGNkjY3/jV1MC+1CmZbaHzugyeRtpg==",
+      "dev": true,
+      "license": "MIT"
+    },
     "node_modules/cssesc": {
       "version": "3.0.0",
       "resolved": "https://registry.npmjs.org/cssesc/-/cssesc-3.0.0.tgz",
@@ -1917,6 +2476,32 @@
         "node": ">=4"
       }
     },
+    "node_modules/cssstyle": {
+      "version": "5.3.7",
+      "resolved": "https://registry.npmjs.org/cssstyle/-/cssstyle-5.3.7.tgz",
+      "integrity": "sha512-7D2EPVltRrsTkhpQmksIu+LxeWAIEk6wRDMJ1qljlv+CKHJM+cJLlfhWIzNA44eAsHXSNe3+vO6DW1yCYx8SuQ==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@asamuzakjp/css-color": "^4.1.1",
+        "@csstools/css-syntax-patches-for-csstree": "^1.0.21",
+        "css-tree": "^3.1.0",
+        "lru-cache": "^11.2.4"
+      },
+      "engines": {
+        "node": ">=20"
+      }
+    },
+    "node_modules/cssstyle/node_modules/lru-cache": {
+      "version": "11.2.5",
+      "resolved": "https://registry.npmjs.org/lru-cache/-/lru-cache-11.2.5.tgz",
+      "integrity": "sha512-vFrFJkWtJvJnD5hg+hJvVE8Lh/TcMzKnTgCWmtBipwI5yLX/iX+5UB2tfuyODF5E7k9xEzMdYgGqaSb1c0c5Yw==",
+      "dev": true,
+      "license": "BlueOak-1.0.0",
+      "engines": {
+        "node": "20 || >=22"
+      }
+    },
     "node_modules/data-uri-to-buffer": {
       "version": "4.0.1",
       "resolved": "https://registry.npmjs.org/data-uri-to-buffer/-/data-uri-to-buffer-4.0.1.tgz",
@@ -1926,6 +2511,30 @@
         "node": ">= 12"
       }
     },
+    "node_modules/data-urls": {
+      "version": "6.0.1",
+      "resolved": "https://registry.npmjs.org/data-urls/-/data-urls-6.0.1.tgz",
+      "integrity": "sha512-euIQENZg6x8mj3fO6o9+fOW8MimUI4PpD/fZBhJfeioZVy9TUpM4UY7KjQNVZFlqwJ0UdzRDzkycB997HEq1BQ==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "whatwg-mimetype": "^5.0.0",
+        "whatwg-url": "^15.1.0"
+      },
+      "engines": {
+        "node": ">=20"
+      }
+    },
+    "node_modules/data-urls/node_modules/whatwg-mimetype": {
+      "version": "5.0.0",
+      "resolved": "https://registry.npmjs.org/whatwg-mimetype/-/whatwg-mimetype-5.0.0.tgz",
+      "integrity": "sha512-sXcNcHOC51uPGF0P/D4NVtrkjSU2fNsm9iog4ZvZJsL3rjoDAzXZhkm2MWt1y+PUdggKAYVoMAIYcs78wJ51Cw==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": ">=20"
+      }
+    },
     "node_modules/debug": {
       "version": "4.4.3",
       "resolved": "https://registry.npmjs.org/debug/-/debug-4.4.3.tgz",
@@ -1943,6 +2552,23 @@
         }
       }
     },
+    "node_modules/decimal.js": {
+      "version": "10.6.0",
+      "resolved": "https://registry.npmjs.org/decimal.js/-/decimal.js-10.6.0.tgz",
+      "integrity": "sha512-YpgQiITW3JXGntzdUmyUR1V812Hn8T1YVXhCu+wO3OpS4eU9l4YdD3qjyiKdV6mvV29zapkMeD390UVEf2lkUg==",
+      "dev": true,
+      "license": "MIT"
+    },
+    "node_modules/dequal": {
+      "version": "2.0.3",
+      "resolved": "https://registry.npmjs.org/dequal/-/dequal-2.0.3.tgz",
+      "integrity": "sha512-0je+qPKHEMohvfRTCEo3CrPG6cAzAYgmzKyxRiYSSDkS6eGJdyVJm7WaYA5ECaAD9wLB2T4EEeymA5aFVcYXCA==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": ">=6"
+      }
+    },
     "node_modules/detect-libc": {
       "version": "2.1.2",
       "resolved": "https://registry.npmjs.org/detect-libc/-/detect-libc-2.1.2.tgz",
@@ -1969,6 +2595,14 @@
       "dev": true,
       "license": "MIT"
     },
+    "node_modules/dom-accessibility-api": {
+      "version": "0.5.16",
+      "resolved": "https://registry.npmjs.org/dom-accessibility-api/-/dom-accessibility-api-0.5.16.tgz",
+      "integrity": "sha512-X7BJ2yElsnOJ30pZF4uIIDfBEVgF4XEBxL9Bxhy6dnrm5hkzqmsWHGTiHqRiITNhMyFLyAiWndIJP7Z1NTteDg==",
+      "dev": true,
+      "license": "MIT",
+      "peer": true
+    },
     "node_modules/dotenv": {
       "version": "17.2.3",
       "resolved": "https://registry.npmjs.org/dotenv/-/dotenv-17.2.3.tgz",
@@ -2010,6 +2644,26 @@
       "integrity": "sha512-L18DaJsXSUk2+42pv8mLs5jJT2hqFkFE4j21wOmgbUqsZ2hL72NsUU785g9RXgo3s0ZNgVl42TiHp3ZtOv/Vyg==",
       "license": "MIT"
     },
+    "node_modules/entities": {
+      "version": "6.0.1",
+      "resolved": "https://registry.npmjs.org/entities/-/entities-6.0.1.tgz",
+      "integrity": "sha512-aN97NXWF6AWBTahfVOIrB/NShkzi5H7F9r1s9mD3cDj4Ko5f2qhhVoYMibXF7GlLveb/D2ioWay8lxI97Ven3g==",
+      "dev": true,
+      "license": "BSD-2-Clause",
+      "engines": {
+        "node": ">=0.12"
+      },
+      "funding": {
+        "url": "https://github.com/fb55/entities?sponsor=1"
+      }
+    },
+    "node_modules/es-module-lexer": {
+      "version": "1.7.0",
+      "resolved": "https://registry.npmjs.org/es-module-lexer/-/es-module-lexer-1.7.0.tgz",
+      "integrity": "sha512-jEQoCwk8hyb2AZziIOLhDqpm5+2ww5uIE6lkO/6jcOCusfk6LhMHpXXfBLXTZ7Ydyt0j4VoUQv6uGNYbdW+kBA==",
+      "dev": true,
+      "license": "MIT"
+    },
     "node_modules/esbuild": {
       "version": "0.25.12",
       "resolved": "https://registry.npmjs.org/esbuild/-/esbuild-0.25.12.tgz",
@@ -2062,6 +2716,26 @@
         "node": ">=6"
       }
     },
+    "node_modules/estree-walker": {
+      "version": "3.0.3",
+      "resolved": "https://registry.npmjs.org/estree-walker/-/estree-walker-3.0.3.tgz",
+      "integrity": "sha512-7RUKfXgSMMkzt6ZuXmqapOurLGPPfgj6l9uRZ7lRGolvk0y2yocc35LdcxKC5PQZdn2DMqioAQ2NoWcrTKmm6g==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@types/estree": "^1.0.0"
+      }
+    },
+    "node_modules/expect-type": {
+      "version": "1.3.0",
+      "resolved": "https://registry.npmjs.org/expect-type/-/expect-type-1.3.0.tgz",
+      "integrity": "sha512-knvyeauYhqjOYvQ66MznSMs83wmHrCycNEN6Ao+2AeYEfxUIkuiVxdEa1qlGEPK+We3n0THiDciYSsCcgW/DoA==",
+      "dev": true,
+      "license": "Apache-2.0",
+      "engines": {
+        "node": ">=12.0.0"
+      }
+    },
     "node_modules/extend": {
       "version": "3.0.2",
       "resolved": "https://registry.npmjs.org/extend/-/extend-3.0.2.tgz",
@@ -2149,6 +2823,13 @@
         "node": "^12.20 || >= 14.13"
       }
     },
+    "node_modules/fflate": {
+      "version": "0.8.2",
+      "resolved": "https://registry.npmjs.org/fflate/-/fflate-0.8.2.tgz",
+      "integrity": "sha512-cPJU47OaAoCbg0pBvzsgpTPhmhqI5eJjh/JIu8tPj5q+T7iLvW/JAYUqmE7KOB4R1ZyEhzBaIQpQpardBF5z8A==",
+      "dev": true,
+      "license": "MIT"
+    },
     "node_modules/fill-range": {
       "version": "7.1.1",
       "resolved": "https://registry.npmjs.org/fill-range/-/fill-range-7.1.1.tgz",
@@ -2162,6 +2843,13 @@
         "node": ">=8"
       }
     },
+    "node_modules/flatted": {
+      "version": "3.3.3",
+      "resolved": "https://registry.npmjs.org/flatted/-/flatted-3.3.3.tgz",
+      "integrity": "sha512-GX+ysw4PBCz0PzosHDepZGANEuFCMLrnRTiEy9McGjmkCQYwRq4A/X786G/fjM/+OjsWSU1ZrY5qyARZmO/uwg==",
+      "dev": true,
+      "license": "ISC"
+    },
     "node_modules/foreground-child": {
       "version": "3.3.1",
       "resolved": "https://registry.npmjs.org/foreground-child/-/foreground-child-3.3.1.tgz",
@@ -2367,6 +3055,33 @@
         "node": ">= 0.4"
       }
     },
+    "node_modules/html-encoding-sniffer": {
+      "version": "6.0.0",
+      "resolved": "https://registry.npmjs.org/html-encoding-sniffer/-/html-encoding-sniffer-6.0.0.tgz",
+      "integrity": "sha512-CV9TW3Y3f8/wT0BRFc1/KAVQ3TUHiXmaAb6VW9vtiMFf7SLoMd1PdAc4W3KFOFETBJUb90KatHqlsZMWV+R9Gg==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@exodus/bytes": "^1.6.0"
+      },
+      "engines": {
+        "node": "^20.19.0 || ^22.12.0 || >=24.0.0"
+      }
+    },
+    "node_modules/http-proxy-agent": {
+      "version": "7.0.2",
+      "resolved": "https://registry.npmjs.org/http-proxy-agent/-/http-proxy-agent-7.0.2.tgz",
+      "integrity": "sha512-T1gkAiYYDWYx3V5Bmyu7HcfcvL7mUrTWiM6yOfa3PIphViJ/gFPbvidQ+veqSOHci/PxBcDabeUNCzpOODJZig==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "agent-base": "^7.1.0",
+        "debug": "^4.3.4"
+      },
+      "engines": {
+        "node": ">= 14"
+      }
+    },
     "node_modules/https-proxy-agent": {
       "version": "7.0.6",
       "resolved": "https://registry.npmjs.org/https-proxy-agent/-/https-proxy-agent-7.0.6.tgz",
@@ -2395,6 +3110,16 @@
       "integrity": "sha512-XXOFtyqDjNDAQxVfYxuF7g9Il/IbWmmlQg2MYKOH8ExIT1qg6xc4zyS3HaEEATgs1btfzxq15ciUiY7gjSXRGQ==",
       "license": "MIT"
     },
+    "node_modules/indent-string": {
+      "version": "4.0.0",
+      "resolved": "https://registry.npmjs.org/indent-string/-/indent-string-4.0.0.tgz",
+      "integrity": "sha512-EdDDZu4A2OyIK7Lr/2zG+w5jmbuk1DVBnEwREQvBzspBJkCEbRa8GxU1lghYcaGJCnRWibjDXlq779X1/y5xwg==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": ">=8"
+      }
+    },
     "node_modules/inherits": {
       "version": "2.0.4",
       "resolved": "https://registry.npmjs.org/inherits/-/inherits-2.0.4.tgz",
@@ -2472,6 +3197,13 @@
         "node": ">=0.12.0"
       }
     },
+    "node_modules/is-potential-custom-element-name": {
+      "version": "1.0.1",
+      "resolved": "https://registry.npmjs.org/is-potential-custom-element-name/-/is-potential-custom-element-name-1.0.1.tgz",
+      "integrity": "sha512-bCYeRA2rVibKZd+s2625gGnGF/t7DSqDs4dP7CrLA1m7jKWz6pps0LpYLJN8Q64HtmPKJ1hrN3nzPNKFEKOUiQ==",
+      "dev": true,
+      "license": "MIT"
+    },
     "node_modules/isarray": {
       "version": "1.0.0",
       "resolved": "https://registry.npmjs.org/isarray/-/isarray-1.0.0.tgz",
@@ -2518,6 +3250,46 @@
       "dev": true,
       "license": "MIT"
     },
+    "node_modules/jsdom": {
+      "version": "27.4.0",
+      "resolved": "https://registry.npmjs.org/jsdom/-/jsdom-27.4.0.tgz",
+      "integrity": "sha512-mjzqwWRD9Y1J1KUi7W97Gja1bwOOM5Ug0EZ6UDK3xS7j7mndrkwozHtSblfomlzyB4NepioNt+B2sOSzczVgtQ==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@acemir/cssom": "^0.9.28",
+        "@asamuzakjp/dom-selector": "^6.7.6",
+        "@exodus/bytes": "^1.6.0",
+        "cssstyle": "^5.3.4",
+        "data-urls": "^6.0.0",
+        "decimal.js": "^10.6.0",
+        "html-encoding-sniffer": "^6.0.0",
+        "http-proxy-agent": "^7.0.2",
+        "https-proxy-agent": "^7.0.6",
+        "is-potential-custom-element-name": "^1.0.1",
+        "parse5": "^8.0.0",
+        "saxes": "^6.0.0",
+        "symbol-tree": "^3.2.4",
+        "tough-cookie": "^6.0.0",
+        "w3c-xmlserializer": "^5.0.0",
+        "webidl-conversions": "^8.0.0",
+        "whatwg-mimetype": "^4.0.0",
+        "whatwg-url": "^15.1.0",
+        "ws": "^8.18.3",
+        "xml-name-validator": "^5.0.0"
+      },
+      "engines": {
+        "node": "^20.19.0 || ^22.12.0 || >=24.0.0"
+      },
+      "peerDependencies": {
+        "canvas": "^3.0.0"
+      },
+      "peerDependenciesMeta": {
+        "canvas": {
+          "optional": true
+        }
+      }
+    },
     "node_modules/jsesc": {
       "version": "3.1.0",
       "resolved": "https://registry.npmjs.org/jsesc/-/jsesc-3.1.0.tgz",
@@ -2914,6 +3686,34 @@
         "react": "^16.5.1 || ^17.0.0 || ^18.0.0 || ^19.0.0"
       }
     },
+    "node_modules/lz-string": {
+      "version": "1.5.0",
+      "resolved": "https://registry.npmjs.org/lz-string/-/lz-string-1.5.0.tgz",
+      "integrity": "sha512-h5bgJWpxJNswbU7qCrV0tIKQCaS3blPDrqKWx+QxzuzL1zGUzij9XCWLrSLsJPu5t+eWA/ycetzYAO5IOMcWAQ==",
+      "dev": true,
+      "license": "MIT",
+      "peer": true,
+      "bin": {
+        "lz-string": "bin/bin.js"
+      }
+    },
+    "node_modules/magic-string": {
+      "version": "0.30.21",
+      "resolved": "https://registry.npmjs.org/magic-string/-/magic-string-0.30.21.tgz",
+      "integrity": "sha512-vd2F4YUyEXKGcLHoq+TEyCjxueSeHnFxyyjNp80yg0XV4vUhnDer/lvvlqM/arB5bXQN5K2/3oinyCRyx8T2CQ==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@jridgewell/sourcemap-codec": "^1.5.5"
+      }
+    },
+    "node_modules/mdn-data": {
+      "version": "2.12.2",
+      "resolved": "https://registry.npmjs.org/mdn-data/-/mdn-data-2.12.2.tgz",
+      "integrity": "sha512-IEn+pegP1aManZuckezWCO+XZQDplx1366JoVhTpMpBB1sPey/SbveZQUosKiKiGYjg1wH4pMlNgXbCiYgihQA==",
+      "dev": true,
+      "license": "CC0-1.0"
+    },
     "node_modules/merge2": {
       "version": "1.4.1",
       "resolved": "https://registry.npmjs.org/merge2/-/merge2-1.4.1.tgz",
@@ -2951,6 +3751,16 @@
         "url": "https://github.com/sponsors/jonschlinkert"
       }
     },
+    "node_modules/min-indent": {
+      "version": "1.0.1",
+      "resolved": "https://registry.npmjs.org/min-indent/-/min-indent-1.0.1.tgz",
+      "integrity": "sha512-I9jwMn07Sy/IwOj3zVkVik2JTvgpaykDZEigL6Rx6N9LbMywwUSMtxET+7lVoDLLd3O3IXwJwvuuns8UB/HeAg==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": ">=4"
+      }
+    },
     "node_modules/mini-svg-data-uri": {
       "version": "1.4.4",
       "resolved": "https://registry.npmjs.org/mini-svg-data-uri/-/mini-svg-data-uri-1.4.4.tgz",
@@ -2985,6 +3795,16 @@
         "node": ">=16 || 14 >=14.17"
       }
     },
+    "node_modules/mrmime": {
+      "version": "2.0.1",
+      "resolved": "https://registry.npmjs.org/mrmime/-/mrmime-2.0.1.tgz",
+      "integrity": "sha512-Y3wQdFg2Va6etvQ5I82yUhGdsKrcYox6p7FfL1LbK2J4V01F9TGlepTIhnK24t7koZibmg82KGglhA1XK5IsLQ==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": ">=10"
+      }
+    },
     "node_modules/ms": {
       "version": "2.1.3",
       "resolved": "https://registry.npmjs.org/ms/-/ms-2.1.3.tgz",
@@ -3097,6 +3917,17 @@
         "node": ">= 6"
       }
     },
+    "node_modules/obug": {
+      "version": "2.1.1",
+      "resolved": "https://registry.npmjs.org/obug/-/obug-2.1.1.tgz",
+      "integrity": "sha512-uTqF9MuPraAQ+IsnPf366RG4cP9RtUi7MLO1N3KEc+wb0a6yKpeL0lmk2IB1jY5KHPAlTc6T/JRdC/YqxHNwkQ==",
+      "dev": true,
+      "funding": [
+        "https://github.com/sponsors/sxzz",
+        "https://opencollective.com/debug"
+      ],
+      "license": "MIT"
+    },
     "node_modules/package-json-from-dist": {
       "version": "1.0.1",
       "resolved": "https://registry.npmjs.org/package-json-from-dist/-/package-json-from-dist-1.0.1.tgz",
@@ -3109,6 +3940,19 @@
       "integrity": "sha512-4hLB8Py4zZce5s4yd9XzopqwVv/yGNhV1Bl8NTmCq1763HeK2+EwVTv+leGeL13Dnh2wfbqowVPXCIO0z4taYw==",
       "license": "(MIT AND Zlib)"
     },
+    "node_modules/parse5": {
+      "version": "8.0.0",
+      "resolved": "https://registry.npmjs.org/parse5/-/parse5-8.0.0.tgz",
+      "integrity": "sha512-9m4m5GSgXjL4AjumKzq1Fgfp3Z8rsvjRNbnkVwfu2ImRqE5D0LnY2QfDen18FSY9C573YU5XxSapdHZTZ2WolA==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "entities": "^6.0.0"
+      },
+      "funding": {
+        "url": "https://github.com/inikulin/parse5?sponsor=1"
+      }
+    },
     "node_modules/path-key": {
       "version": "3.1.1",
       "resolved": "https://registry.npmjs.org/path-key/-/path-key-3.1.1.tgz",
@@ -3147,6 +3991,13 @@
       "integrity": "sha512-JNAzZcXrCt42VGLuYz0zfAzDfAvJWW6AfYlDBQyDV5DClI2m5sAmK+OIO7s59XfsRsWHp02jAJrRadPRGTt6SQ==",
       "license": "ISC"
     },
+    "node_modules/pathe": {
+      "version": "2.0.3",
+      "resolved": "https://registry.npmjs.org/pathe/-/pathe-2.0.3.tgz",
+      "integrity": "sha512-WUjGcAqP1gQacoQe+OBJsFA7Ld4DyXuUIjZ5cc75cLHvJ7dtNsTugphxIADwspS+AraAUePCKrSVtPLFj/F88w==",
+      "dev": true,
+      "license": "MIT"
+    },
     "node_modules/picocolors": {
       "version": "1.1.1",
       "resolved": "https://registry.npmjs.org/picocolors/-/picocolors-1.1.1.tgz",
@@ -3357,6 +4208,47 @@
       "dev": true,
       "license": "MIT"
     },
+    "node_modules/pretty-format": {
+      "version": "27.5.1",
+      "resolved": "https://registry.npmjs.org/pretty-format/-/pretty-format-27.5.1.tgz",
+      "integrity": "sha512-Qb1gy5OrP5+zDf2Bvnzdl3jsTf1qXVMazbvCoKhtKqVs4/YK4ozX4gKQJJVyNe+cajNPn0KoC0MC3FUmaHWEmQ==",
+      "dev": true,
+      "license": "MIT",
+      "peer": true,
+      "dependencies": {
+        "ansi-regex": "^5.0.1",
+        "ansi-styles": "^5.0.0",
+        "react-is": "^17.0.1"
+      },
+      "engines": {
+        "node": "^10.13.0 || ^12.13.0 || ^14.15.0 || >=15.0.0"
+      }
+    },
+    "node_modules/pretty-format/node_modules/ansi-regex": {
+      "version": "5.0.1",
+      "resolved": "https://registry.npmjs.org/ansi-regex/-/ansi-regex-5.0.1.tgz",
+      "integrity": "sha512-quJQXlTSUGL2LH9SUXo8VwsY4soanhgo6LNSm84E1LBcE8s3O0wpdiRzyR9z/ZZJMlMWv37qOOb9pdJlMUEKFQ==",
+      "dev": true,
+      "license": "MIT",
+      "peer": true,
+      "engines": {
+        "node": ">=8"
+      }
+    },
+    "node_modules/pretty-format/node_modules/ansi-styles": {
+      "version": "5.2.0",
+      "resolved": "https://registry.npmjs.org/ansi-styles/-/ansi-styles-5.2.0.tgz",
+      "integrity": "sha512-Cxwpt2SfTzTtXcfOlzGEee8O+c+MmUgGrNiBcXnuWxuFJHe6a5Hz7qwhwe5OgaSYI0IJvkLqWX1ASG+cJOkEiA==",
+      "dev": true,
+      "license": "MIT",
+      "peer": true,
+      "engines": {
+        "node": ">=10"
+      },
+      "funding": {
+        "url": "https://github.com/chalk/ansi-styles?sponsor=1"
+      }
+    },
     "node_modules/process-nextick-args": {
       "version": "2.0.1",
       "resolved": "https://registry.npmjs.org/process-nextick-args/-/process-nextick-args-2.0.1.tgz",
@@ -3387,6 +4279,16 @@
         "node": ">=12.0.0"
       }
     },
+    "node_modules/punycode": {
+      "version": "2.3.1",
+      "resolved": "https://registry.npmjs.org/punycode/-/punycode-2.3.1.tgz",
+      "integrity": "sha512-vYt7UD1U9Wg6138shLtLOvdAu+8DsC/ilFtEVHcH+wydcSpNE20AfSOduf6MkRFahL5FY7X1oU7nKVZFtfq8Fg==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": ">=6"
+      }
+    },
     "node_modules/queue-microtask": {
       "version": "1.2.3",
       "resolved": "https://registry.npmjs.org/queue-microtask/-/queue-microtask-1.2.3.tgz",
@@ -3429,6 +4331,14 @@
         "react": "^19.2.3"
       }
     },
+    "node_modules/react-is": {
+      "version": "17.0.2",
+      "resolved": "https://registry.npmjs.org/react-is/-/react-is-17.0.2.tgz",
+      "integrity": "sha512-w2GsyukL62IJnlaff/nRegPQR94C/XXamvMWmSHRJ4y7Ts/4ocGRmTHvOs8PSE6pB3dWOrD/nueuU5sduBsQ4w==",
+      "dev": true,
+      "license": "MIT",
+      "peer": true
+    },
     "node_modules/react-refresh": {
       "version": "0.18.0",
       "resolved": "https://registry.npmjs.org/react-refresh/-/react-refresh-0.18.0.tgz",
@@ -3496,6 +4406,30 @@
         "url": "https://github.com/sponsors/jonschlinkert"
       }
     },
+    "node_modules/redent": {
+      "version": "3.0.0",
+      "resolved": "https://registry.npmjs.org/redent/-/redent-3.0.0.tgz",
+      "integrity": "sha512-6tDA8g98We0zd0GvVeMT9arEOnTw9qM03L9cJXaCjrip1OO764RDBLBfrB4cwzNGDj5OA5ioymC9GkizgWJDUg==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "indent-string": "^4.0.0",
+        "strip-indent": "^3.0.0"
+      },
+      "engines": {
+        "node": ">=8"
+      }
+    },
+    "node_modules/require-from-string": {
+      "version": "2.0.2",
+      "resolved": "https://registry.npmjs.org/require-from-string/-/require-from-string-2.0.2.tgz",
+      "integrity": "sha512-Xf0nWe6RseziFMu+Ap9biiUbmplq6S9/p+7w7YXP/JBHhrUDDUhwa+vANyubuqfZWTveU//DYVGsDG7RKL/vEw==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": ">=0.10.0"
+      }
+    },
     "node_modules/resolve": {
       "version": "1.22.11",
       "resolved": "https://registry.npmjs.org/resolve/-/resolve-1.22.11.tgz",
@@ -3642,6 +4576,19 @@
       ],
       "license": "MIT"
     },
+    "node_modules/saxes": {
+      "version": "6.0.0",
+      "resolved": "https://registry.npmjs.org/saxes/-/saxes-6.0.0.tgz",
+      "integrity": "sha512-xAg7SOnEhrm5zI3puOOKyy1OMcMlIJZYNJY7xLBwSze0UjhPLnWfj2GF2EpT0jmzaJKIWKHLsaSSajf35bcYnA==",
+      "dev": true,
+      "license": "ISC",
+      "dependencies": {
+        "xmlchars": "^2.2.0"
+      },
+      "engines": {
+        "node": ">=v12.22.7"
+      }
+    },
     "node_modules/scheduler": {
       "version": "0.27.0",
       "resolved": "https://registry.npmjs.org/scheduler/-/scheduler-0.27.0.tgz",
@@ -3685,6 +4632,13 @@
         "node": ">=8"
       }
     },
+    "node_modules/siginfo": {
+      "version": "2.0.0",
+      "resolved": "https://registry.npmjs.org/siginfo/-/siginfo-2.0.0.tgz",
+      "integrity": "sha512-ybx0WO1/8bSBLEWXZvEd7gMW3Sn3JFlW3TvX1nREbDLRNQNaeNN8WK0meBwPdAaOI7TtRRRJn/Es1zhrrCHu7g==",
+      "dev": true,
+      "license": "ISC"
+    },
     "node_modules/signal-exit": {
       "version": "4.1.0",
       "resolved": "https://registry.npmjs.org/signal-exit/-/signal-exit-4.1.0.tgz",
@@ -3697,6 +4651,21 @@
         "url": "https://github.com/sponsors/isaacs"
       }
     },
+    "node_modules/sirv": {
+      "version": "3.0.2",
+      "resolved": "https://registry.npmjs.org/sirv/-/sirv-3.0.2.tgz",
+      "integrity": "sha512-2wcC/oGxHis/BoHkkPwldgiPSYcpZK3JU28WoMVv55yHJgcZ8rlXvuG9iZggz+sU1d4bRgIGASwyWqjxu3FM0g==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@polka/url": "^1.0.0-next.24",
+        "mrmime": "^2.0.0",
+        "totalist": "^3.0.0"
+      },
+      "engines": {
+        "node": ">=18"
+      }
+    },
     "node_modules/source-map-js": {
       "version": "1.2.1",
       "resolved": "https://registry.npmjs.org/source-map-js/-/source-map-js-1.2.1.tgz",
@@ -3707,6 +4676,20 @@
         "node": ">=0.10.0"
       }
     },
+    "node_modules/stackback": {
+      "version": "0.0.2",
+      "resolved": "https://registry.npmjs.org/stackback/-/stackback-0.0.2.tgz",
+      "integrity": "sha512-1XMJE5fQo1jGH6Y/7ebnwPOBEkIEnT4QF32d5R1+VXdXveM0IBMJt8zfaxX1P3QhVwrYe+576+jkANtSS2mBbw==",
+      "dev": true,
+      "license": "MIT"
+    },
+    "node_modules/std-env": {
+      "version": "3.10.0",
+      "resolved": "https://registry.npmjs.org/std-env/-/std-env-3.10.0.tgz",
+      "integrity": "sha512-5GS12FdOZNliM5mAOxFRg7Ir0pWz8MdpYm6AY6VPkGpbA7ZzmbzNcBJQ0GPvvyWgcY7QAhCgf9Uy89I03faLkg==",
+      "dev": true,
+      "license": "MIT"
+    },
     "node_modules/string_decoder": {
       "version": "1.1.1",
       "resolved": "https://registry.npmjs.org/string_decoder/-/string_decoder-1.1.1.tgz",
@@ -3818,6 +4801,19 @@
         "node": ">=8"
       }
     },
+    "node_modules/strip-indent": {
+      "version": "3.0.0",
+      "resolved": "https://registry.npmjs.org/strip-indent/-/strip-indent-3.0.0.tgz",
+      "integrity": "sha512-laJTa3Jb+VQpaC6DseHhF7dXVqHTfJPCRDaEbid/drOhgitgYku/letMUqOXFoWV0zIIUbjpdH2t+tYj4bQMRQ==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "min-indent": "^1.0.0"
+      },
+      "engines": {
+        "node": ">=8"
+      }
+    },
     "node_modules/sucrase": {
       "version": "3.35.1",
       "resolved": "https://registry.npmjs.org/sucrase/-/sucrase-3.35.1.tgz",
@@ -3854,6 +4850,13 @@
         "url": "https://github.com/sponsors/ljharb"
       }
     },
+    "node_modules/symbol-tree": {
+      "version": "3.2.4",
+      "resolved": "https://registry.npmjs.org/symbol-tree/-/symbol-tree-3.2.4.tgz",
+      "integrity": "sha512-9QNk5KwDF+Bvz+PyObkmSYjI5ksVUYtjW7AU22r2NKcfLJcXp96hkDWU3+XndOsUb+AQ9QhfzfCT2O+CNWT5Tw==",
+      "dev": true,
+      "license": "MIT"
+    },
     "node_modules/tailwindcss": {
       "version": "3.4.17",
       "resolved": "https://registry.npmjs.org/tailwindcss/-/tailwindcss-3.4.17.tgz",
@@ -3939,6 +4942,23 @@
         "node": ">=0.8"
       }
     },
+    "node_modules/tinybench": {
+      "version": "2.9.0",
+      "resolved": "https://registry.npmjs.org/tinybench/-/tinybench-2.9.0.tgz",
+      "integrity": "sha512-0+DUvqWMValLmha6lr4kD8iAMK1HzV0/aKnCtWb9v9641TnP/MFb7Pc2bxoxQjTXAErryXVgUOfv2YqNllqGeg==",
+      "dev": true,
+      "license": "MIT"
+    },
+    "node_modules/tinyexec": {
+      "version": "1.0.2",
+      "resolved": "https://registry.npmjs.org/tinyexec/-/tinyexec-1.0.2.tgz",
+      "integrity": "sha512-W/KYk+NFhkmsYpuHq5JykngiOCnxeVL8v8dFnqxSD8qEEdRfXk1SDM6JzNqcERbcGYj9tMrDQBYV9cjgnunFIg==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": ">=18"
+      }
+    },
     "node_modules/tinyglobby": {
       "version": "0.2.15",
       "resolved": "https://registry.npmjs.org/tinyglobby/-/tinyglobby-0.2.15.tgz",
@@ -3956,6 +4976,36 @@
         "url": "https://github.com/sponsors/SuperchupuDev"
       }
     },
+    "node_modules/tinyrainbow": {
+      "version": "3.0.3",
+      "resolved": "https://registry.npmjs.org/tinyrainbow/-/tinyrainbow-3.0.3.tgz",
+      "integrity": "sha512-PSkbLUoxOFRzJYjjxHJt9xro7D+iilgMX/C9lawzVuYiIdcihh9DXmVibBe8lmcFrRi/VzlPjBxbN7rH24q8/Q==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": ">=14.0.0"
+      }
+    },
+    "node_modules/tldts": {
+      "version": "7.0.19",
+      "resolved": "https://registry.npmjs.org/tldts/-/tldts-7.0.19.tgz",
+      "integrity": "sha512-8PWx8tvC4jDB39BQw1m4x8y5MH1BcQ5xHeL2n7UVFulMPH/3Q0uiamahFJ3lXA0zO2SUyRXuVVbWSDmstlt9YA==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "tldts-core": "^7.0.19"
+      },
+      "bin": {
+        "tldts": "bin/cli.js"
+      }
+    },
+    "node_modules/tldts-core": {
+      "version": "7.0.19",
+      "resolved": "https://registry.npmjs.org/tldts-core/-/tldts-core-7.0.19.tgz",
+      "integrity": "sha512-lJX2dEWx0SGH4O6p+7FPwYmJ/bu1JbcGJ8RLaG9b7liIgZ85itUVEPbMtWRVrde/0fnDPEPHW10ZsKW3kVsE9A==",
+      "dev": true,
+      "license": "MIT"
+    },
     "node_modules/to-regex-range": {
       "version": "5.0.1",
       "resolved": "https://registry.npmjs.org/to-regex-range/-/to-regex-range-5.0.1.tgz",
@@ -3969,6 +5019,42 @@
         "node": ">=8.0"
       }
     },
+    "node_modules/totalist": {
+      "version": "3.0.1",
+      "resolved": "https://registry.npmjs.org/totalist/-/totalist-3.0.1.tgz",
+      "integrity": "sha512-sf4i37nQ2LBx4m3wB74y+ubopq6W/dIzXg0FDGjsYnZHVa1Da8FH853wlL2gtUhg+xJXjfk3kUZS3BRoQeoQBQ==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": ">=6"
+      }
+    },
+    "node_modules/tough-cookie": {
+      "version": "6.0.0",
+      "resolved": "https://registry.npmjs.org/tough-cookie/-/tough-cookie-6.0.0.tgz",
+      "integrity": "sha512-kXuRi1mtaKMrsLUxz3sQYvVl37B0Ns6MzfrtV5DvJceE9bPyspOqk9xxv7XbZWcfLWbFmm997vl83qUWVJA64w==",
+      "dev": true,
+      "license": "BSD-3-Clause",
+      "dependencies": {
+        "tldts": "^7.0.5"
+      },
+      "engines": {
+        "node": ">=16"
+      }
+    },
+    "node_modules/tr46": {
+      "version": "6.0.0",
+      "resolved": "https://registry.npmjs.org/tr46/-/tr46-6.0.0.tgz",
+      "integrity": "sha512-bLVMLPtstlZ4iMQHpFHTR7GAGj2jxi8Dg0s2h2MafAE4uSWF98FC/3MomU51iQAMf8/qDUbKWf5GxuvvVcXEhw==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "punycode": "^2.3.1"
+      },
+      "engines": {
+        "node": ">=20"
+      }
+    },
     "node_modules/ts-interface-checker": {
       "version": "0.1.13",
       "resolved": "https://registry.npmjs.org/ts-interface-checker/-/ts-interface-checker-0.1.13.tgz",
@@ -4618,6 +5704,97 @@
         }
       }
     },
+    "node_modules/vitest": {
+      "version": "4.0.18",
+      "resolved": "https://registry.npmjs.org/vitest/-/vitest-4.0.18.tgz",
+      "integrity": "sha512-hOQuK7h0FGKgBAas7v0mSAsnvrIgAvWmRFjmzpJ7SwFHH3g1k2u37JtYwOwmEKhK6ZO3v9ggDBBm0La1LCK4uQ==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@vitest/expect": "4.0.18",
+        "@vitest/mocker": "4.0.18",
+        "@vitest/pretty-format": "4.0.18",
+        "@vitest/runner": "4.0.18",
+        "@vitest/snapshot": "4.0.18",
+        "@vitest/spy": "4.0.18",
+        "@vitest/utils": "4.0.18",
+        "es-module-lexer": "^1.7.0",
+        "expect-type": "^1.2.2",
+        "magic-string": "^0.30.21",
+        "obug": "^2.1.1",
+        "pathe": "^2.0.3",
+        "picomatch": "^4.0.3",
+        "std-env": "^3.10.0",
+        "tinybench": "^2.9.0",
+        "tinyexec": "^1.0.2",
+        "tinyglobby": "^0.2.15",
+        "tinyrainbow": "^3.0.3",
+        "vite": "^6.0.0 || ^7.0.0",
+        "why-is-node-running": "^2.3.0"
+      },
+      "bin": {
+        "vitest": "vitest.mjs"
+      },
+      "engines": {
+        "node": "^20.0.0 || ^22.0.0 || >=24.0.0"
+      },
+      "funding": {
+        "url": "https://opencollective.com/vitest"
+      },
+      "peerDependencies": {
+        "@edge-runtime/vm": "*",
+        "@opentelemetry/api": "^1.9.0",
+        "@types/node": "^20.0.0 || ^22.0.0 || >=24.0.0",
+        "@vitest/browser-playwright": "4.0.18",
+        "@vitest/browser-preview": "4.0.18",
+        "@vitest/browser-webdriverio": "4.0.18",
+        "@vitest/ui": "4.0.18",
+        "happy-dom": "*",
+        "jsdom": "*"
+      },
+      "peerDependenciesMeta": {
+        "@edge-runtime/vm": {
+          "optional": true
+        },
+        "@opentelemetry/api": {
+          "optional": true
+        },
+        "@types/node": {
+          "optional": true
+        },
+        "@vitest/browser-playwright": {
+          "optional": true
+        },
+        "@vitest/browser-preview": {
+          "optional": true
+        },
+        "@vitest/browser-webdriverio": {
+          "optional": true
+        },
+        "@vitest/ui": {
+          "optional": true
+        },
+        "happy-dom": {
+          "optional": true
+        },
+        "jsdom": {
+          "optional": true
+        }
+      }
+    },
+    "node_modules/w3c-xmlserializer": {
+      "version": "5.0.0",
+      "resolved": "https://registry.npmjs.org/w3c-xmlserializer/-/w3c-xmlserializer-5.0.0.tgz",
+      "integrity": "sha512-o8qghlI8NZHU1lLPrpi2+Uq7abh4GGPpYANlalzWxyWteJOCsr/P+oPBA49TOLu5FTZO4d3F9MnWJfiMo4BkmA==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "xml-name-validator": "^5.0.0"
+      },
+      "engines": {
+        "node": ">=18"
+      }
+    },
     "node_modules/web-streams-polyfill": {
       "version": "3.3.3",
       "resolved": "https://registry.npmjs.org/web-streams-polyfill/-/web-streams-polyfill-3.3.3.tgz",
@@ -4627,6 +5804,40 @@
         "node": ">= 8"
       }
     },
+    "node_modules/webidl-conversions": {
+      "version": "8.0.1",
+      "resolved": "https://registry.npmjs.org/webidl-conversions/-/webidl-conversions-8.0.1.tgz",
+      "integrity": "sha512-BMhLD/Sw+GbJC21C/UgyaZX41nPt8bUTg+jWyDeg7e7YN4xOM05YPSIXceACnXVtqyEw/LMClUQMtMZ+PGGpqQ==",
+      "dev": true,
+      "license": "BSD-2-Clause",
+      "engines": {
+        "node": ">=20"
+      }
+    },
+    "node_modules/whatwg-mimetype": {
+      "version": "4.0.0",
+      "resolved": "https://registry.npmjs.org/whatwg-mimetype/-/whatwg-mimetype-4.0.0.tgz",
+      "integrity": "sha512-QaKxh0eNIi2mE9p2vEdzfagOKHCcj1pJ56EEHGQOVxp8r9/iszLUUV7v89x9O1p/T+NlTM5W7jW6+cz4Fq1YVg==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/whatwg-url": {
+      "version": "15.1.0",
+      "resolved": "https://registry.npmjs.org/whatwg-url/-/whatwg-url-15.1.0.tgz",
+      "integrity": "sha512-2ytDk0kiEj/yu90JOAp44PVPUkO9+jVhyf+SybKlRHSDlvOOZhdPIrr7xTH64l4WixO2cP+wQIcgujkGBPPz6g==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "tr46": "^6.0.0",
+        "webidl-conversions": "^8.0.0"
+      },
+      "engines": {
+        "node": ">=20"
+      }
+    },
     "node_modules/which": {
       "version": "2.0.2",
       "resolved": "https://registry.npmjs.org/which/-/which-2.0.2.tgz",
@@ -4642,6 +5853,23 @@
         "node": ">= 8"
       }
     },
+    "node_modules/why-is-node-running": {
+      "version": "2.3.0",
+      "resolved": "https://registry.npmjs.org/why-is-node-running/-/why-is-node-running-2.3.0.tgz",
+      "integrity": "sha512-hUrmaWBdVDcxvYqnyh09zunKzROWjbZTiNy8dBEjkS7ehEDQibXJ7XvlmtbwuTclUiIyN+CyXQD4Vmko8fNm8w==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "siginfo": "^2.0.0",
+        "stackback": "0.0.2"
+      },
+      "bin": {
+        "why-is-node-running": "cli.js"
+      },
+      "engines": {
+        "node": ">=8"
+      }
+    },
     "node_modules/wrap-ansi": {
       "version": "8.1.0",
       "resolved": "https://registry.npmjs.org/wrap-ansi/-/wrap-ansi-8.1.0.tgz",
@@ -4754,6 +5982,23 @@
         }
       }
     },
+    "node_modules/xml-name-validator": {
+      "version": "5.0.0",
+      "resolved": "https://registry.npmjs.org/xml-name-validator/-/xml-name-validator-5.0.0.tgz",
+      "integrity": "sha512-EvGK8EJ3DhaHfbRlETOWAS5pO9MZITeauHKJyb8wyajUfQUenkIg2MvLDTZ4T/TgIcm3HU0TFBgWWboAZ30UHg==",
+      "dev": true,
+      "license": "Apache-2.0",
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/xmlchars": {
+      "version": "2.2.0",
+      "resolved": "https://registry.npmjs.org/xmlchars/-/xmlchars-2.2.0.tgz",
+      "integrity": "sha512-JZnDKK8B0RCDw84FNdDAIpZK+JuJw+s7Lz8nksI7SIuU3UXJJslUthsi+uWBUYOwPFwW7W7PRLRfUKpxjtjFCw==",
+      "dev": true,
+      "license": "MIT"
+    },
     "node_modules/yallist": {
       "version": "3.1.1",
       "resolved": "https://registry.npmjs.org/yallist/-/yallist-3.1.1.tgz",
diff --git a/package.json b/package.json
index 346f3be..ff77f51 100644
--- a/package.json
+++ b/package.json
@@ -6,7 +6,10 @@
   "scripts": {
     "dev": "vite",
     "build": "tsc && vite build",
-    "preview": "vite preview"
+    "preview": "vite preview",
+    "test": "vitest",
+    "test:ui": "vitest --ui",
+    "test:coverage": "vitest --coverage"
   },
   "dependencies": {
     "@google/genai": "^1.37.0",
@@ -21,14 +24,20 @@
     "@tailwindcss/container-queries": "^0.1.1",
     "@tailwindcss/forms": "^0.5.11",
     "@tailwindcss/typography": "^0.5.19",
+    "@testing-library/jest-dom": "^6.9.1",
+    "@testing-library/react": "^16.3.2",
+    "@testing-library/user-event": "^14.6.1",
     "@types/node": "^22.14.0",
     "@vitejs/plugin-react": "^5.0.0",
+    "@vitest/ui": "^4.0.18",
     "autoprefixer": "^10.4.23",
     "dotenv": "^17.2.3",
+    "jsdom": "^27.4.0",
     "postcss": "^8.5.6",
     "tailwindcss": "^3.4.17",
     "tsx": "^4.21.0",
     "typescript": "~5.8.2",
-    "vite": "^6.2.0"
+    "vite": "^6.2.0",
+    "vitest": "^4.0.18"
   }
 }
diff --git a/App.tsx b/src/App.tsx
similarity index 97%
rename from App.tsx
rename to src/App.tsx
index 015216b..973b492 100644
--- a/App.tsx
+++ b/src/App.tsx
@@ -9,6 +9,7 @@ import { UploadView } from './components/UploadView';
 import { ArticleView } from './components/ArticleView';
 import { SettingsView } from './components/SettingsView';
 import { EditorView } from './components/EditorView';
+import { LoginView } from './components/LoginView';
 import { ProcessingModal } from './components/ProcessingModal';
 import { ProcessingStatus } from './components/ProcessingStatus';
 import { SystemHud } from './components/SystemHud';
@@ -17,6 +18,7 @@ import { ManualAssetModal } from './components/ManualAssetModal';
 import { analyzeAsset, generateCaseStudy } from './services/geminiService';
 import { saveCaseStudy, getCaseStudies } from './services/dbService';
 import { DEMO_STUDIES } from './utils/demoData';
+import { useAuth } from './contexts/AuthContext';
 
 const DEFAULT_PREFERENCES: UserPreferences = {
   theme: 'light',
@@ -27,6 +29,7 @@ const DEFAULT_PREFERENCES: UserPreferences = {
 const SUPPORTED_UNPACK_EXTENSIONS = ['md', 'js', 'jsx', 'ts', 'tsx', 'css', 'html', 'json', 'txt', 'py', 'go', 'rs', 'svg', 'fig', 'sql'];
 
 const App: React.FC = () => {
+  const { user, loading: authLoading } = useAuth();
   const [view, setView] = useState<AppView>('timeline');
   const [caseStudies, setCaseStudies] = useState<CaseStudy[]>([]);
   const [assets, setAssets] = useState<Asset[]>([]);
@@ -434,6 +437,22 @@ const App: React.FC = () => {
     setAssets([]);
   };
 
+  // Show login if not authenticated
+  if (authLoading) {
+    return (
+      <div className="h-screen flex items-center justify-center bg-[#F9F9F9]">
+        <div className="text-2xl font-black mono">LOADING...</div>
+      </div>
+    );
+  }
+
+  if (!user) {
+    return <LoginView />;
+  }
+
+  // Check permissions for create/edit operations
+  const canEdit = user.role === 'publisher';
+
   return (
     <div className={`h-screen flex flex-col md:flex-row bg-[#F9F9F9] selection:bg-amber-300 selection:text-black ${preferences.theme === 'dark' ? 'dark-mode-sim' : ''}`}>
 
@@ -492,6 +511,7 @@ const App: React.FC = () => {
                 isUploading={isUploading}
                 progress={processingProgress}
                 isThinkingEnabled={isThinkingEnabled}
+                canEdit={canEdit}
                 onToggleThinking={() => setIsThinkingEnabled(!isThinkingEnabled)}
                 onFileUpload={handleFileUpload}
                 onRemoveAsset={(id) => setAssets(assets.filter(a => a.id !== id))}
diff --git a/components/AppHeader.tsx b/src/components/AppHeader.tsx
similarity index 81%
rename from components/AppHeader.tsx
rename to src/components/AppHeader.tsx
index 04c1301..5752fb3 100644
--- a/components/AppHeader.tsx
+++ b/src/components/AppHeader.tsx
@@ -3,6 +3,7 @@ import React from 'react';
 import { Icon } from './Icon';
 import { BrutalistButton } from './BrutalistButton';
 import { AppView } from '../types';
+import { useAuth } from '../contexts/AuthContext';
 
 interface AppHeaderProps {
   activeView: AppView;
@@ -23,6 +24,8 @@ export const AppHeader: React.FC<AppHeaderProps> = ({
   onToggleSettings,
   onBack
 }) => {
+  const { user, signOut } = useAuth();
+
   const getViewTitle = () => {
     switch (activeView) {
       case 'timeline': return 'Dev_Timeline';
@@ -59,6 +62,23 @@ export const AppHeader: React.FC<AppHeaderProps> = ({
       </div>
 
       <div className="flex gap-3 md:gap-4 items-center">
+        {user && (
+          <div className="hidden md:flex items-center gap-2 bg-black text-amber-300 px-3 py-2 brutalist-border">
+            <span className="mono text-xs font-bold">{user.role.toUpperCase()}</span>
+            <span className="text-white">•</span>
+            <span className="mono text-xs">{user.email}</span>
+          </div>
+        )}
+
+        <BrutalistButton
+          variant="secondary"
+          onClick={signOut}
+          title="Sign Out"
+          className="text-sm py-2 px-4 hover:bg-red-600 hover:text-white transition-colors"
+        >
+          <Icon name="LogOut" size={20} />
+        </BrutalistButton>
+
         <BrutalistButton
           variant={isSettingsOpen ? 'primary' : 'secondary'}
           onClick={onToggleSettings}
diff --git a/components/ArticleView.tsx b/src/components/ArticleView.tsx
similarity index 100%
rename from components/ArticleView.tsx
rename to src/components/ArticleView.tsx
diff --git a/components/BrutalistButton.tsx b/src/components/BrutalistButton.tsx
similarity index 100%
rename from components/BrutalistButton.tsx
rename to src/components/BrutalistButton.tsx
diff --git a/components/Drawer.tsx b/src/components/Drawer.tsx
similarity index 100%
rename from components/Drawer.tsx
rename to src/components/Drawer.tsx
diff --git a/components/EditorView.tsx b/src/components/EditorView.tsx
similarity index 100%
rename from components/EditorView.tsx
rename to src/components/EditorView.tsx
diff --git a/components/Icon.tsx b/src/components/Icon.tsx
similarity index 100%
rename from components/Icon.tsx
rename to src/components/Icon.tsx
diff --git a/components/LazyArtifact.tsx b/src/components/LazyArtifact.tsx
similarity index 100%
rename from components/LazyArtifact.tsx
rename to src/components/LazyArtifact.tsx
diff --git a/src/components/LoginView.tsx b/src/components/LoginView.tsx
new file mode 100644
index 0000000..9b477a9
--- /dev/null
+++ b/src/components/LoginView.tsx
@@ -0,0 +1,206 @@
+import React, { useState } from 'react';
+import { useAuth } from '../contexts/AuthContext';
+import { BrutalistButton } from './BrutalistButton';
+import { Icon } from './Icon';
+
+export const LoginView: React.FC = () => {
+  const { signIn, signUp, signInWithProvider } = useAuth();
+  const [isSignUp, setIsSignUp] = useState(false);
+  const [email, setEmail] = useState('');
+  const [password, setPassword] = useState('');
+  const [showPassword, setShowPassword] = useState(false);
+  const [requestPublisher, setRequestPublisher] = useState(false);
+  const [error, setError] = useState<string | null>(null);
+  const [loading, setLoading] = useState(false);
+  const [success, setSuccess] = useState<string | null>(null);
+
+  const handleSubmit = async (e: React.FormEvent) => {
+    e.preventDefault();
+    setError(null);
+    setSuccess(null);
+    setLoading(true);
+
+    try {
+      if (isSignUp) {
+        // Always sign up as reader, save publisher request for admin approval
+        await signUp(email, password, 'reader', requestPublisher);
+        if (requestPublisher) {
+          setSuccess('Account created! Publisher access requires admin approval. Check your email.');
+        }
+      } else {
+        await signIn(email, password);
+      }
+    } catch (err: any) {
+      setError(err.message || 'Authentication failed');
+    } finally {
+      setLoading(false);
+    }
+  };
+
+  const handleOAuthSignIn = async (provider: 'google' | 'github') => {
+    setError(null);
+    setLoading(true);
+    
+    try {
+      await signInWithProvider(provider);
+    } catch (err: any) {
+      setError(err.message || `${provider} sign-in failed`);
+      setLoading(false);
+    }
+  };
+
+  return (
+    <div className="min-h-screen bg-[#666666] flex items-center justify-center p-4">
+      <div className="max-w-md w-full bg-white brutalist-border brutalist-shadow-lg p-8">
+        <div className="mb-8">
+          <h1 className="text-4xl font-black mb-2">
+            {isSignUp ? 'CREATE ACCOUNT' : 'SIGN IN'}
+          </h1>
+          <p className="text-sm text-gray-600 mono">
+            {isSignUp ? 'Join the case study engine' : 'Access your case studies'}
+          </p>
+        </div>
+
+        {error && (
+          <div className="mb-6 p-4 bg-red-100 brutalist-border border-red-600 text-red-600 text-sm font-bold">
+            {error}
+          </div>
+        )}
+
+        {success && (
+          <div className="mb-6 p-4 bg-green-100 brutalist-border border-green-600 text-green-600 text-sm font-bold">
+            {success}
+          </div>
+        )}
+
+        <form onSubmit={handleSubmit} className="space-y-6">
+          <div>
+            <label className="block text-xs font-bold mb-2 mono">EMAIL</label>
+            <input
+              type="email"
+              value={email}
+              onChange={(e) => setEmail(e.target.value)}
+              className="w-full p-3 brutalist-border focus:outline-none focus:border-amber-300 bg-white mono"
+              placeholder="your@email.com"
+              required
+            />
+          </div>
+
+          <div>
+            <label className="block text-xs font-bold mb-2 mono">PASSWORD</label>
+            <div className="relative">
+              <input
+                type={showPassword ? 'text' : 'password'}
+                value={password}
+                onChange={(e) => setPassword(e.target.value)}
+                className="w-full p-3 pr-12 brutalist-border focus:outline-none focus:border-amber-300 bg-white mono"
+                placeholder="••••••••"
+                required
+              />
+              <button
+                type="button"
+                onClick={() => setShowPassword(!showPassword)}
+                className="absolute right-3 top-1/2 -translate-y-1/2 text-gray-600 hover:text-black"
+                aria-label={showPassword ? 'Hide password' : 'Show password'}
+              >
+                <Icon name={showPassword ? 'EyeOff' : 'Eye'} size={20} />
+              </button>
+            </div>
+          </div>
+
+          {isSignUp && (
+            <div>
+              <label className="block text-xs font-bold mb-3 mono">ACCOUNT TYPE</label>
+              <div className="space-y-3">
+                <div className="p-4 brutalist-border bg-amber-50">
+                  <div className="flex items-center gap-2">
+                    <Icon name="BookOpen" size={16} />
+                    <span className="mono text-sm font-bold">READER ACCESS (Default)</span>
+                  </div>
+                  <p className="text-xs text-gray-600 mt-2 mono">
+                    View published case studies only
+                  </p>
+                </div>
+
+                <label className="flex items-start gap-3 p-4 brutalist-border bg-white cursor-pointer hover:bg-gray-50">
+                  <input
+                    type="checkbox"
+                    checked={requestPublisher}
+                    onChange={(e) => setRequestPublisher(e.target.checked)}
+                    className="w-5 h-5 mt-0.5"
+                  />
+                  <div className="flex-1">
+                    <div className="flex items-center gap-2">
+                      <Icon name="Crown" size={16} />
+                      <span className="mono text-sm font-bold">REQUEST PUBLISHER ACCESS</span>
+                    </div>
+                    <p className="text-xs text-gray-600 mt-2 mono">
+                      Create, edit, and delete case studies (requires admin approval)
+                    </p>
+                  </div>
+                </label>
+              </div>
+            </div>
+          )}
+
+          <BrutalistButton
+            type="submit"
+            fullWidth
+            disabled={loading}
+          >
+            {loading ? 'PROCESSING...' : isSignUp ? 'CREATE ACCOUNT' : 'SIGN IN'}
+          </BrutalistButton>
+
+          <button
+            type="button"
+            onClick={() => {
+              setIsSignUp(!isSignUp);
+              setError(null);
+              setSuccess(null);
+            }}
+            className="w-full text-center text-sm mono text-gray-600 hover:text-black underline font-bold"
+          >
+            {isSignUp ? 'Already have an account? Sign in' : "Don't have an account? Sign up"}
+          </button>
+        </form>
+
+        <div className="mt-8 pt-8 border-t-4 border-black">
+          <p className="text-xs mono text-gray-500 mb-4">OR CONTINUE WITH</p>
+          <div className="space-y-3">
+            <BrutalistButton
+              variant="secondary"
+              fullWidth
+              onClick={() => handleOAuthSignIn('google')}
+              disabled={loading}
+              className="flex items-center justify-center gap-3"
+            >
+              <Icon name="Chrome" size={20} />
+              <span>Google</span>
+            </BrutalistButton>
+            <BrutalistButton
+              variant="secondary"
+              fullWidth
+              onClick={() => handleOAuthSignIn('github')}
+              disabled={loading}
+              className="flex items-center justify-center gap-3"
+            >
+              <Icon name="Github" size={20} />
+              <span>GitHub</span>
+            </BrutalistButton>
+          </div>
+        </div>
+
+        <div className="mt-8 pt-8 border-t-4 border-black">
+          <p className="text-xs mono text-gray-500">
+            ROLE PERMISSIONS:
+          </p>
+          <ul className="mt-2 space-y-1 text-xs mono text-gray-600">
+            <li>• PUBLISHER: Create, edit, delete case studies (approval required)</li>
+            <li>• READER: View published case studies</li>
+          </ul>
+        </div>
+      </div>
+    </div>
+  );
+};
+
diff --git a/components/ManualAssetModal.tsx b/src/components/ManualAssetModal.tsx
similarity index 100%
rename from components/ManualAssetModal.tsx
rename to src/components/ManualAssetModal.tsx
diff --git a/components/Navigation.tsx b/src/components/Navigation.tsx
similarity index 100%
rename from components/Navigation.tsx
rename to src/components/Navigation.tsx
diff --git a/components/ProcessingModal.tsx b/src/components/ProcessingModal.tsx
similarity index 100%
rename from components/ProcessingModal.tsx
rename to src/components/ProcessingModal.tsx
diff --git a/components/ProcessingStatus.tsx b/src/components/ProcessingStatus.tsx
similarity index 100%
rename from components/ProcessingStatus.tsx
rename to src/components/ProcessingStatus.tsx
diff --git a/components/ProgressBar.tsx b/src/components/ProgressBar.tsx
similarity index 100%
rename from components/ProgressBar.tsx
rename to src/components/ProgressBar.tsx
diff --git a/components/SettingsItem.tsx b/src/components/SettingsItem.tsx
similarity index 100%
rename from components/SettingsItem.tsx
rename to src/components/SettingsItem.tsx
diff --git a/components/SettingsView.tsx b/src/components/SettingsView.tsx
similarity index 100%
rename from components/SettingsView.tsx
rename to src/components/SettingsView.tsx
diff --git a/components/SystemHud.tsx b/src/components/SystemHud.tsx
similarity index 100%
rename from components/SystemHud.tsx
rename to src/components/SystemHud.tsx
diff --git a/components/TimelineView.tsx b/src/components/TimelineView.tsx
similarity index 100%
rename from components/TimelineView.tsx
rename to src/components/TimelineView.tsx
diff --git a/components/Toast.tsx b/src/components/Toast.tsx
similarity index 100%
rename from components/Toast.tsx
rename to src/components/Toast.tsx
diff --git a/components/UploadView.tsx b/src/components/UploadView.tsx
similarity index 95%
rename from components/UploadView.tsx
rename to src/components/UploadView.tsx
index b6b0c7d..25df711 100644
--- a/components/UploadView.tsx
+++ b/src/components/UploadView.tsx
@@ -11,6 +11,7 @@ interface UploadViewProps {
   isUploading: boolean;
   progress: number;
   isThinkingEnabled: boolean;
+  canEdit: boolean;
   onToggleThinking: () => void;
   onFileUpload: (e: React.ChangeEvent<HTMLInputElement>) => void;
   onRemoveAsset: (id: string) => void;
@@ -27,6 +28,7 @@ export const UploadView: React.FC<UploadViewProps> = ({
   isUploading,
   progress,
   isThinkingEnabled,
+  canEdit,
   onToggleThinking,
   onFileUpload,
   onRemoveAsset,
@@ -186,7 +188,7 @@ export const UploadView: React.FC<UploadViewProps> = ({
         )}
       </div>
 
-      {assets.length > 0 ? (
+      {assets.length > 0 && canEdit ? (
         <div className="p-6 border-t-4 border-black bg-white sticky bottom-0">
           <BrutalistButton 
             fullWidth 
@@ -198,6 +200,13 @@ export const UploadView: React.FC<UploadViewProps> = ({
             {isUploading ? 'BUILDING...' : 'GENERATE_LOG'}
           </BrutalistButton>
         </div>
+      ) : !canEdit && assets.length > 0 ? (
+        <div className="p-6 border-t-4 border-black bg-white mt-auto">
+          <div className="flex items-center gap-3 justify-center text-red-600">
+            <Icon name="Lock" size={16} />
+            <span className="mono text-[10px] font-black uppercase">READ-ONLY ACCESS</span>
+          </div>
+        </div>
       ) : (
         <div className="p-6 border-t-4 border-black bg-white mt-auto">
           <div className="flex items-center gap-3 justify-center text-zinc-400">
diff --git a/constants.tsx b/src/constants.tsx
similarity index 100%
rename from constants.tsx
rename to src/constants.tsx
diff --git a/src/contexts/AuthContext.tsx b/src/contexts/AuthContext.tsx
new file mode 100644
index 0000000..a313868
--- /dev/null
+++ b/src/contexts/AuthContext.tsx
@@ -0,0 +1,146 @@
+import React, { createContext, useContext, useEffect, useState } from 'react';
+import { supabase } from '../utils/supabase';
+import { User, UserRole } from '../types';
+
+interface AuthContextType {
+  user: User | null;
+  loading: boolean;
+  signIn: (email: string, password: string) => Promise<void>;
+  signUp: (email: string, password: string, role: UserRole, requestPublisher?: boolean) => Promise<void>;
+  signInWithProvider: (provider: 'google' | 'github') => Promise<void>;
+  signOut: () => Promise<void>;
+}
+
+const AuthContext = createContext<AuthContextType | undefined>(undefined);
+
+export const useAuth = () => {
+  const context = useContext(AuthContext);
+  if (!context) {
+    throw new Error('useAuth must be used within AuthProvider');
+  }
+  return context;
+};
+
+const getUserRole = async (userId: string): Promise<UserRole> => {
+  const { data, error } = await supabase
+    .from('user_roles')
+    .select('role')
+    .eq('user_id', userId)
+    .single();
+  
+  if (error || !data) {
+    // If no role exists (OAuth first-time login), create reader role
+    await supabase.from('user_roles').insert({
+      user_id: userId,
+      role: 'reader',
+      publisher_requested: false
+    });
+    return 'reader';
+  }
+  
+  return data.role as UserRole;
+};
+
+export const AuthProvider: React.FC<{ children: React.ReactNode }> = ({ children }) => {
+  const [user, setUser] = useState<User | null>(null);
+  const [loading, setLoading] = useState(true);
+
+  useEffect(() => {
+    // Check active session
+    supabase.auth.getSession().then(async ({ data: { session } }) => {
+      if (session?.user) {
+        const role = await getUserRole(session.user.id);
+        setUser({
+          id: session.user.id,
+          email: session.user.email!,
+          role
+        });
+      }
+      setLoading(false);
+    });
+
+    // Listen for auth changes
+    const { data: { subscription } } = supabase.auth.onAuthStateChange(async (_event, session) => {
+      if (session?.user) {
+        const role = await getUserRole(session.user.id);
+        setUser({
+          id: session.user.id,
+          email: session.user.email!,
+          role
+        });
+      } else {
+        setUser(null);
+      }
+      setLoading(false);
+    });
+
+    return () => subscription.unsubscribe();
+  }, []);
+
+  const signIn = async (email: string, password: string) => {
+    const { data, error } = await supabase.auth.signInWithPassword({
+      email,
+      password
+    });
+
+    if (error) throw error;
+
+    if (data.user) {
+      const role = await getUserRole(data.user.id);
+      setUser({
+        id: data.user.id,
+        email: data.user.email!,
+        role
+      });
+    }
+  };
+
+  const signUp = async (email: string, password: string, role: UserRole, requestPublisher: boolean = false) => {
+    const { data, error } = await supabase.auth.signUp({
+      email,
+      password
+    });
+
+    if (error) throw error;
+
+    // Create role record
+    if (data.user) {
+      await supabase.from('user_roles').insert({
+        user_id: data.user.id,
+        role,
+        publisher_requested: requestPublisher
+      });
+
+      setUser({
+        id: data.user.id,
+        email: data.user.email!,
+        role
+      });
+    }
+  };
+
+  const signInWithProvider = async (provider: 'google' | 'github') => {
+    const { error } = await supabase.auth.signInWithOAuth({
+      provider,
+      options: {
+        redirectTo: window.location.origin
+      }
+    });
+
+    if (error) throw error;
+
+    // Note: User data will be set via onAuthStateChange after redirect
+  };
+
+  const signOut = async () => {
+    const { error } = await supabase.auth.signOut();
+    if (error) throw error;
+    setUser(null);
+  };
+
+  return (
+    <AuthContext.Provider value={{ user, loading, signIn, signUp, signInWithProvider, signOut }}>
+      {children}
+    </AuthContext.Provider>
+  );
+};
diff --git a/index.css b/src/index.css
similarity index 100%
rename from index.css
rename to src/index.css
diff --git a/index.tsx b/src/index.tsx
similarity index 76%
rename from index.tsx
rename to src/index.tsx
index bce7f44..a2a559c 100644
--- a/index.tsx
+++ b/src/index.tsx
@@ -2,6 +2,7 @@ import React from 'react';
 import ReactDOM from 'react-dom/client';
 import App from './App';
 import './index.css';
+import { AuthProvider } from './contexts/AuthContext';
 
 const rootElement = document.getElementById('root');
 if (!rootElement) {
@@ -11,6 +12,8 @@ if (!rootElement) {
 const root = ReactDOM.createRoot(rootElement);
 root.render(
   <React.StrictMode>
-    <App />
+    <AuthProvider>
+      <App />
+    </AuthProvider>
   </React.StrictMode>
 );
diff --git a/services/dbService.ts b/src/services/dbService.ts
similarity index 100%
rename from services/dbService.ts
rename to src/services/dbService.ts
diff --git a/services/geminiService.ts b/src/services/geminiService.ts
similarity index 100%
rename from services/geminiService.ts
rename to src/services/geminiService.ts
diff --git a/src/tests/BrutalistButton.test.tsx b/src/tests/BrutalistButton.test.tsx
new file mode 100644
index 0000000..bb5b723
--- /dev/null
+++ b/src/tests/BrutalistButton.test.tsx
@@ -0,0 +1,31 @@
+import { describe, it, expect } from 'vitest';
+import { render, screen } from '@testing-library/react';
+import { BrutalistButton } from '../components/BrutalistButton';
+
+describe('BrutalistButton', () => {
+  it('renders with default variant', () => {
+    render(<BrutalistButton>Click Me</BrutalistButton>);
+    const button = screen.getByText('Click Me');
+    expect(button).toBeInTheDocument();
+  });
+
+  it('applies primary variant styles', () => {
+    render(<BrutalistButton variant="primary">Primary</BrutalistButton>);
+    const button = screen.getByText('Primary');
+    expect(button).toHaveClass('bg-amber-300');
+  });
+
+  it('handles click events', () => {
+    let clicked = false;
+    render(<BrutalistButton onClick={() => { clicked = true; }}>Click</BrutalistButton>);
+    const button = screen.getByText('Click');
+    button.click();
+    expect(clicked).toBe(true);
+  });
+
+  it('can be disabled', () => {
+    render(<BrutalistButton disabled>Disabled</BrutalistButton>);
+    const button = screen.getByText('Disabled');
+    expect(button).toBeDisabled();
+  });
+});
diff --git a/src/tests/geminiService.test.ts b/src/tests/geminiService.test.ts
new file mode 100644
index 0000000..56f8f18
--- /dev/null
+++ b/src/tests/geminiService.test.ts
@@ -0,0 +1,65 @@
+import { describe, it, expect, vi } from 'vitest';
+import { analyzeAsset, generateCaseStudy } from '../services/geminiService';
+import { Asset } from '../types';
+
+// Mock the Gemini API
+vi.mock('@google/genai', () => ({
+  GoogleGenAI: vi.fn(() => ({
+    models: {
+      generateContent: vi.fn().mockResolvedValue({
+        text: JSON.stringify({
+          topic: 'auth',
+          type: 'wireframe',
+          context: 'mobile',
+          variant: 'dark',
+          version: 'v2'
+        })
+      })
+    }
+  })),
+  Type: {
+    OBJECT: 'object',
+    STRING: 'string',
+    ARRAY: 'array'
+  }
+}));
+
+describe('geminiService', () => {
+  describe('analyzeAsset', () => {
+    it('should analyze a file and return metadata', async () => {
+      const file = new File(['test content'], 'test.png', { type: 'image/png' });
+      
+      const result = await analyzeAsset(file, 'image/png', false);
+      
+      expect(result).toHaveProperty('topic');
+      expect(result).toHaveProperty('type');
+      expect(result).toHaveProperty('context');
+      expect(result).toHaveProperty('variant');
+      expect(result).toHaveProperty('version');
+    });
+  });
+
+  describe('generateCaseStudy', () => {
+    it('should generate a case study from assets', async () => {
+      const assets: Asset[] = [
+        {
+          id: '1',
+          originalName: 'wireframe.png',
+          aiName: 'auth-wireframe-mobile-dark-v2.png',
+          type: 'wireframe',
+          topic: 'auth',
+          context: 'mobile',
+          variant: 'dark',
+          version: 'v2',
+          fileType: 'png',
+          url: 'blob:test',
+          size: 1024
+        }
+      ];
+
+      const result = await generateCaseStudy(assets, 'Test context', false);
+      
+      expect(result).toBeDefined();
+    });
+  });
+});
diff --git a/src/tests/setup.ts b/src/tests/setup.ts
new file mode 100644
index 0000000..117b3a6
--- /dev/null
+++ b/src/tests/setup.ts
@@ -0,0 +1,9 @@
+import { expect, afterEach } from 'vitest';
+import { cleanup } from '@testing-library/react';
+import * as matchers from '@testing-library/jest-dom/matchers';
+
+expect.extend(matchers);
+
+afterEach(() => {
+  cleanup();
+});
diff --git a/types.ts b/src/types.ts
similarity index 83%
rename from types.ts
rename to src/types.ts
index ce74455..4305229 100644
--- a/types.ts
+++ b/src/types.ts
@@ -1,5 +1,13 @@
 
-export type AppView = 'timeline' | 'upload' | 'editor' | 'settings' | 'article';
+export type AppView = 'timeline' | 'upload' | 'editor' | 'settings' | 'article' | 'login';
+
+export type UserRole = 'publisher' | 'reader';
+
+export interface User {
+  id: string;
+  email: string;
+  role: UserRole;
+}
 
 export interface Asset {
   id: string;
diff --git a/utils/demoData.ts b/src/utils/demoData.ts
similarity index 100%
rename from utils/demoData.ts
rename to src/utils/demoData.ts
diff --git a/utils/supabase.ts b/src/utils/supabase.ts
similarity index 100%
rename from utils/supabase.ts
rename to src/utils/supabase.ts
diff --git a/vite-env.d.ts b/src/vite-env.d.ts
similarity index 100%
rename from vite-env.d.ts
rename to src/vite-env.d.ts
diff --git a/supabase/migrations/001_auth_and_rls.sql b/supabase/migrations/001_auth_and_rls.sql
new file mode 100644
index 0000000..18ad17e
--- /dev/null
+++ b/supabase/migrations/001_auth_and_rls.sql
@@ -0,0 +1,168 @@
+-- Enable Row Level Security
+ALTER TABLE case_studies ENABLE ROW LEVEL SECURITY;
+ALTER TABLE assets ENABLE ROW LEVEL SECURITY;
+
+-- Create user_roles table
+CREATE TABLE IF NOT EXISTS user_roles (
+  id UUID DEFAULT gen_random_uuid() PRIMARY KEY,
+  user_id UUID REFERENCES auth.users(id) ON DELETE CASCADE,
+  role TEXT NOT NULL CHECK (role IN ('publisher', 'reader')),
+  publisher_requested BOOLEAN DEFAULT FALSE,
+  created_at TIMESTAMP WITH TIME ZONE DEFAULT NOW(),
+  UNIQUE(user_id)
+);
+
+-- Enable RLS on user_roles
+ALTER TABLE user_roles ENABLE ROW LEVEL SECURITY;
+
+-- User roles policies
+CREATE POLICY "Users can view own role" ON user_roles
+  FOR SELECT USING (auth.uid() = user_id);
+
+CREATE POLICY "Users can insert own role" ON user_roles
+  FOR INSERT WITH CHECK (auth.uid() = user_id);
+
+-- Case Studies Policies
+
+-- Publishers can do everything
+CREATE POLICY "Publishers can insert case studies" ON case_studies
+  FOR INSERT TO authenticated
+  WITH CHECK (
+    EXISTS (
+      SELECT 1 FROM user_roles 
+      WHERE user_id = auth.uid() AND role = 'publisher'
+    )
+  );
+
+CREATE POLICY "Publishers can update case studies" ON case_studies
+  FOR UPDATE TO authenticated
+  USING (
+    EXISTS (
+      SELECT 1 FROM user_roles 
+      WHERE user_id = auth.uid() AND role = 'publisher'
+    )
+  );
+
+CREATE POLICY "Publishers can delete case studies" ON case_studies
+  FOR DELETE TO authenticated
+  USING (
+    EXISTS (
+      SELECT 1 FROM user_roles 
+      WHERE user_id = auth.uid() AND role = 'publisher'
+    )
+  );
+
+-- Both readers and publishers can view published case studies
+-- Publishers can see all (including drafts)
+CREATE POLICY "Users can view case studies" ON case_studies
+  FOR SELECT TO authenticated
+  USING (
+    -- Publishers see everything
+    EXISTS (
+      SELECT 1 FROM user_roles 
+      WHERE user_id = auth.uid() AND role = 'publisher'
+    )
+    OR
+    -- Readers see only published
+    (
+      status = 'published' AND
+      EXISTS (
+        SELECT 1 FROM user_roles 
+        WHERE user_id = auth.uid() AND role = 'reader'
+      )
+    )
+  );
+
+-- Assets Policies (inherit from parent case study)
+
+CREATE POLICY "Publishers can insert assets" ON assets
+  FOR INSERT TO authenticated
+  WITH CHECK (
+    EXISTS (
+      SELECT 1 FROM user_roles 
+      WHERE user_id = auth.uid() AND role = 'publisher'
+    )
+  );
+
+CREATE POLICY "Publishers can update assets" ON assets
+  FOR UPDATE TO authenticated
+  USING (
+    EXISTS (
+      SELECT 1 FROM user_roles 
+      WHERE user_id = auth.uid() AND role = 'publisher'
+    )
+  );
+
+CREATE POLICY "Publishers can delete assets" ON assets
+  FOR DELETE TO authenticated
+  USING (
+    EXISTS (
+      SELECT 1 FROM user_roles 
+      WHERE user_id = auth.uid() AND role = 'publisher'
+    )
+  );
+
+CREATE POLICY "Users can view assets" ON assets
+  FOR SELECT TO authenticated
+  USING (
+    -- Publishers see all assets
+    EXISTS (
+      SELECT 1 FROM user_roles 
+      WHERE user_id = auth.uid() AND role = 'publisher'
+    )
+    OR
+    -- Readers see assets of published case studies only
+    (
+      EXISTS (
+        SELECT 1 FROM user_roles 
+        WHERE user_id = auth.uid() AND role = 'reader'
+      )
+      AND
+      EXISTS (
+        SELECT 1 FROM case_studies 
+        WHERE id = assets.case_study_id AND status = 'published'
+      )
+    )
+  );
+
+-- Storage Policies (update existing)
+
+-- Remove old public policies if they exist
+DROP POLICY IF EXISTS "Upload" ON storage.objects;
+DROP POLICY IF EXISTS "Public Access" ON storage.objects;
+DROP POLICY IF EXISTS "Update" ON storage.objects;
+
+-- New authenticated policies
+CREATE POLICY "Publishers can upload" ON storage.objects
+  FOR INSERT TO authenticated
+  WITH CHECK (
+    bucket_id = 'assets' AND
+    EXISTS (
+      SELECT 1 FROM user_roles 
+      WHERE user_id = auth.uid() AND role = 'publisher'
+    )
+  );
+
+CREATE POLICY "Authenticated users can view assets" ON storage.objects
+  FOR SELECT TO authenticated
+  USING (bucket_id = 'assets');
+
+CREATE POLICY "Publishers can update assets" ON storage.objects
+  FOR UPDATE TO authenticated
+  USING (
+    bucket_id = 'assets' AND
+    EXISTS (
+      SELECT 1 FROM user_roles 
+      WHERE user_id = auth.uid() AND role = 'publisher'
+    )
+  );
+
+CREATE POLICY "Publishers can delete assets" ON storage.objects
+  FOR DELETE TO authenticated
+  USING (
+    bucket_id = 'assets' AND
+    EXISTS (
+      SELECT 1 FROM user_roles 
+      WHERE user_id = auth.uid() AND role = 'publisher'
+    )
+  );
diff --git a/tsconfig.json b/tsconfig.json
index 1d95800..39ba0d3 100644
--- a/tsconfig.json
+++ b/tsconfig.json
@@ -11,7 +11,9 @@
     ],
     "skipLibCheck": true,
     "types": [
-      "node"
+      "node",
+      "vitest/globals",
+      "@testing-library/jest-dom"
     ],
     "moduleResolution": "bundler",
     "isolatedModules": true,
@@ -20,7 +22,7 @@
     "jsx": "react-jsx",
     "paths": {
       "@/*": [
-        "./*"
+        "./src/*"
       ]
     },
     "allowImportingTsExtensions": true,
diff --git a/vite.config.ts b/vite.config.ts
index 99fa992..a5b9874 100644
--- a/vite.config.ts
+++ b/vite.config.ts
@@ -12,7 +12,7 @@ export default defineConfig(() => {
 
       resolve: {
         alias: {
-          '@': path.resolve(__dirname, '.'),
+          '@': path.resolve(__dirname, './src'),
         }
       }
     };
diff --git a/vitest.config.ts b/vitest.config.ts
new file mode 100644
index 0000000..4743b6f
--- /dev/null
+++ b/vitest.config.ts
@@ -0,0 +1,18 @@
+import { defineConfig } from 'vitest/config';
+import react from '@vitejs/plugin-react';
+import path from 'path';
+
+export default defineConfig({
+  plugins: [react()],
+  test: {
+    globals: true,
+    environment: 'jsdom',
+    setupFiles: './src/tests/setup.ts',
+    css: true,
+  },
+  resolve: {
+    alias: {
+      '@': path.resolve(__dirname, './src'),
+    }
+  }
+});