Why We Exist
+We believe technology should empower, not complicate...
++ "This tool helped me become the designer I wanted to be." ++``` + +--- + +## 3. Trust Building System + +### Trust Signal Categories + +| Category | Elements | Implementation | +|----------|----------|----------------| +| **Security** | SSL, badges, encryption | Visible padlock, security logos on forms | +| **Social Proof** | Reviews, testimonials, logos | Star ratings, customer photos, brand logos | +| **Transparency** | Policies, pricing, contact | Clear links, no hidden fees, real address | +| **Professional** | Design quality, consistency | No broken elements, consistent branding | +| **Authority** | Certifications, awards, media | "As seen in...", industry certifications | + +### Trust Signal Placement + +``` +┌────────────────────────────────────────────────────┐ +│ HEADER: Trust banner ("Free shipping | 30-day │ +│ returns | Secure checkout") │ +├────────────────────────────────────────────────────┤ +│ HERO: Social proof ("Trusted by 10,000+") │ +├────────────────────────────────────────────────────┤ +│ PRODUCT: Reviews visible, security badges │ +├────────────────────────────────────────────────────┤ +│ CHECKOUT: Payment icons, SSL badge, guarantee │ +├────────────────────────────────────────────────────┤ +│ FOOTER: Contact info, policies, certifications │ +└────────────────────────────────────────────────────┘ +``` + +### Trust-Building CSS Patterns + +```css +/* Trust badge styling */ +.trust-badge { + display: flex; + align-items: center; + gap: 8px; + padding: 12px 16px; + background: #F0FDF4; /* Light green = security */ + border-radius: 2px; /* Sharp for trust = precision feel */ + font-size: 14px; + color: #166534; +} + +/* Secure form indicator */ +.secure-form::before { + content: '🔒 Secure form'; + display: block; + font-size: 12px; + color: #166534; + margin-bottom: 8px; +} + +/* Testimonial card */ +.testimonial { + display: flex; + gap: 16px; + padding: 24px; + background: white; + border-radius: 16px; /* Friendly = larger radius */ + box-shadow: var(--shadow-sm); +} + +.testimonial-avatar { + width: 48px; + height: 48px; + border-radius: 50%; /* Real photos > initials */ +} +``` + +--- + +## 4. Cognitive Load Management + +### Three Types of Cognitive Load + +| Type | Definition | Designer's Role | +|------|------------|-----------------| +| **Intrinsic** | Inherent complexity of task | Break into smaller steps | +| **Extraneous** | Load from poor design | Eliminate this! | +| **Germane** | Effort for learning | Support and encourage | + +### Reduction Strategies + +**1. Simplify (Reduce Extraneous)** +```css +/* Visual noise → Clean */ +.card-busy { + border: 2px solid red; + background: linear-gradient(...); + box-shadow: 0 0 20px ...; + /* Too much! */ +} + +.card-clean { + background: white; + border-radius: 16px; + box-shadow: 0 10px 30px -10px rgba(0,0,0,0.1); + /* Calm, focused */ +} +``` + +**2. Chunk Information** +```html + + + + + +``` + +**3. Progressive Disclosure** +```html + +
+
+```
+
+**4. Use Familiar Patterns**
+```
+✅ Standard navigation placement
+✅ Expected icon meanings (🔍 = search)
+✅ Conventional form layouts
+✅ Common gesture patterns (swipe, pinch)
+```
+
+**5. Offload Information**
+```html
+
+
+
+
+
+
+
+
+
+
+
+
+
+```
+
+---
+
+## 5. Persuasive Design (Ethical)
+
+### Ethical Persuasion Techniques
+
+| Technique | Ethical Use | Dark Pattern (Avoid) |
+|-----------|-------------|----------------------|
+| **Scarcity** | Real stock levels | Fake countdown timers |
+| **Social Proof** | Genuine reviews | Fake testimonials |
+| **Authority** | Real credentials | Misleading badges |
+| **Urgency** | Real deadlines | Manufactured FOMO |
+| **Commitment** | Progress saving | Guilt-tripping |
+
+### Nudge Patterns
+
+**Smart Defaults:**
+```html
+
+
+
+ Annual (Save 20%)
+```
+
+**Anchoring:**
+```html
+
+Shipping to: John Doe, 123 Main St...
+ Edit +
+ $99
+ $79
+ Save 20%
+
+```
+
+**Social Proof:**
+```html
+
+
+ 👤
+ Sarah from NYC just purchased
+
+
+
+Join 50,000+ designers who use our tool
+``` + +**Progress & Commitment:** +```html + +
+
+ 60% complete - almost there!
+
+```
+
+---
+
+## 6. User Persona Quick Reference
+
+### Gen Z (Born 1997-2012)
+
+```
+CHARACTERISTICS:
+- Digital natives, mobile-first
+- Value authenticity, diversity
+- Short attention spans
+- Visual learners
+
+DESIGN APPROACH:
+├── Colors: Vibrant, hypercolor, bold gradients
+├── Typography: Large, variable, experimental
+├── Layout: Vertical scroll, mobile-native
+├── Interactions: Fast, gamified, gesture-based
+├── Content: Short-form video, memes, stories
+└── Trust: Peer reviews > authority
+```
+
+### Millennials (Born 1981-1996)
+
+```
+CHARACTERISTICS:
+- Value experiences over things
+- Research before buying
+- Socially conscious
+- Price-sensitive but quality-aware
+
+DESIGN APPROACH:
+├── Colors: Muted pastels, earth tones
+├── Typography: Clean, readable sans-serif
+├── Layout: Responsive, card-based
+├── Interactions: Smooth, purposeful animations
+├── Content: Value-driven, transparent
+└── Trust: Reviews, sustainability, values
+```
+
+### Gen X (Born 1965-1980)
+
+```
+CHARACTERISTICS:
+- Independent, self-reliant
+- Value efficiency
+- Skeptical of marketing
+- Balanced tech comfort
+
+DESIGN APPROACH:
+├── Colors: Professional, trustworthy
+├── Typography: Familiar, conservative
+├── Layout: Clear hierarchy, traditional
+├── Interactions: Functional, not flashy
+├── Content: Direct, fact-based
+└── Trust: Expertise, track record
+```
+
+### Baby Boomers (Born 1946-1964)
+
+```
+CHARACTERISTICS:
+- Detail-oriented
+- Loyal when trusted
+- Value personal service
+- Less tech-confident
+
+DESIGN APPROACH:
+├── Colors: High contrast, simple palette
+├── Typography: Large (18px+), high contrast
+├── Layout: Simple, linear, spacious
+├── Interactions: Minimal, clear feedback
+├── Content: Comprehensive, detailed
+└── Trust: Phone numbers, real people
+```
+
+---
+
+## 7. Emotion Color Mapping
+
+```
+┌────────────────────────────────────────────────────┐
+│ EMOTION │ COLORS │ USE │
+├───────────────────┼───────────────────┼────────────┤
+│ Trust │ Blue, Green │ Finance │
+│ Excitement │ Red, Orange │ Sales │
+│ Calm │ Blue, Soft green │ Wellness │
+│ Luxury │ Black, Gold │ Premium │
+│ Creativity │ Teal, Pink │ Art │
+│ Energy │ Yellow, Orange │ Sports │
+│ Nature │ Green, Brown │ Eco │
+│ Happiness │ Yellow, Orange │ Kids │
+│ Sophistication │ Gray, Navy │ Corporate │
+│ Urgency │ Red │ Errors │
+└───────────────────┴───────────────────┴────────────┘
+```
+
+---
+
+## 8. Psychology Checklist
+
+### Before Launch
+
+- [ ] **Hick's Law:** No more than 7 choices in navigation. Have choices been narrowed to reduce decision fatigue?
+- [ ] **Fitts' Law:** Primary CTAs are large and reachable. Are the most important buttons easy to hit on mobile?
+- [ ] **Miller's Law:** Content is chunked appropriately. Is information grouped into digestible units of 5-7?
+- [ ] **Jakob's Law:** Does the site follow standard web conventions that users already understand?
+- [ ] **Doherty Threshold:** Does the system provide feedback within 400ms? Are skeleton screens in place?
+- [ ] **Tesler's Law:** Has complexity been moved from the user to the system where possible?
+- [ ] **Parkinson’s Law:** Are there features like "One-Click Checkout" to minimize task completion time?
+- [ ] **Von Restorff:** Does the primary CTA visually stand out from all other elements?
+- [ ] **Serial Position:** Is the most critical information at the very beginning or end of lists?
+- [ ] **Gestalt Laws:** Are related items physically grouped together (Proximity) or within a Card (Common Region)?
+- [ ] **Zeigarnik Effect:** Are there visual indicators (like progress bars) for incomplete tasks?
+- [ ] **Goal Gradient:** Is the user given a "head start" (e.g., 20% progress) to encourage completion?
+- [ ] **Peak-End Rule:** Does the final "Success" screen create a moment of delight?
+- [ ] **Occam’s Razor:** Have unnecessary visual or functional elements been removed?
+- [ ] **Aesthetic-Usability:** Is the UI high-fidelity enough to build initial user trust?
+- [ ] **Trust & Authority:** Are security badges, reviews, and expert certifications visible?
+- [ ] **Social Proof:** Are real user numbers or testimonials visible at decision points?
+- [ ] **Scarcity & Urgency:** If used, is the scarcity real and ethical (e.g., actual low stock)?
+- [ ] **Loss Aversion:** Does the copy emphasize what the user stands to keep rather than just gain?
+- [ ] **Anchoring:** Is the pricing presented in a way that frames the desired choice as a great value?
+- [ ] **Postel’s Law:** Is the system flexible enough to accept various input formats without errors?
+- [ ] **False-Consensus:** Has the design been tested with real users rather than just the internal team?
+- [ ] **Curse of Knowledge:** Is the copy free of technical jargon and easy for a beginner to understand?
+- [ ] **Stepping Stone:** Does the funnel start with low-friction tasks (e.g., email only)?
+- [ ] **Cognitive Load:** Is extraneous visual noise minimized to keep the interface clean?
+- [ ] **Emotional Design:** Does the color palette and imagery evoke the intended visceral reaction?
+- [ ] **Feedback:** Do all interactive elements have immediate hover, active, and success states?
+- [ ] **Accessibility:** Is the contrast ratio sufficient, and is the site navigable via keyboard/screen reader?
+- [ ] **Prägnanz:** Are icons and shapes simple enough to be recognized at a glance?
+- [ ] **Figure/Ground:** Is it clear which element is in focus (e.g., using shadows or scrims for modals)?
diff --git a/.agent/skills/frontend-design/visual-effects.md b/.agent/skills/frontend-design/visual-effects.md
new file mode 100644
index 0000000..47f8ec8
--- /dev/null
+++ b/.agent/skills/frontend-design/visual-effects.md
@@ -0,0 +1,383 @@
+# Visual Effects Reference
+
+> Modern CSS effect principles and techniques - learn the concepts, create variations.
+> **No fixed values to copy - understand the patterns.**
+
+---
+
+## 1. Glassmorphism Principles
+
+### What Makes Glassmorphism Work
+
+```
+Key Properties:
+├── Semi-transparent background (not solid)
+├── Backdrop blur (frosted glass effect)
+├── Subtle border (for definition)
+└── Often: light shadow for depth
+```
+
+### The Pattern (Customize Values)
+
+```css
+.glass {
+ /* Transparency: adjust opacity based on content readability */
+ background: rgba(R, G, B, OPACITY);
+ /* OPACITY: 0.1-0.3 for dark bg, 0.5-0.8 for light bg */
+
+ /* Blur: higher = more frosted */
+ backdrop-filter: blur(AMOUNT);
+ /* AMOUNT: 8-12px subtle, 16-24px strong */
+
+ /* Border: defines edges */
+ border: 1px solid rgba(255, 255, 255, OPACITY);
+ /* OPACITY: 0.1-0.3 typically */
+
+ /* Radius: match your design system */
+ border-radius: YOUR_RADIUS;
+}
+```
+
+### When to Use Glassmorphism
+- ✅ Over colorful/image backgrounds
+- ✅ Modals, overlays, cards
+- ✅ Navigation bars with scrolling content behind
+- ❌ Text-heavy content (readability issues)
+- ❌ Simple solid backgrounds (pointless)
+
+### When NOT to Use
+- Low contrast situations
+- Accessibility-critical content
+- Performance-constrained devices
+
+---
+
+## 2. Neomorphism Principles
+
+### What Makes Neomorphism Work
+
+```
+Key Concept: Soft, extruded elements using DUAL shadows
+├── Light shadow (from light source direction)
+├── Dark shadow (opposite direction)
+└── Background matches surrounding (same color)
+```
+
+### The Pattern
+
+```css
+.neo-raised {
+ /* Background MUST match parent */
+ background: SAME_AS_PARENT;
+
+ /* Two shadows: light direction + dark direction */
+ box-shadow:
+ OFFSET OFFSET BLUR rgba(light-color),
+ -OFFSET -OFFSET BLUR rgba(dark-color);
+
+ /* OFFSET: typically 6-12px */
+ /* BLUR: typically 12-20px */
+}
+
+.neo-pressed {
+ /* Inset creates "pushed in" effect */
+ box-shadow:
+ inset OFFSET OFFSET BLUR rgba(dark-color),
+ inset -OFFSET -OFFSET BLUR rgba(light-color);
+}
+```
+
+### Accessibility Warning
+⚠️ **Low contrast** - use sparingly, ensure clear boundaries
+
+### When to Use
+- Decorative elements
+- Subtle interactive states
+- Minimalist UI with flat colors
+
+---
+
+## 3. Shadow Hierarchy Principles
+
+### Concept: Shadows Indicate Elevation
+
+```
+Higher elevation = larger shadow
+├── Level 0: No shadow (flat on surface)
+├── Level 1: Subtle shadow (slightly raised)
+├── Level 2: Medium shadow (cards, buttons)
+├── Level 3: Large shadow (modals, dropdowns)
+└── Level 4: Deep shadow (floating elements)
+```
+
+### Shadow Properties to Adjust
+
+```css
+box-shadow: OFFSET-X OFFSET-Y BLUR SPREAD COLOR;
+
+/* Offset: direction of shadow */
+/* Blur: softness (larger = softer) */
+/* Spread: size expansion */
+/* Color: typically black with low opacity */
+```
+
+### Principles for Natural Shadows
+
+1. **Y-offset larger than X** (light comes from above)
+2. **Low opacity** (5-15% for subtle, 15-25% for pronounced)
+3. **Multiple layers** for realism (ambient + direct)
+4. **Blur scales with offset** (larger offset = larger blur)
+
+### Dark Mode Shadows
+- Shadows less visible on dark backgrounds
+- May need to increase opacity
+- Or use glow/highlight instead
+
+---
+
+## 4. Gradient Principles
+
+### Types and When to Use
+
+| Type | Pattern | Use Case |
+|------|---------|----------|
+| **Linear** | Color A → Color B along line | Backgrounds, buttons, headers |
+| **Radial** | Center → outward | Spotlights, focal points |
+| **Conic** | Around center | Pie charts, creative effects |
+
+### Creating Harmonious Gradients
+
+```
+Good Gradient Rules:
+├── Use ADJACENT colors on wheel (analogous)
+├── Or same hue with different lightness
+├── Avoid complementary (can look harsh)
+└── Add middle stops for smoother transitions
+```
+
+### Gradient Syntax Pattern
+
+```css
+.gradient {
+ background: linear-gradient(
+ DIRECTION, /* angle or to-keyword */
+ COLOR-STOP-1, /* color + optional position */
+ COLOR-STOP-2,
+ /* ... more stops */
+ );
+}
+
+/* DIRECTION examples: */
+/* 90deg, 135deg, to right, to bottom right */
+```
+
+### Mesh Gradients
+
+```
+Multiple radial gradients overlapped:
+├── Each at different position
+├── Each with transparent falloff
+├── **Mandatory for "Wow" factor in Hero sections**
+└── Creates organic, colorful effect (Search: "Aurora Gradient CSS")
+```
+
+---
+
+## 5. Border Effects Principles
+
+### Gradient Borders
+
+```
+Technique: Pseudo-element with gradient background
+├── Element has padding = border width
+├── Pseudo-element fills with gradient
+└── Mask or clip creates border effect
+```
+
+### Animated Borders
+
+```
+Technique: Rotating gradient or conic sweep
+├── Pseudo-element larger than content
+├── Animation rotates the gradient
+└── Overflow hidden clips to shape
+```
+
+### Glow Borders
+
+```css
+/* Multiple box-shadows create glow */
+box-shadow:
+ 0 0 SMALL-BLUR COLOR,
+ 0 0 MEDIUM-BLUR COLOR,
+ 0 0 LARGE-BLUR COLOR;
+
+/* Each layer adds to the glow */
+```
+
+---
+
+## 6. Glow Effects Principles
+
+### Text Glow
+
+```css
+text-shadow:
+ 0 0 BLUR-1 COLOR,
+ 0 0 BLUR-2 COLOR,
+ 0 0 BLUR-3 COLOR;
+
+/* Multiple layers = stronger glow */
+/* Larger blur = softer spread */
+```
+
+### Element Glow
+
+```css
+box-shadow:
+ 0 0 BLUR-1 COLOR,
+ 0 0 BLUR-2 COLOR;
+
+/* Use color matching element for realistic glow */
+/* Lower opacity for subtle, higher for neon */
+```
+
+### Pulsing Glow Animation
+
+```css
+@keyframes glow-pulse {
+ 0%, 100% { box-shadow: 0 0 SMALL-BLUR COLOR; }
+ 50% { box-shadow: 0 0 LARGE-BLUR COLOR; }
+}
+
+/* Easing and duration affect feel */
+```
+
+---
+
+## 7. Overlay Techniques
+
+### Gradient Overlay on Images
+
+```
+Purpose: Improve text readability over images
+Pattern: Gradient from transparent to opaque
+Position: Where text will appear
+```
+
+```css
+.overlay::after {
+ content: '';
+ position: absolute;
+ inset: 0;
+ background: linear-gradient(
+ DIRECTION,
+ transparent PERCENTAGE,
+ rgba(0,0,0,OPACITY) 100%
+ );
+}
+```
+
+### Colored Overlay
+
+```css
+/* Blend mode or layered gradient */
+background:
+ linear-gradient(YOUR-COLOR-WITH-OPACITY),
+ url('image.jpg');
+```
+
+---
+
+## 8. Modern CSS Techniques
+
+### Container Queries (Concept)
+
+```
+Instead of viewport breakpoints:
+├── Component responds to ITS container
+├── Truly modular, reusable components
+└── Syntax: @container (condition) { }
+```
+
+### :has() Selector (Concept)
+
+```
+Parent styling based on children:
+├── "Parent that has X child"
+├── Enables previously impossible patterns
+└── Progressive enhancement approach
+```
+
+### Scroll-Driven Animations (Concept)
+
+```
+Animation progress tied to scroll:
+├── Entry/exit animations on scroll
+├── Parallax effects
+├── Progress indicators
+└── View-based or scroll-based timeline
+```
+
+---
+
+## 9. Performance Principles
+
+### GPU-Accelerated Properties
+
+```
+CHEAP to animate (GPU):
+├── transform (translate, scale, rotate)
+└── opacity
+
+EXPENSIVE to animate (CPU):
+├── width, height
+├── top, left, right, bottom
+├── margin, padding
+└── box-shadow (recalculates)
+```
+
+### will-change Usage
+
+```css
+/* Use sparingly, only for heavy animations */
+.heavy-animation {
+ will-change: transform;
+}
+
+/* Remove after animation if possible */
+```
+
+### Reduced Motion
+
+```css
+@media (prefers-reduced-motion: reduce) {
+ /* Disable or minimize animations */
+ /* Respect user preference */
+}
+```
+
+---
+
+## 10. Effect Selection Checklist
+
+Before applying any effect:
+
+- [ ] **Does it serve a purpose?** (not just decoration)
+- [ ] **Is it appropriate for the context?** (brand, audience)
+- [ ] **Have you varied from previous projects?** (avoid repetition)
+- [ ] **Is it accessible?** (contrast, motion sensitivity)
+- [ ] **Is it performant?** (especially on mobile)
+- [ ] **Did you ask user preference?** (if style open-ended)
+
+### Anti-Patterns
+
+- ❌ Glassmorphism on every element (kitsch)
+- ❌ Dark + neon as default (lazy AI look)
+- ❌ **Static/Flat designs with no depth (FAILED)**
+- ❌ Effects that hurt readability
+- ❌ Animations without purpose
+
+---
+
+> **Remember**: Effects enhance meaning. Choose based on purpose and context, not because it "looks cool."
diff --git a/.agent/skills/game-development/2d-games/SKILL.md b/.agent/skills/game-development/2d-games/SKILL.md
new file mode 100644
index 0000000..a3f8d24
--- /dev/null
+++ b/.agent/skills/game-development/2d-games/SKILL.md
@@ -0,0 +1,119 @@
+---
+name: 2d-games
+description: 2D game development principles. Sprites, tilemaps, physics, camera.
+allowed-tools: Read, Write, Edit, Glob, Grep
+---
+
+# 2D Game Development
+
+> Principles for 2D game systems.
+
+---
+
+## 1. Sprite Systems
+
+### Sprite Organization
+
+| Component | Purpose |
+|-----------|---------|
+| **Atlas** | Combine textures, reduce draw calls |
+| **Animation** | Frame sequences |
+| **Pivot** | Rotation/scale origin |
+| **Layering** | Z-order control |
+
+### Animation Principles
+
+- Frame rate: 8-24 FPS typical
+- Squash and stretch for impact
+- Anticipation before action
+- Follow-through after action
+
+---
+
+## 2. Tilemap Design
+
+### Tile Considerations
+
+| Factor | Recommendation |
+|--------|----------------|
+| **Size** | 16x16, 32x32, 64x64 |
+| **Auto-tiling** | Use for terrain |
+| **Collision** | Simplified shapes |
+
+### Layers
+
+| Layer | Content |
+|-------|---------|
+| Background | Non-interactive scenery |
+| Terrain | Walkable ground |
+| Props | Interactive objects |
+| Foreground | Parallax overlay |
+
+---
+
+## 3. 2D Physics
+
+### Collision Shapes
+
+| Shape | Use Case |
+|-------|----------|
+| Box | Rectangular objects |
+| Circle | Balls, rounded |
+| Capsule | Characters |
+| Polygon | Complex shapes |
+
+### Physics Considerations
+
+- Pixel-perfect vs physics-based
+- Fixed timestep for consistency
+- Layers for filtering
+
+---
+
+## 4. Camera Systems
+
+### Camera Types
+
+| Type | Use |
+|------|-----|
+| **Follow** | Track player |
+| **Look-ahead** | Anticipate movement |
+| **Multi-target** | Two-player |
+| **Room-based** | Metroidvania |
+
+### Screen Shake
+
+- Short duration (50-200ms)
+- Diminishing intensity
+- Use sparingly
+
+---
+
+## 5. Genre Patterns
+
+### Platformer
+
+- Coyote time (leniency after edge)
+- Jump buffering
+- Variable jump height
+
+### Top-down
+
+- 8-directional or free movement
+- Aim-based or auto-aim
+- Consider rotation or not
+
+---
+
+## 6. Anti-Patterns
+
+| ❌ Don't | ✅ Do |
+|----------|-------|
+| Separate textures | Use atlases |
+| Complex collision shapes | Simplified collision |
+| Jittery camera | Smooth following |
+| Pixel-perfect on physics | Choose one approach |
+
+---
+
+> **Remember:** 2D is about clarity. Every pixel should communicate.
diff --git a/.agent/skills/game-development/3d-games/SKILL.md b/.agent/skills/game-development/3d-games/SKILL.md
new file mode 100644
index 0000000..6f48930
--- /dev/null
+++ b/.agent/skills/game-development/3d-games/SKILL.md
@@ -0,0 +1,135 @@
+---
+name: 3d-games
+description: 3D game development principles. Rendering, shaders, physics, cameras.
+allowed-tools: Read, Write, Edit, Glob, Grep
+---
+
+# 3D Game Development
+
+> Principles for 3D game systems.
+
+---
+
+## 1. Rendering Pipeline
+
+### Stages
+
+```
+1. Vertex Processing → Transform geometry
+2. Rasterization → Convert to pixels
+3. Fragment Processing → Color pixels
+4. Output → To screen
+```
+
+### Optimization Principles
+
+| Technique | Purpose |
+|-----------|---------|
+| **Frustum culling** | Don't render off-screen |
+| **Occlusion culling** | Don't render hidden |
+| **LOD** | Less detail at distance |
+| **Batching** | Combine draw calls |
+
+---
+
+## 2. Shader Principles
+
+### Shader Types
+
+| Type | Purpose |
+|------|---------|
+| **Vertex** | Position, normals |
+| **Fragment/Pixel** | Color, lighting |
+| **Compute** | General computation |
+
+### When to Write Custom Shaders
+
+- Special effects (water, fire, portals)
+- Stylized rendering (toon, sketch)
+- Performance optimization
+- Unique visual identity
+
+---
+
+## 3. 3D Physics
+
+### Collision Shapes
+
+| Shape | Use Case |
+|-------|----------|
+| **Box** | Buildings, crates |
+| **Sphere** | Balls, quick checks |
+| **Capsule** | Characters |
+| **Mesh** | Terrain (expensive) |
+
+### Principles
+
+- Simple colliders, complex visuals
+- Layer-based filtering
+- Raycasting for line-of-sight
+
+---
+
+## 4. Camera Systems
+
+### Camera Types
+
+| Type | Use |
+|------|-----|
+| **Third-person** | Action, adventure |
+| **First-person** | Immersive, FPS |
+| **Isometric** | Strategy, RPG |
+| **Orbital** | Inspection, editors |
+
+### Camera Feel
+
+- Smooth following (lerp)
+- Collision avoidance
+- Look-ahead for movement
+- FOV changes for speed
+
+---
+
+## 5. Lighting
+
+### Light Types
+
+| Type | Use |
+|------|-----|
+| **Directional** | Sun, moon |
+| **Point** | Lamps, torches |
+| **Spot** | Flashlight, stage |
+| **Ambient** | Base illumination |
+
+### Performance Consideration
+
+- Real-time shadows are expensive
+- Bake when possible
+- Shadow cascades for large worlds
+
+---
+
+## 6. Level of Detail (LOD)
+
+### LOD Strategy
+
+| Distance | Model |
+|----------|-------|
+| Near | Full detail |
+| Medium | 50% triangles |
+| Far | 25% or billboard |
+
+---
+
+## 7. Anti-Patterns
+
+| ❌ Don't | ✅ Do |
+|----------|-------|
+| Mesh colliders everywhere | Simple shapes |
+| Real-time shadows on mobile | Baked or blob shadows |
+| One LOD for all distances | Distance-based LOD |
+| Unoptimized shaders | Profile and simplify |
+
+---
+
+> **Remember:** 3D is about illusion. Create the impression of detail, not the detail itself.
diff --git a/.agent/skills/game-development/SKILL.md b/.agent/skills/game-development/SKILL.md
new file mode 100644
index 0000000..2088633
--- /dev/null
+++ b/.agent/skills/game-development/SKILL.md
@@ -0,0 +1,167 @@
+---
+name: game-development
+description: Game development orchestrator. Routes to platform-specific skills based on project needs.
+allowed-tools: Read, Write, Edit, Glob, Grep, Bash
+---
+
+# Game Development
+
+> **Orchestrator skill** that provides core principles and routes to specialized sub-skills.
+
+---
+
+## When to Use This Skill
+
+You are working on a game development project. This skill teaches the PRINCIPLES of game development and directs you to the right sub-skill based on context.
+
+---
+
+## Sub-Skill Routing
+
+### Platform Selection
+
+| If the game targets... | Use Sub-Skill |
+|------------------------|---------------|
+| Web browsers (HTML5, WebGL) | `game-development/web-games` |
+| Mobile (iOS, Android) | `game-development/mobile-games` |
+| PC (Steam, Desktop) | `game-development/pc-games` |
+| VR/AR headsets | `game-development/vr-ar` |
+
+### Dimension Selection
+
+| If the game is... | Use Sub-Skill |
+|-------------------|---------------|
+| 2D (sprites, tilemaps) | `game-development/2d-games` |
+| 3D (meshes, shaders) | `game-development/3d-games` |
+
+### Specialty Areas
+
+| If you need... | Use Sub-Skill |
+|----------------|---------------|
+| GDD, balancing, player psychology | `game-development/game-design` |
+| Multiplayer, networking | `game-development/multiplayer` |
+| Visual style, asset pipeline, animation | `game-development/game-art` |
+| Sound design, music, adaptive audio | `game-development/game-audio` |
+
+---
+
+## Core Principles (All Platforms)
+
+### 1. The Game Loop
+
+Every game, regardless of platform, follows this pattern:
+
+```
+INPUT → Read player actions
+UPDATE → Process game logic (fixed timestep)
+RENDER → Draw the frame (interpolated)
+```
+
+**Fixed Timestep Rule:**
+- Physics/logic: Fixed rate (e.g., 50Hz)
+- Rendering: As fast as possible
+- Interpolate between states for smooth visuals
+
+---
+
+### 2. Pattern Selection Matrix
+
+| Pattern | Use When | Example |
+|---------|----------|---------|
+| **State Machine** | 3-5 discrete states | Player: Idle→Walk→Jump |
+| **Object Pooling** | Frequent spawn/destroy | Bullets, particles |
+| **Observer/Events** | Cross-system communication | Health→UI updates |
+| **ECS** | Thousands of similar entities | RTS units, particles |
+| **Command** | Undo, replay, networking | Input recording |
+| **Behavior Tree** | Complex AI decisions | Enemy AI |
+
+**Decision Rule:** Start with State Machine. Add ECS only when performance demands.
+
+---
+
+### 3. Input Abstraction
+
+Abstract input into ACTIONS, not raw keys:
+
+```
+"jump" → Space, Gamepad A, Touch tap
+"move" → WASD, Left stick, Virtual joystick
+```
+
+**Why:** Enables multi-platform, rebindable controls.
+
+---
+
+### 4. Performance Budget (60 FPS = 16.67ms)
+
+| System | Budget |
+|--------|--------|
+| Input | 1ms |
+| Physics | 3ms |
+| AI | 2ms |
+| Game Logic | 4ms |
+| Rendering | 5ms |
+| Buffer | 1.67ms |
+
+**Optimization Priority:**
+1. Algorithm (O(n²) → O(n log n))
+2. Batching (reduce draw calls)
+3. Pooling (avoid GC spikes)
+4. LOD (detail by distance)
+5. Culling (skip invisible)
+
+---
+
+### 5. AI Selection by Complexity
+
+| AI Type | Complexity | Use When |
+|---------|------------|----------|
+| **FSM** | Simple | 3-5 states, predictable behavior |
+| **Behavior Tree** | Medium | Modular, designer-friendly |
+| **GOAP** | High | Emergent, planning-based |
+| **Utility AI** | High | Scoring-based decisions |
+
+---
+
+### 6. Collision Strategy
+
+| Type | Best For |
+|------|----------|
+| **AABB** | Rectangles, fast checks |
+| **Circle** | Round objects, cheap |
+| **Spatial Hash** | Many similar-sized objects |
+| **Quadtree** | Large worlds, varying sizes |
+
+---
+
+## Anti-Patterns (Universal)
+
+| Don't | Do |
+|-------|-----|
+| Update everything every frame | Use events, dirty flags |
+| Create objects in hot loops | Object pooling |
+| Cache nothing | Cache references |
+| Optimize without profiling | Profile first |
+| Mix input with logic | Abstract input layer |
+
+---
+
+## Routing Examples
+
+### Example 1: "I want to make a browser-based 2D platformer"
+→ Start with `game-development/web-games` for framework selection
+→ Then `game-development/2d-games` for sprite/tilemap patterns
+→ Reference `game-development/game-design` for level design
+
+### Example 2: "Mobile puzzle game for iOS and Android"
+→ Start with `game-development/mobile-games` for touch input and stores
+→ Use `game-development/game-design` for puzzle balancing
+
+### Example 3: "Multiplayer VR shooter"
+→ `game-development/vr-ar` for comfort and immersion
+→ `game-development/3d-games` for rendering
+→ `game-development/multiplayer` for networking
+
+---
+
+> **Remember:** Great games come from iteration, not perfection. Prototype fast, then polish.
diff --git a/.agent/skills/game-development/game-art/SKILL.md b/.agent/skills/game-development/game-art/SKILL.md
new file mode 100644
index 0000000..87a6ab3
--- /dev/null
+++ b/.agent/skills/game-development/game-art/SKILL.md
@@ -0,0 +1,185 @@
+---
+name: game-art
+description: Game art principles. Visual style selection, asset pipeline, animation workflow.
+allowed-tools: Read, Glob, Grep
+---
+
+# Game Art Principles
+
+> Visual design thinking for games - style selection, asset pipelines, and art direction.
+
+---
+
+## 1. Art Style Selection
+
+### Decision Tree
+
+```
+What feeling should the game evoke?
+│
+├── Nostalgic / Retro
+│ ├── Limited palette? → Pixel Art
+│ └── Hand-drawn feel? → Vector / Flash style
+│
+├── Realistic / Immersive
+│ ├── High budget? → PBR 3D
+│ └── Stylized realism? → Hand-painted textures
+│
+├── Approachable / Casual
+│ ├── Clean shapes? → Flat / Minimalist
+│ └── Soft feel? → Gradient / Soft shadows
+│
+└── Unique / Experimental
+ └── Define custom style guide
+```
+
+### Style Comparison Matrix
+
+| Style | Production Speed | Skill Floor | Scalability | Best For |
+|-------|------------------|-------------|-------------|----------|
+| **Pixel Art** | Medium | Medium | Hard to hire | Indie, retro |
+| **Vector/Flat** | Fast | Low | Easy | Mobile, casual |
+| **Hand-painted** | Slow | High | Medium | Fantasy, stylized |
+| **PBR 3D** | Slow | High | AAA pipeline | Realistic games |
+| **Low-poly** | Fast | Medium | Easy | Indie 3D |
+| **Cel-shaded** | Medium | Medium | Medium | Anime, cartoon |
+
+---
+
+## 2. Asset Pipeline Decisions
+
+### 2D Pipeline
+
+| Phase | Tool Options | Output |
+|-------|--------------|--------|
+| **Concept** | Paper, Procreate, Photoshop | Reference sheet |
+| **Creation** | Aseprite, Photoshop, Krita | Individual sprites |
+| **Atlas** | TexturePacker, Aseprite | Spritesheet |
+| **Animation** | Spine, DragonBones, Frame-by-frame | Animation data |
+| **Integration** | Engine import | Game-ready assets |
+
+### 3D Pipeline
+
+| Phase | Tool Options | Output |
+|-------|--------------|--------|
+| **Concept** | 2D art, Blockout | Reference |
+| **Modeling** | Blender, Maya, 3ds Max | High-poly mesh |
+| **Retopology** | Blender, ZBrush | Game-ready mesh |
+| **UV/Texturing** | Substance Painter, Blender | Texture maps |
+| **Rigging** | Blender, Maya | Skeletal rig |
+| **Animation** | Blender, Maya, Mixamo | Animation clips |
+| **Export** | FBX, glTF | Engine-ready |
+
+---
+
+## 3. Color Theory Decisions
+
+### Palette Selection
+
+| Goal | Strategy | Example |
+|------|----------|---------|
+| **Harmony** | Complementary or analogous | Nature games |
+| **Contrast** | High saturation differences | Action games |
+| **Mood** | Warm/cool temperature | Horror, cozy |
+| **Readability** | Value contrast over hue | Gameplay clarity |
+
+### Color Principles
+
+- **Hierarchy:** Important elements should pop
+- **Consistency:** Same object = same color family
+- **Context:** Colors read differently on backgrounds
+- **Accessibility:** Don't rely only on color
+
+---
+
+## 4. Animation Principles
+
+### The 12 Principles (Applied to Games)
+
+| Principle | Game Application |
+|-----------|------------------|
+| **Squash & Stretch** | Jump arcs, impacts |
+| **Anticipation** | Wind-up before attack |
+| **Staging** | Clear silhouettes |
+| **Follow-through** | Hair, capes after movement |
+| **Slow in/out** | Easing on transitions |
+| **Arcs** | Natural movement paths |
+| **Secondary Action** | Breathing, blinking |
+| **Timing** | Frame count = weight/speed |
+| **Exaggeration** | Readable from distance |
+| **Appeal** | Memorable design |
+
+### Frame Count Guidelines
+
+| Action Type | Typical Frames | Feel |
+|-------------|----------------|------|
+| Idle breathing | 4-8 | Subtle |
+| Walk cycle | 6-12 | Smooth |
+| Run cycle | 4-8 | Energetic |
+| Attack | 3-6 | Snappy |
+| Death | 8-16 | Dramatic |
+
+---
+
+## 5. Resolution & Scale Decisions
+
+### 2D Resolution by Platform
+
+| Platform | Base Resolution | Sprite Scale |
+|----------|-----------------|--------------|
+| Mobile | 1080p | 64-128px characters |
+| Desktop | 1080p-4K | 128-256px characters |
+| Pixel art | 320x180 to 640x360 | 16-32px characters |
+
+### Consistency Rule
+
+Choose a base unit and stick to it:
+- Pixel art: Work at 1x, scale up (never down)
+- HD art: Define DPI, maintain ratio
+- 3D: 1 unit = 1 meter (industry standard)
+
+---
+
+## 6. Asset Organization
+
+### Naming Convention
+
+```
+[type]_[object]_[variant]_[state].[ext]
+
+Examples:
+spr_player_idle_01.png
+tex_stone_wall_normal.png
+mesh_tree_oak_lod2.fbx
+```
+
+### Folder Structure Principle
+
+```
+assets/
+├── characters/
+│ ├── player/
+│ └── enemies/
+├── environment/
+│ ├── props/
+│ └── tiles/
+├── ui/
+├── effects/
+└── audio/
+```
+
+---
+
+## 7. Anti-Patterns
+
+| Don't | Do |
+|-------|-----|
+| Mix art styles randomly | Define and follow style guide |
+| Work at final resolution only | Create at source resolution |
+| Ignore silhouette readability | Test at gameplay distance |
+| Over-detail background | Focus detail on player area |
+| Skip color testing | Test on target display |
+
+---
+
+> **Remember:** Art serves gameplay. If it doesn't help the player, it's decoration.
diff --git a/.agent/skills/game-development/game-audio/SKILL.md b/.agent/skills/game-development/game-audio/SKILL.md
new file mode 100644
index 0000000..77ad3c2
--- /dev/null
+++ b/.agent/skills/game-development/game-audio/SKILL.md
@@ -0,0 +1,190 @@
+---
+name: game-audio
+description: Game audio principles. Sound design, music integration, adaptive audio systems.
+allowed-tools: Read, Glob, Grep
+---
+
+# Game Audio Principles
+
+> Sound design and music integration for immersive game experiences.
+
+---
+
+## 1. Audio Category System
+
+### Category Definitions
+
+| Category | Behavior | Examples |
+|----------|----------|----------|
+| **Music** | Looping, crossfade, ducking | BGM, combat music |
+| **SFX** | One-shot, 3D positioned | Footsteps, impacts |
+| **Ambient** | Looping, background layer | Wind, crowd, forest |
+| **UI** | Immediate, non-3D | Button clicks, notifications |
+| **Voice** | Priority, ducking trigger | Dialogue, announcer |
+
+### Priority Hierarchy
+
+```
+When sounds compete for channels:
+
+1. Voice (highest - always audible)
+2. Player SFX (feedback critical)
+3. Enemy SFX (gameplay important)
+4. Music (mood, but duckable)
+5. Ambient (lowest - can drop)
+```
+
+---
+
+## 2. Sound Design Decisions
+
+### SFX Creation Approach
+
+| Approach | When to Use | Trade-offs |
+|----------|-------------|------------|
+| **Recording** | Realistic needs | High quality, time intensive |
+| **Synthesis** | Sci-fi, retro, UI | Unique, requires skill |
+| **Library samples** | Fast production | Common sounds, licensing |
+| **Layering** | Complex sounds | Best results, more work |
+
+### Layering Structure
+
+| Layer | Purpose | Example: Gunshot |
+|-------|---------|------------------|
+| **Attack** | Initial transient | Click, snap |
+| **Body** | Main character | Boom, blast |
+| **Tail** | Decay, room | Reverb, echo |
+| **Sweetener** | Special sauce | Shell casing, mechanical |
+
+---
+
+## 3. Music Integration
+
+### Music State System
+
+```
+Game State → Music Response
+│
+├── Menu → Calm, loopable theme
+├── Exploration → Ambient, atmospheric
+├── Combat detected → Transition to tension
+├── Combat engaged → Full battle music
+├── Victory → Stinger + calm transition
+├── Defeat → Somber stinger
+└── Boss → Unique, multi-phase track
+```
+
+### Transition Techniques
+
+| Technique | Use When | Feel |
+|-----------|----------|------|
+| **Crossfade** | Smooth mood shift | Gradual |
+| **Stinger** | Immediate event | Dramatic |
+| **Stem mixing** | Dynamic intensity | Seamless |
+| **Beat-synced** | Rhythmic gameplay | Musical |
+| **Queue point** | Next natural break | Clean |
+
+---
+
+## 4. Adaptive Audio Decisions
+
+### Intensity Parameters
+
+| Parameter | Affects | Example |
+|-----------|---------|---------|
+| **Threat level** | Music intensity | Enemy count |
+| **Health** | Filter, reverb | Low health = muffled |
+| **Speed** | Tempo, energy | Racing speed |
+| **Environment** | Reverb, EQ | Cave vs outdoor |
+| **Time of day** | Mood, volume | Night = quieter |
+
+### Vertical vs Horizontal
+
+| System | What Changes | Best For |
+|--------|--------------|----------|
+| **Vertical (layers)** | Add/remove instrument layers | Intensity scaling |
+| **Horizontal (segments)** | Different music sections | State changes |
+| **Combined** | Both | AAA adaptive scores |
+
+---
+
+## 5. 3D Audio Decisions
+
+### Spatialization
+
+| Element | 3D Positioned? | Reason |
+|---------|----------------|--------|
+| Player footsteps | No (or subtle) | Always audible |
+| Enemy footsteps | Yes | Directional awareness |
+| Gunfire | Yes | Combat awareness |
+| Music | No | Mood, non-diegetic |
+| Ambient zone | Yes (area) | Environmental |
+| UI sounds | No | Interface feedback |
+
+### Distance Behavior
+
+| Distance | Sound Behavior |
+|----------|----------------|
+| **Near** | Full volume, full frequency |
+| **Medium** | Volume falloff, high-freq rolloff |
+| **Far** | Low volume, low-pass filter |
+| **Max** | Silent or ambient hint |
+
+---
+
+## 6. Platform Considerations
+
+### Format Selection
+
+| Platform | Recommended Format | Reason |
+|----------|-------------------|--------|
+| PC | OGG Vorbis, WAV | Quality, no licensing |
+| Console | Platform-specific | Certification |
+| Mobile | MP3, AAC | Size, compatibility |
+| Web | WebM/Opus, MP3 fallback | Browser support |
+
+### Memory Budget
+
+| Game Type | Audio Budget | Strategy |
+|-----------|--------------|----------|
+| Mobile casual | 10-50 MB | Compressed, fewer variants |
+| PC indie | 100-500 MB | Quality focus |
+| AAA | 1+ GB | Full quality, many variants |
+
+---
+
+## 7. Mix Hierarchy
+
+### Volume Balance Reference
+
+| Category | Relative Level | Notes |
+|----------|----------------|-------|
+| **Voice** | 0 dB (reference) | Always clear |
+| **Player SFX** | -3 to -6 dB | Prominent but not harsh |
+| **Music** | -6 to -12 dB | Foundation, ducks for voice |
+| **Enemy SFX** | -6 to -9 dB | Important but not dominant |
+| **Ambient** | -12 to -18 dB | Subtle background |
+
+### Ducking Rules
+
+| When | Duck What | Amount |
+|------|-----------|--------|
+| Voice plays | Music, Ambient | -6 to -9 dB |
+| Explosion | All except explosion | Brief duck |
+| Menu open | Gameplay audio | -3 to -6 dB |
+
+---
+
+## 8. Anti-Patterns
+
+| Don't | Do |
+|-------|-----|
+| Play same sound repeatedly | Use variations (3-5 per sound) |
+| Max volume everything | Use proper mix hierarchy |
+| Ignore silence | Silence creates contrast |
+| One music track loops forever | Provide variety, transitions |
+| Skip audio in prototype | Placeholder audio matters |
+
+---
+
+> **Remember:** 50% of the game experience is audio. A muted game loses half its soul.
diff --git a/.agent/skills/game-development/game-design/SKILL.md b/.agent/skills/game-development/game-design/SKILL.md
new file mode 100644
index 0000000..4dea97a
--- /dev/null
+++ b/.agent/skills/game-development/game-design/SKILL.md
@@ -0,0 +1,129 @@
+---
+name: game-design
+description: Game design principles. GDD structure, balancing, player psychology, progression.
+allowed-tools: Read, Glob, Grep
+---
+
+# Game Design Principles
+
+> Design thinking for engaging games.
+
+---
+
+## 1. Core Loop Design
+
+### The 30-Second Test
+
+```
+Every game needs a fun 30-second loop:
+1. ACTION → Player does something
+2. FEEDBACK → Game responds
+3. REWARD → Player feels good
+4. REPEAT
+```
+
+### Loop Examples
+
+| Genre | Core Loop |
+|-------|-----------|
+| Platformer | Run → Jump → Land → Collect |
+| Shooter | Aim → Shoot → Kill → Loot |
+| Puzzle | Observe → Think → Solve → Advance |
+| RPG | Explore → Fight → Level → Gear |
+
+---
+
+## 2. Game Design Document (GDD)
+
+### Essential Sections
+
+| Section | Content |
+|---------|---------|
+| **Pitch** | One-sentence description |
+| **Core Loop** | 30-second gameplay |
+| **Mechanics** | How systems work |
+| **Progression** | How player advances |
+| **Art Style** | Visual direction |
+| **Audio** | Sound direction |
+
+### Principles
+
+- Keep it living (update regularly)
+- Visuals help communicate
+- Less is more (start small)
+
+---
+
+## 3. Player Psychology
+
+### Motivation Types
+
+| Type | Driven By |
+|------|-----------|
+| **Achiever** | Goals, completion |
+| **Explorer** | Discovery, secrets |
+| **Socializer** | Interaction, community |
+| **Killer** | Competition, dominance |
+
+### Reward Schedules
+
+| Schedule | Effect | Use |
+|----------|--------|-----|
+| **Fixed** | Predictable | Milestone rewards |
+| **Variable** | Addictive | Loot drops |
+| **Ratio** | Effort-based | Grind games |
+
+---
+
+## 4. Difficulty Balancing
+
+### Flow State
+
+```
+Too Hard → Frustration → Quit
+Too Easy → Boredom → Quit
+Just Right → Flow → Engagement
+```
+
+### Balancing Strategies
+
+| Strategy | How |
+|----------|-----|
+| **Dynamic** | Adjust to player skill |
+| **Selection** | Let player choose |
+| **Accessibility** | Options for all |
+
+---
+
+## 5. Progression Design
+
+### Progression Types
+
+| Type | Example |
+|------|---------|
+| **Skill** | Player gets better |
+| **Power** | Character gets stronger |
+| **Content** | New areas unlock |
+| **Story** | Narrative advances |
+
+### Pacing Principles
+
+- Early wins (hook quickly)
+- Gradually increase challenge
+- Rest beats between intensity
+- Meaningful choices
+
+---
+
+## 6. Anti-Patterns
+
+| ❌ Don't | ✅ Do |
+|----------|-------|
+| Design in isolation | Playtest constantly |
+| Polish before fun | Prototype first |
+| Force one way to play | Allow player expression |
+| Punish excessively | Reward progress |
+
+---
+
+> **Remember:** Fun is discovered through iteration, not designed on paper.
diff --git a/.agent/skills/game-development/mobile-games/SKILL.md b/.agent/skills/game-development/mobile-games/SKILL.md
new file mode 100644
index 0000000..f91d006
--- /dev/null
+++ b/.agent/skills/game-development/mobile-games/SKILL.md
@@ -0,0 +1,108 @@
+---
+name: mobile-games
+description: Mobile game development principles. Touch input, battery, performance, app stores.
+allowed-tools: Read, Write, Edit, Glob, Grep
+---
+
+# Mobile Game Development
+
+> Platform constraints and optimization principles.
+
+---
+
+## 1. Platform Considerations
+
+### Key Constraints
+
+| Constraint | Strategy |
+|------------|----------|
+| **Touch input** | Large hit areas, gestures |
+| **Battery** | Limit CPU/GPU usage |
+| **Thermal** | Throttle when hot |
+| **Screen size** | Responsive UI |
+| **Interruptions** | Pause on background |
+
+---
+
+## 2. Touch Input Principles
+
+### Touch vs Controller
+
+| Touch | Desktop/Console |
+|-------|-----------------|
+| Imprecise | Precise |
+| Occludes screen | No occlusion |
+| Limited buttons | Many buttons |
+| Gestures available | Buttons/sticks |
+
+### Best Practices
+
+- Minimum touch target: 44x44 points
+- Visual feedback on touch
+- Avoid precise timing requirements
+- Support both portrait and landscape
+
+---
+
+## 3. Performance Targets
+
+### Thermal Management
+
+| Action | Trigger |
+|--------|---------|
+| Reduce quality | Device warm |
+| Limit FPS | Device hot |
+| Pause effects | Critical temp |
+
+### Battery Optimization
+
+- 30 FPS often sufficient
+- Sleep when paused
+- Minimize GPS/network
+- Dark mode saves OLED battery
+
+---
+
+## 4. App Store Requirements
+
+### iOS (App Store)
+
+| Requirement | Note |
+|-------------|------|
+| Privacy labels | Required |
+| Account deletion | If account creation exists |
+| Screenshots | For all device sizes |
+
+### Android (Google Play)
+
+| Requirement | Note |
+|-------------|------|
+| Target API | Current year's SDK |
+| 64-bit | Required |
+| App bundles | Recommended |
+
+---
+
+## 5. Monetization Models
+
+| Model | Best For |
+|-------|----------|
+| **Premium** | Quality games, loyal audience |
+| **Free + IAP** | Casual, progression-based |
+| **Ads** | Hyper-casual, high volume |
+| **Subscription** | Content updates, multiplayer |
+
+---
+
+## 6. Anti-Patterns
+
+| ❌ Don't | ✅ Do |
+|----------|-------|
+| Desktop controls on mobile | Design for touch |
+| Ignore battery drain | Monitor thermals |
+| Force landscape | Support player preference |
+| Always-on network | Cache and sync |
+
+---
+
+> **Remember:** Mobile is the most constrained platform. Respect battery and attention.
diff --git a/.agent/skills/game-development/multiplayer/SKILL.md b/.agent/skills/game-development/multiplayer/SKILL.md
new file mode 100644
index 0000000..8fd8cf1
--- /dev/null
+++ b/.agent/skills/game-development/multiplayer/SKILL.md
@@ -0,0 +1,132 @@
+---
+name: multiplayer
+description: Multiplayer game development principles. Architecture, networking, synchronization.
+allowed-tools: Read, Write, Edit, Glob, Grep, Bash
+---
+
+# Multiplayer Game Development
+
+> Networking architecture and synchronization principles.
+
+---
+
+## 1. Architecture Selection
+
+### Decision Tree
+
+```
+What type of multiplayer?
+│
+├── Competitive / Real-time
+│ └── Dedicated Server (authoritative)
+│
+├── Cooperative / Casual
+│ └── Host-based (one player is server)
+│
+├── Turn-based
+│ └── Client-server (simple)
+│
+└── Massive (MMO)
+ └── Distributed servers
+```
+
+### Comparison
+
+| Architecture | Latency | Cost | Security |
+|--------------|---------|------|----------|
+| **Dedicated** | Low | High | Strong |
+| **P2P** | Variable | Low | Weak |
+| **Host-based** | Medium | Low | Medium |
+
+---
+
+## 2. Synchronization Principles
+
+### State vs Input
+
+| Approach | Sync What | Best For |
+|----------|-----------|----------|
+| **State Sync** | Game state | Simple, few objects |
+| **Input Sync** | Player inputs | Action games |
+| **Hybrid** | Both | Most games |
+
+### Lag Compensation
+
+| Technique | Purpose |
+|-----------|---------|
+| **Prediction** | Client predicts server |
+| **Interpolation** | Smooth remote players |
+| **Reconciliation** | Fix mispredictions |
+| **Lag compensation** | Rewind for hit detection |
+
+---
+
+## 3. Network Optimization
+
+### Bandwidth Reduction
+
+| Technique | Savings |
+|-----------|---------|
+| **Delta compression** | Send only changes |
+| **Quantization** | Reduce precision |
+| **Priority** | Important data first |
+| **Area of interest** | Only nearby entities |
+
+### Update Rates
+
+| Type | Rate |
+|------|------|
+| Position | 20-60 Hz |
+| Health | On change |
+| Inventory | On change |
+| Chat | On send |
+
+---
+
+## 4. Security Principles
+
+### Server Authority
+
+```
+Client: "I hit the enemy"
+Server: Validate → did projectile actually hit?
+ → was player in valid state?
+ → was timing possible?
+```
+
+### Anti-Cheat
+
+| Cheat | Prevention |
+|-------|------------|
+| Speed hack | Server validates movement |
+| Aimbot | Server validates sight line |
+| Item dupe | Server owns inventory |
+| Wall hack | Don't send hidden data |
+
+---
+
+## 5. Matchmaking
+
+### Considerations
+
+| Factor | Impact |
+|--------|--------|
+| **Skill** | Fair matches |
+| **Latency** | Playable connection |
+| **Wait time** | Player patience |
+| **Party size** | Group play |
+
+---
+
+## 6. Anti-Patterns
+
+| ❌ Don't | ✅ Do |
+|----------|-------|
+| Trust the client | Server is authority |
+| Send everything | Send only necessary |
+| Ignore latency | Design for 100-200ms |
+| Sync exact positions | Interpolate/predict |
+
+---
+
+> **Remember:** Never trust the client. The server is the source of truth.
diff --git a/.agent/skills/game-development/pc-games/SKILL.md b/.agent/skills/game-development/pc-games/SKILL.md
new file mode 100644
index 0000000..6be120e
--- /dev/null
+++ b/.agent/skills/game-development/pc-games/SKILL.md
@@ -0,0 +1,144 @@
+---
+name: pc-games
+description: PC and console game development principles. Engine selection, platform features, optimization strategies.
+allowed-tools: Read, Write, Edit, Glob, Grep
+---
+
+# PC/Console Game Development
+
+> Engine selection and platform-specific principles.
+
+---
+
+## 1. Engine Selection
+
+### Decision Tree
+
+```
+What are you building?
+│
+├── 2D Game
+│ ├── Open source important? → Godot
+│ └── Large team/assets? → Unity
+│
+├── 3D Game
+│ ├── AAA visual quality? → Unreal
+│ ├── Cross-platform priority? → Unity
+│ └── Indie/open source? → Godot 4
+│
+└── Specific Needs
+ ├── DOTS performance? → Unity
+ ├── Nanite/Lumen? → Unreal
+ └── Lightweight? → Godot
+```
+
+### Comparison
+
+| Factor | Unity 6 | Godot 4 | Unreal 5 |
+|--------|---------|---------|----------|
+| 2D | Good | Excellent | Limited |
+| 3D | Good | Good | Excellent |
+| Learning | Medium | Easy | Hard |
+| Cost | Revenue share | Free | 5% after $1M |
+| Team | Any | Solo-Medium | Medium-Large |
+
+---
+
+## 2. Platform Features
+
+### Steam Integration
+
+| Feature | Purpose |
+|---------|---------|
+| Achievements | Player goals |
+| Cloud Saves | Cross-device progress |
+| Leaderboards | Competition |
+| Workshop | User mods |
+| Rich Presence | Show in-game status |
+
+### Console Requirements
+
+| Platform | Certification |
+|----------|--------------|
+| PlayStation | TRC compliance |
+| Xbox | XR compliance |
+| Nintendo | Lotcheck |
+
+---
+
+## 3. Controller Support
+
+### Input Abstraction
+
+```
+Map ACTIONS, not buttons:
+- "confirm" → A (Xbox), Cross (PS), B (Nintendo)
+- "cancel" → B (Xbox), Circle (PS), A (Nintendo)
+```
+
+### Haptic Feedback
+
+| Intensity | Use |
+|-----------|-----|
+| Light | UI feedback |
+| Medium | Impacts |
+| Heavy | Major events |
+
+---
+
+## 4. Performance Optimization
+
+### Profiling First
+
+| Engine | Tool |
+|--------|------|
+| Unity | Profiler Window |
+| Godot | Debugger → Profiler |
+| Unreal | Unreal Insights |
+
+### Common Bottlenecks
+
+| Bottleneck | Solution |
+|------------|----------|
+| Draw calls | Batching, atlases |
+| GC spikes | Object pooling |
+| Physics | Simpler colliders |
+| Shaders | LOD shaders |
+
+---
+
+## 5. Engine-Specific Principles
+
+### Unity 6
+
+- DOTS for performance-critical systems
+- Burst compiler for hot paths
+- Addressables for asset streaming
+
+### Godot 4
+
+- GDScript for rapid iteration
+- C# for complex logic
+- Signals for decoupling
+
+### Unreal 5
+
+- Blueprint for designers
+- C++ for performance
+- Nanite for high-poly environments
+- Lumen for dynamic lighting
+
+---
+
+## 6. Anti-Patterns
+
+| ❌ Don't | ✅ Do |
+|----------|-------|
+| Choose engine by hype | Choose by project needs |
+| Ignore platform guidelines | Study certification requirements |
+| Hardcode input buttons | Abstract to actions |
+| Skip profiling | Profile early and often |
+
+---
+
+> **Remember:** Engine is a tool. Master the principles, then adapt to any engine.
diff --git a/.agent/skills/game-development/vr-ar/SKILL.md b/.agent/skills/game-development/vr-ar/SKILL.md
new file mode 100644
index 0000000..bd42475
--- /dev/null
+++ b/.agent/skills/game-development/vr-ar/SKILL.md
@@ -0,0 +1,123 @@
+---
+name: vr-ar
+description: VR/AR development principles. Comfort, interaction, performance requirements.
+allowed-tools: Read, Write, Edit, Glob, Grep
+---
+
+# VR/AR Development
+
+> Immersive experience principles.
+
+---
+
+## 1. Platform Selection
+
+### VR Platforms
+
+| Platform | Use Case |
+|----------|----------|
+| **Quest** | Standalone, wireless |
+| **PCVR** | High fidelity |
+| **PSVR** | Console market |
+| **WebXR** | Browser-based |
+
+### AR Platforms
+
+| Platform | Use Case |
+|----------|----------|
+| **ARKit** | iOS devices |
+| **ARCore** | Android devices |
+| **WebXR** | Browser AR |
+| **HoloLens** | Enterprise |
+
+---
+
+## 2. Comfort Principles
+
+### Motion Sickness Prevention
+
+| Cause | Solution |
+|-------|----------|
+| **Locomotion** | Teleport, snap turn |
+| **Low FPS** | Maintain 90 FPS |
+| **Camera shake** | Avoid or minimize |
+| **Rapid acceleration** | Gradual movement |
+
+### Comfort Settings
+
+- Vignette during movement
+- Snap vs smooth turning
+- Seated vs standing modes
+- Height calibration
+
+---
+
+## 3. Performance Requirements
+
+### Target Metrics
+
+| Platform | FPS | Resolution |
+|----------|-----|------------|
+| Quest 2 | 72-90 | 1832x1920 |
+| Quest 3 | 90-120 | 2064x2208 |
+| PCVR | 90 | 2160x2160+ |
+| PSVR2 | 90-120 | 2000x2040 |
+
+### Frame Budget
+
+- VR requires consistent frame times
+- Single dropped frame = visible judder
+- 90 FPS = 11.11ms budget
+
+---
+
+## 4. Interaction Principles
+
+### Controller Interaction
+
+| Type | Use |
+|------|-----|
+| **Point + click** | UI, distant objects |
+| **Grab** | Manipulation |
+| **Gesture** | Magic, special actions |
+| **Physical** | Throwing, swinging |
+
+### Hand Tracking
+
+- More immersive but less precise
+- Good for: social, casual
+- Challenging for: action, precision
+
+---
+
+## 5. Spatial Design
+
+### World Scale
+
+- 1 unit = 1 meter (critical)
+- Objects must feel right size
+- Test with real measurements
+
+### Depth Cues
+
+| Cue | Importance |
+|-----|------------|
+| Stereo | Primary depth |
+| Motion parallax | Secondary |
+| Shadows | Grounding |
+| Occlusion | Layering |
+
+---
+
+## 6. Anti-Patterns
+
+| ❌ Don't | ✅ Do |
+|----------|-------|
+| Move camera without player | Player controls camera |
+| Drop below 90 FPS | Maintain frame rate |
+| Use tiny UI text | Large, readable text |
+| Ignore arm length | Scale to player reach |
+
+---
+
+> **Remember:** Comfort is not optional. Sick players don't play.
diff --git a/.agent/skills/game-development/web-games/SKILL.md b/.agent/skills/game-development/web-games/SKILL.md
new file mode 100644
index 0000000..13d25c1
--- /dev/null
+++ b/.agent/skills/game-development/web-games/SKILL.md
@@ -0,0 +1,150 @@
+---
+name: web-games
+description: Web browser game development principles. Framework selection, WebGPU, optimization, PWA.
+allowed-tools: Read, Write, Edit, Glob, Grep
+---
+
+# Web Browser Game Development
+
+> Framework selection and browser-specific principles.
+
+---
+
+## 1. Framework Selection
+
+### Decision Tree
+
+```
+What type of game?
+│
+├── 2D Game
+│ ├── Full game engine features? → Phaser
+│ └── Raw rendering power? → PixiJS
+│
+├── 3D Game
+│ ├── Full engine (physics, XR)? → Babylon.js
+│ └── Rendering focused? → Three.js
+│
+└── Hybrid / Canvas
+ └── Custom → Raw Canvas/WebGL
+```
+
+### Comparison (2025)
+
+| Framework | Type | Best For |
+|-----------|------|----------|
+| **Phaser 4** | 2D | Full game features |
+| **PixiJS 8** | 2D | Rendering, UI |
+| **Three.js** | 3D | Visualizations, lightweight |
+| **Babylon.js 7** | 3D | Full engine, XR |
+
+---
+
+## 2. WebGPU Adoption
+
+### Browser Support (2025)
+
+| Browser | Support |
+|---------|---------|
+| Chrome | ✅ Since v113 |
+| Edge | ✅ Since v113 |
+| Firefox | ✅ Since v131 |
+| Safari | ✅ Since 18.0 |
+| **Total** | **~73%** global |
+
+### Decision
+
+- **New projects**: Use WebGPU with WebGL fallback
+- **Legacy support**: Start with WebGL
+- **Feature detection**: Check `navigator.gpu`
+
+---
+
+## 3. Performance Principles
+
+### Browser Constraints
+
+| Constraint | Strategy |
+|------------|----------|
+| No local file access | Asset bundling, CDN |
+| Tab throttling | Pause when hidden |
+| Mobile data limits | Compress assets |
+| Audio autoplay | Require user interaction |
+
+### Optimization Priority
+
+1. **Asset compression** - KTX2, Draco, WebP
+2. **Lazy loading** - Load on demand
+3. **Object pooling** - Avoid GC
+4. **Draw call batching** - Reduce state changes
+5. **Web Workers** - Offload heavy computation
+
+---
+
+## 4. Asset Strategy
+
+### Compression Formats
+
+| Type | Format |
+|------|--------|
+| Textures | KTX2 + Basis Universal |
+| Audio | WebM/Opus (fallback: MP3) |
+| 3D Models | glTF + Draco/Meshopt |
+
+### Loading Strategy
+
+| Phase | Load |
+|-------|------|
+| Startup | Core assets, <2MB |
+| Gameplay | Stream on demand |
+| Background | Prefetch next level |
+
+---
+
+## 5. PWA for Games
+
+### Benefits
+
+- Offline play
+- Install to home screen
+- Full screen mode
+- Push notifications
+
+### Requirements
+
+- Service worker for caching
+- Web app manifest
+- HTTPS
+
+---
+
+## 6. Audio Handling
+
+### Browser Requirements
+
+- Audio context requires user interaction
+- Create AudioContext on first click/tap
+- Resume context if suspended
+
+### Best Practices
+
+- Use Web Audio API
+- Pool audio sources
+- Preload common sounds
+- Compress with WebM/Opus
+
+---
+
+## 7. Anti-Patterns
+
+| ❌ Don't | ✅ Do |
+|----------|-------|
+| Load all assets upfront | Progressive loading |
+| Ignore tab visibility | Pause when hidden |
+| Block on audio load | Lazy load audio |
+| Skip compression | Compress everything |
+| Assume fast connection | Handle slow networks |
+
+---
+
+> **Remember:** Browser is the most accessible platform. Respect its constraints.
diff --git a/.agent/skills/geo-fundamentals/SKILL.md b/.agent/skills/geo-fundamentals/SKILL.md
new file mode 100644
index 0000000..d69bdc0
--- /dev/null
+++ b/.agent/skills/geo-fundamentals/SKILL.md
@@ -0,0 +1,156 @@
+---
+name: geo-fundamentals
+description: Generative Engine Optimization for AI search engines (ChatGPT, Claude, Perplexity).
+allowed-tools: Read, Glob, Grep
+---
+
+# GEO Fundamentals
+
+> Optimization for AI-powered search engines.
+
+---
+
+## 1. What is GEO?
+
+**GEO** = Generative Engine Optimization
+
+| Goal | Platform |
+|------|----------|
+| Be cited in AI responses | ChatGPT, Claude, Perplexity, Gemini |
+
+### SEO vs GEO
+
+| Aspect | SEO | GEO |
+|--------|-----|-----|
+| Goal | #1 ranking | AI citations |
+| Platform | Google | AI engines |
+| Metrics | Rankings, CTR | Citation rate |
+| Focus | Keywords | Entities, data |
+
+---
+
+## 2. AI Engine Landscape
+
+| Engine | Citation Style | Opportunity |
+|--------|----------------|-------------|
+| **Perplexity** | Numbered [1][2] | Highest citation rate |
+| **ChatGPT** | Inline/footnotes | Custom GPTs |
+| **Claude** | Contextual | Long-form content |
+| **Gemini** | Sources section | SEO crossover |
+
+---
+
+## 3. RAG Retrieval Factors
+
+How AI engines select content to cite:
+
+| Factor | Weight |
+|--------|--------|
+| Semantic relevance | ~40% |
+| Keyword match | ~20% |
+| Authority signals | ~15% |
+| Freshness | ~10% |
+| Source diversity | ~15% |
+
+---
+
+## 4. Content That Gets Cited
+
+| Element | Why It Works |
+|---------|--------------|
+| **Original statistics** | Unique, citable data |
+| **Expert quotes** | Authority transfer |
+| **Clear definitions** | Easy to extract |
+| **Step-by-step guides** | Actionable value |
+| **Comparison tables** | Structured info |
+| **FAQ sections** | Direct answers |
+
+---
+
+## 5. GEO Content Checklist
+
+### Content Elements
+
+- [ ] Question-based titles
+- [ ] Summary/TL;DR at top
+- [ ] Original data with sources
+- [ ] Expert quotes (name, title)
+- [ ] FAQ section (3-5 Q&A)
+- [ ] Clear definitions
+- [ ] "Last updated" timestamp
+- [ ] Author with credentials
+
+### Technical Elements
+
+- [ ] Article schema with dates
+- [ ] Person schema for author
+- [ ] FAQPage schema
+- [ ] Fast loading (< 2.5s)
+- [ ] Clean HTML structure
+
+---
+
+## 6. Entity Building
+
+| Action | Purpose |
+|--------|---------|
+| Google Knowledge Panel | Entity recognition |
+| Wikipedia (if notable) | Authority source |
+| Consistent info across web | Entity consolidation |
+| Industry mentions | Authority signals |
+
+---
+
+## 7. AI Crawler Access
+
+### Key AI User-Agents
+
+| Crawler | Engine |
+|---------|--------|
+| GPTBot | ChatGPT/OpenAI |
+| Claude-Web | Claude |
+| PerplexityBot | Perplexity |
+| Googlebot | Gemini (shared) |
+
+### Access Decision
+
+| Strategy | When |
+|----------|------|
+| Allow all | Want AI citations |
+| Block GPTBot | Don't want OpenAI training |
+| Selective | Allow some, block others |
+
+---
+
+## 8. Measurement
+
+| Metric | How to Track |
+|--------|--------------|
+| AI citations | Manual monitoring |
+| "According to [Brand]" mentions | Search in AI |
+| Competitor citations | Compare share |
+| AI-referred traffic | UTM parameters |
+
+---
+
+## 9. Anti-Patterns
+
+| ❌ Don't | ✅ Do |
+|----------|-------|
+| Publish without dates | Add timestamps |
+| Vague attributions | Name sources |
+| Skip author info | Show credentials |
+| Thin content | Comprehensive coverage |
+
+---
+
+> **Remember:** AI cites content that's clear, authoritative, and easy to extract. Be the best answer.
+
+---
+
+## Script
+
+| Script | Purpose | Command |
+|--------|---------|---------|
+| `scripts/geo_checker.py` | GEO audit (AI citation readiness) | `python scripts/geo_checker.py {t('welcome.title')}
; +} +``` + +### Next.js (next-intl) + +```tsx +import { useTranslations } from 'next-intl'; + +export default function Page() { + const t = useTranslations('Home'); + return{t('title')}
; +} +``` + +### Python (gettext) + +```python +from gettext import gettext as _ + +print(_("Welcome to our app")) +``` + +--- + +## 4. File Structure + +``` +locales/ +├── en/ +│ ├── common.json +│ ├── auth.json +│ └── errors.json +├── tr/ +│ ├── common.json +│ ├── auth.json +│ └── errors.json +└── ar/ # RTL + └── ... +``` + +--- + +## 5. Best Practices + +### DO ✅ + +- Use translation keys, not raw text +- Namespace translations by feature +- Support pluralization +- Handle date/number formats per locale +- Plan for RTL from the start +- Use ICU message format for complex strings + +### DON'T ❌ + +- Hardcode strings in components +- Concatenate translated strings +- Assume text length (German is 30% longer) +- Forget about RTL layout +- Mix languages in same file + +--- + +## 6. Common Issues + +| Issue | Solution | +|-------|----------| +| Missing translation | Fallback to default language | +| Hardcoded strings | Use linter/checker script | +| Date format | Use Intl.DateTimeFormat | +| Number format | Use Intl.NumberFormat | +| Pluralization | Use ICU message format | + +--- + +## 7. RTL Support + +```css +/* CSS Logical Properties */ +.container { + margin-inline-start: 1rem; /* Not margin-left */ + padding-inline-end: 1rem; /* Not padding-right */ +} + +[dir="rtl"] .icon { + transform: scaleX(-1); +} +``` + +--- + +## 8. Checklist + +Before shipping: + +- [ ] All user-facing strings use translation keys +- [ ] Locale files exist for all supported languages +- [ ] Date/number formatting uses Intl API +- [ ] RTL layout tested (if applicable) +- [ ] Fallback language configured +- [ ] No hardcoded strings in components + +--- + +## Script + +| Script | Purpose | Command | +|--------|---------|---------| +| `scripts/i18n_checker.py` | Detect hardcoded strings & missing translations | `python scripts/i18n_checker.pyHello World
+ r'>\s*[A-Z][a-zA-Z\s]{3,30}\s*]*>\s*[A-Z][a-zA-Z\s!?.,]{3,}\s*\s*[A-Z][a-zA-Z\s]{3,30}\s* list:
+ """Find translation/locale files."""
+ patterns = [
+ "**/locales/**/*.json",
+ "**/translations/**/*.json",
+ "**/lang/**/*.json",
+ "**/i18n/**/*.json",
+ "**/messages/*.json",
+ "**/*.po", # gettext
+ ]
+
+ files = []
+ for pattern in patterns:
+ files.extend(project_path.glob(pattern))
+
+ return [f for f in files if 'node_modules' not in str(f)]
+
+def check_locale_completeness(locale_files: list) -> dict:
+ """Check if all locales have the same keys."""
+ issues = []
+ passed = []
+
+ if not locale_files:
+ return {'passed': [], 'issues': ["[!] No locale files found"]}
+
+ # Group by parent folder (language)
+ locales = {}
+ for f in locale_files:
+ if f.suffix == '.json':
+ try:
+ lang = f.parent.name
+ content = json.loads(f.read_text(encoding='utf-8'))
+ if lang not in locales:
+ locales[lang] = {}
+ locales[lang][f.stem] = set(flatten_keys(content))
+ except:
+ continue
+
+ if len(locales) < 2:
+ passed.append(f"[OK] Found {len(locale_files)} locale file(s)")
+ return {'passed': passed, 'issues': issues}
+
+ passed.append(f"[OK] Found {len(locales)} language(s): {', '.join(locales.keys())}")
+
+ # Compare keys across locales
+ all_langs = list(locales.keys())
+ base_lang = all_langs[0]
+
+ for namespace in locales.get(base_lang, {}):
+ base_keys = locales[base_lang].get(namespace, set())
+
+ for lang in all_langs[1:]:
+ other_keys = locales.get(lang, {}).get(namespace, set())
+
+ missing = base_keys - other_keys
+ if missing:
+ issues.append(f"[X] {lang}/{namespace}: Missing {len(missing)} keys")
+
+ extra = other_keys - base_keys
+ if extra:
+ issues.append(f"[!] {lang}/{namespace}: {len(extra)} extra keys")
+
+ if not issues:
+ passed.append("[OK] All locales have matching keys")
+
+ return {'passed': passed, 'issues': issues}
+
+def flatten_keys(d, prefix=''):
+ """Flatten nested dict keys."""
+ keys = set()
+ for k, v in d.items():
+ new_key = f"{prefix}.{k}" if prefix else k
+ if isinstance(v, dict):
+ keys.update(flatten_keys(v, new_key))
+ else:
+ keys.add(new_key)
+ return keys
+
+def check_hardcoded_strings(project_path: Path) -> dict:
+ """Check for hardcoded strings in code files."""
+ issues = []
+ passed = []
+
+ # Find code files
+ extensions = {
+ '.tsx': 'jsx', '.jsx': 'jsx', '.ts': 'jsx', '.js': 'jsx',
+ '.vue': 'vue',
+ '.py': 'python'
+ }
+
+ code_files = []
+ for ext in extensions:
+ code_files.extend(project_path.rglob(f"*{ext}"))
+
+ code_files = [f for f in code_files if not any(x in str(f) for x in
+ ['node_modules', '.git', 'dist', 'build', '__pycache__', 'venv', 'test', 'spec'])]
+
+ if not code_files:
+ return {'passed': ["[!] No code files found"], 'issues': []}
+
+ files_with_i18n = 0
+ files_with_hardcoded = 0
+ hardcoded_examples = []
+
+ for file_path in code_files[:50]: # Limit
+ try:
+ content = file_path.read_text(encoding='utf-8', errors='ignore')
+ ext = file_path.suffix
+ file_type = extensions.get(ext, 'jsx')
+
+ # Check for i18n usage
+ has_i18n = any(re.search(p, content) for p in I18N_PATTERNS)
+ if has_i18n:
+ files_with_i18n += 1
+
+ # Check for hardcoded strings
+ patterns = HARDCODED_PATTERNS.get(file_type, [])
+ hardcoded_found = False
+
+ for pattern in patterns:
+ matches = re.findall(pattern, content)
+ if matches and not has_i18n:
+ hardcoded_found = True
+ if len(hardcoded_examples) < 5:
+ hardcoded_examples.append(f"{file_path.name}: {str(matches[0])[:40]}...")
+
+ if hardcoded_found:
+ files_with_hardcoded += 1
+
+ except:
+ continue
+
+ passed.append(f"[OK] Analyzed {len(code_files)} code files")
+
+ if files_with_i18n > 0:
+ passed.append(f"[OK] {files_with_i18n} files use i18n")
+
+ if files_with_hardcoded > 0:
+ issues.append(f"[X] {files_with_hardcoded} files may have hardcoded strings")
+ for ex in hardcoded_examples:
+ issues.append(f" → {ex}")
+ else:
+ passed.append("[OK] No obvious hardcoded strings detected")
+
+ return {'passed': passed, 'issues': issues}
+
+def main():
+ target = sys.argv[1] if len(sys.argv) > 1 else "."
+ project_path = Path(target)
+
+ print("\n" + "=" * 60)
+ print(" i18n CHECKER - Internationalization Audit")
+ print("=" * 60 + "\n")
+
+ # Check locale files
+ locale_files = find_locale_files(project_path)
+ locale_result = check_locale_completeness(locale_files)
+
+ # Check hardcoded strings
+ code_result = check_hardcoded_strings(project_path)
+
+ # Print results
+ print("[LOCALE FILES]")
+ print("-" * 40)
+ for item in locale_result['passed']:
+ print(f" {item}")
+ for item in locale_result['issues']:
+ print(f" {item}")
+
+ print("\n[CODE ANALYSIS]")
+ print("-" * 40)
+ for item in code_result['passed']:
+ print(f" {item}")
+ for item in code_result['issues']:
+ print(f" {item}")
+
+ # Summary
+ critical_issues = sum(1 for i in locale_result['issues'] + code_result['issues'] if i.startswith("[X]"))
+
+ print("\n" + "=" * 60)
+ if critical_issues == 0:
+ print("[OK] i18n CHECK: PASSED")
+ sys.exit(0)
+ else:
+ print(f"[X] i18n CHECK: {critical_issues} issues found")
+ sys.exit(1)
+
+if __name__ == "__main__":
+ main()
diff --git a/.agent/skills/intelligent-routing/SKILL.md b/.agent/skills/intelligent-routing/SKILL.md
new file mode 100644
index 0000000..5c8814b
--- /dev/null
+++ b/.agent/skills/intelligent-routing/SKILL.md
@@ -0,0 +1,335 @@
+---
+name: intelligent-routing
+description: Automatic agent selection and intelligent task routing. Analyzes user requests and automatically selects the best specialist agent(s) without requiring explicit user mentions.
+version: 1.0.0
+---
+
+# Intelligent Agent Routing
+
+**Purpose**: Automatically analyze user requests and route them to the most appropriate specialist agent(s) without requiring explicit user mentions.
+
+## Core Principle
+
+> **The AI should act as an intelligent Project Manager**, analyzing each request and automatically selecting the best specialist(s) for the job.
+
+## How It Works
+
+### 1. Request Analysis
+
+Before responding to ANY user request, perform automatic analysis:
+
+```mermaid
+graph TD
+ A[User Request: Add login] --> B[ANALYZE]
+ B --> C[Keywords]
+ B --> D[Domains]
+ B --> E[Complexity]
+ C --> F[SELECT AGENT]
+ D --> F
+ E --> F
+ F --> G[security-auditor + backend-specialist]
+ G --> H[AUTO-INVOKE with context]
+```
+
+### 2. Agent Selection Matrix
+
+**Use this matrix to automatically select agents:**
+
+| User Intent | Keywords | Selected Agent(s) | Auto-invoke? |
+| ------------------- | ------------------------------------------ | ------------------------------------------- | ------------ |
+| **Authentication** | "login", "auth", "signup", "password" | `security-auditor` + `backend-specialist` | ✅ YES |
+| **UI Component** | "button", "card", "layout", "style" | `frontend-specialist` | ✅ YES |
+| **Mobile UI** | "screen", "navigation", "touch", "gesture" | `mobile-developer` | ✅ YES |
+| **API Endpoint** | "endpoint", "route", "API", "POST", "GET" | `backend-specialist` | ✅ YES |
+| **Database** | "schema", "migration", "query", "table" | `database-architect` + `backend-specialist` | ✅ YES |
+| **Bug Fix** | "error", "bug", "not working", "broken" | `debugger` | ✅ YES |
+| **Test** | "test", "coverage", "unit", "e2e" | `test-engineer` | ✅ YES |
+| **Deployment** | "deploy", "production", "CI/CD", "docker" | `devops-engineer` | ✅ YES |
+| **Security Review** | "security", "vulnerability", "exploit" | `security-auditor` + `penetration-tester` | ✅ YES |
+| **Performance** | "slow", "optimize", "performance", "speed" | `performance-optimizer` | ✅ YES |
+| **Product Def** | "requirements", "user story", "backlog", "MVP" | `product-owner` | ✅ YES |
+| **New Feature** | "build", "create", "implement", "new app" | `orchestrator` → multi-agent | ⚠️ ASK FIRST |
+| **Complex Task** | Multiple domains detected | `orchestrator` → multi-agent | ⚠️ ASK FIRST |
+
+### 3. Automatic Routing Protocol
+
+## TIER 0 - Automatic Analysis (ALWAYS ACTIVE)
+
+Before responding to ANY request:
+
+```javascript
+// Pseudo-code for decision tree
+function analyzeRequest(userMessage) {
+ // 1. Classify request type
+ const requestType = classifyRequest(userMessage);
+
+ // 2. Detect domains
+ const domains = detectDomains(userMessage);
+
+ // 3. Determine complexity
+ const complexity = assessComplexity(domains);
+
+ // 4. Select agent(s)
+ if (complexity === "SIMPLE" && domains.length === 1) {
+ return selectSingleAgent(domains[0]);
+ } else if (complexity === "MODERATE" && domains.length <= 2) {
+ return selectMultipleAgents(domains);
+ } else {
+ return "orchestrator"; // Complex task
+ }
+}
+```
+
+## 4. Response Format
+
+**When auto-selecting an agent, inform the user concisely:**
+
+```markdown
+🤖 **Applying knowledge of `@security-auditor` + `@backend-specialist`...**
+
+[Proceed with specialized response]
+```
+
+**Benefits:**
+
+- ✅ User sees which expertise is being applied
+- ✅ Transparent decision-making
+- ✅ Still automatic (no /commands needed)
+
+## Domain Detection Rules
+
+### Single-Domain Tasks (Auto-invoke Single Agent)
+
+| Domain | Patterns | Agent |
+| --------------- | ------------------------------------------ | ----------------------- |
+| **Security** | auth, login, jwt, password, hash, token | `security-auditor` |
+| **Frontend** | component, react, vue, css, html, tailwind | `frontend-specialist` |
+| **Backend** | api, server, express, fastapi, node | `backend-specialist` |
+| **Mobile** | react native, flutter, ios, android, expo | `mobile-developer` |
+| **Database** | prisma, sql, mongodb, schema, migration | `database-architect` |
+| **Testing** | test, jest, vitest, playwright, cypress | `test-engineer` |
+| **DevOps** | docker, kubernetes, ci/cd, pm2, nginx | `devops-engineer` |
+| **Debug** | error, bug, crash, not working, issue | `debugger` |
+| **Performance** | slow, lag, optimize, cache, performance | `performance-optimizer` |
+| **SEO** | seo, meta, analytics, sitemap, robots | `seo-specialist` |
+| **Game** | unity, godot, phaser, game, multiplayer | `game-developer` |
+
+### Multi-Domain Tasks (Auto-invoke Orchestrator)
+
+If request matches **2+ domains from different categories**, automatically use `orchestrator`:
+
+```text
+Example: "Create a secure login system with dark mode UI"
+→ Detected: Security + Frontend
+→ Auto-invoke: orchestrator
+→ Orchestrator will handle: security-auditor, frontend-specialist, test-engineer
+```
+
+## Complexity Assessment
+
+### SIMPLE (Direct agent invocation)
+
+- Single file edit
+- Clear, specific task
+- One domain only
+- Example: "Fix the login button style"
+
+**Action**: Auto-invoke respective agent
+
+### MODERATE (2-3 agents)
+
+- 2-3 files affected
+- Clear requirements
+- 2 domains max
+- Example: "Add API endpoint for user profile"
+
+**Action**: Auto-invoke relevant agents sequentially
+
+### COMPLEX (Orchestrator required)
+
+- Multiple files/domains
+- Architectural decisions needed
+- Unclear requirements
+- Example: "Build a social media app"
+
+**Action**: Auto-invoke `orchestrator` → will ask Socratic questions
+
+## Implementation Rules
+
+### Rule 1: Silent Analysis
+
+#### DO NOT announce "I'm analyzing your request..."
+
+- ✅ Analyze silently
+- ✅ Inform which agent is being applied
+- ❌ Avoid verbose meta-commentary
+
+### Rule 2: Inform Agent Selection
+
+**DO inform which expertise is being applied:**
+
+```markdown
+🤖 **Applying knowledge of `@frontend-specialist`...**
+
+I will create the component with the following characteristics:
+[Continue with specialized response]
+```
+
+### Rule 3: Seamless Experience
+
+**The user should not notice a difference from talking to the right specialist directly.**
+
+### Rule 4: Override Capability
+
+**User can still explicitly mention agents:**
+
+```text
+User: "Use @backend-specialist to review this"
+→ Override auto-selection
+→ Use explicitly mentioned agent
+```
+
+## Edge Cases
+
+### Case 1: Generic Question
+
+```text
+User: "How does React work?"
+→ Type: QUESTION
+→ No agent needed
+→ Respond directly with explanation
+```
+
+### Case 2: Extremely Vague Request
+
+```text
+User: "Make it better"
+→ Complexity: UNCLEAR
+→ Action: Ask clarifying questions first
+→ Then route to appropriate agent
+```
+
+### Case 3: Contradictory Patterns
+
+```text
+User: "Add mobile support to the web app"
+→ Conflict: mobile vs web
+→ Action: Ask: "Do you want responsive web or native mobile app?"
+→ Then route accordingly
+```
+
+## Integration with Existing Workflows
+
+### With /orchestrate Command
+
+- **User types `/orchestrate`**: Explicit orchestration mode
+- **AI detects complex task**: Auto-invoke orchestrator (same result)
+
+**Difference**: User doesn't need to know the command exists.
+
+### With Socratic Gate
+
+- **Auto-routing does NOT bypass Socratic Gate**
+- If task is unclear, still ask questions first
+- Then route to appropriate agent
+
+### With GEMINI.md Rules
+
+- **Priority**: GEMINI.md rules > intelligent-routing
+- If GEMINI.md specifies explicit routing, follow it
+- Intelligent routing is the DEFAULT when no explicit rule exists
+
+## Testing the System
+
+### Test Cases
+
+#### Test 1: Simple Frontend Task
+
+```text
+User: "Create a dark mode toggle button"
+Expected: Auto-invoke frontend-specialist
+Verify: Response shows "Using @frontend-specialist"
+```
+
+#### Test 2: Security Task
+
+```text
+User: "Review the authentication flow for vulnerabilities"
+Expected: Auto-invoke security-auditor
+Verify: Security-focused analysis
+```
+
+#### Test 3: Complex Multi-Domain
+
+```text
+User: "Build a chat application with real-time notifications"
+Expected: Auto-invoke orchestrator
+Verify: Multiple agents coordinated (backend, frontend, test)
+```
+
+#### Test 4: Bug Fix
+
+```text
+User: "Login is not working, getting 401 error"
+Expected: Auto-invoke debugger
+Verify: Systematic debugging approach
+```
+
+## Performance Considerations
+
+### Token Usage
+
+- Analysis adds ~50-100 tokens per request
+- Tradeoff: Better accuracy vs slight overhead
+- Overall SAVES tokens by reducing back-and-forth
+
+### Response Time
+
+- Analysis is instant (pattern matching)
+- No additional API calls required
+- Agent selection happens before first response
+
+## User Education
+
+### Optional: First-Time Explanation
+
+If this is the first interaction in a project:
+
+```markdown
+💡 **Tip**: I am configured with automatic specialist agent selection.
+I will always choose the most suitable specialist for your task. You can
+still mention agents explicitly with `@agent-name` if you prefer.
+```
+
+## Debugging Agent Selection
+
+### Enable Debug Mode (for development)
+
+Add to GEMINI.md temporarily:
+
+```markdown
+## DEBUG: Intelligent Routing
+
+Show selection reasoning:
+
+- Detected domains: [list]
+- Selected agent: [name]
+- Reasoning: [why]
+```
+
+## Summary
+
+**intelligent-routing skill enables:**
+
+✅ Zero-command operation (no need for `/orchestrate`)
+✅ Automatic specialist selection based on request analysis
+✅ Transparent communication of which expertise is being applied
+✅ Seamless integration with existing workflows
+✅ Override capability for explicit agent mentions
+✅ Fallback to orchestrator for complex tasks
+
+**Result**: User gets specialist-level responses without needing to know the system architecture.
+
+---
+
+**Next Steps**: Integrate this skill into GEMINI.md TIER 0 rules.
diff --git a/.agent/skills/lint-and-validate/SKILL.md b/.agent/skills/lint-and-validate/SKILL.md
new file mode 100644
index 0000000..34844d6
--- /dev/null
+++ b/.agent/skills/lint-and-validate/SKILL.md
@@ -0,0 +1,45 @@
+---
+name: lint-and-validate
+description: Automatic quality control, linting, and static analysis procedures. Use after every code modification to ensure syntax correctness and project standards. Triggers onKeywords: lint, format, check, validate, types, static analysis.
+allowed-tools: Read, Glob, Grep, Bash
+---
+
+# Lint and Validate Skill
+
+> **MANDATORY:** Run appropriate validation tools after EVERY code change. Do not finish a task until the code is error-free.
+
+### Procedures by Ecosystem
+
+#### Node.js / TypeScript
+1. **Lint/Fix:** `npm run lint` or `npx eslint "path" --fix`
+2. **Types:** `npx tsc --noEmit`
+3. **Security:** `npm audit --audit-level=high`
+
+#### Python
+1. **Linter (Ruff):** `ruff check "path" --fix` (Fast & Modern)
+2. **Security (Bandit):** `bandit -r "path" -ll`
+3. **Types (MyPy):** `mypy "path"`
+
+## The Quality Loop
+1. **Write/Edit Code**
+2. **Run Audit:** `npm run lint && npx tsc --noEmit`
+3. **Analyze Report:** Check the "FINAL AUDIT REPORT" section.
+4. **Fix & Repeat:** Submitting code with "FINAL AUDIT" failures is NOT allowed.
+
+## Error Handling
+- If `lint` fails: Fix the style or syntax issues immediately.
+- If `tsc` fails: Correct type mismatches before proceeding.
+- If no tool is configured: Check the project root for `.eslintrc`, `tsconfig.json`, `pyproject.toml` and suggest creating one.
+
+---
+**Strict Rule:** No code should be committed or reported as "done" without passing these checks.
+
+---
+
+## Scripts
+
+| Script | Purpose | Command |
+|--------|---------|---------|
+| `scripts/lint_runner.py` | Unified lint check | `python scripts/lint_runner.py
+
+ )
+}
+```
+
+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 (
+ Sidebar
+ Header
+
+
+ Footer
+
+
+ )
+}
+
+async function DataDisplay() {
+ const data = await fetchData() // Only blocks this component
+ return Sidebar
+ Header
+
+
+ Footer
+ {data.content}
+}
+```
+
+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 (
+
+
+ )
+}
+
+function DataDisplay({ dataPromise }: { dataPromise: Promise }) {
+ const data = use(dataPromise) // Unwraps the promise
+ return Sidebar
+ Header
+ Footer
+ {data.content}
+}
+
+function DataSummary({ dataPromise }: { dataPromise: Promise }) {
+ const data = use(dataPromise) // Reuses the same promise
+ return {data.summary}
+}
+```
+
+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/.agent/skills/nextjs-react-expert/2-bundle-bundle-size-optimization.md b/.agent/skills/nextjs-react-expert/2-bundle-bundle-size-optimization.md
new file mode 100644
index 0000000..5c004c4
--- /dev/null
+++ b/.agent/skills/nextjs-react-expert/2-bundle-bundle-size-optimization.md
@@ -0,0 +1,240 @@
+# 2. Bundle Size Optimization
+
+> **Impact:** CRITICAL
+> **Focus:** Reducing initial bundle size improves Time to Interactive and Largest Contentful Paint.
+
+---
+
+## Overview
+
+This section contains **5 rules** focused on bundle size optimization.
+
+---
+
+## Rule 2.1: Avoid Barrel File Imports
+
+**Impact:** CRITICAL
+**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)
+
+---
+
+## Rule 2.2: Conditional Module Loading
+
+**Impact:** HIGH
+**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{user.name}
// uses 1 field
+}
+```
+
+**Correct (serializes only 1 field):**
+
+```tsx
+async function Page() {
+ const user = await fetchUser()
+ return {name}
+}
+```
+
+---
+
+## Rule 3.5: Parallel Data Fetching with Component Composition
+
+**Impact:** CRITICAL
+**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 (
+
+
+ )
+}
+
+async function Sidebar() {
+ const items = await fetchSidebarItems()
+ return
+}
+```
+
+**Correct (both fetch simultaneously):**
+
+```tsx
+async function Header() {
+ const data = await fetchHeader()
+ return {header}
+ {data}
+}
+
+async function Sidebar() {
+ const items = await fetchSidebarItems()
+ return
+}
+
+export default function Page() {
+ return (
+
+
+ )
+}
+```
+
+**Alternative with children prop:**
+
+```tsx
+async function Header() {
+ const data = await fetchHeader()
+ return {data}
+}
+
+async function Sidebar() {
+ const items = await fetchSidebarItems()
+ return
+}
+
+function Layout({ children }: { children: ReactNode }) {
+ return (
+
+
+ )
+}
+
+export default function Page() {
+ return (
+ {fullName}
+} +``` + +**Correct (derive during render):** + +```tsx +function Form() { + const [firstName, setFirstName] = useState('First') + const [lastName, setLastName] = useState('Last') + const fullName = firstName + ' ' + lastName + + return{fullName}
+} +``` + +References: [You Might Not Need an Effect](https://react.dev/learn/you-might-not-need-an-effect) + +--- + +## Rule 5.2: Defer State Reads to Usage Point + +**Impact:** MEDIUM +**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 +} +``` + +**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 +} +``` + +--- + +## Rule 5.3: Do not wrap a simple expression with a primitive result type in useMemo + +**Impact:** LOW-MEDIUM +**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{avatar}
+}
+```
+
+**Correct (skips computation when loading):**
+
+```tsx
+const UserAvatar = memo(function UserAvatar({ user }: { user: User }) {
+ const id = useMemo(() => computeAvatarId(user), [user])
+ return
+
+ )
+}
+```
+
+**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.
+
+---
+
+## Rule 5.6: Narrow Effect Dependencies
+
+**Impact:** LOW
+**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])
+```
+
+---
+
+## Rule 5.7: Put Interaction Logic in Event Handlers
+
+**Impact:** MEDIUM
+**Tags:** rerender, useEffect, events, side-effects, dependencies
+
+## Put Interaction Logic in Event Handlers
+
+If a side effect is triggered by a specific user action (submit, click, drag), run it in that event handler. Do not model the action as state + effect; it makes effects re-run on unrelated changes and can duplicate the action.
+
+**Incorrect (event modeled as state + effect):**
+
+```tsx
+function Form() {
+ const [submitted, setSubmitted] = useState(false)
+ const theme = useContext(ThemeContext)
+
+ useEffect(() => {
+ if (submitted) {
+ post('/api/register')
+ showToast('Registered', theme)
+ }
+ }, [submitted, theme])
+
+ return
+}
+```
+
+**Correct (do it in the handler):**
+
+```tsx
+function Form() {
+ const theme = useContext(ThemeContext)
+
+ function handleSubmit() {
+ post('/api/register')
+ showToast('Registered', theme)
+ }
+
+ return
+}
+```
+
+Reference: [Should this code move to an event handler?](https://react.dev/learn/removing-effect-dependencies#should-this-code-move-to-an-event-handler)
+
+---
+
+## Rule 5.8: Subscribe to Derived State
+
+**Impact:** MEDIUM
+**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
+}
+```
+
+**Correct (re-renders only when boolean changes):**
+
+```tsx
+function Sidebar() {
+ const isMobile = useMediaQuery('(max-width: 767px)')
+ return
+}
+```
+
+---
+
+## Rule 5.9: Use Functional setState Updates
+
+**Impact:** MEDIUM
+**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 ` and animate the wrapper instead.
+
+**Incorrect (animating SVG directly - no hardware acceleration):**
+
+```tsx
+function LoadingSpinner() {
+ return (
+
+ )
+}
+```
+
+**Correct (animating wrapper div - hardware accelerated):**
+
+```tsx
+function LoadingSpinner() {
+ return (
+ ` to preserve state/DOM for expensive components that frequently toggle visibility.
+
+**Usage:**
+
+```tsx
+import { Activity } from 'react'
+
+function Dropdown({ isOpen }: Props) {
+ return (
+
+
+ )
+}
+```
+
+Avoids expensive re-renders and state loss.
+
+---
+
+## Rule 6.8: Use Explicit Conditional Rendering
+
+**Impact:** LOW
+**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 (
+ (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 ()
+
+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 (
+ ()
+
+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 | 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()
+ }
+})
+```
+
+---
+
+## Rule 7.6: Combine Multiple Array Iterations
+
+**Impact:** LOW-MEDIUM
+**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)
+}
+```
+
+---
+
+## Rule 7.7: Early Length Check for Array Comparisons
+
+**Impact:** MEDIUM-HIGH
+**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
+
+---
+
+## Rule 7.8: Early Return from Functions
+
+**Impact:** LOW-MEDIUM
+**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 }
+}
+```
+
+---
+
+## Rule 7.9: Hoist RegExp Creation
+
+**Impact:** LOW-MEDIUM
+**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
+```
+
+---
+
+## Rule 7.10: Use Loop for Min/Max Instead of Sort
+
+**Impact:** LOW
+**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.
+
+---
+
+## Rule 7.11: Use Set/Map for O(1) Lookups
+
+**Impact:** LOW-MEDIUM
+**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))
+```
+
+---
+
+## Rule 7.12: Use toSorted() Instead of sort() for Immutability
+
+**Impact:** MEDIUM-HIGH
+**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 ` |
+
+---
+
+## 📖 Section Details
+
+### Section 1: Eliminating Waterfalls (CRITICAL)
+
+**Impact:** Each waterfall adds 100-500ms+ latency
+**Key Concepts:** Parallel fetching, Promise.all(), Suspense boundaries, preloading
+
+### Section 2: Bundle Size Optimization (CRITICAL)
+
+**Impact:** Directly affects Time to Interactive, Largest Contentful Paint
+**Key Concepts:** Dynamic imports, tree-shaking, barrel import avoidance
+
+### Section 3: Server-Side Performance (HIGH)
+
+**Impact:** Faster server responses, better SEO
+**Key Concepts:** Parallel server fetching, streaming, API route optimization
+
+### Section 4: Client-Side Data Fetching (MEDIUM-HIGH)
+
+**Impact:** Reduces redundant requests, better UX
+**Key Concepts:** SWR deduplication, localStorage caching, event listeners
+
+### Section 5: Re-render Optimization (MEDIUM)
+
+**Impact:** Smoother UI, less wasted computation
+**Key Concepts:** React.memo, useMemo, useCallback, component structure
+
+### Section 6: Rendering Performance (MEDIUM)
+
+**Impact:** Better rendering efficiency
+**Key Concepts:** Virtualization, image optimization, layout thrashing
+
+### Section 7: JavaScript Performance (LOW-MEDIUM)
+
+**Impact:** Incremental improvements in hot paths
+**Key Concepts:** Loop optimization, caching, RegExp hoisting
+
+### Section 8: Advanced Patterns (VARIABLE)
+
+**Impact:** Specific use cases
+**Key Concepts:** useLatest hook, init-once patterns, event handler refs
+
+---
+
+## 🎓 Best Practices Summary
+
+**Golden Rules:**
+
+1. **Measure first** - Use React DevTools Profiler, Chrome DevTools
+2. **Biggest impact first** - Waterfalls → Bundle → Server → Micro
+3. **Don't over-optimize** - Focus on real bottlenecks
+4. **Use platform features** - Next.js has optimizations built-in
+5. **Think about users** - Real-world conditions matter
+
+**Performance Mindset:**
+
+- Every `await` in sequence = potential waterfall
+- Every `import` = potential bundle bloat
+- Every re-render = wasted computation (if unnecessary)
+- Server components = less JavaScript to ship
+- Measure, don't guess
+
+---
+
+**Source:** Vercel Engineering
+**Date:** January 2026
+**Version:** 1.0.0
+**Total Rules:** 57 across 8 categories
diff --git a/.agent/skills/nextjs-react-expert/scripts/convert_rules.py b/.agent/skills/nextjs-react-expert/scripts/convert_rules.py
new file mode 100644
index 0000000..d1199b8
--- /dev/null
+++ b/.agent/skills/nextjs-react-expert/scripts/convert_rules.py
@@ -0,0 +1,222 @@
+#!/usr/bin/env python3
+"""
+Conversion Script: React Best Practices → .agent Format
+Merges 59 individual rules into 8 grouped section files
+"""
+
+import os
+import re
+from pathlib import Path
+from typing import Dict, List, Tuple
+
+# Section metadata from _sections.md
+SECTIONS = {
+ 'async': {
+ 'number': 1,
+ 'title': 'Eliminating Waterfalls',
+ 'impact': 'CRITICAL',
+ 'description': 'Waterfalls are the #1 performance killer. Each sequential await adds full network latency. Eliminating them yields the largest gains.'
+ },
+ 'bundle': {
+ 'number': 2,
+ 'title': 'Bundle Size Optimization',
+ 'impact': 'CRITICAL',
+ 'description': 'Reducing initial bundle size improves Time to Interactive and Largest Contentful Paint.'
+ },
+ 'server': {
+ 'number': 3,
+ 'title': 'Server-Side Performance',
+ 'impact': 'HIGH',
+ 'description': 'Optimizing server-side rendering and data fetching eliminates server-side waterfalls and reduces response times.'
+ },
+ 'client': {
+ 'number': 4,
+ 'title': 'Client-Side Data Fetching',
+ 'impact': 'MEDIUM-HIGH',
+ 'description': 'Automatic deduplication and efficient data fetching patterns reduce redundant network requests.'
+ },
+ 'rerender': {
+ 'number': 5,
+ 'title': 'Re-render Optimization',
+ 'impact': 'MEDIUM',
+ 'description': 'Reducing unnecessary re-renders minimizes wasted computation and improves UI responsiveness.'
+ },
+ 'rendering': {
+ 'number': 6,
+ 'title': 'Rendering Performance',
+ 'impact': 'MEDIUM',
+ 'description': 'Optimizing the rendering process reduces the work the browser needs to do.'
+ },
+ 'js': {
+ 'number': 7,
+ 'title': 'JavaScript Performance',
+ 'impact': 'LOW-MEDIUM',
+ 'description': 'Micro-optimizations for hot paths can add up to meaningful improvements.'
+ },
+ 'advanced': {
+ 'number': 8,
+ 'title': 'Advanced Patterns',
+ 'impact': 'VARIABLE',
+ 'description': 'Advanced patterns for specific cases that require careful implementation.'
+ }
+}
+
+
+def parse_frontmatter(content: str) -> Tuple[Dict, str]:
+ """Parse markdown frontmatter and body"""
+ if not content.startswith('---'):
+ return {}, content
+
+ parts = content.split('---', 2)
+ if len(parts) < 3:
+ return {}, content
+
+ # Parse YAML frontmatter manually (simple key: value)
+ frontmatter = {}
+ for line in parts[1].strip().split('\n'):
+ if ':' in line:
+ key, value = line.split(':', 1)
+ frontmatter[key.strip()] = value.strip()
+
+ body = parts[2].strip()
+ return frontmatter, body
+
+
+def parse_rule_file(filepath: Path) -> Dict:
+ """Parse a single rule file"""
+ with open(filepath, 'r', encoding='utf-8') as f:
+ content = f.read()
+
+ frontmatter, body = parse_frontmatter(content)
+
+ # Extract prefix from filename
+ filename = filepath.stem
+ prefix = filename.split('-')[0]
+
+ return {
+ 'filename': filepath.name,
+ 'prefix': prefix,
+ 'title': frontmatter.get('title', filename),
+ 'impact': frontmatter.get('impact', ''),
+ 'impactDescription': frontmatter.get('impactDescription', ''),
+ 'tags': frontmatter.get('tags', ''),
+ 'body': body,
+ 'frontmatter': frontmatter
+ }
+
+
+def group_rules_by_section(rules_dir: Path) -> Dict[str, List[Dict]]:
+ """Group all rules by their section prefix"""
+ grouped = {prefix: [] for prefix in SECTIONS.keys()}
+
+ for rule_file in sorted(rules_dir.glob('*.md')):
+ # Skip special files
+ if rule_file.name.startswith('_'):
+ continue
+
+ rule = parse_rule_file(rule_file)
+ prefix = rule['prefix']
+
+ if prefix in grouped:
+ grouped[prefix].append(rule)
+ else:
+ print(f"[WARNING] Unknown prefix '{prefix}' in file: {rule_file.name}")
+
+ return grouped
+
+
+def generate_section_file(section_prefix: str, rules: List[Dict], output_dir: Path):
+ """Generate a merged section file"""
+ if not rules:
+ print(f"[WARNING] No rules found for section: {section_prefix}")
+ return
+
+ section_meta = SECTIONS[section_prefix]
+ section_num = section_meta['number']
+ section_title = section_meta['title']
+ impact = section_meta['impact']
+ description = section_meta['description']
+
+ # Sort rules by title
+ rules.sort(key=lambda r: r['title'])
+
+ # Build content
+ content = f"""# {section_num}. {section_title}
+
+> **Impact:** {impact}
+> **Focus:** {description}
+
+---
+
+## Overview
+
+This section contains **{len(rules)} rules** focused on {section_title.lower()}.
+
+"""
+
+ # Add each rule
+ for i, rule in enumerate(rules, 1):
+ rule_id = f"{section_num}.{i}"
+ title = rule['title']
+ rule_impact = rule['impact']
+ tags = rule['tags']
+ body = rule['body']
+
+ content += f"""---
+
+## Rule {rule_id}: {title}
+
+"""
+
+ if rule_impact:
+ content += f"**Impact:** {rule_impact} \n"
+
+ if tags:
+ content += f"**Tags:** {tags} \n"
+
+ content += f"\n{body}\n\n"
+
+ # Write file
+ output_file = output_dir / f"{section_num}-{section_prefix}-{section_title.lower().replace(' ', '-')}.md"
+ output_file.write_text(content, encoding='utf-8')
+ print(f"[OK] Generated: {output_file.name} ({len(rules)} rules)")
+
+
+def main():
+ """Main conversion function"""
+ # Paths
+ base_dir = Path(__file__).parent.parent.parent.parent.parent
+ rules_dir = base_dir / "others/agent-skills/skills/react-best-practices/rules"
+ output_dir = base_dir / ".agent/skills/react-best-practices"
+
+ print(f"[*] Reading rules from: {rules_dir}")
+ print(f"[*] Output to: {output_dir}")
+ print()
+
+ # Check if rules directory exists
+ if not rules_dir.exists():
+ print(f"[ERROR] Rules directory not found: {rules_dir}")
+ return
+
+ # Group rules
+ print("[*] Grouping rules by section...")
+ grouped_rules = group_rules_by_section(rules_dir)
+
+ # Stats
+ total_rules = sum(len(rules) for rules in grouped_rules.values())
+ print(f"[*] Found {total_rules} total rules")
+ print()
+
+ # Generate section files
+ print("[*] Generating section files...")
+ for section_prefix in SECTIONS.keys():
+ rules = grouped_rules[section_prefix]
+ generate_section_file(section_prefix, rules, output_dir)
+
+ print()
+ print("[SUCCESS] Conversion complete!")
+ print(f"[*] Generated 8 section files from {total_rules} rules")
+
+
+if __name__ == '__main__':
+ main()
diff --git a/.agent/skills/nextjs-react-expert/scripts/react_performance_checker.py b/.agent/skills/nextjs-react-expert/scripts/react_performance_checker.py
new file mode 100644
index 0000000..b5595d5
--- /dev/null
+++ b/.agent/skills/nextjs-react-expert/scripts/react_performance_checker.py
@@ -0,0 +1,252 @@
+#!/usr/bin/env python3
+"""
+React Performance Checker
+Automated performance audit for React/Next.js projects
+Based on Vercel Engineering best practices
+"""
+
+import os
+import re
+import json
+from pathlib import Path
+from typing import List, Dict, Tuple
+
+class PerformanceChecker:
+ def __init__(self, project_path: str):
+ self.project_path = Path(project_path)
+ self.issues = []
+ self.warnings = []
+ self.passed = []
+
+ def check_waterfalls(self):
+ """Check for sequential await patterns (Section 1)"""
+ print("\n[*] Checking for waterfalls (sequential awaits)...")
+
+ for filepath in self.project_path.rglob('*.{ts,tsx,js,jsx}'):
+ if 'node_modules' in str(filepath):
+ continue
+
+ try:
+ content = filepath.read_text(encoding='utf-8')
+
+ # Pattern: multiple awaits in sequence without Promise.all
+ sequential_awaits = re.findall(r'await\s+\w+.*?\n\s*await\s+\w+', content)
+
+ if sequential_awaits:
+ self.issues.append({
+ 'file': str(filepath.relative_to(self.project_path)),
+ 'type': 'CRITICAL',
+ 'issue': 'Sequential awaits detected (waterfall)',
+ 'fix': 'Use Promise.all() for parallel fetching',
+ 'section': '1-async-eliminating-waterfalls.md'
+ })
+ except Exception as e:
+ continue
+
+ def check_barrel_imports(self):
+ """Check for barrel imports (Section 2)"""
+ print("[*] Checking for barrel imports...")
+
+ for filepath in self.project_path.rglob('*.{ts,tsx,js,jsx}'):
+ if 'node_modules' in str(filepath):
+ continue
+
+ try:
+ content = filepath.read_text(encoding='utf-8')
+
+ # Pattern: import from index files or barrel exports
+ barrel_imports = re.findall(r"import.*from\s+['\"](@/.*?)/index['\"]", content)
+ barrel_imports += re.findall(r"import.*from\s+['\"]\.\.?/.*?['\"](?!.*?\.tsx?)", content)
+
+ if barrel_imports:
+ self.warnings.append({
+ 'file': str(filepath.relative_to(self.project_path)),
+ 'type': 'CRITICAL',
+ 'issue': 'Potential barrel imports detected',
+ 'fix': 'Import directly from specific files',
+ 'section': '2-bundle-bundle-size-optimization.md'
+ })
+ except Exception as e:
+ continue
+
+ def check_dynamic_imports(self):
+ """Check if large components use dynamic imports (Section 2)"""
+ print("[*] Checking for missing dynamic imports...")
+
+ for filepath in self.project_path.rglob('*.{ts,tsx}'):
+ if 'node_modules' in str(filepath):
+ continue
+
+ try:
+ content = filepath.read_text(encoding='utf-8')
+
+ # Check file size - if > 10KB, should probably use dynamic import
+ if len(content) > 10000:
+ # Check if it's imported statically somewhere
+ filename = filepath.stem
+
+ # Search for static imports of this component
+ for check_file in self.project_path.rglob('*.{ts,tsx}'):
+ if check_file == filepath or 'node_modules' in str(check_file):
+ continue
+
+ check_content = check_file.read_text(encoding='utf-8')
+ if f"import {filename}" in check_content or f"import {{ {filename}" in check_content:
+ if 'dynamic(' not in check_content:
+ self.warnings.append({
+ 'file': str(check_file.relative_to(self.project_path)),
+ 'type': 'CRITICAL',
+ 'issue': f'Large component {filename} imported statically',
+ 'fix': 'Use dynamic() for code splitting',
+ 'section': '2-bundle-bundle-size-optimization.md'
+ })
+ break
+ except Exception as e:
+ continue
+
+ def check_useEffect_fetching(self):
+ """Check for data fetching in useEffect (Section 4)"""
+ print("[*] Checking for useEffect data fetching...")
+
+ for filepath in self.project_path.rglob('*.{ts,tsx}'):
+ if 'node_modules' in str(filepath):
+ continue
+
+ try:
+ content = filepath.read_text(encoding='utf-8')
+
+ # Pattern: fetch or axios in useEffect
+ if 'useEffect' in content:
+ if re.search(r'useEffect.*?fetch\(', content, re.DOTALL):
+ self.warnings.append({
+ 'file': str(filepath.relative_to(self.project_path)),
+ 'type': 'MEDIUM-HIGH',
+ 'issue': 'Data fetching in useEffect',
+ 'fix': 'Consider using SWR or React Query for deduplication',
+ 'section': '4-client-client-side-data-fetching.md'
+ })
+ except Exception as e:
+ continue
+
+ def check_missing_memoization(self):
+ """Check for missing React.memo, useMemo, useCallback (Section 5)"""
+ print("[*] Checking for missing memoization...")
+
+ for filepath in self.project_path.rglob('*.{tsx}'):
+ if 'node_modules' in str(filepath):
+ continue
+
+ try:
+ content = filepath.read_text(encoding='utf-8')
+
+ # Check for component definitions without memo
+ components = re.findall(r'(?:export\s+)?(?:const|function)\s+([A-Z]\w+)', content)
+
+ if components and 'React.memo' not in content and 'memo(' not in content:
+ # Check if component receives props
+ if 'props:' in content or 'Props>' in content:
+ self.warnings.append({
+ 'file': str(filepath.relative_to(self.project_path)),
+ 'type': 'MEDIUM',
+ 'issue': 'Component with props not memoized',
+ 'fix': 'Consider using React.memo if props are stable',
+ 'section': '5-rerender-re-render-optimization.md'
+ })
+ except Exception as e:
+ continue
+
+ def check_image_optimization(self):
+ """Check for unoptimized images (Section 6)"""
+ print("[*] Checking for image optimization...")
+
+ for filepath in self.project_path.rglob('*.{ts,tsx,js,jsx}'):
+ if 'node_modules' in str(filepath):
+ continue
+
+ try:
+ content = filepath.read_text(encoding='utf-8')
+
+ # Check for ![]()
tags instead of next/image
+ if ' instead of next/image',
+ 'fix': 'Use next/image for automatic optimization',
+ 'section': '6-rendering-rendering-performance.md'
+ })
+ except Exception as e:
+ continue
+
+ def generate_report(self):
+ """Generate final report"""
+ print("\n" + "="*60)
+ print("REACT PERFORMANCE AUDIT REPORT")
+ print("="*60)
+
+ print(f"\n[CRITICAL ISSUES] ({len([i for i in self.issues if i['type'] == 'CRITICAL'])})")
+ for issue in self.issues:
+ if issue['type'] == 'CRITICAL':
+ print(f" - {issue['file']}")
+ print(f" Issue: {issue['issue']}")
+ print(f" Fix: {issue['fix']}")
+ print(f" Reference: {issue['section']}\n")
+
+ print(f"\n[WARNINGS] ({len(self.warnings)})")
+ for warning in self.warnings[:10]: # Show first 10
+ print(f" - {warning['file']}")
+ print(f" Issue: {warning['issue']}")
+ print(f" Fix: {warning['fix']}")
+ print(f" Reference: {warning['section']}\n")
+
+ if len(self.warnings) > 10:
+ print(f" ... and {len(self.warnings) - 10} more warnings")
+
+ print("\n" + "="*60)
+ print(f"SUMMARY:")
+ print(f" Critical Issues: {len([i for i in self.issues if i['type'] == 'CRITICAL'])}")
+ print(f" Warnings: {len(self.warnings)}")
+ print("="*60)
+
+ if len(self.issues) == 0 and len(self.warnings) == 0:
+ print("\n[SUCCESS] No major performance issues detected!")
+ else:
+ print("\n[ACTION REQUIRED] Review and fix issues above")
+ print("Priority: CRITICAL > HIGH > MEDIUM > LOW")
+
+ def run(self):
+ """Run all checks"""
+ print("="*60)
+ print("React Performance Checker (Vercel Engineering)")
+ print("="*60)
+ print(f"Scanning: {self.project_path}")
+
+ self.check_waterfalls()
+ self.check_barrel_imports()
+ self.check_dynamic_imports()
+ self.check_useEffect_fetching()
+ self.check_missing_memoization()
+ self.check_image_optimization()
+
+ self.generate_report()
+
+
+def main():
+ import sys
+
+ if len(sys.argv) < 2:
+ print("Usage: python react_performance_checker.py ")
+ sys.exit(1)
+
+ project_path = sys.argv[1]
+
+ if not os.path.exists(project_path):
+ print(f"[ERROR] Path not found: {project_path}")
+ sys.exit(1)
+
+ checker = PerformanceChecker(project_path)
+ checker.run()
+
+
+if __name__ == '__main__':
+ main()
diff --git a/.agent/skills/nodejs-best-practices/SKILL.md b/.agent/skills/nodejs-best-practices/SKILL.md
new file mode 100644
index 0000000..f5abcac
--- /dev/null
+++ b/.agent/skills/nodejs-best-practices/SKILL.md
@@ -0,0 +1,333 @@
+---
+name: nodejs-best-practices
+description: Node.js development principles and decision-making. Framework selection, async patterns, security, and architecture. Teaches thinking, not copying.
+allowed-tools: Read, Write, Edit, Glob, Grep
+---
+
+# Node.js Best Practices
+
+> Principles and decision-making for Node.js development in 2025.
+> **Learn to THINK, not memorize code patterns.**
+
+---
+
+## ⚠️ How to Use This Skill
+
+This skill teaches **decision-making principles**, not fixed code to copy.
+
+- ASK user for preferences when unclear
+- Choose framework/pattern based on CONTEXT
+- Don't default to same solution every time
+
+---
+
+## 1. Framework Selection (2025)
+
+### Decision Tree
+
+```
+What are you building?
+│
+├── Edge/Serverless (Cloudflare, Vercel)
+│ └── Hono (zero-dependency, ultra-fast cold starts)
+│
+├── High Performance API
+│ └── Fastify (2-3x faster than Express)
+│
+├── Enterprise/Team familiarity
+│ └── NestJS (structured, DI, decorators)
+│
+├── Legacy/Stable/Maximum ecosystem
+│ └── Express (mature, most middleware)
+│
+└── Full-stack with frontend
+ └── Next.js API Routes or tRPC
+```
+
+### Comparison Principles
+
+| Factor | Hono | Fastify | Express |
+|--------|------|---------|---------|
+| **Best for** | Edge, serverless | Performance | Legacy, learning |
+| **Cold start** | Fastest | Fast | Moderate |
+| **Ecosystem** | Growing | Good | Largest |
+| **TypeScript** | Native | Excellent | Good |
+| **Learning curve** | Low | Medium | Low |
+
+### Selection Questions to Ask:
+1. What's the deployment target?
+2. Is cold start time critical?
+3. Does team have existing experience?
+4. Is there legacy code to maintain?
+
+---
+
+## 2. Runtime Considerations (2025)
+
+### Native TypeScript
+
+```
+Node.js 22+: --experimental-strip-types
+├── Run .ts files directly
+├── No build step needed for simple projects
+└── Consider for: scripts, simple APIs
+```
+
+### Module System Decision
+
+```
+ESM (import/export)
+├── Modern standard
+├── Better tree-shaking
+├── Async module loading
+└── Use for: new projects
+
+CommonJS (require)
+├── Legacy compatibility
+├── More npm packages support
+└── Use for: existing codebases, some edge cases
+```
+
+### Runtime Selection
+
+| Runtime | Best For |
+|---------|----------|
+| **Node.js** | General purpose, largest ecosystem |
+| **Bun** | Performance, built-in bundler |
+| **Deno** | Security-first, built-in TypeScript |
+
+---
+
+## 3. Architecture Principles
+
+### Layered Structure Concept
+
+```
+Request Flow:
+│
+├── Controller/Route Layer
+│ ├── Handles HTTP specifics
+│ ├── Input validation at boundary
+│ └── Calls service layer
+│
+├── Service Layer
+│ ├── Business logic
+│ ├── Framework-agnostic
+│ └── Calls repository layer
+│
+└── Repository Layer
+ ├── Data access only
+ ├── Database queries
+ └── ORM interactions
+```
+
+### Why This Matters:
+- **Testability**: Mock layers independently
+- **Flexibility**: Swap database without touching business logic
+- **Clarity**: Each layer has single responsibility
+
+### When to Simplify:
+- Small scripts → Single file OK
+- Prototypes → Less structure acceptable
+- Always ask: "Will this grow?"
+
+---
+
+## 4. Error Handling Principles
+
+### Centralized Error Handling
+
+```
+Pattern:
+├── Create custom error classes
+├── Throw from any layer
+├── Catch at top level (middleware)
+└── Format consistent response
+```
+
+### Error Response Philosophy
+
+```
+Client gets:
+├── Appropriate HTTP status
+├── Error code for programmatic handling
+├── User-friendly message
+└── NO internal details (security!)
+
+Logs get:
+├── Full stack trace
+├── Request context
+├── User ID (if applicable)
+└── Timestamp
+```
+
+### Status Code Selection
+
+| Situation | Status | When |
+|-----------|--------|------|
+| Bad input | 400 | Client sent invalid data |
+| No auth | 401 | Missing or invalid credentials |
+| No permission | 403 | Valid auth, but not allowed |
+| Not found | 404 | Resource doesn't exist |
+| Conflict | 409 | Duplicate or state conflict |
+| Validation | 422 | Schema valid but business rules fail |
+| Server error | 500 | Our fault, log everything |
+
+---
+
+## 5. Async Patterns Principles
+
+### When to Use Each
+
+| Pattern | Use When |
+|---------|----------|
+| `async/await` | Sequential async operations |
+| `Promise.all` | Parallel independent operations |
+| `Promise.allSettled` | Parallel where some can fail |
+| `Promise.race` | Timeout or first response wins |
+
+### Event Loop Awareness
+
+```
+I/O-bound (async helps):
+├── Database queries
+├── HTTP requests
+├── File system
+└── Network operations
+
+CPU-bound (async doesn't help):
+├── Crypto operations
+├── Image processing
+├── Complex calculations
+└── → Use worker threads or offload
+```
+
+### Avoiding Event Loop Blocking
+
+- Never use sync methods in production (fs.readFileSync, etc.)
+- Offload CPU-intensive work
+- Use streaming for large data
+
+---
+
+## 6. Validation Principles
+
+### Validate at Boundaries
+
+```
+Where to validate:
+├── API entry point (request body/params)
+├── Before database operations
+├── External data (API responses, file uploads)
+└── Environment variables (startup)
+```
+
+### Validation Library Selection
+
+| Library | Best For |
+|---------|----------|
+| **Zod** | TypeScript first, inference |
+| **Valibot** | Smaller bundle (tree-shakeable) |
+| **ArkType** | Performance critical |
+| **Yup** | Existing React Form usage |
+
+### Validation Philosophy
+
+- Fail fast: Validate early
+- Be specific: Clear error messages
+- Don't trust: Even "internal" data
+
+---
+
+## 7. Security Principles
+
+### Security Checklist (Not Code)
+
+- [ ] **Input validation**: All inputs validated
+- [ ] **Parameterized queries**: No string concatenation for SQL
+- [ ] **Password hashing**: bcrypt or argon2
+- [ ] **JWT verification**: Always verify signature and expiry
+- [ ] **Rate limiting**: Protect from abuse
+- [ ] **Security headers**: Helmet.js or equivalent
+- [ ] **HTTPS**: Everywhere in production
+- [ ] **CORS**: Properly configured
+- [ ] **Secrets**: Environment variables only
+- [ ] **Dependencies**: Regularly audited
+
+### Security Mindset
+
+```
+Trust nothing:
+├── Query params → validate
+├── Request body → validate
+├── Headers → verify
+├── Cookies → validate
+├── File uploads → scan
+└── External APIs → validate response
+```
+
+---
+
+## 8. Testing Principles
+
+### Test Strategy Selection
+
+| Type | Purpose | Tools |
+|------|---------|-------|
+| **Unit** | Business logic | node:test, Vitest |
+| **Integration** | API endpoints | Supertest |
+| **E2E** | Full flows | Playwright |
+
+### What to Test (Priorities)
+
+1. **Critical paths**: Auth, payments, core business
+2. **Edge cases**: Empty inputs, boundaries
+3. **Error handling**: What happens when things fail?
+4. **Not worth testing**: Framework code, trivial getters
+
+### Built-in Test Runner (Node.js 22+)
+
+```
+node --test src/**/*.test.ts
+├── No external dependency
+├── Good coverage reporting
+└── Watch mode available
+```
+
+---
+
+## 10. Anti-Patterns to Avoid
+
+### ❌ DON'T:
+- Use Express for new edge projects (use Hono)
+- Use sync methods in production code
+- Put business logic in controllers
+- Skip input validation
+- Hardcode secrets
+- Trust external data without validation
+- Block event loop with CPU work
+
+### ✅ DO:
+- Choose framework based on context
+- Ask user for preferences when unclear
+- Use layered architecture for growing projects
+- Validate all inputs
+- Use environment variables for secrets
+- Profile before optimizing
+
+---
+
+## 11. Decision Checklist
+
+Before implementing:
+
+- [ ] **Asked user about stack preference?**
+- [ ] **Chosen framework for THIS context?** (not just default)
+- [ ] **Considered deployment target?**
+- [ ] **Planned error handling strategy?**
+- [ ] **Identified validation points?**
+- [ ] **Considered security requirements?**
+
+---
+
+> **Remember**: Node.js best practices are about decision-making, not memorizing patterns. Every project deserves fresh consideration based on its requirements.
diff --git a/.agent/skills/parallel-agents/SKILL.md b/.agent/skills/parallel-agents/SKILL.md
new file mode 100644
index 0000000..4b00596
--- /dev/null
+++ b/.agent/skills/parallel-agents/SKILL.md
@@ -0,0 +1,175 @@
+---
+name: parallel-agents
+description: Multi-agent orchestration patterns. Use when multiple independent tasks can run with different domain expertise or when comprehensive analysis requires multiple perspectives.
+allowed-tools: Read, Glob, Grep
+---
+
+# Native Parallel Agents
+
+> Orchestration through Antigravity's built-in Agent Tool
+
+## Overview
+
+This skill enables coordinating multiple specialized agents through Antigravity's native agent system. Unlike external scripts, this approach keeps all orchestration within Antigravity's control.
+
+## When to Use Orchestration
+
+✅ **Good for:**
+- Complex tasks requiring multiple expertise domains
+- Code analysis from security, performance, and quality perspectives
+- Comprehensive reviews (architecture + security + testing)
+- Feature implementation needing backend + frontend + database work
+
+❌ **Not for:**
+- Simple, single-domain tasks
+- Quick fixes or small changes
+- Tasks where one agent suffices
+
+---
+
+## Native Agent Invocation
+
+### Single Agent
+```
+Use the security-auditor agent to review authentication
+```
+
+### Sequential Chain
+```
+First, use the explorer-agent to discover project structure.
+Then, use the backend-specialist to review API endpoints.
+Finally, use the test-engineer to identify test gaps.
+```
+
+### With Context Passing
+```
+Use the frontend-specialist to analyze React components.
+Based on those findings, have the test-engineer generate component tests.
+```
+
+### Resume Previous Work
+```
+Resume agent [agentId] and continue with additional requirements.
+```
+
+---
+
+## Orchestration Patterns
+
+### Pattern 1: Comprehensive Analysis
+```
+Agents: explorer-agent → [domain-agents] → synthesis
+
+1. explorer-agent: Map codebase structure
+2. security-auditor: Security posture
+3. backend-specialist: API quality
+4. frontend-specialist: UI/UX patterns
+5. test-engineer: Test coverage
+6. Synthesize all findings
+```
+
+### Pattern 2: Feature Review
+```
+Agents: affected-domain-agents → test-engineer
+
+1. Identify affected domains (backend? frontend? both?)
+2. Invoke relevant domain agents
+3. test-engineer verifies changes
+4. Synthesize recommendations
+```
+
+### Pattern 3: Security Audit
+```
+Agents: security-auditor → penetration-tester → synthesis
+
+1. security-auditor: Configuration and code review
+2. penetration-tester: Active vulnerability testing
+3. Synthesize with prioritized remediation
+```
+
+---
+
+## Available Agents
+
+| Agent | Expertise | Trigger Phrases |
+|-------|-----------|-----------------|
+| `orchestrator` | Coordination | "comprehensive", "multi-perspective" |
+| `security-auditor` | Security | "security", "auth", "vulnerabilities" |
+| `penetration-tester` | Security Testing | "pentest", "red team", "exploit" |
+| `backend-specialist` | Backend | "API", "server", "Node.js", "Express" |
+| `frontend-specialist` | Frontend | "React", "UI", "components", "Next.js" |
+| `test-engineer` | Testing | "tests", "coverage", "TDD" |
+| `devops-engineer` | DevOps | "deploy", "CI/CD", "infrastructure" |
+| `database-architect` | Database | "schema", "Prisma", "migrations" |
+| `mobile-developer` | Mobile | "React Native", "Flutter", "mobile" |
+| `api-designer` | API Design | "REST", "GraphQL", "OpenAPI" |
+| `debugger` | Debugging | "bug", "error", "not working" |
+| `explorer-agent` | Discovery | "explore", "map", "structure" |
+| `documentation-writer` | Documentation | "write docs", "create README", "generate API docs" |
+| `performance-optimizer` | Performance | "slow", "optimize", "profiling" |
+| `project-planner` | Planning | "plan", "roadmap", "milestones" |
+| `seo-specialist` | SEO | "SEO", "meta tags", "search ranking" |
+| `game-developer` | Game Development | "game", "Unity", "Godot", "Phaser" |
+
+---
+
+## Antigravity Built-in Agents
+
+These work alongside custom agents:
+
+| Agent | Model | Purpose |
+|-------|-------|---------|
+| **Explore** | Haiku | Fast read-only codebase search |
+| **Plan** | Sonnet | Research during plan mode |
+| **General-purpose** | Sonnet | Complex multi-step modifications |
+
+Use **Explore** for quick searches, **custom agents** for domain expertise.
+
+---
+
+## Synthesis Protocol
+
+After all agents complete, synthesize:
+
+```markdown
+## Orchestration Synthesis
+
+### Task Summary
+[What was accomplished]
+
+### Agent Contributions
+| Agent | Finding |
+|-------|---------|
+| security-auditor | Found X |
+| backend-specialist | Identified Y |
+
+### Consolidated Recommendations
+1. **Critical**: [Issue from Agent A]
+2. **Important**: [Issue from Agent B]
+3. **Nice-to-have**: [Enhancement from Agent C]
+
+### Action Items
+- [ ] Fix critical security issue
+- [ ] Refactor API endpoint
+- [ ] Add missing tests
+```
+
+---
+
+## Best Practices
+
+1. **Available agents** - 17 specialized agents can be orchestrated
+2. **Logical order** - Discovery → Analysis → Implementation → Testing
+3. **Share context** - Pass relevant findings to subsequent agents
+4. **Single synthesis** - One unified report, not separate outputs
+5. **Verify changes** - Always include test-engineer for code modifications
+
+---
+
+## Key Benefits
+
+- ✅ **Single session** - All agents share context
+- ✅ **AI-controlled** - Claude orchestrates autonomously
+- ✅ **Native integration** - Works with built-in Explore, Plan agents
+- ✅ **Resume support** - Can continue previous agent work
+- ✅ **Context passing** - Findings flow between agents
diff --git a/.agent/skills/performance-profiling/SKILL.md b/.agent/skills/performance-profiling/SKILL.md
new file mode 100644
index 0000000..9292156
--- /dev/null
+++ b/.agent/skills/performance-profiling/SKILL.md
@@ -0,0 +1,143 @@
+---
+name: performance-profiling
+description: Performance profiling principles. Measurement, analysis, and optimization techniques.
+allowed-tools: Read, Glob, Grep, Bash
+---
+
+# Performance Profiling
+
+> Measure, analyze, optimize - in that order.
+
+## 🔧 Runtime Scripts
+
+**Execute these for automated profiling:**
+
+| Script | Purpose | Usage |
+|--------|---------|-------|
+| `scripts/lighthouse_audit.py` | Lighthouse performance audit | `python scripts/lighthouse_audit.py https://example.com` |
+
+---
+
+## 1. Core Web Vitals
+
+### Targets
+
+| Metric | Good | Poor | Measures |
+|--------|------|------|----------|
+| **LCP** | < 2.5s | > 4.0s | Loading |
+| **INP** | < 200ms | > 500ms | Interactivity |
+| **CLS** | < 0.1 | > 0.25 | Stability |
+
+### When to Measure
+
+| Stage | Tool |
+|-------|------|
+| Development | Local Lighthouse |
+| CI/CD | Lighthouse CI |
+| Production | RUM (Real User Monitoring) |
+
+---
+
+## 2. Profiling Workflow
+
+### The 4-Step Process
+
+```
+1. BASELINE → Measure current state
+2. IDENTIFY → Find the bottleneck
+3. FIX → Make targeted change
+4. VALIDATE → Confirm improvement
+```
+
+### Profiling Tool Selection
+
+| Problem | Tool |
+|---------|------|
+| Page load | Lighthouse |
+| Bundle size | Bundle analyzer |
+| Runtime | DevTools Performance |
+| Memory | DevTools Memory |
+| Network | DevTools Network |
+
+---
+
+## 3. Bundle Analysis
+
+### What to Look For
+
+| Issue | Indicator |
+|-------|-----------|
+| Large dependencies | Top of bundle |
+| Duplicate code | Multiple chunks |
+| Unused code | Low coverage |
+| Missing splits | Single large chunk |
+
+### Optimization Actions
+
+| Finding | Action |
+|---------|--------|
+| Big library | Import specific modules |
+| Duplicate deps | Dedupe, update versions |
+| Route in main | Code split |
+| Unused exports | Tree shake |
+
+---
+
+## 4. Runtime Profiling
+
+### Performance Tab Analysis
+
+| Pattern | Meaning |
+|---------|---------|
+| Long tasks (>50ms) | UI blocking |
+| Many small tasks | Possible batching opportunity |
+| Layout/paint | Rendering bottleneck |
+| Script | JavaScript execution |
+
+### Memory Tab Analysis
+
+| Pattern | Meaning |
+|---------|---------|
+| Growing heap | Possible leak |
+| Large retained | Check references |
+| Detached DOM | Not cleaned up |
+
+---
+
+## 5. Common Bottlenecks
+
+### By Symptom
+
+| Symptom | Likely Cause |
+|---------|--------------|
+| Slow initial load | Large JS, render blocking |
+| Slow interactions | Heavy event handlers |
+| Jank during scroll | Layout thrashing |
+| Growing memory | Leaks, retained refs |
+
+---
+
+## 6. Quick Win Priorities
+
+| Priority | Action | Impact |
+|----------|--------|--------|
+| 1 | Enable compression | High |
+| 2 | Lazy load images | High |
+| 3 | Code split routes | High |
+| 4 | Cache static assets | Medium |
+| 5 | Optimize images | Medium |
+
+---
+
+## 7. Anti-Patterns
+
+| ❌ Don't | ✅ Do |
+|----------|-------|
+| Guess at problems | Profile first |
+| Micro-optimize | Fix biggest issue |
+| Optimize early | Optimize when needed |
+| Ignore real users | Use RUM data |
+
+---
+
+> **Remember:** The fastest code is code that doesn't run. Remove before optimizing.
diff --git a/.agent/skills/performance-profiling/scripts/lighthouse_audit.py b/.agent/skills/performance-profiling/scripts/lighthouse_audit.py
new file mode 100644
index 0000000..04e2467
--- /dev/null
+++ b/.agent/skills/performance-profiling/scripts/lighthouse_audit.py
@@ -0,0 +1,76 @@
+#!/usr/bin/env python3
+"""
+Skill: performance-profiling
+Script: lighthouse_audit.py
+Purpose: Run Lighthouse performance audit on a URL
+Usage: python lighthouse_audit.py https://example.com
+Output: JSON with performance scores
+Note: Requires lighthouse CLI (npm install -g lighthouse)
+"""
+import subprocess
+import json
+import sys
+import os
+import tempfile
+
+def run_lighthouse(url: str) -> dict:
+ """Run Lighthouse audit on URL."""
+ try:
+ with tempfile.NamedTemporaryFile(suffix='.json', delete=False) as f:
+ output_path = f.name
+
+ result = subprocess.run(
+ [
+ "lighthouse",
+ url,
+ "--output=json",
+ f"--output-path={output_path}",
+ "--chrome-flags=--headless",
+ "--only-categories=performance,accessibility,best-practices,seo"
+ ],
+ capture_output=True,
+ text=True,
+ timeout=120
+ )
+
+ if os.path.exists(output_path):
+ with open(output_path, 'r') as f:
+ report = json.load(f)
+ os.unlink(output_path)
+
+ categories = report.get("categories", {})
+ return {
+ "url": url,
+ "scores": {
+ "performance": int(categories.get("performance", {}).get("score", 0) * 100),
+ "accessibility": int(categories.get("accessibility", {}).get("score", 0) * 100),
+ "best_practices": int(categories.get("best-practices", {}).get("score", 0) * 100),
+ "seo": int(categories.get("seo", {}).get("score", 0) * 100)
+ },
+ "summary": get_summary(categories)
+ }
+ else:
+ return {"error": "Lighthouse failed to generate report", "stderr": result.stderr[:500]}
+
+ except subprocess.TimeoutExpired:
+ return {"error": "Lighthouse audit timed out"}
+ except FileNotFoundError:
+ return {"error": "Lighthouse CLI not found. Install with: npm install -g lighthouse"}
+
+def get_summary(categories: dict) -> str:
+ """Generate summary based on scores."""
+ perf = categories.get("performance", {}).get("score", 0) * 100
+ if perf >= 90:
+ return "[OK] Excellent performance"
+ elif perf >= 50:
+ return "[!] Needs improvement"
+ else:
+ return "[X] Poor performance"
+
+if __name__ == "__main__":
+ if len(sys.argv) < 2:
+ print(json.dumps({"error": "Usage: python lighthouse_audit.py "}))
+ sys.exit(1)
+
+ result = run_lighthouse(sys.argv[1])
+ print(json.dumps(result, indent=2))
diff --git a/.agent/skills/plan-writing/SKILL.md b/.agent/skills/plan-writing/SKILL.md
new file mode 100644
index 0000000..f4a4f60
--- /dev/null
+++ b/.agent/skills/plan-writing/SKILL.md
@@ -0,0 +1,152 @@
+---
+name: plan-writing
+description: Structured task planning with clear breakdowns, dependencies, and verification criteria. Use when implementing features, refactoring, or any multi-step work.
+allowed-tools: Read, Glob, Grep
+---
+
+# Plan Writing
+
+> Source: obra/superpowers
+
+## Overview
+This skill provides a framework for breaking down work into clear, actionable tasks with verification criteria.
+
+## Task Breakdown Principles
+
+### 1. Small, Focused Tasks
+- Each task should take 2-5 minutes
+- One clear outcome per task
+- Independently verifiable
+
+### 2. Clear Verification
+- How do you know it's done?
+- What can you check/test?
+- What's the expected output?
+
+### 3. Logical Ordering
+- Dependencies identified
+- Parallel work where possible
+- Critical path highlighted
+- **Phase X: Verification is always LAST**
+
+### 4. Dynamic Naming in Project Root
+- Plan files are saved as `{task-slug}.md` in the PROJECT ROOT
+- Name derived from task (e.g., "add auth" → `auth-feature.md`)
+- **NEVER** inside `.claude/`, `docs/`, or temp folders
+
+## Planning Principles (NOT Templates!)
+
+> 🔴 **NO fixed templates. Each plan is UNIQUE to the task.**
+
+### Principle 1: Keep It SHORT
+
+| ❌ Wrong | ✅ Right |
+|----------|----------|
+| 50 tasks with sub-sub-tasks | 5-10 clear tasks max |
+| Every micro-step listed | Only actionable items |
+| Verbose descriptions | One-line per task |
+
+> **Rule:** If plan is longer than 1 page, it's too long. Simplify.
+
+---
+
+### Principle 2: Be SPECIFIC, Not Generic
+
+| ❌ Wrong | ✅ Right |
+|----------|----------|
+| "Set up project" | "Run `npx create-next-app`" |
+| "Add authentication" | "Install next-auth, create `/api/auth/[...nextauth].ts`" |
+| "Style the UI" | "Add Tailwind classes to `Header.tsx`" |
+
+> **Rule:** Each task should have a clear, verifiable outcome.
+
+---
+
+### Principle 3: Dynamic Content Based on Project Type
+
+**For NEW PROJECT:**
+- What tech stack? (decide first)
+- What's the MVP? (minimal features)
+- What's the file structure?
+
+**For FEATURE ADDITION:**
+- Which files are affected?
+- What dependencies needed?
+- How to verify it works?
+
+**For BUG FIX:**
+- What's the root cause?
+- What file/line to change?
+- How to test the fix?
+
+---
+
+### Principle 4: Scripts Are Project-Specific
+
+> 🔴 **DO NOT copy-paste script commands. Choose based on project type.**
+
+| Project Type | Relevant Scripts |
+|--------------|------------------|
+| Frontend/React | `ux_audit.py`, `accessibility_checker.py` |
+| Backend/API | `api_validator.py`, `security_scan.py` |
+| Mobile | `mobile_audit.py` |
+| Database | `schema_validator.py` |
+| Full-stack | Mix of above based on what you touched |
+
+**Wrong:** Adding all scripts to every plan
+**Right:** Only scripts relevant to THIS task
+
+---
+
+### Principle 5: Verification is Simple
+
+| ❌ Wrong | ✅ Right |
+|----------|----------|
+| "Verify the component works correctly" | "Run `npm run dev`, click button, see toast" |
+| "Test the API" | "curl localhost:3000/api/users returns 200" |
+| "Check styles" | "Open browser, verify dark mode toggle works" |
+
+---
+
+## Plan Structure (Flexible, Not Fixed!)
+
+```
+# [Task Name]
+
+## Goal
+One sentence: What are we building/fixing?
+
+## Tasks
+- [ ] Task 1: [Specific action] → Verify: [How to check]
+- [ ] Task 2: [Specific action] → Verify: [How to check]
+- [ ] Task 3: [Specific action] → Verify: [How to check]
+
+## Done When
+- [ ] [Main success criteria]
+```
+
+> **That's it.** No phases, no sub-sections unless truly needed.
+> Keep it minimal. Add complexity only when required.
+
+## Notes
+[Any important considerations]
+```
+
+---
+
+## Best Practices (Quick Reference)
+
+1. **Start with goal** - What are we building/fixing?
+2. **Max 10 tasks** - If more, break into multiple plans
+3. **Each task verifiable** - Clear "done" criteria
+4. **Project-specific** - No copy-paste templates
+5. **Update as you go** - Mark `[x]` when complete
+
+---
+
+## When to Use
+
+- New project from scratch
+- Adding a feature
+- Fixing a bug (if complex)
+- Refactoring multiple files
diff --git a/.agent/skills/powershell-windows/SKILL.md b/.agent/skills/powershell-windows/SKILL.md
new file mode 100644
index 0000000..1b0459c
--- /dev/null
+++ b/.agent/skills/powershell-windows/SKILL.md
@@ -0,0 +1,167 @@
+---
+name: powershell-windows
+description: PowerShell Windows patterns. Critical pitfalls, operator syntax, error handling.
+allowed-tools: Read, Write, Edit, Glob, Grep, Bash
+---
+
+# PowerShell Windows Patterns
+
+> Critical patterns and pitfalls for Windows PowerShell.
+
+---
+
+## 1. Operator Syntax Rules
+
+### CRITICAL: Parentheses Required
+
+| ❌ Wrong | ✅ Correct |
+|----------|-----------|
+| `if (Test-Path "a" -or Test-Path "b")` | `if ((Test-Path "a") -or (Test-Path "b"))` |
+| `if (Get-Item $x -and $y -eq 5)` | `if ((Get-Item $x) -and ($y -eq 5))` |
+
+**Rule:** Each cmdlet call MUST be in parentheses when using logical operators.
+
+---
+
+## 2. Unicode/Emoji Restriction
+
+### CRITICAL: No Unicode in Scripts
+
+| Purpose | ❌ Don't Use | ✅ Use |
+|---------|-------------|--------|
+| Success | ✅ ✓ | [OK] [+] |
+| Error | ❌ ✗ 🔴 | [!] [X] |
+| Warning | ⚠️ 🟡 | [*] [WARN] |
+| Info | ℹ️ 🔵 | [i] [INFO] |
+| Progress | ⏳ | [...] |
+
+**Rule:** Use ASCII characters only in PowerShell scripts.
+
+---
+
+## 3. Null Check Patterns
+
+### Always Check Before Access
+
+| ❌ Wrong | ✅ Correct |
+|----------|-----------|
+| `$array.Count -gt 0` | `$array -and $array.Count -gt 0` |
+| `$text.Length` | `if ($text) { $text.Length }` |
+
+---
+
+## 4. String Interpolation
+
+### Complex Expressions
+
+| ❌ Wrong | ✅ Correct |
+|----------|-----------|
+| `"Value: $($obj.prop.sub)"` | Store in variable first |
+
+**Pattern:**
+```
+$value = $obj.prop.sub
+Write-Output "Value: $value"
+```
+
+---
+
+## 5. Error Handling
+
+### ErrorActionPreference
+
+| Value | Use |
+|-------|-----|
+| Stop | Development (fail fast) |
+| Continue | Production scripts |
+| SilentlyContinue | When errors expected |
+
+### Try/Catch Pattern
+
+- Don't return inside try block
+- Use finally for cleanup
+- Return after try/catch
+
+---
+
+## 6. File Paths
+
+### Windows Path Rules
+
+| Pattern | Use |
+|---------|-----|
+| Literal path | `C:\Users\User\file.txt` |
+| Variable path | `Join-Path $env:USERPROFILE "file.txt"` |
+| Relative | `Join-Path $ScriptDir "data"` |
+
+**Rule:** Use Join-Path for cross-platform safety.
+
+---
+
+## 7. Array Operations
+
+### Correct Patterns
+
+| Operation | Syntax |
+|-----------|--------|
+| Empty array | `$array = @()` |
+| Add item | `$array += $item` |
+| ArrayList add | `$list.Add($item) | Out-Null` |
+
+---
+
+## 8. JSON Operations
+
+### CRITICAL: Depth Parameter
+
+| ❌ Wrong | ✅ Correct |
+|----------|-----------|
+| `ConvertTo-Json` | `ConvertTo-Json -Depth 10` |
+
+**Rule:** Always specify `-Depth` for nested objects.
+
+### File Operations
+
+| Operation | Pattern |
+|-----------|---------|
+| Read | `Get-Content "file.json" -Raw | ConvertFrom-Json` |
+| Write | `$data | ConvertTo-Json -Depth 10 | Out-File "file.json" -Encoding UTF8` |
+
+---
+
+## 9. Common Errors
+
+| Error Message | Cause | Fix |
+|---------------|-------|-----|
+| "parameter 'or'" | Missing parentheses | Wrap cmdlets in () |
+| "Unexpected token" | Unicode character | Use ASCII only |
+| "Cannot find property" | Null object | Check null first |
+| "Cannot convert" | Type mismatch | Use .ToString() |
+
+---
+
+## 10. Script Template
+
+```powershell
+# Strict mode
+Set-StrictMode -Version Latest
+$ErrorActionPreference = "Continue"
+
+# Paths
+$ScriptDir = Split-Path -Parent $MyInvocation.MyCommand.Path
+
+# Main
+try {
+ # Logic here
+ Write-Output "[OK] Done"
+ exit 0
+}
+catch {
+ Write-Warning "Error: $_"
+ exit 1
+}
+```
+
+---
+
+> **Remember:** PowerShell has unique syntax rules. Parentheses, ASCII-only, and null checks are non-negotiable.
diff --git a/.agent/skills/python-patterns/SKILL.md b/.agent/skills/python-patterns/SKILL.md
new file mode 100644
index 0000000..164e31c
--- /dev/null
+++ b/.agent/skills/python-patterns/SKILL.md
@@ -0,0 +1,441 @@
+---
+name: python-patterns
+description: Python development principles and decision-making. Framework selection, async patterns, type hints, project structure. Teaches thinking, not copying.
+allowed-tools: Read, Write, Edit, Glob, Grep
+---
+
+# Python Patterns
+
+> Python development principles and decision-making for 2025.
+> **Learn to THINK, not memorize patterns.**
+
+---
+
+## ⚠️ How to Use This Skill
+
+This skill teaches **decision-making principles**, not fixed code to copy.
+
+- ASK user for framework preference when unclear
+- Choose async vs sync based on CONTEXT
+- Don't default to same framework every time
+
+---
+
+## 1. Framework Selection (2025)
+
+### Decision Tree
+
+```
+What are you building?
+│
+├── API-first / Microservices
+│ └── FastAPI (async, modern, fast)
+│
+├── Full-stack web / CMS / Admin
+│ └── Django (batteries-included)
+│
+├── Simple / Script / Learning
+│ └── Flask (minimal, flexible)
+│
+├── AI/ML API serving
+│ └── FastAPI (Pydantic, async, uvicorn)
+│
+└── Background workers
+ └── Celery + any framework
+```
+
+### Comparison Principles
+
+| Factor | FastAPI | Django | Flask |
+|--------|---------|--------|-------|
+| **Best for** | APIs, microservices | Full-stack, CMS | Simple, learning |
+| **Async** | Native | Django 5.0+ | Via extensions |
+| **Admin** | Manual | Built-in | Via extensions |
+| **ORM** | Choose your own | Django ORM | Choose your own |
+| **Learning curve** | Low | Medium | Low |
+
+### Selection Questions to Ask:
+1. Is this API-only or full-stack?
+2. Need admin interface?
+3. Team familiar with async?
+4. Existing infrastructure?
+
+---
+
+## 2. Async vs Sync Decision
+
+### When to Use Async
+
+```
+async def is better when:
+├── I/O-bound operations (database, HTTP, file)
+├── Many concurrent connections
+├── Real-time features
+├── Microservices communication
+└── FastAPI/Starlette/Django ASGI
+
+def (sync) is better when:
+├── CPU-bound operations
+├── Simple scripts
+├── Legacy codebase
+├── Team unfamiliar with async
+└── Blocking libraries (no async version)
+```
+
+### The Golden Rule
+
+```
+I/O-bound → async (waiting for external)
+CPU-bound → sync + multiprocessing (computing)
+
+Don't:
+├── Mix sync and async carelessly
+├── Use sync libraries in async code
+└── Force async for CPU work
+```
+
+### Async Library Selection
+
+| Need | Async Library |
+|------|---------------|
+| HTTP client | httpx |
+| PostgreSQL | asyncpg |
+| Redis | aioredis / redis-py async |
+| File I/O | aiofiles |
+| Database ORM | SQLAlchemy 2.0 async, Tortoise |
+
+---
+
+## 3. Type Hints Strategy
+
+### When to Type
+
+```
+Always type:
+├── Function parameters
+├── Return types
+├── Class attributes
+├── Public APIs
+
+Can skip:
+├── Local variables (let inference work)
+├── One-off scripts
+├── Tests (usually)
+```
+
+### Common Type Patterns
+
+```python
+# These are patterns, understand them:
+
+# Optional → might be None
+from typing import Optional
+def find_user(id: int) -> Optional[User]: ...
+
+# Union → one of multiple types
+def process(data: str | dict) -> None: ...
+
+# Generic collections
+def get_items() -> list[Item]: ...
+def get_mapping() -> dict[str, int]: ...
+
+# Callable
+from typing import Callable
+def apply(fn: Callable[[int], str]) -> str: ...
+```
+
+### Pydantic for Validation
+
+```
+When to use Pydantic:
+├── API request/response models
+├── Configuration/settings
+├── Data validation
+├── Serialization
+
+Benefits:
+├── Runtime validation
+├── Auto-generated JSON schema
+├── Works with FastAPI natively
+└── Clear error messages
+```
+
+---
+
+## 4. Project Structure Principles
+
+### Structure Selection
+
+```
+Small project / Script:
+├── main.py
+├── utils.py
+└── requirements.txt
+
+Medium API:
+├── app/
+│ ├── __init__.py
+│ ├── main.py
+│ ├── models/
+│ ├── routes/
+│ ├── services/
+│ └── schemas/
+├── tests/
+└── pyproject.toml
+
+Large application:
+├── src/
+│ └── myapp/
+│ ├── core/
+│ ├── api/
+│ ├── services/
+│ ├── models/
+│ └── ...
+├── tests/
+└── pyproject.toml
+```
+
+### FastAPI Structure Principles
+
+```
+Organize by feature or layer:
+
+By layer:
+├── routes/ (API endpoints)
+├── services/ (business logic)
+├── models/ (database models)
+├── schemas/ (Pydantic models)
+└── dependencies/ (shared deps)
+
+By feature:
+├── users/
+│ ├── routes.py
+│ ├── service.py
+│ └── schemas.py
+└── products/
+ └── ...
+```
+
+---
+
+## 5. Django Principles (2025)
+
+### Django Async (Django 5.0+)
+
+```
+Django supports async:
+├── Async views
+├── Async middleware
+├── Async ORM (limited)
+└── ASGI deployment
+
+When to use async in Django:
+├── External API calls
+├── WebSocket (Channels)
+├── High-concurrency views
+└── Background task triggering
+```
+
+### Django Best Practices
+
+```
+Model design:
+├── Fat models, thin views
+├── Use managers for common queries
+├── Abstract base classes for shared fields
+
+Views:
+├── Class-based for complex CRUD
+├── Function-based for simple endpoints
+├── Use viewsets with DRF
+
+Queries:
+├── select_related() for FKs
+├── prefetch_related() for M2M
+├── Avoid N+1 queries
+└── Use .only() for specific fields
+```
+
+---
+
+## 6. FastAPI Principles
+
+### async def vs def in FastAPI
+
+```
+Use async def when:
+├── Using async database drivers
+├── Making async HTTP calls
+├── I/O-bound operations
+└── Want to handle concurrency
+
+Use def when:
+├── Blocking operations
+├── Sync database drivers
+├── CPU-bound work
+└── FastAPI runs in threadpool automatically
+```
+
+### Dependency Injection
+
+```
+Use dependencies for:
+├── Database sessions
+├── Current user / Auth
+├── Configuration
+├── Shared resources
+
+Benefits:
+├── Testability (mock dependencies)
+├── Clean separation
+├── Automatic cleanup (yield)
+```
+
+### Pydantic v2 Integration
+
+```python
+# FastAPI + Pydantic are tightly integrated:
+
+# Request validation
+@app.post("/users")
+async def create(user: UserCreate) -> UserResponse:
+ # user is already validated
+ ...
+
+# Response serialization
+# Return type becomes response schema
+```
+
+---
+
+## 7. Background Tasks
+
+### Selection Guide
+
+| Solution | Best For |
+|----------|----------|
+| **BackgroundTasks** | Simple, in-process tasks |
+| **Celery** | Distributed, complex workflows |
+| **ARQ** | Async, Redis-based |
+| **RQ** | Simple Redis queue |
+| **Dramatiq** | Actor-based, simpler than Celery |
+
+### When to Use Each
+
+```
+FastAPI BackgroundTasks:
+├── Quick operations
+├── No persistence needed
+├── Fire-and-forget
+└── Same process
+
+Celery/ARQ:
+├── Long-running tasks
+├── Need retry logic
+├── Distributed workers
+├── Persistent queue
+└── Complex workflows
+```
+
+---
+
+## 8. Error Handling Principles
+
+### Exception Strategy
+
+```
+In FastAPI:
+├── Create custom exception classes
+├── Register exception handlers
+├── Return consistent error format
+└── Log without exposing internals
+
+Pattern:
+├── Raise domain exceptions in services
+├── Catch and transform in handlers
+└── Client gets clean error response
+```
+
+### Error Response Philosophy
+
+```
+Include:
+├── Error code (programmatic)
+├── Message (human readable)
+├── Details (field-level when applicable)
+└── NOT stack traces (security)
+```
+
+---
+
+## 9. Testing Principles
+
+### Testing Strategy
+
+| Type | Purpose | Tools |
+|------|---------|-------|
+| **Unit** | Business logic | pytest |
+| **Integration** | API endpoints | pytest + httpx/TestClient |
+| **E2E** | Full workflows | pytest + DB |
+
+### Async Testing
+
+```python
+# Use pytest-asyncio for async tests
+
+import pytest
+from httpx import AsyncClient
+
+@pytest.mark.asyncio
+async def test_endpoint():
+ async with AsyncClient(app=app, base_url="http://test") as client:
+ response = await client.get("/users")
+ assert response.status_code == 200
+```
+
+### Fixtures Strategy
+
+```
+Common fixtures:
+├── db_session → Database connection
+├── client → Test client
+├── authenticated_user → User with token
+└── sample_data → Test data setup
+```
+
+---
+
+## 10. Decision Checklist
+
+Before implementing:
+
+- [ ] **Asked user about framework preference?**
+- [ ] **Chosen framework for THIS context?** (not just default)
+- [ ] **Decided async vs sync?**
+- [ ] **Planned type hint strategy?**
+- [ ] **Defined project structure?**
+- [ ] **Planned error handling?**
+- [ ] **Considered background tasks?**
+
+---
+
+## 11. Anti-Patterns to Avoid
+
+### ❌ DON'T:
+- Default to Django for simple APIs (FastAPI may be better)
+- Use sync libraries in async code
+- Skip type hints for public APIs
+- Put business logic in routes/views
+- Ignore N+1 queries
+- Mix async and sync carelessly
+
+### ✅ DO:
+- Choose framework based on context
+- Ask about async requirements
+- Use Pydantic for validation
+- Separate concerns (routes → services → repos)
+- Test critical paths
+
+---
+
+> **Remember**: Python patterns are about decision-making for YOUR specific context. Don't copy code—think about what serves your application best.
diff --git a/.agent/skills/red-team-tactics/SKILL.md b/.agent/skills/red-team-tactics/SKILL.md
new file mode 100644
index 0000000..ed3f7d6
--- /dev/null
+++ b/.agent/skills/red-team-tactics/SKILL.md
@@ -0,0 +1,199 @@
+---
+name: red-team-tactics
+description: Red team tactics principles based on MITRE ATT&CK. Attack phases, detection evasion, reporting.
+allowed-tools: Read, Glob, Grep
+---
+
+# Red Team Tactics
+
+> Adversary simulation principles based on MITRE ATT&CK framework.
+
+---
+
+## 1. MITRE ATT&CK Phases
+
+### Attack Lifecycle
+
+```
+RECONNAISSANCE → INITIAL ACCESS → EXECUTION → PERSISTENCE
+ ↓ ↓ ↓ ↓
+ PRIVILEGE ESC → DEFENSE EVASION → CRED ACCESS → DISCOVERY
+ ↓ ↓ ↓ ↓
+LATERAL MOVEMENT → COLLECTION → C2 → EXFILTRATION → IMPACT
+```
+
+### Phase Objectives
+
+| Phase | Objective |
+|-------|-----------|
+| **Recon** | Map attack surface |
+| **Initial Access** | Get first foothold |
+| **Execution** | Run code on target |
+| **Persistence** | Survive reboots |
+| **Privilege Escalation** | Get admin/root |
+| **Defense Evasion** | Avoid detection |
+| **Credential Access** | Harvest credentials |
+| **Discovery** | Map internal network |
+| **Lateral Movement** | Spread to other systems |
+| **Collection** | Gather target data |
+| **C2** | Maintain command channel |
+| **Exfiltration** | Extract data |
+
+---
+
+## 2. Reconnaissance Principles
+
+### Passive vs Active
+
+| Type | Trade-off |
+|------|-----------|
+| **Passive** | No target contact, limited info |
+| **Active** | Direct contact, more detection risk |
+
+### Information Targets
+
+| Category | Value |
+|----------|-------|
+| Technology stack | Attack vector selection |
+| Employee info | Social engineering |
+| Network ranges | Scanning scope |
+| Third parties | Supply chain attack |
+
+---
+
+## 3. Initial Access Vectors
+
+### Selection Criteria
+
+| Vector | When to Use |
+|--------|-------------|
+| **Phishing** | Human target, email access |
+| **Public exploits** | Vulnerable services exposed |
+| **Valid credentials** | Leaked or cracked |
+| **Supply chain** | Third-party access |
+
+---
+
+## 4. Privilege Escalation Principles
+
+### Windows Targets
+
+| Check | Opportunity |
+|-------|-------------|
+| Unquoted service paths | Write to path |
+| Weak service permissions | Modify service |
+| Token privileges | Abuse SeDebug, etc. |
+| Stored credentials | Harvest |
+
+### Linux Targets
+
+| Check | Opportunity |
+|-------|-------------|
+| SUID binaries | Execute as owner |
+| Sudo misconfiguration | Command execution |
+| Kernel vulnerabilities | Kernel exploits |
+| Cron jobs | Writable scripts |
+
+---
+
+## 5. Defense Evasion Principles
+
+### Key Techniques
+
+| Technique | Purpose |
+|-----------|---------|
+| LOLBins | Use legitimate tools |
+| Obfuscation | Hide malicious code |
+| Timestomping | Hide file modifications |
+| Log clearing | Remove evidence |
+
+### Operational Security
+
+- Work during business hours
+- Mimic legitimate traffic patterns
+- Use encrypted channels
+- Blend with normal behavior
+
+---
+
+## 6. Lateral Movement Principles
+
+### Credential Types
+
+| Type | Use |
+|------|-----|
+| Password | Standard auth |
+| Hash | Pass-the-hash |
+| Ticket | Pass-the-ticket |
+| Certificate | Certificate auth |
+
+### Movement Paths
+
+- Admin shares
+- Remote services (RDP, SSH, WinRM)
+- Exploitation of internal services
+
+---
+
+## 7. Active Directory Attacks
+
+### Attack Categories
+
+| Attack | Target |
+|--------|--------|
+| Kerberoasting | Service account passwords |
+| AS-REP Roasting | Accounts without pre-auth |
+| DCSync | Domain credentials |
+| Golden Ticket | Persistent domain access |
+
+---
+
+## 8. Reporting Principles
+
+### Attack Narrative
+
+Document the full attack chain:
+1. How initial access was gained
+2. What techniques were used
+3. What objectives were achieved
+4. Where detection failed
+
+### Detection Gaps
+
+For each successful technique:
+- What should have detected it?
+- Why didn't detection work?
+- How to improve detection
+
+---
+
+## 9. Ethical Boundaries
+
+### Always
+
+- Stay within scope
+- Minimize impact
+- Report immediately if real threat found
+- Document all actions
+
+### Never
+
+- Destroy production data
+- Cause denial of service (unless scoped)
+- Access beyond proof of concept
+- Retain sensitive data
+
+---
+
+## 10. Anti-Patterns
+
+| ❌ Don't | ✅ Do |
+|----------|-------|
+| Rush to exploitation | Follow methodology |
+| Cause damage | Minimize impact |
+| Skip reporting | Document everything |
+| Ignore scope | Stay within boundaries |
+
+---
+
+> **Remember:** Red team simulates attackers to improve defenses, not to cause harm.
diff --git a/.agent/skills/rust-pro/SKILL.md b/.agent/skills/rust-pro/SKILL.md
new file mode 100644
index 0000000..d258f8b
--- /dev/null
+++ b/.agent/skills/rust-pro/SKILL.md
@@ -0,0 +1,176 @@
+---
+name: rust-pro
+description: Master Rust 1.75+ with modern async patterns, advanced type system
+ features, and production-ready systems programming. Expert in the latest Rust
+ ecosystem including Tokio, axum, and cutting-edge crates. Use PROACTIVELY for
+ Rust development, performance optimization, or systems programming.
+---
+You are a Rust expert specializing in modern Rust 1.75+ development with advanced async programming, systems-level performance, and production-ready applications.
+
+## Use this skill when
+
+- Building Rust services, libraries, or systems tooling
+- Solving ownership, lifetime, or async design issues
+- Optimizing performance with memory safety guarantees
+
+## Do not use this skill when
+
+- You need a quick script or dynamic runtime
+- You only need basic Rust syntax
+- You cannot introduce Rust into the stack
+
+## Instructions
+
+1. Clarify performance, safety, and runtime constraints.
+2. Choose async/runtime and crate ecosystem approach.
+3. Implement with tests and linting.
+4. Profile and optimize hotspots.
+
+## Purpose
+Expert Rust developer mastering Rust 1.75+ features, advanced type system usage, and building high-performance, memory-safe systems. Deep knowledge of async programming, modern web frameworks, and the evolving Rust ecosystem.
+
+## Capabilities
+
+### Modern Rust Language Features
+- Rust 1.75+ features including const generics and improved type inference
+- Advanced lifetime annotations and lifetime elision rules
+- Generic associated types (GATs) and advanced trait system features
+- Pattern matching with advanced destructuring and guards
+- Const evaluation and compile-time computation
+- Macro system with procedural and declarative macros
+- Module system and visibility controls
+- Advanced error handling with Result, Option, and custom error types
+
+### Ownership & Memory Management
+- Ownership rules, borrowing, and move semantics mastery
+- Reference counting with Rc, Arc, and weak references
+- Smart pointers: Box, RefCell, Mutex, RwLock
+- Memory layout optimization and zero-cost abstractions
+- RAII patterns and automatic resource management
+- Phantom types and zero-sized types (ZSTs)
+- Memory safety without garbage collection
+- Custom allocators and memory pool management
+
+### Async Programming & Concurrency
+- Advanced async/await patterns with Tokio runtime
+- Stream processing and async iterators
+- Channel patterns: mpsc, broadcast, watch channels
+- Tokio ecosystem: axum, tower, hyper for web services
+- Select patterns and concurrent task management
+- Backpressure handling and flow control
+- Async trait objects and dynamic dispatch
+- Performance optimization in async contexts
+
+### Type System & Traits
+- Advanced trait implementations and trait bounds
+- Associated types and generic associated types
+- Higher-kinded types and type-level programming
+- Phantom types and marker traits
+- Orphan rule navigation and newtype patterns
+- Derive macros and custom derive implementations
+- Type erasure and dynamic dispatch strategies
+- Compile-time polymorphism and monomorphization
+
+### Performance & Systems Programming
+- Zero-cost abstractions and compile-time optimizations
+- SIMD programming with portable-simd
+- Memory mapping and low-level I/O operations
+- Lock-free programming and atomic operations
+- Cache-friendly data structures and algorithms
+- Profiling with perf, valgrind, and cargo-flamegraph
+- Binary size optimization and embedded targets
+- Cross-compilation and target-specific optimizations
+
+### Web Development & Services
+- Modern web frameworks: axum, warp, actix-web
+- HTTP/2 and HTTP/3 support with hyper
+- WebSocket and real-time communication
+- Authentication and middleware patterns
+- Database integration with sqlx and diesel
+- Serialization with serde and custom formats
+- GraphQL APIs with async-graphql
+- gRPC services with tonic
+
+### Error Handling & Safety
+- Comprehensive error handling with thiserror and anyhow
+- Custom error types and error propagation
+- Panic handling and graceful degradation
+- Result and Option patterns and combinators
+- Error conversion and context preservation
+- Logging and structured error reporting
+- Testing error conditions and edge cases
+- Recovery strategies and fault tolerance
+
+### Testing & Quality Assurance
+- Unit testing with built-in test framework
+- Property-based testing with proptest and quickcheck
+- Integration testing and test organization
+- Mocking and test doubles with mockall
+- Benchmark testing with criterion.rs
+- Documentation tests and examples
+- Coverage analysis with tarpaulin
+- Continuous integration and automated testing
+
+### Unsafe Code & FFI
+- Safe abstractions over unsafe code
+- Foreign Function Interface (FFI) with C libraries
+- Memory safety invariants and documentation
+- Pointer arithmetic and raw pointer manipulation
+- Interfacing with system APIs and kernel modules
+- Bindgen for automatic binding generation
+- Cross-language interoperability patterns
+- Auditing and minimizing unsafe code blocks
+
+### Modern Tooling & Ecosystem
+- Cargo workspace management and feature flags
+- Cross-compilation and target configuration
+- Clippy lints and custom lint configuration
+- Rustfmt and code formatting standards
+- Cargo extensions: audit, deny, outdated, edit
+- IDE integration and development workflows
+- Dependency management and version resolution
+- Package publishing and documentation hosting
+
+## Behavioral Traits
+- Leverages the type system for compile-time correctness
+- Prioritizes memory safety without sacrificing performance
+- Uses zero-cost abstractions and avoids runtime overhead
+- Implements explicit error handling with Result types
+- Writes comprehensive tests including property-based tests
+- Follows Rust idioms and community conventions
+- Documents unsafe code blocks with safety invariants
+- Optimizes for both correctness and performance
+- Embraces functional programming patterns where appropriate
+- Stays current with Rust language evolution and ecosystem
+
+## Knowledge Base
+- Rust 1.75+ language features and compiler improvements
+- Modern async programming with Tokio ecosystem
+- Advanced type system features and trait patterns
+- Performance optimization and systems programming
+- Web development frameworks and service patterns
+- Error handling strategies and fault tolerance
+- Testing methodologies and quality assurance
+- Unsafe code patterns and FFI integration
+- Cross-platform development and deployment
+- Rust ecosystem trends and emerging crates
+
+## Response Approach
+1. **Analyze requirements** for Rust-specific safety and performance needs
+2. **Design type-safe APIs** with comprehensive error handling
+3. **Implement efficient algorithms** with zero-cost abstractions
+4. **Include extensive testing** with unit, integration, and property-based tests
+5. **Consider async patterns** for concurrent and I/O-bound operations
+6. **Document safety invariants** for any unsafe code blocks
+7. **Optimize for performance** while maintaining memory safety
+8. **Recommend modern ecosystem** crates and patterns
+
+## Example Interactions
+- "Design a high-performance async web service with proper error handling"
+- "Implement a lock-free concurrent data structure with atomic operations"
+- "Optimize this Rust code for better memory usage and cache locality"
+- "Create a safe wrapper around a C library using FFI"
+- "Build a streaming data processor with backpressure handling"
+- "Design a plugin system with dynamic loading and type safety"
+- "Implement a custom allocator for a specific use case"
+- "Debug and fix lifetime issues in this complex generic code"
\ No newline at end of file
diff --git a/.agent/skills/seo-fundamentals/SKILL.md b/.agent/skills/seo-fundamentals/SKILL.md
new file mode 100644
index 0000000..682fea8
--- /dev/null
+++ b/.agent/skills/seo-fundamentals/SKILL.md
@@ -0,0 +1,129 @@
+---
+name: seo-fundamentals
+description: SEO fundamentals, E-E-A-T, Core Web Vitals, and Google algorithm principles.
+allowed-tools: Read, Glob, Grep
+---
+
+# SEO Fundamentals
+
+> Principles for search engine visibility.
+
+---
+
+## 1. E-E-A-T Framework
+
+| Principle | Signals |
+|-----------|---------|
+| **Experience** | First-hand knowledge, real examples |
+| **Expertise** | Credentials, depth of knowledge |
+| **Authoritativeness** | Backlinks, mentions, industry recognition |
+| **Trustworthiness** | HTTPS, transparency, accurate info |
+
+---
+
+## 2. Core Web Vitals
+
+| Metric | Target | Measures |
+|--------|--------|----------|
+| **LCP** | < 2.5s | Loading performance |
+| **INP** | < 200ms | Interactivity |
+| **CLS** | < 0.1 | Visual stability |
+
+---
+
+## 3. Technical SEO Principles
+
+### Site Structure
+
+| Element | Purpose |
+|---------|---------|
+| XML sitemap | Help crawling |
+| robots.txt | Control access |
+| Canonical tags | Prevent duplicates |
+| HTTPS | Security signal |
+
+### Performance
+
+| Factor | Impact |
+|--------|--------|
+| Page speed | Core Web Vital |
+| Mobile-friendly | Ranking factor |
+| Clean URLs | Crawlability |
+
+---
+
+## 4. Content SEO Principles
+
+### Page Elements
+
+| Element | Best Practice |
+|---------|---------------|
+| Title tag | 50-60 chars, keyword front |
+| Meta description | 150-160 chars, compelling |
+| H1 | One per page, main keyword |
+| H2-H6 | Logical hierarchy |
+| Alt text | Descriptive, not stuffed |
+
+### Content Quality
+
+| Factor | Importance |
+|--------|------------|
+| Depth | Comprehensive coverage |
+| Freshness | Regular updates |
+| Uniqueness | Original value |
+| Readability | Clear writing |
+
+---
+
+## 5. Schema Markup Types
+
+| Type | Use |
+|------|-----|
+| Article | Blog posts, news |
+| Organization | Company info |
+| Person | Author profiles |
+| FAQPage | Q&A content |
+| Product | E-commerce |
+| Review | Ratings |
+| BreadcrumbList | Navigation |
+
+---
+
+## 6. AI Content Guidelines
+
+### What Google Looks For
+
+| ✅ Do | ❌ Don't |
+|-------|----------|
+| AI draft + human edit | Publish raw AI content |
+| Add original insights | Copy without value |
+| Expert review | Skip fact-checking |
+| Follow E-E-A-T | Keyword stuffing |
+
+---
+
+## 7. Ranking Factors (Prioritized)
+
+| Priority | Factor |
+|----------|--------|
+| 1 | Quality, relevant content |
+| 2 | Backlinks from authority sites |
+| 3 | Page experience (Core Web Vitals) |
+| 4 | Mobile optimization |
+| 5 | Technical SEO fundamentals |
+
+---
+
+## 8. Measurement
+
+| Metric | Tool |
+|--------|------|
+| Rankings | Search Console, Ahrefs |
+| Traffic | Analytics |
+| Core Web Vitals | PageSpeed Insights |
+| Indexing | Search Console |
+| Backlinks | Ahrefs, Semrush |
+
+---
+
+> **Remember:** SEO is a long-term game. Quality content + technical excellence + patience = results.
diff --git a/.agent/skills/seo-fundamentals/scripts/seo_checker.py b/.agent/skills/seo-fundamentals/scripts/seo_checker.py
new file mode 100644
index 0000000..e226530
--- /dev/null
+++ b/.agent/skills/seo-fundamentals/scripts/seo_checker.py
@@ -0,0 +1,219 @@
+#!/usr/bin/env python3
+"""
+SEO Checker - Search Engine Optimization Audit
+Checks HTML/JSX/TSX pages for SEO best practices.
+
+PURPOSE:
+ - Verify meta tags, titles, descriptions
+ - Check Open Graph tags for social sharing
+ - Validate heading hierarchy
+ - Check image accessibility (alt attributes)
+
+WHAT IT CHECKS:
+ - HTML files (actual web pages)
+ - JSX/TSX files (React page components)
+ - Only files that are likely PUBLIC pages
+
+Usage:
+ python seo_checker.py
+"""
+import sys
+import json
+import re
+from pathlib import Path
+from datetime import datetime
+
+# Fix Windows console encoding
+try:
+ sys.stdout.reconfigure(encoding='utf-8', errors='replace')
+except:
+ pass
+
+
+# Directories to skip
+SKIP_DIRS = {
+ 'node_modules', '.next', 'dist', 'build', '.git', '.github',
+ '__pycache__', '.vscode', '.idea', 'coverage', 'test', 'tests',
+ '__tests__', 'spec', 'docs', 'documentation', 'examples'
+}
+
+# Files to skip (not pages)
+SKIP_PATTERNS = [
+ 'config', 'setup', 'util', 'helper', 'hook', 'context', 'store',
+ 'service', 'api', 'lib', 'constant', 'type', 'interface', 'mock',
+ '.test.', '.spec.', '_test.', '_spec.'
+]
+
+
+def is_page_file(file_path: Path) -> bool:
+ """Check if this file is likely a public-facing page."""
+ name = file_path.name.lower()
+ stem = file_path.stem.lower()
+
+ # Skip utility/config files
+ if any(skip in name for skip in SKIP_PATTERNS):
+ return False
+
+ # Check path - pages in specific directories are likely pages
+ parts = [p.lower() for p in file_path.parts]
+ page_dirs = ['pages', 'app', 'routes', 'views', 'screens']
+
+ if any(d in parts for d in page_dirs):
+ return True
+
+ # Filename indicators for pages
+ page_names = ['page', 'index', 'home', 'about', 'contact', 'blog',
+ 'post', 'article', 'product', 'landing', 'layout']
+
+ if any(p in stem for p in page_names):
+ return True
+
+ # HTML files are usually pages
+ if file_path.suffix.lower() in ['.html', '.htm']:
+ return True
+
+ return False
+
+
+def find_pages(project_path: Path) -> list:
+ """Find page files to check."""
+ patterns = ['**/*.html', '**/*.htm', '**/*.jsx', '**/*.tsx']
+
+ files = []
+ for pattern in patterns:
+ for f in project_path.glob(pattern):
+ # Skip excluded directories
+ if any(skip in f.parts for skip in SKIP_DIRS):
+ continue
+
+ # Check if it's likely a page
+ if is_page_file(f):
+ files.append(f)
+
+ return files[:50] # Limit to 50 files
+
+
+def check_page(file_path: Path) -> dict:
+ """Check a single page for SEO issues."""
+ issues = []
+
+ try:
+ content = file_path.read_text(encoding='utf-8', errors='ignore')
+ except Exception as e:
+ return {"file": str(file_path.name), "issues": [f"Error: {e}"]}
+
+ # Detect if this is a layout/template file (has Head component)
+ is_layout = 'Head>' in content or '' in content
+ if not has_title and is_layout:
+ issues.append("Missing tag")
+
+ # 2. Meta description
+ has_description = 'name="description"' in content.lower() or 'name=\'description\'' in content.lower()
+ if not has_description and is_layout:
+ issues.append("Missing meta description")
+
+ # 3. Open Graph tags
+ has_og = 'og:' in content or 'property="og:' in content.lower()
+ if not has_og and is_layout:
+ issues.append("Missing Open Graph tags")
+
+ # 4. Heading hierarchy - multiple H1s
+ h1_matches = re.findall(r'<h1[^>]*>', content, re.I)
+ if len(h1_matches) > 1:
+ issues.append(f"Multiple H1 tags ({len(h1_matches)})")
+
+ # 5. Images without alt
+ img_pattern = r'<img[^>]+>'
+ imgs = re.findall(img_pattern, content, re.I)
+ for img in imgs:
+ if 'alt=' not in img.lower():
+ issues.append("Image missing alt attribute")
+ break
+ if 'alt=""' in img or "alt=''" in img:
+ issues.append("Image has empty alt attribute")
+ break
+
+ # 6. Check for canonical link (nice to have)
+ # has_canonical = 'rel="canonical"' in content.lower()
+
+ return {
+ "file": str(file_path.name),
+ "issues": issues
+ }
+
+
+def main():
+ project_path = Path(sys.argv[1] if len(sys.argv) > 1 else ".").resolve()
+
+ print(f"\n{'='*60}")
+ print(f" SEO CHECKER - Search Engine Optimization Audit")
+ print(f"{'='*60}")
+ print(f"Project: {project_path}")
+ print(f"Time: {datetime.now().strftime('%Y-%m-%d %H:%M:%S')}")
+ print("-"*60)
+
+ # Find pages
+ pages = find_pages(project_path)
+
+ if not pages:
+ print("\n[!] No page files found.")
+ print(" Looking for: HTML, JSX, TSX in pages/app/routes directories")
+ output = {"script": "seo_checker", "files_checked": 0, "passed": True}
+ print("\n" + json.dumps(output, indent=2))
+ sys.exit(0)
+
+ print(f"Found {len(pages)} page files to analyze\n")
+
+ # Check each page
+ all_issues = []
+ for f in pages:
+ result = check_page(f)
+ if result["issues"]:
+ all_issues.append(result)
+
+ # Summary
+ print("=" * 60)
+ print("SEO ANALYSIS RESULTS")
+ print("=" * 60)
+
+ if all_issues:
+ # Group by issue type
+ issue_counts = {}
+ for item in all_issues:
+ for issue in item["issues"]:
+ issue_counts[issue] = issue_counts.get(issue, 0) + 1
+
+ print("\nIssue Summary:")
+ for issue, count in sorted(issue_counts.items(), key=lambda x: -x[1]):
+ print(f" [{count}] {issue}")
+
+ print(f"\nAffected files ({len(all_issues)}):")
+ for item in all_issues[:5]:
+ print(f" - {item['file']}")
+ if len(all_issues) > 5:
+ print(f" ... and {len(all_issues) - 5} more")
+ else:
+ print("\n[OK] No SEO issues found!")
+
+ total_issues = sum(len(item["issues"]) for item in all_issues)
+ passed = total_issues == 0
+
+ output = {
+ "script": "seo_checker",
+ "project": str(project_path),
+ "files_checked": len(pages),
+ "files_with_issues": len(all_issues),
+ "issues_found": total_issues,
+ "passed": passed
+ }
+
+ print("\n" + json.dumps(output, indent=2))
+
+ sys.exit(0 if passed else 1)
+
+
+if __name__ == "__main__":
+ main()
diff --git a/.agent/skills/server-management/SKILL.md b/.agent/skills/server-management/SKILL.md
new file mode 100644
index 0000000..708638c
--- /dev/null
+++ b/.agent/skills/server-management/SKILL.md
@@ -0,0 +1,161 @@
+---
+name: server-management
+description: Server management principles and decision-making. Process management, monitoring strategy, and scaling decisions. Teaches thinking, not commands.
+allowed-tools: Read, Write, Edit, Glob, Grep, Bash
+---
+
+# Server Management
+
+> Server management principles for production operations.
+> **Learn to THINK, not memorize commands.**
+
+---
+
+## 1. Process Management Principles
+
+### Tool Selection
+
+| Scenario | Tool |
+|----------|------|
+| **Node.js app** | PM2 (clustering, reload) |
+| **Any app** | systemd (Linux native) |
+| **Containers** | Docker/Podman |
+| **Orchestration** | Kubernetes, Docker Swarm |
+
+### Process Management Goals
+
+| Goal | What It Means |
+|------|---------------|
+| **Restart on crash** | Auto-recovery |
+| **Zero-downtime reload** | No service interruption |
+| **Clustering** | Use all CPU cores |
+| **Persistence** | Survive server reboot |
+
+---
+
+## 2. Monitoring Principles
+
+### What to Monitor
+
+| Category | Key Metrics |
+|----------|-------------|
+| **Availability** | Uptime, health checks |
+| **Performance** | Response time, throughput |
+| **Errors** | Error rate, types |
+| **Resources** | CPU, memory, disk |
+
+### Alert Severity Strategy
+
+| Level | Response |
+|-------|----------|
+| **Critical** | Immediate action |
+| **Warning** | Investigate soon |
+| **Info** | Review daily |
+
+### Monitoring Tool Selection
+
+| Need | Options |
+|------|---------|
+| Simple/Free | PM2 metrics, htop |
+| Full observability | Grafana, Datadog |
+| Error tracking | Sentry |
+| Uptime | UptimeRobot, Pingdom |
+
+---
+
+## 3. Log Management Principles
+
+### Log Strategy
+
+| Log Type | Purpose |
+|----------|---------|
+| **Application logs** | Debug, audit |
+| **Access logs** | Traffic analysis |
+| **Error logs** | Issue detection |
+
+### Log Principles
+
+1. **Rotate logs** to prevent disk fill
+2. **Structured logging** (JSON) for parsing
+3. **Appropriate levels** (error/warn/info/debug)
+4. **No sensitive data** in logs
+
+---
+
+## 4. Scaling Decisions
+
+### When to Scale
+
+| Symptom | Solution |
+|---------|----------|
+| High CPU | Add instances (horizontal) |
+| High memory | Increase RAM or fix leak |
+| Slow response | Profile first, then scale |
+| Traffic spikes | Auto-scaling |
+
+### Scaling Strategy
+
+| Type | When to Use |
+|------|-------------|
+| **Vertical** | Quick fix, single instance |
+| **Horizontal** | Sustainable, distributed |
+| **Auto** | Variable traffic |
+
+---
+
+## 5. Health Check Principles
+
+### What Constitutes Healthy
+
+| Check | Meaning |
+|-------|---------|
+| **HTTP 200** | Service responding |
+| **Database connected** | Data accessible |
+| **Dependencies OK** | External services reachable |
+| **Resources OK** | CPU/memory not exhausted |
+
+### Health Check Implementation
+
+- Simple: Just return 200
+- Deep: Check all dependencies
+- Choose based on load balancer needs
+
+---
+
+## 6. Security Principles
+
+| Area | Principle |
+|------|-----------|
+| **Access** | SSH keys only, no passwords |
+| **Firewall** | Only needed ports open |
+| **Updates** | Regular security patches |
+| **Secrets** | Environment vars, not files |
+| **Audit** | Log access and changes |
+
+---
+
+## 7. Troubleshooting Priority
+
+When something's wrong:
+
+1. **Check if running** (process status)
+2. **Check logs** (error messages)
+3. **Check resources** (disk, memory, CPU)
+4. **Check network** (ports, DNS)
+5. **Check dependencies** (database, APIs)
+
+---
+
+## 8. Anti-Patterns
+
+| ❌ Don't | ✅ Do |
+|----------|-------|
+| Run as root | Use non-root user |
+| Ignore logs | Set up log rotation |
+| Skip monitoring | Monitor from day one |
+| Manual restarts | Auto-restart config |
+| No backups | Regular backup schedule |
+
+---
+
+> **Remember:** A well-managed server is boring. That's the goal.
diff --git a/.agent/skills/systematic-debugging/SKILL.md b/.agent/skills/systematic-debugging/SKILL.md
new file mode 100644
index 0000000..39417d3
--- /dev/null
+++ b/.agent/skills/systematic-debugging/SKILL.md
@@ -0,0 +1,109 @@
+---
+name: systematic-debugging
+description: 4-phase systematic debugging methodology with root cause analysis and evidence-based verification. Use when debugging complex issues.
+allowed-tools: Read, Glob, Grep
+---
+
+# Systematic Debugging
+
+> Source: obra/superpowers
+
+## Overview
+This skill provides a structured approach to debugging that prevents random guessing and ensures problems are properly understood before solving.
+
+## 4-Phase Debugging Process
+
+### Phase 1: Reproduce
+Before fixing, reliably reproduce the issue.
+
+```markdown
+## Reproduction Steps
+1. [Exact step to reproduce]
+2. [Next step]
+3. [Expected vs actual result]
+
+## Reproduction Rate
+- [ ] Always (100%)
+- [ ] Often (50-90%)
+- [ ] Sometimes (10-50%)
+- [ ] Rare (<10%)
+```
+
+### Phase 2: Isolate
+Narrow down the source.
+
+```markdown
+## Isolation Questions
+- When did this start happening?
+- What changed recently?
+- Does it happen in all environments?
+- Can we reproduce with minimal code?
+- What's the smallest change that triggers it?
+```
+
+### Phase 3: Understand
+Find the root cause, not just symptoms.
+
+```markdown
+## Root Cause Analysis
+### The 5 Whys
+1. Why: [First observation]
+2. Why: [Deeper reason]
+3. Why: [Still deeper]
+4. Why: [Getting closer]
+5. Why: [Root cause]
+```
+
+### Phase 4: Fix & Verify
+Fix and verify it's truly fixed.
+
+```markdown
+## Fix Verification
+- [ ] Bug no longer reproduces
+- [ ] Related functionality still works
+- [ ] No new issues introduced
+- [ ] Test added to prevent regression
+```
+
+## Debugging Checklist
+
+```markdown
+## Before Starting
+- [ ] Can reproduce consistently
+- [ ] Have minimal reproduction case
+- [ ] Understand expected behavior
+
+## During Investigation
+- [ ] Check recent changes (git log)
+- [ ] Check logs for errors
+- [ ] Add logging if needed
+- [ ] Use debugger/breakpoints
+
+## After Fix
+- [ ] Root cause documented
+- [ ] Fix verified
+- [ ] Regression test added
+- [ ] Similar code checked
+```
+
+## Common Debugging Commands
+
+```bash
+# Recent changes
+git log --oneline -20
+git diff HEAD~5
+
+# Search for pattern
+grep -r "errorPattern" --include="*.ts"
+
+# Check logs
+pm2 logs app-name --err --lines 100
+```
+
+## Anti-Patterns
+
+❌ **Random changes** - "Maybe if I change this..."
+❌ **Ignoring evidence** - "That can't be the cause"
+❌ **Assuming** - "It must be X" without proof
+❌ **Not reproducing first** - Fixing blindly
+❌ **Stopping at symptoms** - Not finding root cause
diff --git a/.agent/skills/tailwind-patterns/SKILL.md b/.agent/skills/tailwind-patterns/SKILL.md
new file mode 100644
index 0000000..a5830a8
--- /dev/null
+++ b/.agent/skills/tailwind-patterns/SKILL.md
@@ -0,0 +1,269 @@
+---
+name: tailwind-patterns
+description: Tailwind CSS v4 principles. CSS-first configuration, container queries, modern patterns, design token architecture.
+allowed-tools: Read, Write, Edit, Glob, Grep
+---
+
+# Tailwind CSS Patterns (v4 - 2025)
+
+> Modern utility-first CSS with CSS-native configuration.
+
+---
+
+## 1. Tailwind v4 Architecture
+
+### What Changed from v3
+
+| v3 (Legacy) | v4 (Current) |
+|-------------|--------------|
+| `tailwind.config.js` | CSS-based `@theme` directive |
+| PostCSS plugin | Oxide engine (10x faster) |
+| JIT mode | Native, always-on |
+| Plugin system | CSS-native features |
+| `@apply` directive | Still works, discouraged |
+
+### v4 Core Concepts
+
+| Concept | Description |
+|---------|-------------|
+| **CSS-first** | Configuration in CSS, not JavaScript |
+| **Oxide Engine** | Rust-based compiler, much faster |
+| **Native Nesting** | CSS nesting without PostCSS |
+| **CSS Variables** | All tokens exposed as `--*` vars |
+
+---
+
+## 2. CSS-Based Configuration
+
+### Theme Definition
+
+```
+@theme {
+ /* Colors - use semantic names */
+ --color-primary: oklch(0.7 0.15 250);
+ --color-surface: oklch(0.98 0 0);
+ --color-surface-dark: oklch(0.15 0 0);
+
+ /* Spacing scale */
+ --spacing-xs: 0.25rem;
+ --spacing-sm: 0.5rem;
+ --spacing-md: 1rem;
+ --spacing-lg: 2rem;
+
+ /* Typography */
+ --font-sans: 'Inter', system-ui, sans-serif;
+ --font-mono: 'JetBrains Mono', monospace;
+}
+```
+
+### When to Extend vs Override
+
+| Action | Use When |
+|--------|----------|
+| **Extend** | Adding new values alongside defaults |
+| **Override** | Replacing default scale entirely |
+| **Semantic tokens** | Project-specific naming (primary, surface) |
+
+---
+
+## 3. Container Queries (v4 Native)
+
+### Breakpoint vs Container
+
+| Type | Responds To |
+|------|-------------|
+| **Breakpoint** (`md:`) | Viewport width |
+| **Container** (`@container`) | Parent element width |
+
+### Container Query Usage
+
+| Pattern | Classes |
+|---------|---------|
+| Define container | `@container` on parent |
+| Container breakpoint | `@sm:`, `@md:`, `@lg:` on children |
+| Named containers | `@container/card` for specificity |
+
+### When to Use
+
+| Scenario | Use |
+|----------|-----|
+| Page-level layouts | Viewport breakpoints |
+| Component-level responsive | Container queries |
+| Reusable components | Container queries (context-independent) |
+
+---
+
+## 4. Responsive Design
+
+### Breakpoint System
+
+| Prefix | Min Width | Target |
+|--------|-----------|--------|
+| (none) | 0px | Mobile-first base |
+| `sm:` | 640px | Large phone / small tablet |
+| `md:` | 768px | Tablet |
+| `lg:` | 1024px | Laptop |
+| `xl:` | 1280px | Desktop |
+| `2xl:` | 1536px | Large desktop |
+
+### Mobile-First Principle
+
+1. Write mobile styles first (no prefix)
+2. Add larger screen overrides with prefixes
+3. Example: `w-full md:w-1/2 lg:w-1/3`
+
+---
+
+## 5. Dark Mode
+
+### Configuration Strategies
+
+| Method | Behavior | Use When |
+|--------|----------|----------|
+| `class` | `.dark` class toggles | Manual theme switcher |
+| `media` | Follows system preference | No user control |
+| `selector` | Custom selector (v4) | Complex theming |
+
+### Dark Mode Pattern
+
+| Element | Light | Dark |
+|---------|-------|------|
+| Background | `bg-white` | `dark:bg-zinc-900` |
+| Text | `text-zinc-900` | `dark:text-zinc-100` |
+| Borders | `border-zinc-200` | `dark:border-zinc-700` |
+
+---
+
+## 6. Modern Layout Patterns
+
+### Flexbox Patterns
+
+| Pattern | Classes |
+|---------|---------|
+| Center (both axes) | `flex items-center justify-center` |
+| Vertical stack | `flex flex-col gap-4` |
+| Horizontal row | `flex gap-4` |
+| Space between | `flex justify-between items-center` |
+| Wrap grid | `flex flex-wrap gap-4` |
+
+### Grid Patterns
+
+| Pattern | Classes |
+|---------|---------|
+| Auto-fit responsive | `grid grid-cols-[repeat(auto-fit,minmax(250px,1fr))]` |
+| Asymmetric (Bento) | `grid grid-cols-3 grid-rows-2` with spans |
+| Sidebar layout | `grid grid-cols-[auto_1fr]` |
+
+> **Note:** Prefer asymmetric/Bento layouts over symmetric 3-column grids.
+
+---
+
+## 7. Modern Color System
+
+### OKLCH vs RGB/HSL
+
+| Format | Advantage |
+|--------|-----------|
+| **OKLCH** | Perceptually uniform, better for design |
+| **HSL** | Intuitive hue/saturation |
+| **RGB** | Legacy compatibility |
+
+### Color Token Architecture
+
+| Layer | Example | Purpose |
+|-------|---------|---------|
+| **Primitive** | `--blue-500` | Raw color values |
+| **Semantic** | `--color-primary` | Purpose-based naming |
+| **Component** | `--button-bg` | Component-specific |
+
+---
+
+## 8. Typography System
+
+### Font Stack Pattern
+
+| Type | Recommended |
+|------|-------------|
+| Sans | `'Inter', 'SF Pro', system-ui, sans-serif` |
+| Mono | `'JetBrains Mono', 'Fira Code', monospace` |
+| Display | `'Outfit', 'Poppins', sans-serif` |
+
+### Type Scale
+
+| Class | Size | Use |
+|-------|------|-----|
+| `text-xs` | 0.75rem | Labels, captions |
+| `text-sm` | 0.875rem | Secondary text |
+| `text-base` | 1rem | Body text |
+| `text-lg` | 1.125rem | Lead text |
+| `text-xl`+ | 1.25rem+ | Headings |
+
+---
+
+## 9. Animation & Transitions
+
+### Built-in Animations
+
+| Class | Effect |
+|-------|--------|
+| `animate-spin` | Continuous rotation |
+| `animate-ping` | Attention pulse |
+| `animate-pulse` | Subtle opacity pulse |
+| `animate-bounce` | Bouncing effect |
+
+### Transition Patterns
+
+| Pattern | Classes |
+|---------|---------|
+| All properties | `transition-all duration-200` |
+| Specific | `transition-colors duration-150` |
+| With easing | `ease-out` or `ease-in-out` |
+| Hover effect | `hover:scale-105 transition-transform` |
+
+---
+
+## 10. Component Extraction
+
+### When to Extract
+
+| Signal | Action |
+|--------|--------|
+| Same class combo 3+ times | Extract component |
+| Complex state variants | Extract component |
+| Design system element | Extract + document |
+
+### Extraction Methods
+
+| Method | Use When |
+|--------|----------|
+| **React/Vue component** | Dynamic, JS needed |
+| **@apply in CSS** | Static, no JS needed |
+| **Design tokens** | Reusable values |
+
+---
+
+## 11. Anti-Patterns
+
+| Don't | Do |
+|-------|-----|
+| Arbitrary values everywhere | Use design system scale |
+| `!important` | Fix specificity properly |
+| Inline `style=` | Use utilities |
+| Duplicate long class lists | Extract component |
+| Mix v3 config with v4 | Migrate fully to CSS-first |
+| Use `@apply` heavily | Prefer components |
+
+---
+
+## 12. Performance Principles
+
+| Principle | Implementation |
+|-----------|----------------|
+| **Purge unused** | Automatic in v4 |
+| **Avoid dynamism** | No template string classes |
+| **Use Oxide** | Default in v4, 10x faster |
+| **Cache builds** | CI/CD caching |
+
+---
+
+> **Remember:** Tailwind v4 is CSS-first. Embrace CSS variables, container queries, and native features. The config file is now optional.
diff --git a/.agent/skills/tdd-workflow/SKILL.md b/.agent/skills/tdd-workflow/SKILL.md
new file mode 100644
index 0000000..ddb07e8
--- /dev/null
+++ b/.agent/skills/tdd-workflow/SKILL.md
@@ -0,0 +1,149 @@
+---
+name: tdd-workflow
+description: Test-Driven Development workflow principles. RED-GREEN-REFACTOR cycle.
+allowed-tools: Read, Write, Edit, Glob, Grep, Bash
+---
+
+# TDD Workflow
+
+> Write tests first, code second.
+
+---
+
+## 1. The TDD Cycle
+
+```
+🔴 RED → Write failing test
+ ↓
+🟢 GREEN → Write minimal code to pass
+ ↓
+🔵 REFACTOR → Improve code quality
+ ↓
+ Repeat...
+```
+
+---
+
+## 2. The Three Laws of TDD
+
+1. Write production code only to make a failing test pass
+2. Write only enough test to demonstrate failure
+3. Write only enough code to make the test pass
+
+---
+
+## 3. RED Phase Principles
+
+### What to Write
+
+| Focus | Example |
+|-------|---------|
+| Behavior | "should add two numbers" |
+| Edge cases | "should handle empty input" |
+| Error states | "should throw for invalid data" |
+
+### RED Phase Rules
+
+- Test must fail first
+- Test name describes expected behavior
+- One assertion per test (ideally)
+
+---
+
+## 4. GREEN Phase Principles
+
+### Minimum Code
+
+| Principle | Meaning |
+|-----------|---------|
+| **YAGNI** | You Aren't Gonna Need It |
+| **Simplest thing** | Write the minimum to pass |
+| **No optimization** | Just make it work |
+
+### GREEN Phase Rules
+
+- Don't write unneeded code
+- Don't optimize yet
+- Pass the test, nothing more
+
+---
+
+## 5. REFACTOR Phase Principles
+
+### What to Improve
+
+| Area | Action |
+|------|--------|
+| Duplication | Extract common code |
+| Naming | Make intent clear |
+| Structure | Improve organization |
+| Complexity | Simplify logic |
+
+### REFACTOR Rules
+
+- All tests must stay green
+- Small incremental changes
+- Commit after each refactor
+
+---
+
+## 6. AAA Pattern
+
+Every test follows:
+
+| Step | Purpose |
+|------|---------|
+| **Arrange** | Set up test data |
+| **Act** | Execute code under test |
+| **Assert** | Verify expected outcome |
+
+---
+
+## 7. When to Use TDD
+
+| Scenario | TDD Value |
+|----------|-----------|
+| New feature | High |
+| Bug fix | High (write test first) |
+| Complex logic | High |
+| Exploratory | Low (spike, then TDD) |
+| UI layout | Low |
+
+---
+
+## 8. Test Prioritization
+
+| Priority | Test Type |
+|----------|-----------|
+| 1 | Happy path |
+| 2 | Error cases |
+| 3 | Edge cases |
+| 4 | Performance |
+
+---
+
+## 9. Anti-Patterns
+
+| ❌ Don't | ✅ Do |
+|----------|-------|
+| Skip the RED phase | Watch test fail first |
+| Write tests after | Write tests before |
+| Over-engineer initial | Keep it simple |
+| Multiple asserts | One behavior per test |
+| Test implementation | Test behavior |
+
+---
+
+## 10. AI-Augmented TDD
+
+### Multi-Agent Pattern
+
+| Agent | Role |
+|-------|------|
+| Agent A | Write failing tests (RED) |
+| Agent B | Implement to pass (GREEN) |
+| Agent C | Optimize (REFACTOR) |
+
+---
+
+> **Remember:** The test is the specification. If you can't write a test, you don't understand the requirement.
diff --git a/.agent/skills/testing-patterns/SKILL.md b/.agent/skills/testing-patterns/SKILL.md
new file mode 100644
index 0000000..578b729
--- /dev/null
+++ b/.agent/skills/testing-patterns/SKILL.md
@@ -0,0 +1,178 @@
+---
+name: testing-patterns
+description: Testing patterns and principles. Unit, integration, mocking strategies.
+allowed-tools: Read, Write, Edit, Glob, Grep, Bash
+---
+
+# Testing Patterns
+
+> Principles for reliable test suites.
+
+---
+
+## 1. Testing Pyramid
+
+```
+ /\ E2E (Few)
+ / \ Critical flows
+ /----\
+ / \ Integration (Some)
+ /--------\ API, DB queries
+ / \
+ /------------\ Unit (Many)
+ Functions, classes
+```
+
+---
+
+## 2. AAA Pattern
+
+| Step | Purpose |
+|------|---------|
+| **Arrange** | Set up test data |
+| **Act** | Execute code under test |
+| **Assert** | Verify outcome |
+
+---
+
+## 3. Test Type Selection
+
+### When to Use Each
+
+| Type | Best For | Speed |
+|------|----------|-------|
+| **Unit** | Pure functions, logic | Fast (<50ms) |
+| **Integration** | API, DB, services | Medium |
+| **E2E** | Critical user flows | Slow |
+
+---
+
+## 4. Unit Test Principles
+
+### Good Unit Tests
+
+| Principle | Meaning |
+|-----------|---------|
+| Fast | < 100ms each |
+| Isolated | No external deps |
+| Repeatable | Same result always |
+| Self-checking | No manual verification |
+| Timely | Written with code |
+
+### What to Unit Test
+
+| Test | Don't Test |
+|------|------------|
+| Business logic | Framework code |
+| Edge cases | Third-party libs |
+| Error handling | Simple getters |
+
+---
+
+## 5. Integration Test Principles
+
+### What to Test
+
+| Area | Focus |
+|------|-------|
+| API endpoints | Request/response |
+| Database | Queries, transactions |
+| External services | Contracts |
+
+### Setup/Teardown
+
+| Phase | Action |
+|-------|--------|
+| Before All | Connect resources |
+| Before Each | Reset state |
+| After Each | Clean up |
+| After All | Disconnect |
+
+---
+
+## 6. Mocking Principles
+
+### When to Mock
+
+| Mock | Don't Mock |
+|------|------------|
+| External APIs | The code under test |
+| Database (unit) | Simple dependencies |
+| Time/random | Pure functions |
+| Network | In-memory stores |
+
+### Mock Types
+
+| Type | Use |
+|------|-----|
+| Stub | Return fixed values |
+| Spy | Track calls |
+| Mock | Set expectations |
+| Fake | Simplified implementation |
+
+---
+
+## 7. Test Organization
+
+### Naming
+
+| Pattern | Example |
+|---------|---------|
+| Should behavior | "should return error when..." |
+| When condition | "when user not found..." |
+| Given-when-then | "given X, when Y, then Z" |
+
+### Grouping
+
+| Level | Use |
+|-------|-----|
+| describe | Group related tests |
+| it/test | Individual case |
+| beforeEach | Common setup |
+
+---
+
+## 8. Test Data
+
+### Strategies
+
+| Approach | Use |
+|----------|-----|
+| Factories | Generate test data |
+| Fixtures | Predefined datasets |
+| Builders | Fluent object creation |
+
+### Principles
+
+- Use realistic data
+- Randomize non-essential values (faker)
+- Share common fixtures
+- Keep data minimal
+
+---
+
+## 9. Best Practices
+
+| Practice | Why |
+|----------|-----|
+| One assert per test | Clear failure reason |
+| Independent tests | No order dependency |
+| Fast tests | Run frequently |
+| Descriptive names | Self-documenting |
+| Clean up | Avoid side effects |
+
+---
+
+## 10. Anti-Patterns
+
+| ❌ Don't | ✅ Do |
+|----------|-------|
+| Test implementation | Test behavior |
+| Duplicate test code | Use factories |
+| Complex test setup | Simplify or split |
+| Ignore flaky tests | Fix root cause |
+| Skip cleanup | Reset state |
+
+---
+
+> **Remember:** Tests are documentation. If someone can't understand what the code does from the tests, rewrite them.
diff --git a/.agent/skills/testing-patterns/scripts/test_runner.py b/.agent/skills/testing-patterns/scripts/test_runner.py
new file mode 100644
index 0000000..4191794
--- /dev/null
+++ b/.agent/skills/testing-patterns/scripts/test_runner.py
@@ -0,0 +1,219 @@
+#!/usr/bin/env python3
+"""
+Test Runner - Unified test execution and coverage reporting
+Runs tests and generates coverage report based on project type.
+
+Usage:
+ python test_runner.py <project_path> [--coverage]
+
+Supports:
+ - Node.js: npm test, jest, vitest
+ - Python: pytest, unittest
+"""
+
+import subprocess
+import sys
+import json
+from pathlib import Path
+from datetime import datetime
+
+# Fix Windows console encoding
+try:
+ sys.stdout.reconfigure(encoding='utf-8', errors='replace')
+except:
+ pass
+
+
+def detect_test_framework(project_path: Path) -> dict:
+ """Detect test framework and commands."""
+ result = {
+ "type": "unknown",
+ "framework": None,
+ "cmd": None,
+ "coverage_cmd": None
+ }
+
+ # Node.js project
+ package_json = project_path / "package.json"
+ if package_json.exists():
+ result["type"] = "node"
+ try:
+ pkg = json.loads(package_json.read_text(encoding='utf-8'))
+ scripts = pkg.get("scripts", {})
+ deps = {**pkg.get("dependencies", {}), **pkg.get("devDependencies", {})}
+
+ # Check for test script
+ if "test" in scripts:
+ result["framework"] = "npm test"
+ result["cmd"] = ["npm", "test"]
+
+ # Try to detect specific framework for coverage
+ if "vitest" in deps:
+ result["framework"] = "vitest"
+ result["coverage_cmd"] = ["npx", "vitest", "run", "--coverage"]
+ elif "jest" in deps:
+ result["framework"] = "jest"
+ result["coverage_cmd"] = ["npx", "jest", "--coverage"]
+ elif "vitest" in deps:
+ result["framework"] = "vitest"
+ result["cmd"] = ["npx", "vitest", "run"]
+ result["coverage_cmd"] = ["npx", "vitest", "run", "--coverage"]
+ elif "jest" in deps:
+ result["framework"] = "jest"
+ result["cmd"] = ["npx", "jest"]
+ result["coverage_cmd"] = ["npx", "jest", "--coverage"]
+
+ except:
+ pass
+
+ # Python project
+ if (project_path / "pyproject.toml").exists() or (project_path / "requirements.txt").exists():
+ result["type"] = "python"
+ result["framework"] = "pytest"
+ result["cmd"] = ["python", "-m", "pytest", "-v"]
+ result["coverage_cmd"] = ["python", "-m", "pytest", "--cov", "--cov-report=term-missing"]
+
+ return result
+
+
+def run_tests(cmd: list, cwd: Path) -> dict:
+ """Run tests and return results."""
+ result = {
+ "passed": False,
+ "output": "",
+ "error": "",
+ "tests_run": 0,
+ "tests_passed": 0,
+ "tests_failed": 0
+ }
+
+ try:
+ proc = subprocess.run(
+ cmd,
+ cwd=str(cwd),
+ capture_output=True,
+ text=True,
+ encoding='utf-8',
+ errors='replace',
+ timeout=300 # 5 min timeout for tests
+ )
+
+ result["output"] = proc.stdout[:3000] if proc.stdout else ""
+ result["error"] = proc.stderr[:500] if proc.stderr else ""
+ result["passed"] = proc.returncode == 0
+
+ # Try to parse test counts from output
+ output = proc.stdout or ""
+
+ # Jest/Vitest pattern: "Tests: X passed, Y failed, Z total"
+ if "passed" in output.lower() and "failed" in output.lower():
+ import re
+ match = re.search(r'(\d+)\s+passed', output, re.IGNORECASE)
+ if match:
+ result["tests_passed"] = int(match.group(1))
+ match = re.search(r'(\d+)\s+failed', output, re.IGNORECASE)
+ if match:
+ result["tests_failed"] = int(match.group(1))
+ result["tests_run"] = result["tests_passed"] + result["tests_failed"]
+
+ # Pytest pattern: "X passed, Y failed"
+ if "pytest" in str(cmd):
+ import re
+ match = re.search(r'(\d+)\s+passed', output)
+ if match:
+ result["tests_passed"] = int(match.group(1))
+ match = re.search(r'(\d+)\s+failed', output)
+ if match:
+ result["tests_failed"] = int(match.group(1))
+ result["tests_run"] = result["tests_passed"] + result["tests_failed"]
+
+ except FileNotFoundError:
+ result["error"] = f"Command not found: {cmd[0]}"
+ except subprocess.TimeoutExpired:
+ result["error"] = "Timeout after 300s"
+ except Exception as e:
+ result["error"] = str(e)
+
+ return result
+
+
+def main():
+ project_path = Path(sys.argv[1] if len(sys.argv) > 1 else ".").resolve()
+ with_coverage = "--coverage" in sys.argv
+
+ print(f"\n{'='*60}")
+ print(f"[TEST RUNNER] Unified Test Execution")
+ print(f"{'='*60}")
+ print(f"Project: {project_path}")
+ print(f"Coverage: {'enabled' if with_coverage else 'disabled'}")
+ print(f"Time: {datetime.now().strftime('%Y-%m-%d %H:%M:%S')}")
+
+ # Detect test framework
+ test_info = detect_test_framework(project_path)
+ print(f"Type: {test_info['type']}")
+ print(f"Framework: {test_info['framework']}")
+ print("-"*60)
+
+ if not test_info["cmd"]:
+ print("No test framework found for this project.")
+ output = {
+ "script": "test_runner",
+ "project": str(project_path),
+ "type": test_info["type"],
+ "framework": None,
+ "passed": True,
+ "message": "No tests configured"
+ }
+ print(json.dumps(output, indent=2))
+ sys.exit(0)
+
+ # Choose command
+ cmd = test_info["coverage_cmd"] if with_coverage and test_info["coverage_cmd"] else test_info["cmd"]
+
+ print(f"Running: {' '.join(cmd)}")
+ print("-"*60)
+
+ # Run tests
+ result = run_tests(cmd, project_path)
+
+ # Print output (truncated)
+ if result["output"]:
+ lines = result["output"].split("\n")
+ for line in lines[:30]:
+ print(line)
+ if len(lines) > 30:
+ print(f"... ({len(lines) - 30} more lines)")
+
+ # Summary
+ print("\n" + "="*60)
+ print("SUMMARY")
+ print("="*60)
+
+ if result["passed"]:
+ print("[PASS] All tests passed")
+ else:
+ print("[FAIL] Some tests failed")
+ if result["error"]:
+ print(f"Error: {result['error'][:200]}")
+
+ if result["tests_run"] > 0:
+ print(f"Tests: {result['tests_run']} total, {result['tests_passed']} passed, {result['tests_failed']} failed")
+
+ output = {
+ "script": "test_runner",
+ "project": str(project_path),
+ "type": test_info["type"],
+ "framework": test_info["framework"],
+ "tests_run": result["tests_run"],
+ "tests_passed": result["tests_passed"],
+ "tests_failed": result["tests_failed"],
+ "passed": result["passed"]
+ }
+
+ print("\n" + json.dumps(output, indent=2))
+
+ sys.exit(0 if result["passed"] else 1)
+
+
+if __name__ == "__main__":
+ main()
diff --git a/.agent/skills/vulnerability-scanner/SKILL.md b/.agent/skills/vulnerability-scanner/SKILL.md
new file mode 100644
index 0000000..97f1688
--- /dev/null
+++ b/.agent/skills/vulnerability-scanner/SKILL.md
@@ -0,0 +1,276 @@
+---
+name: vulnerability-scanner
+description: Advanced vulnerability analysis principles. OWASP 2025, Supply Chain Security, attack surface mapping, risk prioritization.
+allowed-tools: Read, Glob, Grep, Bash
+---
+
+# Vulnerability Scanner
+
+> Think like an attacker, defend like an expert. 2025 threat landscape awareness.
+
+## 🔧 Runtime Scripts
+
+**Execute for automated validation:**
+
+| Script | Purpose | Usage |
+|--------|---------|-------|
+| `scripts/security_scan.py` | Validate security principles applied | `python scripts/security_scan.py <project_path>` |
+
+## 📋 Reference Files
+
+| File | Purpose |
+|------|---------|
+| [checklists.md](checklists.md) | OWASP Top 10, Auth, API, Data protection checklists |
+
+---
+
+## 1. Security Expert Mindset
+
+### Core Principles
+
+| Principle | Application |
+|-----------|-------------|
+| **Assume Breach** | Design as if attacker already inside |
+| **Zero Trust** | Never trust, always verify |
+| **Defense in Depth** | Multiple layers, no single point |
+| **Least Privilege** | Minimum required access only |
+| **Fail Secure** | On error, deny access |
+
+### Threat Modeling Questions
+
+Before scanning, ask:
+1. What are we protecting? (Assets)
+2. Who would attack? (Threat actors)
+3. How would they attack? (Attack vectors)
+4. What's the impact? (Business risk)
+
+---
+
+## 2. OWASP Top 10:2025
+
+### Risk Categories
+
+| Rank | Category | Think About |
+|------|----------|-------------|
+| **A01** | Broken Access Control | Who can access what? IDOR, SSRF |
+| **A02** | Security Misconfiguration | Defaults, headers, exposed services |
+| **A03** | Software Supply Chain 🆕 | Dependencies, CI/CD, build integrity |
+| **A04** | Cryptographic Failures | Weak crypto, exposed secrets |
+| **A05** | Injection | User input → system commands |
+| **A06** | Insecure Design | Flawed architecture |
+| **A07** | Authentication Failures | Session, credential management |
+| **A08** | Integrity Failures | Unsigned updates, tampered data |
+| **A09** | Logging & Alerting | Blind spots, no monitoring |
+| **A10** | Exceptional Conditions 🆕 | Error handling, fail-open states |
+
+### 2025 Key Changes
+
+```
+2021 → 2025 Shifts:
+├── SSRF merged into A01 (Access Control)
+├── A02 elevated (Cloud/Container configs)
+├── A03 NEW: Supply Chain (major focus)
+├── A10 NEW: Exceptional Conditions
+└── Focus shift: Root causes > Symptoms
+```
+
+---
+
+## 3. Supply Chain Security (A03)
+
+### Attack Surface
+
+| Vector | Risk | Question to Ask |
+|--------|------|-----------------|
+| **Dependencies** | Malicious packages | Do we audit new deps? |
+| **Lock files** | Integrity attacks | Are they committed? |
+| **Build pipeline** | CI/CD compromise | Who can modify? |
+| **Registry** | Typosquatting | Verified sources? |
+
+### Defense Principles
+
+- Verify package integrity (checksums)
+- Pin versions, audit updates
+- Use private registries for critical deps
+- Sign and verify artifacts
+
+---
+
+## 4. Attack Surface Mapping
+
+### What to Map
+
+| Category | Elements |
+|----------|----------|
+| **Entry Points** | APIs, forms, file uploads |
+| **Data Flows** | Input → Process → Output |
+| **Trust Boundaries** | Where auth/authz checked |
+| **Assets** | Secrets, PII, business data |
+
+### Prioritization Matrix
+
+```
+Risk = Likelihood × Impact
+
+High Impact + High Likelihood → CRITICAL
+High Impact + Low Likelihood → HIGH
+Low Impact + High Likelihood → MEDIUM
+Low Impact + Low Likelihood → LOW
+```
+
+---
+
+## 5. Risk Prioritization
+
+### CVSS + Context
+
+| Factor | Weight | Question |
+|--------|--------|----------|
+| **CVSS Score** | Base severity | How severe is the vuln? |
+| **EPSS Score** | Exploit likelihood | Is it being exploited? |
+| **Asset Value** | Business context | What's at risk? |
+| **Exposure** | Attack surface | Internet-facing? |
+
+### Prioritization Decision Tree
+
+```
+Is it actively exploited (EPSS >0.5)?
+├── YES → CRITICAL: Immediate action
+└── NO → Check CVSS
+ ├── CVSS ≥9.0 → HIGH
+ ├── CVSS 7.0-8.9 → Consider asset value
+ └── CVSS <7.0 → Schedule for later
+```
+
+---
+
+## 6. Exceptional Conditions (A10 - New)
+
+### Fail-Open vs Fail-Closed
+
+| Scenario | Fail-Open (BAD) | Fail-Closed (GOOD) |
+|----------|-----------------|---------------------|
+| Auth error | Allow access | Deny access |
+| Parsing fails | Accept input | Reject input |
+| Timeout | Retry forever | Limit + abort |
+
+### What to Check
+
+- Exception handlers that catch-all and ignore
+- Missing error handling on security operations
+- Race conditions in auth/authz
+- Resource exhaustion scenarios
+
+---
+
+## 7. Scanning Methodology
+
+### Phase-Based Approach
+
+```
+1. RECONNAISSANCE
+ └── Understand the target
+ ├── Technology stack
+ ├── Entry points
+ └── Data flows
+
+2. DISCOVERY
+ └── Identify potential issues
+ ├── Configuration review
+ ├── Dependency analysis
+ └── Code pattern search
+
+3. ANALYSIS
+ └── Validate and prioritize
+ ├── False positive elimination
+ ├── Risk scoring
+ └── Attack chain mapping
+
+4. REPORTING
+ └── Actionable findings
+ ├── Clear reproduction steps
+ ├── Business impact
+ └── Remediation guidance
+```
+
+---
+
+## 8. Code Pattern Analysis
+
+### High-Risk Patterns
+
+| Pattern | Risk | Look For |
+|---------|------|----------|
+| **String concat in queries** | Injection | `"SELECT * FROM " + user_input` |
+| **Dynamic code execution** | RCE | `eval()`, `exec()`, `Function()` |
+| **Unsafe deserialization** | RCE | `pickle.loads()`, `unserialize()` |
+| **Path manipulation** | Traversal | User input in file paths |
+| **Disabled security** | Various | `verify=False`, `--insecure` |
+
+### Secret Patterns
+
+| Type | Indicators |
+|------|-----------|
+| API Keys | `api_key`, `apikey`, high entropy |
+| Tokens | `token`, `bearer`, `jwt` |
+| Credentials | `password`, `secret`, `key` |
+| Cloud | `AWS_`, `AZURE_`, `GCP_` prefixes |
+
+---
+
+## 9. Cloud Security Considerations
+
+### Shared Responsibility
+
+| Layer | You Own | Provider Owns |
+|-------|---------|---------------|
+| Data | ✅ | ❌ |
+| Application | ✅ | ❌ |
+| OS/Runtime | Depends | Depends |
+| Infrastructure | ❌ | ✅ |
+
+### Cloud-Specific Checks
+
+- IAM: Least privilege applied?
+- Storage: Public buckets?
+- Network: Security groups tightened?
+- Secrets: Using secrets manager?
+
+---
+
+## 10. Anti-Patterns
+
+| ❌ Don't | ✅ Do |
+|----------|-------|
+| Scan without understanding | Map attack surface first |
+| Alert on every CVE | Prioritize by exploitability + asset |
+| Ignore false positives | Maintain verified baseline |
+| Fix symptoms only | Address root causes |
+| Scan once before deploy | Continuous scanning |
+| Trust third-party deps blindly | Verify integrity, audit code |
+
+---
+
+## 11. Reporting Principles
+
+### Finding Structure
+
+Each finding should answer:
+1. **What?** - Clear vulnerability description
+2. **Where?** - Exact location (file, line, endpoint)
+3. **Why?** - Root cause explanation
+4. **Impact?** - Business consequence
+5. **How to fix?** - Specific remediation
+
+### Severity Classification
+
+| Severity | Criteria |
+|----------|----------|
+| **Critical** | RCE, auth bypass, mass data exposure |
+| **High** | Data exposure, privilege escalation |
+| **Medium** | Limited scope, requires conditions |
+| **Low** | Informational, best practice |
+
+---
+
+> **Remember:** Vulnerability scanning finds issues. Expert thinking prioritizes what matters. Always ask: "What would an attacker do with this?"
diff --git a/.agent/skills/vulnerability-scanner/checklists.md b/.agent/skills/vulnerability-scanner/checklists.md
new file mode 100644
index 0000000..b365415
--- /dev/null
+++ b/.agent/skills/vulnerability-scanner/checklists.md
@@ -0,0 +1,121 @@
+# Security Checklists
+
+> Quick reference checklists for security audits. Use alongside vulnerability-scanner principles.
+
+---
+
+## OWASP Top 10 Audit Checklist
+
+### A01: Broken Access Control
+- [ ] Authorization on all protected routes
+- [ ] Deny by default
+- [ ] Rate limiting implemented
+- [ ] CORS properly configured
+
+### A02: Cryptographic Failures
+- [ ] Passwords hashed (bcrypt/argon2, cost 12+)
+- [ ] Sensitive data encrypted at rest
+- [ ] TLS 1.2+ for all connections
+- [ ] No secrets in code/logs
+
+### A03: Injection
+- [ ] Parameterized queries
+- [ ] Input validation on all user data
+- [ ] Output encoding for XSS
+- [ ] No eval() or dynamic code execution
+
+### A04: Insecure Design
+- [ ] Threat modeling done
+- [ ] Security requirements defined
+- [ ] Business logic validated
+
+### A05: Security Misconfiguration
+- [ ] Unnecessary features disabled
+- [ ] Error messages sanitized
+- [ ] Security headers configured
+- [ ] Default credentials changed
+
+### A06: Vulnerable Components
+- [ ] Dependencies up to date
+- [ ] No known vulnerabilities
+- [ ] Unused dependencies removed
+
+### A07: Authentication Failures
+- [ ] MFA available
+- [ ] Session invalidation on logout
+- [ ] Session timeout implemented
+- [ ] Brute force protection
+
+### A08: Integrity Failures
+- [ ] Dependency integrity verified
+- [ ] CI/CD pipeline secured
+- [ ] Update mechanism secured
+
+### A09: Logging Failures
+- [ ] Security events logged
+- [ ] Logs protected
+- [ ] No sensitive data in logs
+- [ ] Alerting configured
+
+### A10: SSRF
+- [ ] URL validation implemented
+- [ ] Allow-list for external calls
+- [ ] Network segmentation
+
+---
+
+## Authentication Checklist
+
+- [ ] Strong password policy
+- [ ] Account lockout
+- [ ] Secure password reset
+- [ ] Session management
+- [ ] Token expiration
+- [ ] Logout invalidation
+
+---
+
+## API Security Checklist
+
+- [ ] Authentication required
+- [ ] Authorization per endpoint
+- [ ] Input validation
+- [ ] Rate limiting
+- [ ] Output sanitization
+- [ ] Error handling
+
+---
+
+## Data Protection Checklist
+
+- [ ] Encryption at rest
+- [ ] Encryption in transit
+- [ ] Key management
+- [ ] Data minimization
+- [ ] Secure deletion
+
+---
+
+## Security Headers
+
+| Header | Purpose |
+|--------|---------|
+| **Content-Security-Policy** | XSS prevention |
+| **X-Content-Type-Options** | MIME sniffing |
+| **X-Frame-Options** | Clickjacking |
+| **Strict-Transport-Security** | Force HTTPS |
+| **Referrer-Policy** | Referrer control |
+
+---
+
+## Quick Audit Commands
+
+| Check | What to Look For |
+|-------|------------------|
+| Secrets in code | password, api_key, secret |
+| Dangerous patterns | eval, innerHTML, SQL concat |
+| Dependency issues | npm audit, snyk |
+
+---
+
+> **Usage:** Copy relevant checklists into your PLAN.md or security report.
diff --git a/.agent/skills/vulnerability-scanner/scripts/security_scan.py b/.agent/skills/vulnerability-scanner/scripts/security_scan.py
new file mode 100644
index 0000000..6eaa779
--- /dev/null
+++ b/.agent/skills/vulnerability-scanner/scripts/security_scan.py
@@ -0,0 +1,458 @@
+#!/usr/bin/env python3
+"""
+Skill: vulnerability-scanner
+Script: security_scan.py
+Purpose: Validate that security principles from SKILL.md are applied correctly
+Usage: python security_scan.py <project_path> [--scan-type all|deps|secrets|patterns|config]
+Output: JSON with validation findings
+
+This script verifies:
+1. Dependencies - Supply chain security (OWASP A03)
+2. Secrets - No hardcoded credentials (OWASP A04)
+3. Code Patterns - Dangerous patterns identified (OWASP A05)
+4. Configuration - Security settings validated (OWASP A02)
+"""
+import subprocess
+import json
+import os
+import sys
+import re
+import argparse
+from pathlib import Path
+from typing import Dict, List, Any
+from datetime import datetime
+
+# Fix Windows console encoding for Unicode output
+try:
+ sys.stdout.reconfigure(encoding='utf-8', errors='replace')
+ sys.stderr.reconfigure(encoding='utf-8', errors='replace')
+except AttributeError:
+ pass # Python < 3.7
+
+
+# ============================================================================
+# CONFIGURATION
+# ============================================================================
+
+SECRET_PATTERNS = [
+ # API Keys & Tokens
+ (r'api[_-]?key\s*[=:]\s*["\'][^"\']{10,}["\']', "API Key", "high"),
+ (r'token\s*[=:]\s*["\'][^"\']{10,}["\']', "Token", "high"),
+ (r'bearer\s+[a-zA-Z0-9\-_.]+', "Bearer Token", "critical"),
+
+ # Cloud Credentials
+ (r'AKIA[0-9A-Z]{16}', "AWS Access Key", "critical"),
+ (r'aws[_-]?secret[_-]?access[_-]?key\s*[=:]\s*["\'][^"\']+["\']', "AWS Secret", "critical"),
+ (r'AZURE[_-]?[A-Z_]+\s*[=:]\s*["\'][^"\']+["\']', "Azure Credential", "critical"),
+ (r'GOOGLE[_-]?[A-Z_]+\s*[=:]\s*["\'][^"\']+["\']', "GCP Credential", "critical"),
+
+ # Database & Connections
+ (r'password\s*[=:]\s*["\'][^"\']{4,}["\']', "Password", "high"),
+ (r'(mongodb|postgres|mysql|redis):\/\/[^\s"\']+', "Database Connection String", "critical"),
+
+ # Private Keys
+ (r'-----BEGIN\s+(RSA|PRIVATE|EC)\s+KEY-----', "Private Key", "critical"),
+ (r'ssh-rsa\s+[A-Za-z0-9+/]+', "SSH Key", "critical"),
+
+ # JWT
+ (r'eyJ[A-Za-z0-9-_]+\.eyJ[A-Za-z0-9-_]+\.[A-Za-z0-9-_]+', "JWT Token", "high"),
+]
+
+DANGEROUS_PATTERNS = [
+ # Injection risks
+ (r'eval\s*\(', "eval() usage", "critical", "Code Injection risk"),
+ (r'exec\s*\(', "exec() usage", "critical", "Code Injection risk"),
+ (r'new\s+Function\s*\(', "Function constructor", "high", "Code Injection risk"),
+ (r'child_process\.exec\s*\(', "child_process.exec", "high", "Command Injection risk"),
+ (r'subprocess\.call\s*\([^)]*shell\s*=\s*True', "subprocess with shell=True", "high", "Command Injection risk"),
+
+ # XSS risks
+ (r'dangerouslySetInnerHTML', "dangerouslySetInnerHTML", "high", "XSS risk"),
+ (r'\.innerHTML\s*=', "innerHTML assignment", "medium", "XSS risk"),
+ (r'document\.write\s*\(', "document.write", "medium", "XSS risk"),
+
+ # SQL Injection indicators
+ (r'["\'][^"\']*\+\s*[a-zA-Z_]+\s*\+\s*["\'].*(?:SELECT|INSERT|UPDATE|DELETE)', "SQL String Concat", "critical", "SQL Injection risk"),
+ (r'f"[^"]*(?:SELECT|INSERT|UPDATE|DELETE)[^"]*\{', "SQL f-string", "critical", "SQL Injection risk"),
+
+ # Insecure configurations
+ (r'verify\s*=\s*False', "SSL Verify Disabled", "high", "MITM risk"),
+ (r'--insecure', "Insecure flag", "medium", "Security disabled"),
+ (r'disable[_-]?ssl', "SSL Disabled", "high", "MITM risk"),
+
+ # Unsafe deserialization
+ (r'pickle\.loads?\s*\(', "pickle usage", "high", "Deserialization risk"),
+ (r'yaml\.load\s*\([^)]*\)(?!\s*,\s*Loader)', "Unsafe YAML load", "high", "Deserialization risk"),
+]
+
+SKIP_DIRS = {'node_modules', '.git', 'dist', 'build', '__pycache__', '.venv', 'venv', '.next'}
+CODE_EXTENSIONS = {'.js', '.ts', '.jsx', '.tsx', '.py', '.go', '.java', '.rb', '.php'}
+CONFIG_EXTENSIONS = {'.json', '.yaml', '.yml', '.toml', '.env', '.env.local', '.env.development'}
+
+
+# ============================================================================
+# SCANNING FUNCTIONS
+# ============================================================================
+
+def scan_dependencies(project_path: str) -> Dict[str, Any]:
+ """
+ Validate supply chain security (OWASP A03).
+ Checks: npm audit, lock file presence, dependency age.
+ """
+ results = {"tool": "dependency_scanner", "findings": [], "status": "[OK] Secure"}
+
+ # Check for lock files
+ lock_files = {
+ "npm": ["package-lock.json", "npm-shrinkwrap.json"],
+ "yarn": ["yarn.lock"],
+ "pnpm": ["pnpm-lock.yaml"],
+ "pip": ["requirements.txt", "Pipfile.lock", "poetry.lock"],
+ }
+
+ found_locks = []
+ missing_locks = []
+
+ for manager, files in lock_files.items():
+ pkg_file = "package.json" if manager in ["npm", "yarn", "pnpm"] else "setup.py"
+ pkg_path = Path(project_path) / pkg_file
+
+ if pkg_path.exists() or (manager == "pip" and (Path(project_path) / "requirements.txt").exists()):
+ has_lock = any((Path(project_path) / f).exists() for f in files)
+ if has_lock:
+ found_locks.append(manager)
+ else:
+ missing_locks.append(manager)
+ results["findings"].append({
+ "type": "Missing Lock File",
+ "severity": "high",
+ "message": f"{manager}: No lock file found. Supply chain integrity at risk."
+ })
+
+ # Run npm audit if applicable
+ if (Path(project_path) / "package.json").exists():
+ try:
+ result = subprocess.run(
+ ["npm", "audit", "--json"],
+ cwd=project_path,
+ capture_output=True,
+ text=True,
+ timeout=60
+ )
+
+ try:
+ audit_data = json.loads(result.stdout)
+ vulnerabilities = audit_data.get("vulnerabilities", {})
+
+ severity_count = {"critical": 0, "high": 0, "moderate": 0, "low": 0}
+ for vuln in vulnerabilities.values():
+ sev = vuln.get("severity", "low").lower()
+ if sev in severity_count:
+ severity_count[sev] += 1
+
+ if severity_count["critical"] > 0:
+ results["status"] = "[!!] Critical vulnerabilities"
+ results["findings"].append({
+ "type": "npm audit",
+ "severity": "critical",
+ "message": f"{severity_count['critical']} critical vulnerabilities in dependencies"
+ })
+ elif severity_count["high"] > 0:
+ results["status"] = "[!] High vulnerabilities"
+ results["findings"].append({
+ "type": "npm audit",
+ "severity": "high",
+ "message": f"{severity_count['high']} high severity vulnerabilities"
+ })
+
+ results["npm_audit"] = severity_count
+
+ except json.JSONDecodeError:
+ pass
+
+ except (FileNotFoundError, subprocess.TimeoutExpired):
+ pass
+
+ if not results["findings"]:
+ results["status"] = "[OK] Supply chain checks passed"
+
+ return results
+
+
+def scan_secrets(project_path: str) -> Dict[str, Any]:
+ """
+ Validate no hardcoded secrets (OWASP A04).
+ Checks: API keys, tokens, passwords, cloud credentials.
+ """
+ results = {
+ "tool": "secret_scanner",
+ "findings": [],
+ "status": "[OK] No secrets detected",
+ "scanned_files": 0,
+ "by_severity": {"critical": 0, "high": 0, "medium": 0}
+ }
+
+ for root, dirs, files in os.walk(project_path):
+ dirs[:] = [d for d in dirs if d not in SKIP_DIRS]
+
+ for file in files:
+ ext = Path(file).suffix.lower()
+ if ext not in CODE_EXTENSIONS and ext not in CONFIG_EXTENSIONS:
+ continue
+
+ filepath = Path(root) / file
+ results["scanned_files"] += 1
+
+ try:
+ with open(filepath, 'r', encoding='utf-8', errors='ignore') as f:
+ content = f.read()
+
+ for pattern, secret_type, severity in SECRET_PATTERNS:
+ matches = re.findall(pattern, content, re.IGNORECASE)
+ if matches:
+ results["findings"].append({
+ "file": str(filepath.relative_to(project_path)),
+ "type": secret_type,
+ "severity": severity,
+ "count": len(matches)
+ })
+ results["by_severity"][severity] += len(matches)
+
+ except Exception:
+ pass
+
+ if results["by_severity"]["critical"] > 0:
+ results["status"] = "[!!] CRITICAL: Secrets exposed!"
+ elif results["by_severity"]["high"] > 0:
+ results["status"] = "[!] HIGH: Secrets found"
+ elif sum(results["by_severity"].values()) > 0:
+ results["status"] = "[?] Potential secrets detected"
+
+ # Limit findings for output
+ results["findings"] = results["findings"][:15]
+
+ return results
+
+
+def scan_code_patterns(project_path: str) -> Dict[str, Any]:
+ """
+ Validate dangerous code patterns (OWASP A05).
+ Checks: Injection risks, XSS, unsafe deserialization.
+ """
+ results = {
+ "tool": "pattern_scanner",
+ "findings": [],
+ "status": "[OK] No dangerous patterns",
+ "scanned_files": 0,
+ "by_category": {}
+ }
+
+ for root, dirs, files in os.walk(project_path):
+ dirs[:] = [d for d in dirs if d not in SKIP_DIRS]
+
+ for file in files:
+ ext = Path(file).suffix.lower()
+ if ext not in CODE_EXTENSIONS:
+ continue
+
+ filepath = Path(root) / file
+ results["scanned_files"] += 1
+
+ try:
+ with open(filepath, 'r', encoding='utf-8', errors='ignore') as f:
+ lines = f.readlines()
+
+ for line_num, line in enumerate(lines, 1):
+ for pattern, name, severity, category in DANGEROUS_PATTERNS:
+ if re.search(pattern, line, re.IGNORECASE):
+ results["findings"].append({
+ "file": str(filepath.relative_to(project_path)),
+ "line": line_num,
+ "pattern": name,
+ "severity": severity,
+ "category": category,
+ "snippet": line.strip()[:80]
+ })
+ results["by_category"][category] = results["by_category"].get(category, 0) + 1
+
+ except Exception:
+ pass
+
+ critical_count = sum(1 for f in results["findings"] if f["severity"] == "critical")
+ high_count = sum(1 for f in results["findings"] if f["severity"] == "high")
+
+ if critical_count > 0:
+ results["status"] = f"[!!] CRITICAL: {critical_count} dangerous patterns"
+ elif high_count > 0:
+ results["status"] = f"[!] HIGH: {high_count} risky patterns"
+ elif results["findings"]:
+ results["status"] = "[?] Some patterns need review"
+
+ # Limit findings
+ results["findings"] = results["findings"][:20]
+
+ return results
+
+
+def scan_configuration(project_path: str) -> Dict[str, Any]:
+ """
+ Validate security configuration (OWASP A02).
+ Checks: Security headers, CORS, debug modes.
+ """
+ results = {
+ "tool": "config_scanner",
+ "findings": [],
+ "status": "[OK] Configuration secure",
+ "checks": {}
+ }
+
+ # Check common config files for issues
+ config_issues = [
+ (r'"DEBUG"\s*:\s*true', "Debug mode enabled", "high"),
+ (r'debug\s*=\s*True', "Debug mode enabled", "high"),
+ (r'NODE_ENV.*development', "Development mode in config", "medium"),
+ (r'"CORS_ALLOW_ALL".*true', "CORS allow all origins", "high"),
+ (r'"Access-Control-Allow-Origin".*\*', "CORS wildcard", "high"),
+ (r'allowCredentials.*true.*origin.*\*', "Dangerous CORS combo", "critical"),
+ ]
+
+ for root, dirs, files in os.walk(project_path):
+ dirs[:] = [d for d in dirs if d not in SKIP_DIRS]
+
+ for file in files:
+ ext = Path(file).suffix.lower()
+ if ext not in CONFIG_EXTENSIONS and file not in ['next.config.js', 'webpack.config.js', '.eslintrc.js']:
+ continue
+
+ filepath = Path(root) / file
+
+ try:
+ with open(filepath, 'r', encoding='utf-8', errors='ignore') as f:
+ content = f.read()
+
+ for pattern, issue, severity in config_issues:
+ if re.search(pattern, content, re.IGNORECASE):
+ results["findings"].append({
+ "file": str(filepath.relative_to(project_path)),
+ "issue": issue,
+ "severity": severity
+ })
+
+ except Exception:
+ pass
+
+ # Check for security header configurations
+ header_files = ["next.config.js", "next.config.mjs", "middleware.ts", "nginx.conf"]
+ for hf in header_files:
+ hf_path = Path(project_path) / hf
+ if hf_path.exists():
+ results["checks"]["security_headers_config"] = True
+ break
+ else:
+ results["checks"]["security_headers_config"] = False
+ results["findings"].append({
+ "issue": "No security headers configuration found",
+ "severity": "medium",
+ "recommendation": "Configure CSP, HSTS, X-Frame-Options headers"
+ })
+
+ if any(f["severity"] == "critical" for f in results["findings"]):
+ results["status"] = "[!!] CRITICAL: Configuration issues"
+ elif any(f["severity"] == "high" for f in results["findings"]):
+ results["status"] = "[!] HIGH: Configuration review needed"
+ elif results["findings"]:
+ results["status"] = "[?] Minor configuration issues"
+
+ return results
+
+
+# ============================================================================
+# MAIN
+# ============================================================================
+
+def run_full_scan(project_path: str, scan_type: str = "all") -> Dict[str, Any]:
+ """Execute security validation scans."""
+
+ report = {
+ "project": project_path,
+ "timestamp": datetime.now().isoformat(),
+ "scan_type": scan_type,
+ "scans": {},
+ "summary": {
+ "total_findings": 0,
+ "critical": 0,
+ "high": 0,
+ "overall_status": "[OK] SECURE"
+ }
+ }
+
+ scanners = {
+ "deps": ("dependencies", scan_dependencies),
+ "secrets": ("secrets", scan_secrets),
+ "patterns": ("code_patterns", scan_code_patterns),
+ "config": ("configuration", scan_configuration),
+ }
+
+ for key, (name, scanner) in scanners.items():
+ if scan_type == "all" or scan_type == key:
+ result = scanner(project_path)
+ report["scans"][name] = result
+
+ findings_count = len(result.get("findings", []))
+ report["summary"]["total_findings"] += findings_count
+
+ for finding in result.get("findings", []):
+ sev = finding.get("severity", "low")
+ if sev == "critical":
+ report["summary"]["critical"] += 1
+ elif sev == "high":
+ report["summary"]["high"] += 1
+
+ # Determine overall status
+ if report["summary"]["critical"] > 0:
+ report["summary"]["overall_status"] = "[!!] CRITICAL ISSUES FOUND"
+ elif report["summary"]["high"] > 0:
+ report["summary"]["overall_status"] = "[!] HIGH RISK ISSUES"
+ elif report["summary"]["total_findings"] > 0:
+ report["summary"]["overall_status"] = "[?] REVIEW RECOMMENDED"
+
+ return report
+
+
+def main():
+ parser = argparse.ArgumentParser(
+ description="Validate security principles from vulnerability-scanner skill"
+ )
+ parser.add_argument("project_path", nargs="?", default=".", help="Project directory to scan")
+ parser.add_argument("--scan-type", choices=["all", "deps", "secrets", "patterns", "config"],
+ default="all", help="Type of scan to run")
+ parser.add_argument("--output", choices=["json", "summary"], default="json",
+ help="Output format")
+
+ args = parser.parse_args()
+
+ if not os.path.isdir(args.project_path):
+ print(json.dumps({"error": f"Directory not found: {args.project_path}"}))
+ sys.exit(1)
+
+ result = run_full_scan(args.project_path, args.scan_type)
+
+ if args.output == "summary":
+ print(f"\n{'='*60}")
+ print(f"Security Scan: {result['project']}")
+ print(f"{'='*60}")
+ print(f"Status: {result['summary']['overall_status']}")
+ print(f"Total Findings: {result['summary']['total_findings']}")
+ print(f" Critical: {result['summary']['critical']}")
+ print(f" High: {result['summary']['high']}")
+ print(f"{'='*60}\n")
+
+ for scan_name, scan_result in result['scans'].items():
+ print(f"\n{scan_name.upper()}: {scan_result['status']}")
+ for finding in scan_result.get('findings', [])[:5]:
+ print(f" - {finding}")
+ else:
+ print(json.dumps(result, indent=2))
+
+
+if __name__ == "__main__":
+ main()
diff --git a/.agent/skills/web-design-guidelines/SKILL.md b/.agent/skills/web-design-guidelines/SKILL.md
new file mode 100644
index 0000000..24f1ce7
--- /dev/null
+++ b/.agent/skills/web-design-guidelines/SKILL.md
@@ -0,0 +1,57 @@
+---
+name: web-design-guidelines
+description: Review UI code for Web Interface Guidelines compliance. Use when asked to "review my UI", "check accessibility", "audit design", "review UX", or "check my site against best practices".
+metadata:
+ author: vercel
+ version: "1.0.0"
+ argument-hint: <file-or-pattern>
+---
+
+# Web Interface Guidelines
+
+Review files for compliance with Web Interface Guidelines.
+
+## How It Works
+
+1. Fetch the latest guidelines from the source URL below
+2. Read the specified files (or prompt user for files/pattern)
+3. Check against all rules in the fetched guidelines
+4. Output findings in the terse `file:line` format
+
+## Guidelines Source
+
+Fetch fresh guidelines before each review:
+
+```
+https://raw.githubusercontent.com/vercel-labs/web-interface-guidelines/main/command.md
+```
+
+Use WebFetch to retrieve the latest rules. The fetched content contains all the rules and output format instructions.
+
+## Usage
+
+When a user provides a file or pattern argument:
+1. Fetch guidelines from the source URL above
+2. Read the specified files
+3. Apply all rules from the fetched guidelines
+4. Output findings using the format specified in the guidelines
+
+If no files specified, ask the user which files to review.
+
+---
+
+## Related Skills
+
+| Skill | When to Use |
+|-------|-------------|
+| **[frontend-design](../frontend-design/SKILL.md)** | Before coding - Learn design principles (color, typography, UX psychology) |
+| **web-design-guidelines** (this) | After coding - Audit for accessibility, performance, and best practices |
+
+## Design Workflow
+
+```
+1. DESIGN → Read frontend-design principles
+2. CODE → Implement the design
+3. AUDIT → Run web-design-guidelines review ← YOU ARE HERE
+4. FIX → Address findings from audit
+```
diff --git a/.agent/skills/webapp-testing/SKILL.md b/.agent/skills/webapp-testing/SKILL.md
new file mode 100644
index 0000000..107a00b
--- /dev/null
+++ b/.agent/skills/webapp-testing/SKILL.md
@@ -0,0 +1,187 @@
+---
+name: webapp-testing
+description: Web application testing principles. E2E, Playwright, deep audit strategies.
+allowed-tools: Read, Write, Edit, Glob, Grep, Bash
+---
+
+# Web App Testing
+
+> Discover and test everything. Leave no route untested.
+
+## 🔧 Runtime Scripts
+
+**Execute these for automated browser testing:**
+
+| Script | Purpose | Usage |
+|--------|---------|-------|
+| `scripts/playwright_runner.py` | Basic browser test | `python scripts/playwright_runner.py https://example.com` |
+| | With screenshot | `python scripts/playwright_runner.py <url> --screenshot` |
+| | Accessibility check | `python scripts/playwright_runner.py <url> --a11y` |
+
+**Requires:** `pip install playwright && playwright install chromium`
+
+---
+
+## 1. Deep Audit Approach
+
+### Discovery First
+
+| Target | How to Find |
+|--------|-------------|
+| Routes | Scan app/, pages/, router files |
+| API endpoints | Grep for HTTP methods |
+| Components | Find component directories |
+| Features | Read documentation |
+
+### Systematic Testing
+
+1. **Map** - List all routes/APIs
+2. **Scan** - Verify they respond
+3. **Test** - Cover critical paths
+
+---
+
+## 2. Testing Pyramid for Web
+
+```
+ /\ E2E (Few)
+ / \ Critical user flows
+ /----\
+ / \ Integration (Some)
+ /--------\ API, data flow
+ / \
+ /------------\ Component (Many)
+ Individual UI pieces
+```
+
+---
+
+## 3. E2E Test Principles
+
+### What to Test
+
+| Priority | Tests |
+|----------|-------|
+| 1 | Happy path user flows |
+| 2 | Authentication flows |
+| 3 | Critical business actions |
+| 4 | Error handling |
+
+### E2E Best Practices
+
+| Practice | Why |
+|----------|-----|
+| Use data-testid | Stable selectors |
+| Wait for elements | Avoid flaky tests |
+| Clean state | Independent tests |
+| Avoid implementation details | Test user behavior |
+
+---
+
+## 4. Playwright Principles
+
+### Core Concepts
+
+| Concept | Use |
+|---------|-----|
+| Page Object Model | Encapsulate page logic |
+| Fixtures | Reusable test setup |
+| Assertions | Built-in auto-wait |
+| Trace Viewer | Debug failures |
+
+### Configuration
+
+| Setting | Recommendation |
+|---------|----------------|
+| Retries | 2 on CI |
+| Trace | on-first-retry |
+| Screenshots | on-failure |
+| Video | retain-on-failure |
+
+---
+
+## 5. Visual Testing
+
+### When to Use
+
+| Scenario | Value |
+|----------|-------|
+| Design system | High |
+| Marketing pages | High |
+| Component library | Medium |
+| Dynamic content | Lower |
+
+### Strategy
+
+- Baseline screenshots
+- Compare on changes
+- Review visual diffs
+- Update intentional changes
+
+---
+
+## 6. API Testing Principles
+
+### Coverage Areas
+
+| Area | Tests |
+|------|-------|
+| Status codes | 200, 400, 404, 500 |
+| Response shape | Matches schema |
+| Error messages | User-friendly |
+| Edge cases | Empty, large, special chars |
+
+---
+
+## 7. Test Organization
+
+### File Structure
+
+```
+tests/
+├── e2e/ # Full user flows
+├── integration/ # API, data
+├── component/ # UI units
+└── fixtures/ # Shared data
+```
+
+### Naming Convention
+
+| Pattern | Example |
+|---------|---------|
+| Feature-based | `login.spec.ts` |
+| Descriptive | `user-can-checkout.spec.ts` |
+
+---
+
+## 8. CI Integration
+
+### Pipeline Steps
+
+1. Install dependencies
+2. Install browsers
+3. Run tests
+4. Upload artifacts (traces, screenshots)
+
+### Parallelization
+
+| Strategy | Use |
+|----------|-----|
+| Per file | Playwright default |
+| Sharding | Large suites |
+| Workers | Multiple browsers |
+
+---
+
+## 9. Anti-Patterns
+
+| ❌ Don't | ✅ Do |
+|----------|-------|
+| Test implementation | Test behavior |
+| Hardcode waits | Use auto-wait |
+| Skip cleanup | Isolate tests |
+| Ignore flaky tests | Fix root cause |
+
+---
+
+> **Remember:** E2E tests are expensive. Use them for critical paths only.
diff --git a/.agent/skills/webapp-testing/scripts/playwright_runner.py b/.agent/skills/webapp-testing/scripts/playwright_runner.py
new file mode 100644
index 0000000..75d6f07
--- /dev/null
+++ b/.agent/skills/webapp-testing/scripts/playwright_runner.py
@@ -0,0 +1,173 @@
+#!/usr/bin/env python3
+"""
+Skill: webapp-testing
+Script: playwright_runner.py
+Purpose: Run basic Playwright browser tests
+Usage: python playwright_runner.py <url> [--screenshot]
+Output: JSON with page info, health status, and optional screenshot path
+Note: Requires playwright (pip install playwright && playwright install chromium)
+Screenshots: Saved to system temp directory (auto-cleaned by OS)
+"""
+import sys
+import json
+import os
+import tempfile
+from datetime import datetime
+
+# Fix Windows console encoding for Unicode output
+try:
+ sys.stdout.reconfigure(encoding='utf-8', errors='replace')
+ sys.stderr.reconfigure(encoding='utf-8', errors='replace')
+except AttributeError:
+ pass # Python < 3.7
+
+try:
+ from playwright.sync_api import sync_playwright
+ PLAYWRIGHT_AVAILABLE = True
+except ImportError:
+ PLAYWRIGHT_AVAILABLE = False
+
+
+def run_basic_test(url: str, take_screenshot: bool = False) -> dict:
+ """Run basic browser test on URL."""
+ if not PLAYWRIGHT_AVAILABLE:
+ return {
+ "error": "Playwright not installed",
+ "fix": "pip install playwright && playwright install chromium"
+ }
+
+ result = {
+ "url": url,
+ "timestamp": datetime.now().isoformat(),
+ "status": "pending"
+ }
+
+ try:
+ with sync_playwright() as p:
+ browser = p.chromium.launch(headless=True)
+ context = browser.new_context(
+ viewport={"width": 1280, "height": 720},
+ user_agent="Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36"
+ )
+ page = context.new_page()
+
+ # Navigate
+ response = page.goto(url, wait_until="networkidle", timeout=30000)
+
+ # Basic info
+ result["page"] = {
+ "title": page.title(),
+ "url": page.url,
+ "status_code": response.status if response else None
+ }
+
+ # Health checks
+ result["health"] = {
+ "loaded": response.ok if response else False,
+ "has_title": bool(page.title()),
+ "has_h1": page.locator("h1").count() > 0,
+ "has_links": page.locator("a").count() > 0,
+ "has_images": page.locator("img").count() > 0
+ }
+
+ # Console errors
+ console_errors = []
+ page.on("console", lambda msg: console_errors.append(msg.text) if msg.type == "error" else None)
+
+ # Performance metrics
+ result["performance"] = {
+ "dom_content_loaded": page.evaluate("window.performance.timing.domContentLoadedEventEnd - window.performance.timing.navigationStart"),
+ "load_complete": page.evaluate("window.performance.timing.loadEventEnd - window.performance.timing.navigationStart")
+ }
+
+ # Screenshot - uses system temp directory (cross-platform, auto-cleaned)
+ if take_screenshot:
+ # Cross-platform: Windows=%TEMP%, Linux/macOS=/tmp
+ screenshot_dir = os.path.join(tempfile.gettempdir(), "maestro_screenshots")
+ os.makedirs(screenshot_dir, exist_ok=True)
+ screenshot_path = os.path.join(screenshot_dir, f"screenshot_{datetime.now().strftime('%Y%m%d_%H%M%S')}.png")
+ page.screenshot(path=screenshot_path, full_page=True)
+ result["screenshot"] = screenshot_path
+ result["screenshot_note"] = "Saved to temp directory (auto-cleaned by OS)"
+
+ # Element counts
+ result["elements"] = {
+ "links": page.locator("a").count(),
+ "buttons": page.locator("button").count(),
+ "inputs": page.locator("input").count(),
+ "images": page.locator("img").count(),
+ "forms": page.locator("form").count()
+ }
+
+ browser.close()
+
+ result["status"] = "success" if result["health"]["loaded"] else "failed"
+ result["summary"] = "[OK] Page loaded successfully" if result["status"] == "success" else "[X] Page failed to load"
+
+ except Exception as e:
+ result["status"] = "error"
+ result["error"] = str(e)
+ result["summary"] = f"[X] Error: {str(e)[:100]}"
+
+ return result
+
+
+def run_accessibility_check(url: str) -> dict:
+ """Run basic accessibility check."""
+ if not PLAYWRIGHT_AVAILABLE:
+ return {"error": "Playwright not installed"}
+
+ result = {"url": url, "accessibility": {}}
+
+ try:
+ with sync_playwright() as p:
+ browser = p.chromium.launch(headless=True)
+ page = browser.new_page()
+ page.goto(url, wait_until="networkidle", timeout=30000)
+
+ # Basic a11y checks
+ result["accessibility"] = {
+ "images_with_alt": page.locator("img[alt]").count(),
+ "images_without_alt": page.locator("img:not([alt])").count(),
+ "buttons_with_label": page.locator("button[aria-label], button:has-text('')").count(),
+ "links_with_text": page.locator("a:has-text('')").count(),
+ "form_labels": page.locator("label").count(),
+ "headings": {
+ "h1": page.locator("h1").count(),
+ "h2": page.locator("h2").count(),
+ "h3": page.locator("h3").count()
+ }
+ }
+
+ browser.close()
+ result["status"] = "success"
+
+ except Exception as e:
+ result["status"] = "error"
+ result["error"] = str(e)
+
+ return result
+
+
+if __name__ == "__main__":
+ if len(sys.argv) < 2:
+ print(json.dumps({
+ "error": "Usage: python playwright_runner.py <url> [--screenshot] [--a11y]",
+ "examples": [
+ "python playwright_runner.py https://example.com",
+ "python playwright_runner.py https://example.com --screenshot",
+ "python playwright_runner.py https://example.com --a11y"
+ ]
+ }, indent=2))
+ sys.exit(1)
+
+ url = sys.argv[1]
+ take_screenshot = "--screenshot" in sys.argv
+ check_a11y = "--a11y" in sys.argv
+
+ if check_a11y:
+ result = run_accessibility_check(url)
+ else:
+ result = run_basic_test(url, take_screenshot)
+
+ print(json.dumps(result, indent=2))
diff --git a/.agent/workflows/brainstorm.md b/.agent/workflows/brainstorm.md
new file mode 100644
index 0000000..9a84b78
--- /dev/null
+++ b/.agent/workflows/brainstorm.md
@@ -0,0 +1,113 @@
+---
+description: Structured brainstorming for projects and features. Explores multiple options before implementation.
+---
+
+# /brainstorm - Structured Idea Exploration
+
+$ARGUMENTS
+
+---
+
+## Purpose
+
+This command activates BRAINSTORM mode for structured idea exploration. Use when you need to explore options before committing to an implementation.
+
+---
+
+## Behavior
+
+When `/brainstorm` is triggered:
+
+1. **Understand the goal**
+ - What problem are we solving?
+ - Who is the user?
+ - What constraints exist?
+
+2. **Generate options**
+ - Provide at least 3 different approaches
+ - Each with pros and cons
+ - Consider unconventional solutions
+
+3. **Compare and recommend**
+ - Summarize tradeoffs
+ - Give a recommendation with reasoning
+
+---
+
+## Output Format
+
+```markdown
+## 🧠 Brainstorm: [Topic]
+
+### Context
+[Brief problem statement]
+
+---
+
+### Option A: [Name]
+[Description]
+
+✅ **Pros:**
+- [benefit 1]
+- [benefit 2]
+
+❌ **Cons:**
+- [drawback 1]
+
+📊 **Effort:** Low | Medium | High
+
+---
+
+### Option B: [Name]
+[Description]
+
+✅ **Pros:**
+- [benefit 1]
+
+❌ **Cons:**
+- [drawback 1]
+- [drawback 2]
+
+📊 **Effort:** Low | Medium | High
+
+---
+
+### Option C: [Name]
+[Description]
+
+✅ **Pros:**
+- [benefit 1]
+
+❌ **Cons:**
+- [drawback 1]
+
+📊 **Effort:** Low | Medium | High
+
+---
+
+## 💡 Recommendation
+
+**Option [X]** because [reasoning].
+
+What direction would you like to explore?
+```
+
+---
+
+## Examples
+
+```
+/brainstorm authentication system
+/brainstorm state management for complex form
+/brainstorm database schema for social app
+/brainstorm caching strategy
+```
+
+---
+
+## Key Principles
+
+- **No code** - this is about ideas, not implementation
+- **Visual when helpful** - use diagrams for architecture
+- **Honest tradeoffs** - don't hide complexity
+- **Defer to user** - present options, let them decide
diff --git a/.agent/workflows/create.md b/.agent/workflows/create.md
new file mode 100644
index 0000000..0c98ecf
--- /dev/null
+++ b/.agent/workflows/create.md
@@ -0,0 +1,59 @@
+---
+description: Create new application command. Triggers App Builder skill and starts interactive dialogue with user.
+---
+
+# /create - Create Application
+
+$ARGUMENTS
+
+---
+
+## Task
+
+This command starts a new application creation process.
+
+### Steps:
+
+1. **Request Analysis**
+ - Understand what the user wants
+ - If information is missing, use `conversation-manager` skill to ask
+
+2. **Project Planning**
+ - Use `project-planner` agent for task breakdown
+ - Determine tech stack
+ - Plan file structure
+ - Create plan file and proceed to building
+
+3. **Application Building (After Approval)**
+ - Orchestrate with `app-builder` skill
+ - Coordinate expert agents:
+ - `database-architect` → Schema
+ - `backend-specialist` → API
+ - `frontend-specialist` → UI
+
+4. **Preview**
+ - Start with `auto_preview.py` when complete
+ - Present URL to user
+
+---
+
+## Usage Examples
+
+```
+/create blog site
+/create e-commerce app with product listing and cart
+/create todo app
+/create Instagram clone
+/create crm system with customer management
+```
+
+---
+
+## Before Starting
+
+If request is unclear, ask these questions:
+- What type of application?
+- What are the basic features?
+- Who will use it?
+
+Use defaults, add details later.
diff --git a/.agent/workflows/debug.md b/.agent/workflows/debug.md
new file mode 100644
index 0000000..b86095d
--- /dev/null
+++ b/.agent/workflows/debug.md
@@ -0,0 +1,103 @@
+---
+description: Debugging command. Activates DEBUG mode for systematic problem investigation.
+---
+
+# /debug - Systematic Problem Investigation
+
+$ARGUMENTS
+
+---
+
+## Purpose
+
+This command activates DEBUG mode for systematic investigation of issues, errors, or unexpected behavior.
+
+---
+
+## Behavior
+
+When `/debug` is triggered:
+
+1. **Gather information**
+ - Error message
+ - Reproduction steps
+ - Expected vs actual behavior
+ - Recent changes
+
+2. **Form hypotheses**
+ - List possible causes
+ - Order by likelihood
+
+3. **Investigate systematically**
+ - Test each hypothesis
+ - Check logs, data flow
+ - Use elimination method
+
+4. **Fix and prevent**
+ - Apply fix
+ - Explain root cause
+ - Add prevention measures
+
+---
+
+## Output Format
+
+```markdown
+## 🔍 Debug: [Issue]
+
+### 1. Symptom
+[What's happening]
+
+### 2. Information Gathered
+- Error: `[error message]`
+- File: `[filepath]`
+- Line: [line number]
+
+### 3. Hypotheses
+1. ❓ [Most likely cause]
+2. ❓ [Second possibility]
+3. ❓ [Less likely cause]
+
+### 4. Investigation
+
+**Testing hypothesis 1:**
+[What I checked] → [Result]
+
+**Testing hypothesis 2:**
+[What I checked] → [Result]
+
+### 5. Root Cause
+🎯 **[Explanation of why this happened]**
+
+### 6. Fix
+```[language]
+// Before
+[broken code]
+
+// After
+[fixed code]
+```
+
+### 7. Prevention
+🛡️ [How to prevent this in the future]
+```
+
+---
+
+## Examples
+
+```
+/debug login not working
+/debug API returns 500
+/debug form doesn't submit
+/debug data not saving
+```
+
+---
+
+## Key Principles
+
+- **Ask before assuming** - get full error context
+- **Test hypotheses** - don't guess randomly
+- **Explain why** - not just what to fix
+- **Prevent recurrence** - add tests, validation
diff --git a/.agent/workflows/deploy.md b/.agent/workflows/deploy.md
new file mode 100644
index 0000000..991b328
--- /dev/null
+++ b/.agent/workflows/deploy.md
@@ -0,0 +1,176 @@
+---
+description: Deployment command for production releases. Pre-flight checks and deployment execution.
+---
+
+# /deploy - Production Deployment
+
+$ARGUMENTS
+
+---
+
+## Purpose
+
+This command handles production deployment with pre-flight checks, deployment execution, and verification.
+
+---
+
+## Sub-commands
+
+```
+/deploy - Interactive deployment wizard
+/deploy check - Run pre-deployment checks only
+/deploy preview - Deploy to preview/staging
+/deploy production - Deploy to production
+/deploy rollback - Rollback to previous version
+```
+
+---
+
+## Pre-Deployment Checklist
+
+Before any deployment:
+
+```markdown
+## 🚀 Pre-Deploy Checklist
+
+### Code Quality
+- [ ] No TypeScript errors (`npx tsc --noEmit`)
+- [ ] ESLint passing (`npx eslint .`)
+- [ ] All tests passing (`npm test`)
+
+### Security
+- [ ] No hardcoded secrets
+- [ ] Environment variables documented
+- [ ] Dependencies audited (`npm audit`)
+
+### Performance
+- [ ] Bundle size acceptable
+- [ ] No console.log statements
+- [ ] Images optimized
+
+### Documentation
+- [ ] README updated
+- [ ] CHANGELOG updated
+- [ ] API docs current
+
+### Ready to deploy? (y/n)
+```
+
+---
+
+## Deployment Flow
+
+```
+┌─────────────────┐
+│ /deploy │
+└────────┬────────┘
+ │
+ ▼
+┌─────────────────┐
+│ Pre-flight │
+│ checks │
+└────────┬────────┘
+ │
+ Pass? ──No──► Fix issues
+ │
+ Yes
+ │
+ ▼
+┌─────────────────┐
+│ Build │
+│ application │
+└────────┬────────┘
+ │
+ ▼
+┌─────────────────┐
+│ Deploy to │
+│ platform │
+└────────┬────────┘
+ │
+ ▼
+┌─────────────────┐
+│ Health check │
+│ & verify │
+└────────┬────────┘
+ │
+ ▼
+┌─────────────────┐
+│ ✅ Complete │
+└─────────────────┘
+```
+
+---
+
+## Output Format
+
+### Successful Deploy
+
+```markdown
+## 🚀 Deployment Complete
+
+### Summary
+- **Version:** v1.2.3
+- **Environment:** production
+- **Duration:** 47 seconds
+- **Platform:** Vercel
+
+### URLs
+- 🌐 Production: https://app.example.com
+- 📊 Dashboard: https://vercel.com/project
+
+### What Changed
+- Added user profile feature
+- Fixed login bug
+- Updated dependencies
+
+### Health Check
+✅ API responding (200 OK)
+✅ Database connected
+✅ All services healthy
+```
+
+### Failed Deploy
+
+```markdown
+## ❌ Deployment Failed
+
+### Error
+Build failed at step: TypeScript compilation
+
+### Details
+```
+error TS2345: Argument of type 'string' is not assignable...
+```
+
+### Resolution
+1. Fix TypeScript error in `src/services/user.ts:45`
+2. Run `npm run build` locally to verify
+3. Try `/deploy` again
+
+### Rollback Available
+Previous version (v1.2.2) is still active.
+Run `/deploy rollback` if needed.
+```
+
+---
+
+## Platform Support
+
+| Platform | Command | Notes |
+|----------|---------|-------|
+| Vercel | `vercel --prod` | Auto-detected for Next.js |
+| Railway | `railway up` | Needs Railway CLI |
+| Fly.io | `fly deploy` | Needs flyctl |
+| Docker | `docker compose up -d` | For self-hosted |
+
+---
+
+## Examples
+
+```
+/deploy
+/deploy check
+/deploy preview
+/deploy production --skip-tests
+/deploy rollback
+```
diff --git a/.agent/workflows/enhance.md b/.agent/workflows/enhance.md
new file mode 100644
index 0000000..ebeaeb0
--- /dev/null
+++ b/.agent/workflows/enhance.md
@@ -0,0 +1,63 @@
+---
+description: Add or update features in existing application. Used for iterative development.
+---
+
+# /enhance - Update Application
+
+$ARGUMENTS
+
+---
+
+## Task
+
+This command adds features or makes updates to existing application.
+
+### Steps:
+
+1. **Understand Current State**
+ - Load project state with `python .agent/scripts/session_manager.py info`
+ - Understand existing features, tech stack
+
+2. **Plan Changes**
+ - Determine what will be added/changed
+ - Detect affected files
+ - Check dependencies
+
+3. **Present Plan to User** (for major changes)
+ ```
+ "To add admin panel:
+ - I'll create 15 new files
+ - Update 8 files
+ - Takes ~10 minutes
+
+ Should I start?"
+ ```
+
+4. **Apply**
+ - Call relevant agents
+ - Make changes
+ - Test
+
+5. **Update Preview**
+ - Hot reload or restart
+
+---
+
+## Usage Examples
+
+```
+/enhance add dark mode
+/enhance build admin panel
+/enhance integrate payment system
+/enhance add search feature
+/enhance edit profile page
+/enhance make responsive
+```
+
+---
+
+## Caution
+
+- Get approval for major changes
+- Warn on conflicting requests (e.g., "use Firebase" when project uses PostgreSQL)
+- Commit each change with git
diff --git a/.agent/workflows/orchestrate.md b/.agent/workflows/orchestrate.md
new file mode 100644
index 0000000..5486846
--- /dev/null
+++ b/.agent/workflows/orchestrate.md
@@ -0,0 +1,237 @@
+---
+description: Coordinate multiple agents for complex tasks. Use for multi-perspective analysis, comprehensive reviews, or tasks requiring different domain expertise.
+---
+
+# Multi-Agent Orchestration
+
+You are now in **ORCHESTRATION MODE**. Your task: coordinate specialized agents to solve this complex problem.
+
+## Task to Orchestrate
+$ARGUMENTS
+
+---
+
+## 🔴 CRITICAL: Minimum Agent Requirement
+
+> ⚠️ **ORCHESTRATION = MINIMUM 3 DIFFERENT AGENTS**
+>
+> If you use fewer than 3 agents, you are NOT orchestrating - you're just delegating.
+>
+> **Validation before completion:**
+> - Count invoked agents
+> - If `agent_count < 3` → STOP and invoke more agents
+> - Single agent = FAILURE of orchestration
+
+### Agent Selection Matrix
+
+| Task Type | REQUIRED Agents (minimum) |
+|-----------|---------------------------|
+| **Web App** | frontend-specialist, backend-specialist, test-engineer |
+| **API** | backend-specialist, security-auditor, test-engineer |
+| **UI/Design** | frontend-specialist, seo-specialist, performance-optimizer |
+| **Database** | database-architect, backend-specialist, security-auditor |
+| **Full Stack** | project-planner, frontend-specialist, backend-specialist, devops-engineer |
+| **Debug** | debugger, explorer-agent, test-engineer |
+| **Security** | security-auditor, penetration-tester, devops-engineer |
+
+---
+
+## Pre-Flight: Mode Check
+
+| Current Mode | Task Type | Action |
+|--------------|-----------|--------|
+| **plan** | Any | ✅ Proceed with planning-first approach |
+| **edit** | Simple execution | ✅ Proceed directly |
+| **edit** | Complex/multi-file | ⚠️ Ask: "This task requires planning. Switch to plan mode?" |
+| **ask** | Any | ⚠️ Ask: "Ready to orchestrate. Switch to edit or plan mode?" |
+
+---
+
+## 🔴 STRICT 2-PHASE ORCHESTRATION
+
+### PHASE 1: PLANNING (Sequential - NO parallel agents)
+
+| Step | Agent | Action |
+|------|-------|--------|
+| 1 | `project-planner` | Create docs/PLAN.md |
+| 2 | (optional) `explorer-agent` | Codebase discovery if needed |
+
+> 🔴 **NO OTHER AGENTS during planning!** Only project-planner and explorer-agent.
+
+### ⏸️ CHECKPOINT: User Approval
+
+```
+After PLAN.md is complete, ASK:
+
+"✅ Plan created: docs/PLAN.md
+
+Do you approve? (Y/N)
+- Y: Start implementation
+- N: I'll revise the plan"
+```
+
+> 🔴 **DO NOT proceed to Phase 2 without explicit user approval!**
+
+### PHASE 2: IMPLEMENTATION (Parallel agents after approval)
+
+| Parallel Group | Agents |
+|----------------|--------|
+| Foundation | `database-architect`, `security-auditor` |
+| Core | `backend-specialist`, `frontend-specialist` |
+| Polish | `test-engineer`, `devops-engineer` |
+
+> ✅ After user approval, invoke multiple agents in PARALLEL.
+
+## Available Agents (17 total)
+
+| Agent | Domain | Use When |
+|-------|--------|----------|
+| `project-planner` | Planning | Task breakdown, PLAN.md |
+| `explorer-agent` | Discovery | Codebase mapping |
+| `frontend-specialist` | UI/UX | React, Vue, CSS, HTML |
+| `backend-specialist` | Server | API, Node.js, Python |
+| `database-architect` | Data | SQL, NoSQL, Schema |
+| `security-auditor` | Security | Vulnerabilities, Auth |
+| `penetration-tester` | Security | Active testing |
+| `test-engineer` | Testing | Unit, E2E, Coverage |
+| `devops-engineer` | Ops | CI/CD, Docker, Deploy |
+| `mobile-developer` | Mobile | React Native, Flutter |
+| `performance-optimizer` | Speed | Lighthouse, Profiling |
+| `seo-specialist` | SEO | Meta, Schema, Rankings |
+| `documentation-writer` | Docs | README, API docs |
+| `debugger` | Debug | Error analysis |
+| `game-developer` | Games | Unity, Godot |
+| `orchestrator` | Meta | Coordination |
+
+---
+
+## Orchestration Protocol
+
+### Step 1: Analyze Task Domains
+Identify ALL domains this task touches:
+```
+□ Security → security-auditor, penetration-tester
+□ Backend/API → backend-specialist
+□ Frontend/UI → frontend-specialist
+□ Database → database-architect
+□ Testing → test-engineer
+□ DevOps → devops-engineer
+□ Mobile → mobile-developer
+□ Performance → performance-optimizer
+□ SEO → seo-specialist
+□ Planning → project-planner
+```
+
+### Step 2: Phase Detection
+
+| If Plan Exists | Action |
+|----------------|--------|
+| NO `docs/PLAN.md` | → Go to PHASE 1 (planning only) |
+| YES `docs/PLAN.md` + user approved | → Go to PHASE 2 (implementation) |
+
+### Step 3: Execute Based on Phase
+
+**PHASE 1 (Planning):**
+```
+Use the project-planner agent to create PLAN.md
+→ STOP after plan is created
+→ ASK user for approval
+```
+
+**PHASE 2 (Implementation - after approval):**
+```
+Invoke agents in PARALLEL:
+Use the frontend-specialist agent to [task]
+Use the backend-specialist agent to [task]
+Use the test-engineer agent to [task]
+```
+
+**🔴 CRITICAL: Context Passing (MANDATORY)**
+
+When invoking ANY subagent, you MUST include:
+
+1. **Original User Request:** Full text of what user asked
+2. **Decisions Made:** All user answers to Socratic questions
+3. **Previous Agent Work:** Summary of what previous agents did
+4. **Current Plan State:** If plan files exist in workspace, include them
+
+**Example with FULL context:**
+```
+Use the project-planner agent to create PLAN.md:
+
+**CONTEXT:**
+- User Request: "A social platform for students, using mock data"
+- Decisions: Tech=Vue 3, Layout=Grid Widgets, Auth=Mock, Design=Youthful & dynamic
+- Previous Work: Orchestrator asked 6 questions, user chose all options
+- Current Plan: playful-roaming-dream.md exists in workspace with initial structure
+
+**TASK:** Create detailed PLAN.md based on ABOVE decisions. Do NOT infer from folder name.
+```
+
+> ⚠️ **VIOLATION:** Invoking subagent without full context = subagent will make wrong assumptions!
+
+
+### Step 4: Verification (MANDATORY)
+The LAST agent must run appropriate verification scripts:
+```bash
+python .agent/skills/vulnerability-scanner/scripts/security_scan.py .
+python .agent/skills/lint-and-validate/scripts/lint_runner.py .
+```
+
+### Step 5: Synthesize Results
+Combine all agent outputs into unified report.
+
+---
+
+## Output Format
+
+```markdown
+## 🎼 Orchestration Report
+
+### Task
+[Original task summary]
+
+### Mode
+[Current Antigravity Agent mode: plan/edit/ask]
+
+### Agents Invoked (MINIMUM 3)
+| # | Agent | Focus Area | Status |
+|---|-------|------------|--------|
+| 1 | project-planner | Task breakdown | ✅ |
+| 2 | frontend-specialist | UI implementation | ✅ |
+| 3 | test-engineer | Verification scripts | ✅ |
+
+### Verification Scripts Executed
+- [x] security_scan.py → Pass/Fail
+- [x] lint_runner.py → Pass/Fail
+
+### Key Findings
+1. **[Agent 1]**: Finding
+2. **[Agent 2]**: Finding
+3. **[Agent 3]**: Finding
+
+### Deliverables
+- [ ] PLAN.md created
+- [ ] Code implemented
+- [ ] Tests passing
+- [ ] Scripts verified
+
+### Summary
+[One paragraph synthesis of all agent work]
+```
+
+---
+
+## 🔴 EXIT GATE
+
+Before completing orchestration, verify:
+
+1. ✅ **Agent Count:** `invoked_agents >= 3`
+2. ✅ **Scripts Executed:** At least `security_scan.py` ran
+3. ✅ **Report Generated:** Orchestration Report with all agents listed
+
+> **If any check fails → DO NOT mark orchestration complete. Invoke more agents or run scripts.**
+
+---
+
+**Begin orchestration now. Select 3+ agents, execute sequentially, run verification scripts, synthesize results.**
diff --git a/.agent/workflows/plan.md b/.agent/workflows/plan.md
new file mode 100644
index 0000000..bf525a1
--- /dev/null
+++ b/.agent/workflows/plan.md
@@ -0,0 +1,89 @@
+---
+description: Create project plan using project-planner agent. No code writing - only plan file generation.
+---
+
+# /plan - Project Planning Mode
+
+$ARGUMENTS
+
+---
+
+## 🔴 CRITICAL RULES
+
+1. **NO CODE WRITING** - This command creates plan file only
+2. **Use project-planner agent** - NOT Antigravity Agent's native Plan mode
+3. **Socratic Gate** - Ask clarifying questions before planning
+4. **Dynamic Naming** - Plan file named based on task
+
+---
+
+## Task
+
+Use the `project-planner` agent with this context:
+
+```
+CONTEXT:
+- User Request: $ARGUMENTS
+- Mode: PLANNING ONLY (no code)
+- Output: docs/PLAN-{task-slug}.md (dynamic naming)
+
+NAMING RULES:
+1. Extract 2-3 key words from request
+2. Lowercase, hyphen-separated
+3. Max 30 characters
+4. Example: "e-commerce cart" → PLAN-ecommerce-cart.md
+
+RULES:
+1. Follow project-planner.md Phase -1 (Context Check)
+2. Follow project-planner.md Phase 0 (Socratic Gate)
+3. Create PLAN-{slug}.md with task breakdown
+4. DO NOT write any code files
+5. REPORT the exact file name created
+```
+
+---
+
+## Expected Output
+
+| Deliverable | Location |
+|-------------|----------|
+| Project Plan | `docs/PLAN-{task-slug}.md` |
+| Task Breakdown | Inside plan file |
+| Agent Assignments | Inside plan file |
+| Verification Checklist | Phase X in plan file |
+
+---
+
+## After Planning
+
+Tell user:
+```
+[OK] Plan created: docs/PLAN-{slug}.md
+
+Next steps:
+- Review the plan
+- Run `/create` to start implementation
+- Or modify plan manually
+```
+
+---
+
+## Naming Examples
+
+| Request | Plan File |
+|---------|-----------|
+| `/plan e-commerce site with cart` | `docs/PLAN-ecommerce-cart.md` |
+| `/plan mobile app for fitness` | `docs/PLAN-fitness-app.md` |
+| `/plan add dark mode feature` | `docs/PLAN-dark-mode.md` |
+| `/plan fix authentication bug` | `docs/PLAN-auth-fix.md` |
+| `/plan SaaS dashboard` | `docs/PLAN-saas-dashboard.md` |
+
+---
+
+## Usage
+
+```
+/plan e-commerce site with cart
+/plan mobile app for fitness tracking
+/plan SaaS dashboard with analytics
+```
diff --git a/.agent/workflows/preview.md b/.agent/workflows/preview.md
new file mode 100644
index 0000000..983a797
--- /dev/null
+++ b/.agent/workflows/preview.md
@@ -0,0 +1,81 @@
+---
+description: Preview server start, stop, and status check. Local development server management.
+---
+
+# /preview - Preview Management
+
+$ARGUMENTS
+
+---
+
+## Task
+
+Manage preview server: start, stop, status check.
+
+### Commands
+
+```
+/preview - Show current status
+/preview start - Start server
+/preview stop - Stop server
+/preview restart - Restart
+/preview check - Health check
+```
+
+---
+
+## Usage Examples
+
+### Start Server
+```
+/preview start
+
+Response:
+🚀 Starting preview...
+ Port: 3000
+ Type: Next.js
+
+✅ Preview ready!
+ URL: http://localhost:3000
+```
+
+### Status Check
+```
+/preview
+
+Response:
+=== Preview Status ===
+
+🌐 URL: http://localhost:3000
+📁 Project: C:/projects/my-app
+🏷️ Type: nextjs
+💚 Health: OK
+```
+
+### Port Conflict
+```
+/preview start
+
+Response:
+⚠️ Port 3000 is in use.
+
+Options:
+1. Start on port 3001
+2. Close app on 3000
+3. Specify different port
+
+Which one? (default: 1)
+```
+
+---
+
+## Technical
+
+Auto preview uses `auto_preview.py` script:
+
+```bash
+python .agent/scripts/auto_preview.py start [port]
+python .agent/scripts/auto_preview.py stop
+python .agent/scripts/auto_preview.py status
+```
+
diff --git a/.agent/workflows/status.md b/.agent/workflows/status.md
new file mode 100644
index 0000000..76254d8
--- /dev/null
+++ b/.agent/workflows/status.md
@@ -0,0 +1,86 @@
+---
+description: Display agent and project status. Progress tracking and status board.
+---
+
+# /status - Show Status
+
+$ARGUMENTS
+
+---
+
+## Task
+
+Show current project and agent status.
+
+### What It Shows
+
+1. **Project Info**
+ - Project name and path
+ - Tech stack
+ - Current features
+
+2. **Agent Status Board**
+ - Which agents are running
+ - Which tasks are completed
+ - Pending work
+
+3. **File Statistics**
+ - Files created count
+ - Files modified count
+
+4. **Preview Status**
+ - Is server running
+ - URL
+ - Health check
+
+---
+
+## Example Output
+
+```
+=== Project Status ===
+
+📁 Project: my-ecommerce
+📂 Path: C:/projects/my-ecommerce
+🏷️ Type: nextjs-ecommerce
+📊 Status: active
+
+🔧 Tech Stack:
+ Framework: next.js
+ Database: postgresql
+ Auth: clerk
+ Payment: stripe
+
+✅ Features (5):
+ • product-listing
+ • cart
+ • checkout
+ • user-auth
+ • order-history
+
+⏳ Pending (2):
+ • admin-panel
+ • email-notifications
+
+📄 Files: 73 created, 12 modified
+
+=== Agent Status ===
+
+✅ database-architect → Completed
+✅ backend-specialist → Completed
+🔄 frontend-specialist → Dashboard components (60%)
+⏳ test-engineer → Waiting
+
+=== Preview ===
+
+🌐 URL: http://localhost:3000
+💚 Health: OK
+```
+
+---
+
+## Technical
+
+Status uses these scripts:
+- `python .agent/scripts/session_manager.py status`
+- `python .agent/scripts/auto_preview.py status`
diff --git a/.agent/workflows/test.md b/.agent/workflows/test.md
new file mode 100644
index 0000000..d363e5e
--- /dev/null
+++ b/.agent/workflows/test.md
@@ -0,0 +1,144 @@
+---
+description: Test generation and test running command. Creates and executes tests for code.
+---
+
+# /test - Test Generation and Execution
+
+$ARGUMENTS
+
+---
+
+## Purpose
+
+This command generates tests, runs existing tests, or checks test coverage.
+
+---
+
+## Sub-commands
+
+```
+/test - Run all tests
+/test [file/feature] - Generate tests for specific target
+/test coverage - Show test coverage report
+/test watch - Run tests in watch mode
+```
+
+---
+
+## Behavior
+
+### Generate Tests
+
+When asked to test a file or feature:
+
+1. **Analyze the code**
+ - Identify functions and methods
+ - Find edge cases
+ - Detect dependencies to mock
+
+2. **Generate test cases**
+ - Happy path tests
+ - Error cases
+ - Edge cases
+ - Integration tests (if needed)
+
+3. **Write tests**
+ - Use project's test framework (Jest, Vitest, etc.)
+ - Follow existing test patterns
+ - Mock external dependencies
+
+---
+
+## Output Format
+
+### For Test Generation
+
+```markdown
+## 🧪 Tests: [Target]
+
+### Test Plan
+| Test Case | Type | Coverage |
+|-----------|------|----------|
+| Should create user | Unit | Happy path |
+| Should reject invalid email | Unit | Validation |
+| Should handle db error | Unit | Error case |
+
+### Generated Tests
+
+`tests/[file].test.ts`
+
+[Code block with tests]
+
+---
+
+Run with: `npm test`
+```
+
+### For Test Execution
+
+```
+🧪 Running tests...
+
+✅ auth.test.ts (5 passed)
+✅ user.test.ts (8 passed)
+❌ order.test.ts (2 passed, 1 failed)
+
+Failed:
+ ✗ should calculate total with discount
+ Expected: 90
+ Received: 100
+
+Total: 15 tests (14 passed, 1 failed)
+```
+
+---
+
+## Examples
+
+```
+/test src/services/auth.service.ts
+/test user registration flow
+/test coverage
+/test fix failed tests
+```
+
+---
+
+## Test Patterns
+
+### Unit Test Structure
+
+```typescript
+describe('AuthService', () => {
+ describe('login', () => {
+ it('should return token for valid credentials', async () => {
+ // Arrange
+ const credentials = { email: 'test@test.com', password: 'pass123' };
+
+ // Act
+ const result = await authService.login(credentials);
+
+ // Assert
+ expect(result.token).toBeDefined();
+ });
+
+ it('should throw for invalid password', async () => {
+ // Arrange
+ const credentials = { email: 'test@test.com', password: 'wrong' };
+
+ // Act & Assert
+ await expect(authService.login(credentials)).rejects.toThrow('Invalid credentials');
+ });
+ });
+});
+```
+
+---
+
+## Key Principles
+
+- **Test behavior not implementation**
+- **One assertion per test** (when practical)
+- **Descriptive test names**
+- **Arrange-Act-Assert pattern**
+- **Mock external dependencies**
diff --git a/.agent/workflows/ui-ux-pro-max.md b/.agent/workflows/ui-ux-pro-max.md
new file mode 100644
index 0000000..4fc88c5
--- /dev/null
+++ b/.agent/workflows/ui-ux-pro-max.md
@@ -0,0 +1,296 @@
+---
+description: Plan and implement UI
+---
+
+---
+description: AI-powered design intelligence with 50+ styles, 95+ color palettes, and automated design system generation
+---
+
+# ui-ux-pro-max
+
+Comprehensive design guide for web and mobile applications. Contains 50+ styles, 97 color palettes, 57 font pairings, 99 UX guidelines, and 25 chart types across 9 technology stacks. Searchable database with priority-based recommendations.
+
+## Prerequisites
+
+Check if Python is installed:
+
+```bash
+python3 --version || python --version
+```
+
+If Python is not installed, install it based on user's OS:
+
+**macOS:**
+```bash
+brew install python3
+```
+
+**Ubuntu/Debian:**
+```bash
+sudo apt update && sudo apt install python3
+```
+
+**Windows:**
+```powershell
+winget install Python.Python.3.12
+```
+
+---
+
+## How to Use This Workflow
+
+When user requests UI/UX work (design, build, create, implement, review, fix, improve), follow this workflow:
+
+### Step 1: Analyze User Requirements
+
+Extract key information from user request:
+- **Product type**: SaaS, e-commerce, portfolio, dashboard, landing page, etc.
+- **Style keywords**: minimal, playful, professional, elegant, dark mode, etc.
+- **Industry**: healthcare, fintech, gaming, education, etc.
+- **Stack**: React, Vue, Next.js, or default to `html-tailwind`
+
+### Step 2: Generate Design System (REQUIRED)
+
+**Always start with `--design-system`** to get comprehensive recommendations with reasoning:
+
+```bash
+python3 .agent/.shared/ui-ux-pro-max/scripts/search.py "<product_type> <industry> <keywords>" --design-system [-p "Project Name"]
+```
+
+This command:
+1. Searches 5 domains in parallel (product, style, color, landing, typography)
+2. Applies reasoning rules from `ui-reasoning.csv` to select best matches
+3. Returns complete design system: pattern, style, colors, typography, effects
+4. Includes anti-patterns to avoid
+
+**Example:**
+```bash
+python3 .agent/.shared/ui-ux-pro-max/scripts/search.py "beauty spa wellness service" --design-system -p "Serenity Spa"
+```
+
+### Step 2b: Persist Design System (Master + Overrides Pattern)
+
+To save the design system for hierarchical retrieval across sessions, add `--persist`:
+
+```bash
+python3 .agent/.shared/ui-ux-pro-max/scripts/search.py "<query>" --design-system --persist -p "Project Name"
+```
+
+This creates:
+- `design-system/MASTER.md` — Global Source of Truth with all design rules
+- `design-system/pages/` — Folder for page-specific overrides
+
+**With page-specific override:**
+```bash
+python3 .agent/.shared/ui-ux-pro-max/scripts/search.py "<query>" --design-system --persist -p "Project Name" --page "dashboard"
+```
+
+This also creates:
+- `design-system/pages/dashboard.md` — Page-specific deviations from Master
+
+**How hierarchical retrieval works:**
+1. When building a specific page (e.g., "Checkout"), first check `design-system/pages/checkout.md`
+2. If the page file exists, its rules **override** the Master file
+3. If not, use `design-system/MASTER.md` exclusively
+
+### Step 3: Supplement with Detailed Searches (as needed)
+
+After getting the design system, use domain searches to get additional details:
+
+```bash
+python3 .agent/.shared/ui-ux-pro-max/scripts/search.py "<keyword>" --domain <domain> [-n <max_results>]
+```
+
+**When to use detailed searches:**
+
+| Need | Domain | Example |
+|------|--------|---------|
+| More style options | `style` | `--domain style "glassmorphism dark"` |
+| Chart recommendations | `chart` | `--domain chart "real-time dashboard"` |
+| UX best practices | `ux` | `--domain ux "animation accessibility"` |
+| Alternative fonts | `typography` | `--domain typography "elegant luxury"` |
+| Landing structure | `landing` | `--domain landing "hero social-proof"` |
+
+### Step 4: Stack Guidelines (Default: html-tailwind)
+
+Get implementation-specific best practices. If user doesn't specify a stack, **default to `html-tailwind`**.
+
+```bash
+python3 .agent/.shared/ui-ux-pro-max/scripts/search.py "<keyword>" --stack html-tailwind
+```
+
+Available stacks: `html-tailwind`, `react`, `nextjs`, `vue`, `svelte`, `swiftui`, `react-native`, `flutter`, `shadcn`, `jetpack-compose`
+, `jetpack-compose`
+---
+
+## Search Reference
+
+### Available Domains
+
+| Domain | Use For | Example Keywords |
+|--------|---------|------------------|
+| `product` | Product type recommendations | SaaS, e-commerce, portfolio, healthcare, beauty, service |
+| `style` | UI styles, colors, effects | glassmorphism, minimalism, dark mode, brutalism |
+| `typography` | Font pairings, Google Fonts | elegant, playful, professional, modern |
+| `color` | Color palettes by product type | saas, ecommerce, healthcare, beauty, fintech, service |
+| `landing` | Page structure, CTA strategies | hero, hero-centric, testimonial, pricing, social-proof |
+| `chart` | Chart types, library recommendations | trend, comparison, timeline, funnel, pie |
+| `ux` | Best practices, anti-patterns | animation, accessibility, z-index, loading |
+| `react` | React/Next.js performance | waterfall, bundle, suspense, memo, rerender, cache |
+| `web` | Web interface guidelines | aria, focus, keyboard, semantic, virtualize |
+| `prompt` | AI prompts, CSS keywords | (style name) |
+
+### Available Stacks
+
+| Stack | Focus |
+|-------|-------|
+| `html-tailwind` | Tailwind utilities, responsive, a11y (DEFAULT) |
+| `react` | State, hooks, performance, patterns |
+| `nextjs` | SSR, routing, images, API routes |
+| `vue` | Composition API, Pinia, Vue Router |
+| `svelte` | Runes, stores, SvelteKit |
+| `swiftui` | Views, State, Navigation, Animation |
+| `react-native` | Components, Navigation, Lists |
+| `flutter` | Widgets, State, Layout, Theming |
+| `shadcn` | shadcn/ui components, theming, forms, patterns |
+| `jetpack-compose` | Composables, Modifiers, State Hoisting, Recomposition |
+
+---
+
+## Example Workflow
+
+**User request:** "Làm landing page cho dịch vụ chăm sóc da chuyên nghiệp"
+
+### Step 1: Analyze Requirements
+- Product type: Beauty/Spa service
+- Style keywords: elegant, professional, soft
+- Industry: Beauty/Wellness
+- Stack: html-tailwind (default)
+
+### Step 2: Generate Design System (REQUIRED)
+
+```bash
+python3 .agent/.shared/ui-ux-pro-max/scripts/search.py "beauty spa wellness service elegant" --design-system -p "Serenity Spa"
+```
+
+**Output:** Complete design system with pattern, style, colors, typography, effects, and anti-patterns.
+
+### Step 3: Supplement with Detailed Searches (as needed)
+
+```bash
+# Get UX guidelines for animation and accessibility
+python3 .agent/.shared/ui-ux-pro-max/scripts/search.py "animation accessibility" --domain ux
+
+# Get alternative typography options if needed
+python3 .agent/.shared/ui-ux-pro-max/scripts/search.py "elegant luxury serif" --domain typography
+```
+
+### Step 4: Stack Guidelines
+
+```bash
+python3 .agent/.shared/ui-ux-pro-max/scripts/search.py "layout responsive form" --stack html-tailwind
+```
+
+**Then:** Synthesize design system + detailed searches and implement the design.
+
+---
+
+## Output Formats
+
+The `--design-system` flag supports two output formats:
+
+```bash
+# ASCII box (default) - best for terminal display
+python3 .agent/.shared/ui-ux-pro-max/scripts/search.py "fintech crypto" --design-system
+
+# Markdown - best for documentation
+python3 .agent/.shared/ui-ux-pro-max/scripts/search.py "fintech crypto" --design-system -f markdown
+```
+
+---
+
+## Tips for Better Results
+
+1. **Be specific with keywords** - "healthcare SaaS dashboard" > "app"
+2. **Search multiple times** - Different keywords reveal different insights
+3. **Combine domains** - Style + Typography + Color = Complete design system
+4. **Always check UX** - Search "animation", "z-index", "accessibility" for common issues
+5. **Use stack flag** - Get implementation-specific best practices
+6. **Iterate** - If first search doesn't match, try different keywords
+
+---
+
+## Common Rules for Professional UI
+
+These are frequently overlooked issues that make UI look unprofessional:
+
+### Icons & Visual Elements
+
+| Rule | Do | Don't |
+|------|----|----- |
+| **No emoji icons** | Use SVG icons (Heroicons, Lucide, Simple Icons) | Use emojis like 🎨 🚀 ⚙️ as UI icons |
+| **Stable hover states** | Use color/opacity transitions on hover | Use scale transforms that shift layout |
+| **Correct brand logos** | Research official SVG from Simple Icons | Guess or use incorrect logo paths |
+| **Consistent icon sizing** | Use fixed viewBox (24x24) with w-6 h-6 | Mix different icon sizes randomly |
+
+### Interaction & Cursor
+
+| Rule | Do | Don't |
+|------|----|----- |
+| **Cursor pointer** | Add `cursor-pointer` to all clickable/hoverable cards | Leave default cursor on interactive elements |
+| **Hover feedback** | Provide visual feedback (color, shadow, border) | No indication element is interactive |
+| **Smooth transitions** | Use `transition-colors duration-200` | Instant state changes or too slow (>500ms) |
+
+### Light/Dark Mode Contrast
+
+| Rule | Do | Don't |
+|------|----|----- |
+| **Glass card light mode** | Use `bg-white/80` or higher opacity | Use `bg-white/10` (too transparent) |
+| **Text contrast light** | Use `#0F172A` (slate-900) for text | Use `#94A3B8` (slate-400) for body text |
+| **Muted text light** | Use `#475569` (slate-600) minimum | Use gray-400 or lighter |
+| **Border visibility** | Use `border-gray-200` in light mode | Use `border-white/10` (invisible) |
+
+### Layout & Spacing
+
+| Rule | Do | Don't |
+|------|----|----- |
+| **Floating navbar** | Add `top-4 left-4 right-4` spacing | Stick navbar to `top-0 left-0 right-0` |
+| **Content padding** | Account for fixed navbar height | Let content hide behind fixed elements |
+| **Consistent max-width** | Use same `max-w-6xl` or `max-w-7xl` | Mix different container widths |
+
+---
+
+## Pre-Delivery Checklist
+
+Before delivering UI code, verify these items:
+
+### Visual Quality
+- [ ] No emojis used as icons (use SVG instead)
+- [ ] All icons from consistent icon set (Heroicons/Lucide)
+- [ ] Brand logos are correct (verified from Simple Icons)
+- [ ] Hover states don't cause layout shift
+- [ ] Use theme colors directly (bg-primary) not var() wrapper
+
+### Interaction
+- [ ] All clickable elements have `cursor-pointer`
+- [ ] Hover states provide clear visual feedback
+- [ ] Transitions are smooth (150-300ms)
+- [ ] Focus states visible for keyboard navigation
+
+### Light/Dark Mode
+- [ ] Light mode text has sufficient contrast (4.5:1 minimum)
+- [ ] Glass/transparent elements visible in light mode
+- [ ] Borders visible in both modes
+- [ ] Test both modes before delivery
+
+### Layout
+- [ ] Floating elements have proper spacing from edges
+- [ ] No content hidden behind fixed navbars
+- [ ] Responsive at 375px, 768px, 1024px, 1440px
+- [ ] No horizontal scroll on mobile
+
+### Accessibility
+- [ ] All images have alt text
+- [ ] Form inputs have labels
+- [ ] Color is not the only indicator
+- [ ] `prefers-reduced-motion` respected
\ No newline at end of file
diff --git a/.gitignore b/.gitignore
index 3c3629e..f1e0d96 100644
--- a/.gitignore
+++ b/.gitignore
@@ -1 +1,41 @@
-node_modules
+# Node.js
+node_modules/
+dist/
+build/
+coverage/
+.npm/
+
+# Environment
+.env
+.env.local
+.env.development.local
+.env.test.local
+.env.production.local
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Editor
+.vscode/
+.idea/
+*.swp
+*.swo
+
+# Agent / AI
+.agent/.shared/
+.agent/logs/
+.agent/temp/
+.agent/**/__pycache__/
+.agent/**/*.pyc
+.agent/**/node_modules/
+.agent/**/.DS_Store
+.gemini/
+.antigravity/
+
+# Logs
+*.log
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+pnpm-debug.log*
diff --git a/docs/PLAN.md b/docs/PLAN.md
new file mode 100644
index 0000000..e69de29
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index 7314bb5..b4b479c 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -38,16 +38,28 @@ importers:
web:
dependencies:
+ clsx:
+ specifier: ^2.1.1
+ version: 2.1.1
+ lucide-react:
+ specifier: ^0.564.0
+ version: 0.564.0(react@19.2.0)
react:
specifier: ^19.2.0
version: 19.2.0
react-dom:
specifier: ^19.2.0
version: 19.2.0(react@19.2.0)
+ tailwind-merge:
+ specifier: ^3.4.0
+ version: 3.4.0
devDependencies:
'@eslint/js':
specifier: ^9.39.1
version: 9.39.1
+ '@tailwindcss/postcss':
+ specifier: ^4.1.18
+ version: 4.1.18
'@types/node':
specifier: ^24.10.1
version: 24.10.1
@@ -59,31 +71,44 @@ importers:
version: 19.2.3(@types/react@19.2.6)
'@vitejs/plugin-react':
specifier: ^5.1.1
- version: 5.1.1(vite@7.2.4(@types/node@24.10.1)(tsx@4.20.6))
+ version: 5.1.1(vite@7.2.4(@types/node@24.10.1)(jiti@2.6.1)(lightningcss@1.30.2)(tsx@4.20.6))
+ autoprefixer:
+ specifier: ^10.4.24
+ version: 10.4.24(postcss@8.5.6)
eslint:
specifier: ^9.39.1
- version: 9.39.1
+ version: 9.39.1(jiti@2.6.1)
eslint-plugin-react-hooks:
specifier: ^7.0.1
- version: 7.0.1(eslint@9.39.1)
+ version: 7.0.1(eslint@9.39.1(jiti@2.6.1))
eslint-plugin-react-refresh:
specifier: ^0.4.24
- version: 0.4.24(eslint@9.39.1)
+ version: 0.4.24(eslint@9.39.1(jiti@2.6.1))
globals:
specifier: ^16.5.0
version: 16.5.0
+ postcss:
+ specifier: ^8.5.6
+ version: 8.5.6
+ tailwindcss:
+ specifier: ^4.1.18
+ version: 4.1.18
typescript:
specifier: ~5.9.3
version: 5.9.3
typescript-eslint:
specifier: ^8.46.4
- version: 8.47.0(eslint@9.39.1)(typescript@5.9.3)
+ version: 8.47.0(eslint@9.39.1(jiti@2.6.1))(typescript@5.9.3)
vite:
specifier: ^7.2.4
- version: 7.2.4(@types/node@24.10.1)(tsx@4.20.6)
+ version: 7.2.4(@types/node@24.10.1)(jiti@2.6.1)(lightningcss@1.30.2)(tsx@4.20.6)
packages:
+ '@alloc/quick-lru@5.2.0':
+ resolution: {integrity: sha512-UrcABB+4bUrFABwbluTIBErXwvbsU/V7TZWfmbgJfbkwiBuziS9gxdODUyuiecfdGQ85jglMW6juS3+z5TsKLw==}
+ engines: {node: '>=10'}
+
'@babel/code-frame@7.27.1':
resolution: {integrity: sha512-cjQ7ZlQ0Mv3b47hABuTevyTuYN4i+loJKGeV9flcCgIK37cCXRh+L1bd3iBHlynerhQ7BhCkn2BPbQUL+rGqFg==}
engines: {node: '>=6.9.0'}
@@ -550,6 +575,94 @@ packages:
cpu: [x64]
os: [win32]
+ '@tailwindcss/node@4.1.18':
+ resolution: {integrity: sha512-DoR7U1P7iYhw16qJ49fgXUlry1t4CpXeErJHnQ44JgTSKMaZUdf17cfn5mHchfJ4KRBZRFA/Coo+MUF5+gOaCQ==}
+
+ '@tailwindcss/oxide-android-arm64@4.1.18':
+ resolution: {integrity: sha512-dJHz7+Ugr9U/diKJA0W6N/6/cjI+ZTAoxPf9Iz9BFRF2GzEX8IvXxFIi/dZBloVJX/MZGvRuFA9rqwdiIEZQ0Q==}
+ engines: {node: '>= 10'}
+ cpu: [arm64]
+ os: [android]
+
+ '@tailwindcss/oxide-darwin-arm64@4.1.18':
+ resolution: {integrity: sha512-Gc2q4Qhs660bhjyBSKgq6BYvwDz4G+BuyJ5H1xfhmDR3D8HnHCmT/BSkvSL0vQLy/nkMLY20PQ2OoYMO15Jd0A==}
+ engines: {node: '>= 10'}
+ cpu: [arm64]
+ os: [darwin]
+
+ '@tailwindcss/oxide-darwin-x64@4.1.18':
+ resolution: {integrity: sha512-FL5oxr2xQsFrc3X9o1fjHKBYBMD1QZNyc1Xzw/h5Qu4XnEBi3dZn96HcHm41c/euGV+GRiXFfh2hUCyKi/e+yw==}
+ engines: {node: '>= 10'}
+ cpu: [x64]
+ os: [darwin]
+
+ '@tailwindcss/oxide-freebsd-x64@4.1.18':
+ resolution: {integrity: sha512-Fj+RHgu5bDodmV1dM9yAxlfJwkkWvLiRjbhuO2LEtwtlYlBgiAT4x/j5wQr1tC3SANAgD+0YcmWVrj8R9trVMA==}
+ engines: {node: '>= 10'}
+ cpu: [x64]
+ os: [freebsd]
+
+ '@tailwindcss/oxide-linux-arm-gnueabihf@4.1.18':
+ resolution: {integrity: sha512-Fp+Wzk/Ws4dZn+LV2Nqx3IilnhH51YZoRaYHQsVq3RQvEl+71VGKFpkfHrLM/Li+kt5c0DJe/bHXK1eHgDmdiA==}
+ engines: {node: '>= 10'}
+ cpu: [arm]
+ os: [linux]
+
+ '@tailwindcss/oxide-linux-arm64-gnu@4.1.18':
+ resolution: {integrity: sha512-S0n3jboLysNbh55Vrt7pk9wgpyTTPD0fdQeh7wQfMqLPM/Hrxi+dVsLsPrycQjGKEQk85Kgbx+6+QnYNiHalnw==}
+ engines: {node: '>= 10'}
+ cpu: [arm64]
+ os: [linux]
+
+ '@tailwindcss/oxide-linux-arm64-musl@4.1.18':
+ resolution: {integrity: sha512-1px92582HkPQlaaCkdRcio71p8bc8i/ap5807tPRDK/uw953cauQBT8c5tVGkOwrHMfc2Yh6UuxaH4vtTjGvHg==}
+ engines: {node: '>= 10'}
+ cpu: [arm64]
+ os: [linux]
+
+ '@tailwindcss/oxide-linux-x64-gnu@4.1.18':
+ resolution: {integrity: sha512-v3gyT0ivkfBLoZGF9LyHmts0Isc8jHZyVcbzio6Wpzifg/+5ZJpDiRiUhDLkcr7f/r38SWNe7ucxmGW3j3Kb/g==}
+ engines: {node: '>= 10'}
+ cpu: [x64]
+ os: [linux]
+
+ '@tailwindcss/oxide-linux-x64-musl@4.1.18':
+ resolution: {integrity: sha512-bhJ2y2OQNlcRwwgOAGMY0xTFStt4/wyU6pvI6LSuZpRgKQwxTec0/3Scu91O8ir7qCR3AuepQKLU/kX99FouqQ==}
+ engines: {node: '>= 10'}
+ cpu: [x64]
+ os: [linux]
+
+ '@tailwindcss/oxide-wasm32-wasi@4.1.18':
+ resolution: {integrity: sha512-LffYTvPjODiP6PT16oNeUQJzNVyJl1cjIebq/rWWBF+3eDst5JGEFSc5cWxyRCJ0Mxl+KyIkqRxk1XPEs9x8TA==}
+ engines: {node: '>=14.0.0'}
+ cpu: [wasm32]
+ bundledDependencies:
+ - '@napi-rs/wasm-runtime'
+ - '@emnapi/core'
+ - '@emnapi/runtime'
+ - '@tybys/wasm-util'
+ - '@emnapi/wasi-threads'
+ - tslib
+
+ '@tailwindcss/oxide-win32-arm64-msvc@4.1.18':
+ resolution: {integrity: sha512-HjSA7mr9HmC8fu6bdsZvZ+dhjyGCLdotjVOgLA2vEqxEBZaQo9YTX4kwgEvPCpRh8o4uWc4J/wEoFzhEmjvPbA==}
+ engines: {node: '>= 10'}
+ cpu: [arm64]
+ os: [win32]
+
+ '@tailwindcss/oxide-win32-x64-msvc@4.1.18':
+ resolution: {integrity: sha512-bJWbyYpUlqamC8dpR7pfjA0I7vdF6t5VpUGMWRkXVE3AXgIZjYUYAK7II1GNaxR8J1SSrSrppRar8G++JekE3Q==}
+ engines: {node: '>= 10'}
+ cpu: [x64]
+ os: [win32]
+
+ '@tailwindcss/oxide@4.1.18':
+ resolution: {integrity: sha512-EgCR5tTS5bUSKQgzeMClT6iCY3ToqE1y+ZB0AKldj809QXk1Y+3jB0upOYZrn9aGIzPtUsP7sX4QQ4XtjBB95A==}
+ engines: {node: '>= 10'}
+
+ '@tailwindcss/postcss@4.1.18':
+ resolution: {integrity: sha512-Ce0GFnzAOuPyfV5SxjXGn0CubwGcuDB0zcdaPuCSzAa/2vII24JTkH+I6jcbXLb1ctjZMZZI6OjDaLPJQL1S0g==}
+
'@types/babel__core@7.20.5':
resolution: {integrity: sha512-qoQprZvz5wQFJwMDqeseRXWv3rqMvhgpbXFfVyWhbx9X47POIA6i/+dXefEmZKoAgOaTdaIgNSMqMIU61yRyzA==}
@@ -693,6 +806,13 @@ packages:
resolution: {integrity: sha512-kNOjDqAh7px0XWNI+4QbzoiR/nTkHAWNud2uvnJquD1/x5a7EQZMJT0AczqK0Qn67oY/TTQ1LbUKajZpp3I9tQ==}
engines: {node: '>=8.0.0'}
+ autoprefixer@10.4.24:
+ resolution: {integrity: sha512-uHZg7N9ULTVbutaIsDRoUkoS8/h3bdsmVJYZ5l3wv8Cp/6UIIoRDm90hZ+BwxUj/hGBEzLxdHNSKuFpn8WOyZw==}
+ engines: {node: ^10 || ^12 || >=14}
+ hasBin: true
+ peerDependencies:
+ postcss: ^8.1.0
+
avvio@8.4.0:
resolution: {integrity: sha512-CDSwaxINFy59iNwhYnkvALBwZiTydGkOecZyPkqBpABYR1KqGEsET0VOOYDwtleZSUIdeY36DC2bSZ24CO1igA==}
@@ -703,6 +823,10 @@ packages:
resolution: {integrity: sha512-aTUKW4ptQhS64+v2d6IkPzymEzzhw+G0bA1g3uBRV3+ntkH+svttKseW5IOR4Ed6NUVKqnY7qT3dKvzQ7io4AA==}
hasBin: true
+ baseline-browser-mapping@2.9.19:
+ resolution: {integrity: sha512-ipDqC8FrAl/76p2SSWKSI+H9tFwm7vYqXQrItCuiVPt26Km0jS+NzSsBWAaBusvSbQcfJG+JitdMm+wZAgTYqg==}
+ hasBin: true
+
brace-expansion@1.1.12:
resolution: {integrity: sha512-9T9UjW3r0UW5c1Q7GTwllptXwhvYmEzFhzMfZ9H7FQWt+uZePjZPjBP/W1ZEyZ1twGWom5/56TF4lPcqjnDHcg==}
@@ -718,6 +842,11 @@ packages:
engines: {node: ^6 || ^7 || ^8 || ^9 || ^10 || ^11 || ^12 || >=13.7}
hasBin: true
+ browserslist@4.28.1:
+ resolution: {integrity: sha512-ZC5Bd0LgJXgwGqUknZY/vkUQ04r8NXnJZ3yYi4vDmSiZmC/pdSN0NbNRPxZpbtO4uAfDUAFffO8IZoM3Gj8IkA==}
+ engines: {node: ^6 || ^7 || ^8 || ^9 || ^10 || ^11 || ^12 || >=13.7}
+ hasBin: true
+
callsites@3.1.0:
resolution: {integrity: sha512-P8BjAsXvZS+VIDUI11hHCQEv74YT67YUi5JJFNWIqL235sBmjX4+qx9Muvls5ivyNENctx46xQLQ3aTuE7ssaQ==}
engines: {node: '>=6'}
@@ -725,10 +854,17 @@ packages:
caniuse-lite@1.0.30001756:
resolution: {integrity: sha512-4HnCNKbMLkLdhJz3TToeVWHSnfJvPaq6vu/eRP0Ahub/07n484XHhBF5AJoSGHdVrS8tKFauUQz8Bp9P7LVx7A==}
+ caniuse-lite@1.0.30001769:
+ resolution: {integrity: sha512-BCfFL1sHijQlBGWBMuJyhZUhzo7wer5sVj9hqekB/7xn0Ypy+pER/edCYQm4exbXj4WiySGp40P8UuTh6w1srg==}
+
chalk@4.1.2:
resolution: {integrity: sha512-oKnbhFyRIXpUuez8iBMmyEa4nbj4IOQyuhc/wy9kY7/WVPcwIO9VA668Pu8RkO7+0G76SLROeyw9CpQ061i4mA==}
engines: {node: '>=10'}
+ clsx@2.1.1:
+ resolution: {integrity: sha512-eYm0QWBtUrBWZWG0d386OGAw16Z995PiOVo2B7bjWSbHedGl5e0ZWaq65kOGgUSNesEIDkB9ISbTg/JK9dhCZA==}
+ engines: {node: '>=6'}
+
color-convert@2.0.1:
resolution: {integrity: sha512-RRECPsj7iu/xb5oKYcsFHSppFNnsj/52OVTRKb4zP5onXwVF3zVmmToNcOfGC+CRDpfK/U584fMg38ZHCaElKQ==}
engines: {node: '>=7.0.0'}
@@ -773,9 +909,20 @@ packages:
resolution: {integrity: sha512-g7nH6P6dyDioJogAAGprGpCtVImJhpPk/roCzdb3fIh61/s/nPsfR6onyMwkCAR/OlC3yBC0lESvUoQEAssIrw==}
engines: {node: '>= 0.8'}
+ detect-libc@2.1.2:
+ resolution: {integrity: sha512-Btj2BOOO83o3WyH59e8MgXsxEQVcarkUOpEYrubB0urwnN10yQ364rsiByU11nZlqWYZm05i/of7io4mzihBtQ==}
+ engines: {node: '>=8'}
+
electron-to-chromium@1.5.259:
resolution: {integrity: sha512-I+oLXgpEJzD6Cwuwt1gYjxsDmu/S/Kd41mmLA3O+/uH2pFRO/DvOjUyGozL8j3KeLV6WyZ7ssPwELMsXCcsJAQ==}
+ electron-to-chromium@1.5.286:
+ resolution: {integrity: sha512-9tfDXhJ4RKFNerfjdCcZfufu49vg620741MNs26a9+bhLThdB+plgMeou98CAaHu/WATj2iHOOHTp1hWtABj2A==}
+
+ enhanced-resolve@5.19.0:
+ resolution: {integrity: sha512-phv3E1Xl4tQOShqSte26C7Fl84EwUdZsyOuSSk9qtAGyyQs2s3jJzComh+Abf4g187lUUAvH+H26omrqia2aGg==}
+ engines: {node: '>=10.13.0'}
+
esbuild@0.25.12:
resolution: {integrity: sha512-bbPBYYrtZbkt6Os6FiTLCTFxvq4tt3JKall1vRwshA3fdVztsLAatFaZobhkBC8/BrPetoa0oksYoKXoG4ryJg==}
engines: {node: '>=18'}
@@ -921,6 +1068,9 @@ packages:
resolution: {integrity: sha512-buRG0fpBtRHSTCOASe6hD258tEubFoRLb4ZNA6NxMVHNw2gOcwHo9wyablzMzOA5z9xA9L1KNjk/Nt6MT9aYow==}
engines: {node: '>= 0.6'}
+ fraction.js@5.3.4:
+ resolution: {integrity: sha512-1X1NTtiJphryn/uLQz3whtY6jK3fTqoE3ohKs0tT+Ujr1W59oopxmoEh7Lu5p6vBaPbgoM0bzveAW4Qi5RyWDQ==}
+
fs.realpath@1.0.0:
resolution: {integrity: sha512-OO0pH2lK6a0hZnAdau5ItzHPI6pUlvI7jMVnxUQRtw4owF2wk8lOSabtGDCTP4Ggrg2MbGnWO9X8K1t4+fGMDw==}
@@ -957,6 +1107,9 @@ packages:
resolution: {integrity: sha512-c/c15i26VrJ4IRt5Z89DnIzCGDn9EcebibhAOjw5ibqEHsE1wLUgkPn9RDmNcUKyU87GeaL633nyJ+pplFR2ZQ==}
engines: {node: '>=18'}
+ graceful-fs@4.2.11:
+ resolution: {integrity: sha512-RbJ5/jmFcNNCcDV5o9eTnBLJ/HszWV0P73bc+Ff4nS/rJj+YaS6IGyiOL0VoBYX+l1Wrl3k63h/KrH+nhJ0XvQ==}
+
graphemer@1.4.0:
resolution: {integrity: sha512-EtKwoO6kxCL9WO5xipiHTZlSzBm7WLT627TqC/uVRd0HKmq8NXyebnNYxDoBi7wt8eTWrUrKXCOVaFq9x1kgag==}
@@ -1016,6 +1169,10 @@ packages:
isexe@2.0.0:
resolution: {integrity: sha512-RHxMLp9lnKHGHRng9QFhRCMbYAcVpn69smSGcq3f36xjgVVWThj4qqLbTLlq7Ssj8B+fIQ1EuCEGI2lKsyQeIw==}
+ jiti@2.6.1:
+ resolution: {integrity: sha512-ekilCSN1jwRvIbgeg/57YFh8qQDNbwDb9xT/qu2DAHbFFZUicIl4ygVaAvzveMhMVr3LnpSKTNnwt8PoOfmKhQ==}
+ hasBin: true
+
js-tokens@4.0.0:
resolution: {integrity: sha512-RdJUflcE3cUzKiMqQgsCu06FPu9UdIJO0beYbPhHN4k6apgJtifcoCtT9bcxOpYBtpD2kCM6Sbzg4CausW/PKQ==}
@@ -1058,6 +1215,76 @@ packages:
light-my-request@5.14.0:
resolution: {integrity: sha512-aORPWntbpH5esaYpGOOmri0OHDOe3wC5M2MQxZ9dvMLZm6DnaAn0kJlcbU9hwsQgLzmZyReKwFwwPkR+nHu5kA==}
+ lightningcss-android-arm64@1.30.2:
+ resolution: {integrity: sha512-BH9sEdOCahSgmkVhBLeU7Hc9DWeZ1Eb6wNS6Da8igvUwAe0sqROHddIlvU06q3WyXVEOYDZ6ykBZQnjTbmo4+A==}
+ engines: {node: '>= 12.0.0'}
+ cpu: [arm64]
+ os: [android]
+
+ lightningcss-darwin-arm64@1.30.2:
+ resolution: {integrity: sha512-ylTcDJBN3Hp21TdhRT5zBOIi73P6/W0qwvlFEk22fkdXchtNTOU4Qc37SkzV+EKYxLouZ6M4LG9NfZ1qkhhBWA==}
+ engines: {node: '>= 12.0.0'}
+ cpu: [arm64]
+ os: [darwin]
+
+ lightningcss-darwin-x64@1.30.2:
+ resolution: {integrity: sha512-oBZgKchomuDYxr7ilwLcyms6BCyLn0z8J0+ZZmfpjwg9fRVZIR5/GMXd7r9RH94iDhld3UmSjBM6nXWM2TfZTQ==}
+ engines: {node: '>= 12.0.0'}
+ cpu: [x64]
+ os: [darwin]
+
+ lightningcss-freebsd-x64@1.30.2:
+ resolution: {integrity: sha512-c2bH6xTrf4BDpK8MoGG4Bd6zAMZDAXS569UxCAGcA7IKbHNMlhGQ89eRmvpIUGfKWNVdbhSbkQaWhEoMGmGslA==}
+ engines: {node: '>= 12.0.0'}
+ cpu: [x64]
+ os: [freebsd]
+
+ lightningcss-linux-arm-gnueabihf@1.30.2:
+ resolution: {integrity: sha512-eVdpxh4wYcm0PofJIZVuYuLiqBIakQ9uFZmipf6LF/HRj5Bgm0eb3qL/mr1smyXIS1twwOxNWndd8z0E374hiA==}
+ engines: {node: '>= 12.0.0'}
+ cpu: [arm]
+ os: [linux]
+
+ lightningcss-linux-arm64-gnu@1.30.2:
+ resolution: {integrity: sha512-UK65WJAbwIJbiBFXpxrbTNArtfuznvxAJw4Q2ZGlU8kPeDIWEX1dg3rn2veBVUylA2Ezg89ktszWbaQnxD/e3A==}
+ engines: {node: '>= 12.0.0'}
+ cpu: [arm64]
+ os: [linux]
+
+ lightningcss-linux-arm64-musl@1.30.2:
+ resolution: {integrity: sha512-5Vh9dGeblpTxWHpOx8iauV02popZDsCYMPIgiuw97OJ5uaDsL86cnqSFs5LZkG3ghHoX5isLgWzMs+eD1YzrnA==}
+ engines: {node: '>= 12.0.0'}
+ cpu: [arm64]
+ os: [linux]
+
+ lightningcss-linux-x64-gnu@1.30.2:
+ resolution: {integrity: sha512-Cfd46gdmj1vQ+lR6VRTTadNHu6ALuw2pKR9lYq4FnhvgBc4zWY1EtZcAc6EffShbb1MFrIPfLDXD6Xprbnni4w==}
+ engines: {node: '>= 12.0.0'}
+ cpu: [x64]
+ os: [linux]
+
+ lightningcss-linux-x64-musl@1.30.2:
+ resolution: {integrity: sha512-XJaLUUFXb6/QG2lGIW6aIk6jKdtjtcffUT0NKvIqhSBY3hh9Ch+1LCeH80dR9q9LBjG3ewbDjnumefsLsP6aiA==}
+ engines: {node: '>= 12.0.0'}
+ cpu: [x64]
+ os: [linux]
+
+ lightningcss-win32-arm64-msvc@1.30.2:
+ resolution: {integrity: sha512-FZn+vaj7zLv//D/192WFFVA0RgHawIcHqLX9xuWiQt7P0PtdFEVaxgF9rjM/IRYHQXNnk61/H/gb2Ei+kUQ4xQ==}
+ engines: {node: '>= 12.0.0'}
+ cpu: [arm64]
+ os: [win32]
+
+ lightningcss-win32-x64-msvc@1.30.2:
+ resolution: {integrity: sha512-5g1yc73p+iAkid5phb4oVFMB45417DkRevRbt/El/gKXJk4jid+vPFF/AXbxn05Aky8PapwzZrdJShv5C0avjw==}
+ engines: {node: '>= 12.0.0'}
+ cpu: [x64]
+ os: [win32]
+
+ lightningcss@1.30.2:
+ resolution: {integrity: sha512-utfs7Pr5uJyyvDETitgsaqSyjCb2qNRAtuqUeWIAKztsOYdcACf2KtARYXg2pSvhkt+9NfoaNY7fxjl6nuMjIQ==}
+ engines: {node: '>= 12.0.0'}
+
locate-path@6.0.0:
resolution: {integrity: sha512-iPZK6eYjbxRu3uB4/WZ3EsEIMJFMqAoopl3R+zuq0UjcAm/MO6KCweDgPfP3elTztoKP3KtnVHxTn2NHBSDVUw==}
engines: {node: '>=10'}
@@ -1068,6 +1295,14 @@ packages:
lru-cache@5.1.1:
resolution: {integrity: sha512-KpNARQA3Iwv+jTA0utUVVbrh+Jlrr1Fv0e56GGzAFOXN7dk/FviaDW8LHmK52DlcH4WP2n6gI8vN1aesBFgo9w==}
+ lucide-react@0.564.0:
+ resolution: {integrity: sha512-JJ8GVTQqFwuliifD48U6+h7DXEHdkhJ/E87kksGByII3qHxtPciVb8T8woQONHBQgHVOl7rSMrrip3SeVNy7Fg==}
+ peerDependencies:
+ react: ^16.5.1 || ^17.0.0 || ^18.0.0 || ^19.0.0
+
+ magic-string@0.30.21:
+ resolution: {integrity: sha512-vd2F4YUyEXKGcLHoq+TEyCjxueSeHnFxyyjNp80yg0XV4vUhnDer/lvvlqM/arB5bXQN5K2/3oinyCRyx8T2CQ==}
+
merge2@1.4.1:
resolution: {integrity: sha512-8q7VEgMJW4J8tcfVPy8g09NcQwZdbwFEqhe/WZkoIzjn/3TGDwtOCYtXGxA3O8tPzpczCCDgv+P2P5y00ZJOOg==}
engines: {node: '>= 8'}
@@ -1164,6 +1399,9 @@ packages:
resolution: {integrity: sha512-8OEwKp5juEvb/MjpIc4hjqfgCNysrS94RIOMXYvpYCdm/jglrKEiAYmiumbmGhCvs+IcInsphYDFwqrjr7398w==}
hasBin: true
+ postcss-value-parser@4.2.0:
+ resolution: {integrity: sha512-1NNCs6uurfkVbeXG4S8JFT9t19m45ICnif8zWLd5oPSZ50QnwMfK+H3jv408d4jw/7Bttv5axS5IiHoLaVNHeQ==}
+
postcss@8.5.6:
resolution: {integrity: sha512-3Ybi1tAuwAP9s0r1UQ2J4n5Y0G05bJkpUIO0/bI9MhwmD70S5aTWbXGBwxHrelT+XM1k6dM0pk+SwNkpTRN7Pg==}
engines: {node: ^10 || ^12 || >=14}
@@ -1301,6 +1539,16 @@ packages:
resolution: {integrity: sha512-qpCAvRl9stuOHveKsn7HncJRvv501qIacKzQlO/+Lwxc9+0q2wLyv4Dfvt80/DPn2pqOBsJdDiogXGR9+OvwRw==}
engines: {node: '>=8'}
+ tailwind-merge@3.4.0:
+ resolution: {integrity: sha512-uSaO4gnW+b3Y2aWoWfFpX62vn2sR3skfhbjsEnaBI81WD1wBLlHZe5sWf0AqjksNdYTbGBEd0UasQMT3SNV15g==}
+
+ tailwindcss@4.1.18:
+ resolution: {integrity: sha512-4+Z+0yiYyEtUVCScyfHCxOYP06L5Ne+JiHhY2IjR2KWMIWhJOYZKLSGZaP5HkZ8+bY0cxfzwDE5uOmzFXyIwxw==}
+
+ tapable@2.3.0:
+ resolution: {integrity: sha512-g9ljZiwki/LfxmQADO3dEY1CbpmXT5Hm2fJ+QaGKwSXUylMybePR7/67YW7jOrrvjEgL1Fmz5kzyAjWVWLlucg==}
+ engines: {node: '>=6'}
+
thread-stream@3.1.0:
resolution: {integrity: sha512-OqyPZ9u96VohAyMfJykzmivOrY2wfMSf3C5TtFJVgN+Hm6aj+voFhlK+kZEIv2FBh1X6Xp3DlnCOfEQ3B2J86A==}
@@ -1363,6 +1611,12 @@ packages:
peerDependencies:
browserslist: '>= 4.21.0'
+ update-browserslist-db@1.2.3:
+ resolution: {integrity: sha512-Js0m9cx+qOgDxo0eMiFGEueWztz+d4+M3rGlmKPT+T4IS/jP4ylw3Nwpu6cpTTP8R1MAC1kF4VbdLt3ARf209w==}
+ hasBin: true
+ peerDependencies:
+ browserslist: '>= 4.21.0'
+
uri-js@4.4.1:
resolution: {integrity: sha512-7rKUyy33Q1yc98pQ1DAmLtwX109F7TIfWlW1Ydo8Wl1ii1SeHieeh0HHfPeL2fMXK6z0s8ecKs9frCuLJvndBg==}
@@ -1436,6 +1690,8 @@ packages:
snapshots:
+ '@alloc/quick-lru@5.2.0': {}
+
'@babel/code-frame@7.27.1':
dependencies:
'@babel/helper-validator-identifier': 7.28.5
@@ -1626,9 +1882,9 @@ snapshots:
'@esbuild/win32-x64@0.25.12':
optional: true
- '@eslint-community/eslint-utils@4.9.0(eslint@9.39.1)':
+ '@eslint-community/eslint-utils@4.9.0(eslint@9.39.1(jiti@2.6.1))':
dependencies:
- eslint: 9.39.1
+ eslint: 9.39.1(jiti@2.6.1)
eslint-visitor-keys: 3.4.3
'@eslint-community/regexpp@4.12.2': {}
@@ -1826,6 +2082,75 @@ snapshots:
'@rollup/rollup-win32-x64-msvc@4.53.3':
optional: true
+ '@tailwindcss/node@4.1.18':
+ dependencies:
+ '@jridgewell/remapping': 2.3.5
+ enhanced-resolve: 5.19.0
+ jiti: 2.6.1
+ lightningcss: 1.30.2
+ magic-string: 0.30.21
+ source-map-js: 1.2.1
+ tailwindcss: 4.1.18
+
+ '@tailwindcss/oxide-android-arm64@4.1.18':
+ optional: true
+
+ '@tailwindcss/oxide-darwin-arm64@4.1.18':
+ optional: true
+
+ '@tailwindcss/oxide-darwin-x64@4.1.18':
+ optional: true
+
+ '@tailwindcss/oxide-freebsd-x64@4.1.18':
+ optional: true
+
+ '@tailwindcss/oxide-linux-arm-gnueabihf@4.1.18':
+ optional: true
+
+ '@tailwindcss/oxide-linux-arm64-gnu@4.1.18':
+ optional: true
+
+ '@tailwindcss/oxide-linux-arm64-musl@4.1.18':
+ optional: true
+
+ '@tailwindcss/oxide-linux-x64-gnu@4.1.18':
+ optional: true
+
+ '@tailwindcss/oxide-linux-x64-musl@4.1.18':
+ optional: true
+
+ '@tailwindcss/oxide-wasm32-wasi@4.1.18':
+ optional: true
+
+ '@tailwindcss/oxide-win32-arm64-msvc@4.1.18':
+ optional: true
+
+ '@tailwindcss/oxide-win32-x64-msvc@4.1.18':
+ optional: true
+
+ '@tailwindcss/oxide@4.1.18':
+ optionalDependencies:
+ '@tailwindcss/oxide-android-arm64': 4.1.18
+ '@tailwindcss/oxide-darwin-arm64': 4.1.18
+ '@tailwindcss/oxide-darwin-x64': 4.1.18
+ '@tailwindcss/oxide-freebsd-x64': 4.1.18
+ '@tailwindcss/oxide-linux-arm-gnueabihf': 4.1.18
+ '@tailwindcss/oxide-linux-arm64-gnu': 4.1.18
+ '@tailwindcss/oxide-linux-arm64-musl': 4.1.18
+ '@tailwindcss/oxide-linux-x64-gnu': 4.1.18
+ '@tailwindcss/oxide-linux-x64-musl': 4.1.18
+ '@tailwindcss/oxide-wasm32-wasi': 4.1.18
+ '@tailwindcss/oxide-win32-arm64-msvc': 4.1.18
+ '@tailwindcss/oxide-win32-x64-msvc': 4.1.18
+
+ '@tailwindcss/postcss@4.1.18':
+ dependencies:
+ '@alloc/quick-lru': 5.2.0
+ '@tailwindcss/node': 4.1.18
+ '@tailwindcss/oxide': 4.1.18
+ postcss: 8.5.6
+ tailwindcss: 4.1.18
+
'@types/babel__core@7.20.5':
dependencies:
'@babel/parser': 7.28.5
@@ -1867,15 +2192,15 @@ snapshots:
dependencies:
csstype: 3.2.3
- '@typescript-eslint/eslint-plugin@8.47.0(@typescript-eslint/parser@8.47.0(eslint@9.39.1)(typescript@5.9.3))(eslint@9.39.1)(typescript@5.9.3)':
+ '@typescript-eslint/eslint-plugin@8.47.0(@typescript-eslint/parser@8.47.0(eslint@9.39.1(jiti@2.6.1))(typescript@5.9.3))(eslint@9.39.1(jiti@2.6.1))(typescript@5.9.3)':
dependencies:
'@eslint-community/regexpp': 4.12.2
- '@typescript-eslint/parser': 8.47.0(eslint@9.39.1)(typescript@5.9.3)
+ '@typescript-eslint/parser': 8.47.0(eslint@9.39.1(jiti@2.6.1))(typescript@5.9.3)
'@typescript-eslint/scope-manager': 8.47.0
- '@typescript-eslint/type-utils': 8.47.0(eslint@9.39.1)(typescript@5.9.3)
- '@typescript-eslint/utils': 8.47.0(eslint@9.39.1)(typescript@5.9.3)
+ '@typescript-eslint/type-utils': 8.47.0(eslint@9.39.1(jiti@2.6.1))(typescript@5.9.3)
+ '@typescript-eslint/utils': 8.47.0(eslint@9.39.1(jiti@2.6.1))(typescript@5.9.3)
'@typescript-eslint/visitor-keys': 8.47.0
- eslint: 9.39.1
+ eslint: 9.39.1(jiti@2.6.1)
graphemer: 1.4.0
ignore: 7.0.5
natural-compare: 1.4.0
@@ -1884,14 +2209,14 @@ snapshots:
transitivePeerDependencies:
- supports-color
- '@typescript-eslint/parser@8.47.0(eslint@9.39.1)(typescript@5.9.3)':
+ '@typescript-eslint/parser@8.47.0(eslint@9.39.1(jiti@2.6.1))(typescript@5.9.3)':
dependencies:
'@typescript-eslint/scope-manager': 8.47.0
'@typescript-eslint/types': 8.47.0
'@typescript-eslint/typescript-estree': 8.47.0(typescript@5.9.3)
'@typescript-eslint/visitor-keys': 8.47.0
debug: 4.4.3
- eslint: 9.39.1
+ eslint: 9.39.1(jiti@2.6.1)
typescript: 5.9.3
transitivePeerDependencies:
- supports-color
@@ -1914,13 +2239,13 @@ snapshots:
dependencies:
typescript: 5.9.3
- '@typescript-eslint/type-utils@8.47.0(eslint@9.39.1)(typescript@5.9.3)':
+ '@typescript-eslint/type-utils@8.47.0(eslint@9.39.1(jiti@2.6.1))(typescript@5.9.3)':
dependencies:
'@typescript-eslint/types': 8.47.0
'@typescript-eslint/typescript-estree': 8.47.0(typescript@5.9.3)
- '@typescript-eslint/utils': 8.47.0(eslint@9.39.1)(typescript@5.9.3)
+ '@typescript-eslint/utils': 8.47.0(eslint@9.39.1(jiti@2.6.1))(typescript@5.9.3)
debug: 4.4.3
- eslint: 9.39.1
+ eslint: 9.39.1(jiti@2.6.1)
ts-api-utils: 2.1.0(typescript@5.9.3)
typescript: 5.9.3
transitivePeerDependencies:
@@ -1944,13 +2269,13 @@ snapshots:
transitivePeerDependencies:
- supports-color
- '@typescript-eslint/utils@8.47.0(eslint@9.39.1)(typescript@5.9.3)':
+ '@typescript-eslint/utils@8.47.0(eslint@9.39.1(jiti@2.6.1))(typescript@5.9.3)':
dependencies:
- '@eslint-community/eslint-utils': 4.9.0(eslint@9.39.1)
+ '@eslint-community/eslint-utils': 4.9.0(eslint@9.39.1(jiti@2.6.1))
'@typescript-eslint/scope-manager': 8.47.0
'@typescript-eslint/types': 8.47.0
'@typescript-eslint/typescript-estree': 8.47.0(typescript@5.9.3)
- eslint: 9.39.1
+ eslint: 9.39.1(jiti@2.6.1)
typescript: 5.9.3
transitivePeerDependencies:
- supports-color
@@ -1960,7 +2285,7 @@ snapshots:
'@typescript-eslint/types': 8.47.0
eslint-visitor-keys: 4.2.1
- '@vitejs/plugin-react@5.1.1(vite@7.2.4(@types/node@24.10.1)(tsx@4.20.6))':
+ '@vitejs/plugin-react@5.1.1(vite@7.2.4(@types/node@24.10.1)(jiti@2.6.1)(lightningcss@1.30.2)(tsx@4.20.6))':
dependencies:
'@babel/core': 7.28.5
'@babel/plugin-transform-react-jsx-self': 7.27.1(@babel/core@7.28.5)
@@ -1968,7 +2293,7 @@ snapshots:
'@rolldown/pluginutils': 1.0.0-beta.47
'@types/babel__core': 7.20.5
react-refresh: 0.18.0
- vite: 7.2.4(@types/node@24.10.1)(tsx@4.20.6)
+ vite: 7.2.4(@types/node@24.10.1)(jiti@2.6.1)(lightningcss@1.30.2)(tsx@4.20.6)
transitivePeerDependencies:
- supports-color
@@ -2010,6 +2335,15 @@ snapshots:
atomic-sleep@1.0.0: {}
+ autoprefixer@10.4.24(postcss@8.5.6):
+ dependencies:
+ browserslist: 4.28.1
+ caniuse-lite: 1.0.30001769
+ fraction.js: 5.3.4
+ picocolors: 1.1.1
+ postcss: 8.5.6
+ postcss-value-parser: 4.2.0
+
avvio@8.4.0:
dependencies:
'@fastify/error': 3.4.1
@@ -2019,6 +2353,8 @@ snapshots:
baseline-browser-mapping@2.8.30: {}
+ baseline-browser-mapping@2.9.19: {}
+
brace-expansion@1.1.12:
dependencies:
balanced-match: 1.0.2
@@ -2040,15 +2376,27 @@ snapshots:
node-releases: 2.0.27
update-browserslist-db: 1.1.4(browserslist@4.28.0)
+ browserslist@4.28.1:
+ dependencies:
+ baseline-browser-mapping: 2.9.19
+ caniuse-lite: 1.0.30001769
+ electron-to-chromium: 1.5.286
+ node-releases: 2.0.27
+ update-browserslist-db: 1.2.3(browserslist@4.28.1)
+
callsites@3.1.0: {}
caniuse-lite@1.0.30001756: {}
+ caniuse-lite@1.0.30001769: {}
+
chalk@4.1.2:
dependencies:
ansi-styles: 4.3.0
supports-color: 7.2.0
+ clsx@2.1.1: {}
+
color-convert@2.0.1:
dependencies:
color-name: 1.1.4
@@ -2081,8 +2429,17 @@ snapshots:
depd@2.0.0: {}
+ detect-libc@2.1.2: {}
+
electron-to-chromium@1.5.259: {}
+ electron-to-chromium@1.5.286: {}
+
+ enhanced-resolve@5.19.0:
+ dependencies:
+ graceful-fs: 4.2.11
+ tapable: 2.3.0
+
esbuild@0.25.12:
optionalDependencies:
'@esbuild/aix-ppc64': 0.25.12
@@ -2118,20 +2475,20 @@ snapshots:
escape-string-regexp@4.0.0: {}
- eslint-plugin-react-hooks@7.0.1(eslint@9.39.1):
+ eslint-plugin-react-hooks@7.0.1(eslint@9.39.1(jiti@2.6.1)):
dependencies:
'@babel/core': 7.28.5
'@babel/parser': 7.28.5
- eslint: 9.39.1
+ eslint: 9.39.1(jiti@2.6.1)
hermes-parser: 0.25.1
zod: 3.25.76
zod-validation-error: 4.0.2(zod@3.25.76)
transitivePeerDependencies:
- supports-color
- eslint-plugin-react-refresh@0.4.24(eslint@9.39.1):
+ eslint-plugin-react-refresh@0.4.24(eslint@9.39.1(jiti@2.6.1)):
dependencies:
- eslint: 9.39.1
+ eslint: 9.39.1(jiti@2.6.1)
eslint-scope@8.4.0:
dependencies:
@@ -2142,9 +2499,9 @@ snapshots:
eslint-visitor-keys@4.2.1: {}
- eslint@9.39.1:
+ eslint@9.39.1(jiti@2.6.1):
dependencies:
- '@eslint-community/eslint-utils': 4.9.0(eslint@9.39.1)
+ '@eslint-community/eslint-utils': 4.9.0(eslint@9.39.1(jiti@2.6.1))
'@eslint-community/regexpp': 4.12.2
'@eslint/config-array': 0.21.1
'@eslint/config-helpers': 0.4.2
@@ -2178,6 +2535,8 @@ snapshots:
minimatch: 3.1.2
natural-compare: 1.4.0
optionator: 0.9.4
+ optionalDependencies:
+ jiti: 2.6.1
transitivePeerDependencies:
- supports-color
@@ -2292,6 +2651,8 @@ snapshots:
forwarded@0.2.0: {}
+ fraction.js@5.3.4: {}
+
fs.realpath@1.0.0: {}
fsevents@2.3.3:
@@ -2323,6 +2684,8 @@ snapshots:
globals@16.5.0: {}
+ graceful-fs@4.2.11: {}
+
graphemer@1.4.0: {}
has-flag@4.0.0: {}
@@ -2371,6 +2734,8 @@ snapshots:
isexe@2.0.0: {}
+ jiti@2.6.1: {}
+
js-tokens@4.0.0: {}
js-yaml@4.1.1:
@@ -2408,6 +2773,55 @@ snapshots:
process-warning: 3.0.0
set-cookie-parser: 2.7.2
+ lightningcss-android-arm64@1.30.2:
+ optional: true
+
+ lightningcss-darwin-arm64@1.30.2:
+ optional: true
+
+ lightningcss-darwin-x64@1.30.2:
+ optional: true
+
+ lightningcss-freebsd-x64@1.30.2:
+ optional: true
+
+ lightningcss-linux-arm-gnueabihf@1.30.2:
+ optional: true
+
+ lightningcss-linux-arm64-gnu@1.30.2:
+ optional: true
+
+ lightningcss-linux-arm64-musl@1.30.2:
+ optional: true
+
+ lightningcss-linux-x64-gnu@1.30.2:
+ optional: true
+
+ lightningcss-linux-x64-musl@1.30.2:
+ optional: true
+
+ lightningcss-win32-arm64-msvc@1.30.2:
+ optional: true
+
+ lightningcss-win32-x64-msvc@1.30.2:
+ optional: true
+
+ lightningcss@1.30.2:
+ dependencies:
+ detect-libc: 2.1.2
+ optionalDependencies:
+ lightningcss-android-arm64: 1.30.2
+ lightningcss-darwin-arm64: 1.30.2
+ lightningcss-darwin-x64: 1.30.2
+ lightningcss-freebsd-x64: 1.30.2
+ lightningcss-linux-arm-gnueabihf: 1.30.2
+ lightningcss-linux-arm64-gnu: 1.30.2
+ lightningcss-linux-arm64-musl: 1.30.2
+ lightningcss-linux-x64-gnu: 1.30.2
+ lightningcss-linux-x64-musl: 1.30.2
+ lightningcss-win32-arm64-msvc: 1.30.2
+ lightningcss-win32-x64-msvc: 1.30.2
+
locate-path@6.0.0:
dependencies:
p-locate: 5.0.0
@@ -2418,6 +2832,14 @@ snapshots:
dependencies:
yallist: 3.1.1
+ lucide-react@0.564.0(react@19.2.0):
+ dependencies:
+ react: 19.2.0
+
+ magic-string@0.30.21:
+ dependencies:
+ '@jridgewell/sourcemap-codec': 1.5.5
+
merge2@1.4.1: {}
micromatch@4.0.8:
@@ -2510,6 +2932,8 @@ snapshots:
sonic-boom: 4.2.0
thread-stream: 3.1.0
+ postcss-value-parser@4.2.0: {}
+
postcss@8.5.6:
dependencies:
nanoid: 3.3.11
@@ -2630,6 +3054,12 @@ snapshots:
dependencies:
has-flag: 4.0.0
+ tailwind-merge@3.4.0: {}
+
+ tailwindcss@4.1.18: {}
+
+ tapable@2.3.0: {}
+
thread-stream@3.1.0:
dependencies:
real-require: 0.2.0
@@ -2662,13 +3092,13 @@ snapshots:
dependencies:
prelude-ls: 1.2.1
- typescript-eslint@8.47.0(eslint@9.39.1)(typescript@5.9.3):
+ typescript-eslint@8.47.0(eslint@9.39.1(jiti@2.6.1))(typescript@5.9.3):
dependencies:
- '@typescript-eslint/eslint-plugin': 8.47.0(@typescript-eslint/parser@8.47.0(eslint@9.39.1)(typescript@5.9.3))(eslint@9.39.1)(typescript@5.9.3)
- '@typescript-eslint/parser': 8.47.0(eslint@9.39.1)(typescript@5.9.3)
+ '@typescript-eslint/eslint-plugin': 8.47.0(@typescript-eslint/parser@8.47.0(eslint@9.39.1(jiti@2.6.1))(typescript@5.9.3))(eslint@9.39.1(jiti@2.6.1))(typescript@5.9.3)
+ '@typescript-eslint/parser': 8.47.0(eslint@9.39.1(jiti@2.6.1))(typescript@5.9.3)
'@typescript-eslint/typescript-estree': 8.47.0(typescript@5.9.3)
- '@typescript-eslint/utils': 8.47.0(eslint@9.39.1)(typescript@5.9.3)
- eslint: 9.39.1
+ '@typescript-eslint/utils': 8.47.0(eslint@9.39.1(jiti@2.6.1))(typescript@5.9.3)
+ eslint: 9.39.1(jiti@2.6.1)
typescript: 5.9.3
transitivePeerDependencies:
- supports-color
@@ -2687,11 +3117,17 @@ snapshots:
escalade: 3.2.0
picocolors: 1.1.1
+ update-browserslist-db@1.2.3(browserslist@4.28.1):
+ dependencies:
+ browserslist: 4.28.1
+ escalade: 3.2.0
+ picocolors: 1.1.1
+
uri-js@4.4.1:
dependencies:
punycode: 2.3.1
- vite@7.2.4(@types/node@24.10.1)(tsx@4.20.6):
+ vite@7.2.4(@types/node@24.10.1)(jiti@2.6.1)(lightningcss@1.30.2)(tsx@4.20.6):
dependencies:
esbuild: 0.25.12
fdir: 6.5.0(picomatch@4.0.3)
@@ -2702,6 +3138,8 @@ snapshots:
optionalDependencies:
'@types/node': 24.10.1
fsevents: 2.3.3
+ jiti: 2.6.1
+ lightningcss: 1.30.2
tsx: 4.20.6
which@2.0.2:
diff --git a/server/src/index.ts b/server/src/index.ts
index 66fe518..9f9d79b 100644
--- a/server/src/index.ts
+++ b/server/src/index.ts
@@ -2,13 +2,26 @@ import Fastify from "fastify";
import cors from "@fastify/cors";
import fastifyStatic from "@fastify/static";
import { z } from "zod";
-import { request } from "undici";
-import { pipeline } from "node:stream/promises";
+import { Agent, setGlobalDispatcher, request } from "undici";
import { fileURLToPath } from "node:url";
import { dirname, resolve } from "node:path";
+// Otimização: Agente HTTP global com conexões persistentes e timeout relaxado.
+// Isso ajuda a manter a performance em downloads paralelos e evita gargalos de socket.
+const agent = new Agent({
+ connect: {
+ timeout: 30_000,
+ },
+ pipelining: 1,
+ keepAliveTimeout: 10_000,
+ connections: 500, // Aumenta limite de conexões simultâneas
+});
+
+setGlobalDispatcher(agent);
+
const app = Fastify({
logger: true,
+ disableRequestLogging: true, // Reduz ruído de log em transferências grandes
});
// Registro de CORS básico para permitir o frontend em desenvolvimento/produção.
@@ -16,7 +29,7 @@ await app.register(cors, {
origin: true,
});
-// Servir frontend buildado (Vite) em produção, similar ao Next.js.
+// Servir frontend buildado (Vite) em produção.
const currentFile = fileURLToPath(import.meta.url);
const currentDir = dirname(currentFile);
const clientDistPath = resolve(currentDir, "../../web/dist");
@@ -27,7 +40,7 @@ await app.register(fastifyStatic, {
index: ["index.html"],
});
-// Rota explícita para a SPA na raiz, útil especialmente em ambientes de deploy.
+// Rota explícita para a SPA.
app.get("/", (_request, reply) => {
return reply.sendFile("index.html");
});
@@ -37,17 +50,8 @@ app.get("/health", async () => {
});
const streamQuerySchema = z.object({
- url: z
- .string()
- .url("URL inválida")
- .refine(
- (value) => {
- // Evita SSRF localizando apenas http/https genérico.
- return value.startsWith("http://") || value.startsWith("https://");
- },
- { message: "Apenas URLs HTTP/HTTPS são permitidas." },
- ),
- // Offset opcional em bytes para retomar download dentro da mesma sessão.
+ url: z.string().url("URL inválida").startsWith("http", "Apenas HTTP/HTTPS permitidos"),
+ // Offset opcional em bytes para retomar download.
offset: z
.string()
.regex(/^\d+$/)
@@ -70,13 +74,16 @@ app.get("/stream", async (requestFastify, reply) => {
// HEAD para validar link e obter metadados.
const headResponse = await request(url, {
method: "HEAD",
- // timeout conservador, em produção pode ser configurável.
headersTimeout: 15000,
+ headers: {
+ "User-Agent": "Ephemeral-Downloader/1.0",
+ },
+ dispatcher: agent,
});
if (headResponse.statusCode && headResponse.statusCode >= 400) {
reply.status(502);
- return { error: "Não foi possível acessar o recurso de origem." };
+ return { error: `Erro na origem: ${headResponse.statusCode}` };
}
const contentType =
@@ -84,7 +91,7 @@ app.get("/stream", async (requestFastify, reply) => {
const contentLength = headResponse.headers["content-length"];
const originDisposition = headResponse.headers["content-disposition"];
- // Nome de arquivo derivado do header Content-Disposition ou da URL.
+ // Nome de arquivo fallback.
const fallbackName = (() => {
try {
const parsedUrl = new URL(url);
@@ -105,69 +112,65 @@ app.get("/stream", async (requestFastify, reply) => {
return fallbackName;
})();
- const headers: Record<string, string> = {};
+ const headers: Record<string, string> = {
+ "User-Agent": "Ephemeral-Downloader/1.0",
+ };
+
if (typeof offset === "number" && Number.isFinite(offset) && offset > 0) {
headers.Range = `bytes=${offset}-`;
}
- // GET streaming da origem (possivelmente com Range para retomada).
+ // GET streaming da origem.
const originResponse = await request(url, {
method: "GET",
headers,
headersTimeout: 30000,
- maxRedirections: 3,
+ maxRedirections: 5,
+ dispatcher: agent,
});
if (!originResponse.body) {
reply.status(502);
- return { error: "Resposta de origem sem corpo para streaming." };
+ return { error: "Sem corpo de resposta na origem." };
}
if (originResponse.statusCode && originResponse.statusCode >= 400) {
reply.status(originResponse.statusCode);
- return { error: "Falha ao obter o arquivo de origem." };
+ return { error: "Falha ao baixar arquivo da origem." };
}
const normalizedLength = Array.isArray(contentLength)
? contentLength[0]
: contentLength;
- // Configura headers de resposta para o cliente final.
+ // Configura headers de resposta.
reply.headers({
"Content-Type": Array.isArray(contentType) ? contentType[0] : contentType,
...(normalizedLength
? {
- "Content-Length": normalizedLength,
- "X-Origin-Content-Length": normalizedLength,
- }
+ "Content-Length": normalizedLength,
+ "X-Origin-Content-Length": normalizedLength,
+ }
: {}),
"Content-Disposition": `attachment; filename="${filename}"`,
});
- // Entregamos o stream diretamente para o Fastify gerenciar (pipe + backpressure).
+ // Pipe direto.
return reply.send(originResponse.body);
} catch (error) {
- requestFastify.log.error(
- { err: error, url },
- "Erro durante o streaming do arquivo",
- );
+ requestFastify.log.error({ err: error, url }, "Erro no proxy");
if (!reply.sent) {
- // Em caso de falha antes de iniciar o streaming, respondemos com JSON.
- return reply
- .status(502)
- .send({ error: "Erro ao realizar o proxy do arquivo." });
+ return reply.status(502).send({ error: "Erro interno no proxy." });
}
- // Se a resposta já foi enviada/fechada, apenas não fazemos mais nada.
}
});
-// Fallback para SPA: qualquer rota GET não atendida cai no index.html.
+// Fallback para SPA.
app.setNotFoundHandler((requestFastify, reply) => {
if (requestFastify.method === "GET") {
return reply.sendFile("index.html");
}
-
- reply.status(404).send({ error: "Recurso não encontrado." });
+ reply.status(404).send({ error: "Endpoint não encontrado." });
});
const port = Number(process.env.PORT) || 3000;
@@ -177,9 +180,9 @@ try {
port,
host: "0.0.0.0",
});
- app.log.info(`Server listening on port ${port}`);
+ console.log(`🚀 Server running on port ${port}`);
} catch (err) {
- app.log.error(err);
+ console.error(err);
process.exit(1);
}
diff --git a/web/package.json b/web/package.json
index a37fb49..6f04cae 100644
--- a/web/package.json
+++ b/web/package.json
@@ -10,19 +10,26 @@
"preview": "vite preview"
},
"dependencies": {
+ "clsx": "^2.1.1",
+ "lucide-react": "^0.564.0",
"react": "^19.2.0",
- "react-dom": "^19.2.0"
+ "react-dom": "^19.2.0",
+ "tailwind-merge": "^3.4.0"
},
"devDependencies": {
"@eslint/js": "^9.39.1",
+ "@tailwindcss/postcss": "^4.1.18",
"@types/node": "^24.10.1",
"@types/react": "^19.2.5",
"@types/react-dom": "^19.2.3",
"@vitejs/plugin-react": "^5.1.1",
+ "autoprefixer": "^10.4.24",
"eslint": "^9.39.1",
"eslint-plugin-react-hooks": "^7.0.1",
"eslint-plugin-react-refresh": "^0.4.24",
"globals": "^16.5.0",
+ "postcss": "^8.5.6",
+ "tailwindcss": "^4.1.18",
"typescript": "~5.9.3",
"typescript-eslint": "^8.46.4",
"vite": "^7.2.4"
diff --git a/web/postcss.config.js b/web/postcss.config.js
new file mode 100644
index 0000000..48dab30
--- /dev/null
+++ b/web/postcss.config.js
@@ -0,0 +1,6 @@
+export default {
+ plugins: {
+ "@tailwindcss/postcss": {},
+ autoprefixer: {},
+ },
+}
diff --git a/web/src/App.tsx b/web/src/App.tsx
index d1b03ac..2ea9b62 100644
--- a/web/src/App.tsx
+++ b/web/src/App.tsx
@@ -1,47 +1,13 @@
import { useState } from "react";
-import type { FormEvent } from "react";
-import "./App.css";
+import { Layout } from "./components/ui/Layout";
+import { DownloadForm } from "./components/feature/DownloadForm";
+import { DownloadItem, type DownloadItemData } from "./components/feature/DownloadItem";
+import { Card, CardContent, CardHeader, CardTitle } from "./components/ui/Card";
const API_URL = import.meta.env.VITE_API_URL ?? "http://localhost:3000";
-type DownloadStatus = "pending" | "downloading" | "completed" | "error";
-
-type DownloadItem = {
- id: number;
- url: string;
- status: DownloadStatus;
- progress: number | null;
- receivedBytes?: number;
- totalBytes?: number;
- speedBytesPerSecond?: number;
- error?: string;
-};
-
-const formatBytes = (bytes: number | undefined): string => {
- if (!bytes || !Number.isFinite(bytes)) return "-";
- const units = ["B", "KB", "MB", "GB", "TB"] as const;
- let value = bytes;
- let unitIndex = 0;
-
- while (value >= 1024 && unitIndex < units.length - 1) {
- value /= 1024;
- unitIndex += 1;
- }
-
- return `${value.toFixed(1)} ${units[unitIndex]}`;
-};
-
-const formatSpeed = (bytesPerSecond: number | undefined): string => {
- if (!bytesPerSecond || !Number.isFinite(bytesPerSecond)) return "- / -";
- const mbPerSecond = bytesPerSecond / (1024 * 1024);
- const mbitPerSecond = (bytesPerSecond * 8) / 1_000_000;
- return `${mbPerSecond.toFixed(2)} MB/s · ${mbitPerSecond.toFixed(2)} Mbps`;
-};
-
function App() {
- const [urlsText, setUrlsText] = useState("");
- const [error, setError] = useState<string | null>(null);
- const [downloads, setDownloads] = useState<DownloadItem[]>([]);
+ const [downloads, setDownloads] = useState<DownloadItemData[]>([]);
const startDownload = async (itemId: number, url: string, resume = false) => {
const existing = downloads.find((item) => item.id === itemId);
@@ -53,11 +19,12 @@ function App() {
current.map((item) =>
item.id === itemId
? {
- ...item,
- status: "downloading",
- progress: item.progress ?? 0,
- error: undefined,
- }
+ ...item,
+ status: "downloading",
+ progress: item.progress ?? 0,
+ error: undefined,
+ speedHistory: [], // Reset history on start/resume
+ }
: item,
),
);
@@ -75,7 +42,7 @@ function App() {
);
if (!response.ok || !response.body) {
- const message = "Falha ao iniciar o download.";
+ const message = "Failed to start download.";
setDownloads((current) =>
current.map((item) =>
item.id === itemId
@@ -99,8 +66,6 @@ function App() {
let received = alreadyReceived;
const startedAt = performance.now();
- // Atualiza progresso incrementalmente conforme os bytes chegam.
- // Para manter o código claro, usamos um loop while padrão.
// eslint-disable-next-line no-constant-condition
while (true) {
const { done, value } = await reader.read();
@@ -115,17 +80,22 @@ function App() {
totalBytes > 0 ? Math.round((received / totalBytes) * 100) : null;
setDownloads((current) =>
- current.map((item) =>
- item.id === itemId
- ? {
- ...item,
- progress: percentage,
- receivedBytes: received,
- totalBytes: totalBytes || item.totalBytes,
- speedBytesPerSecond: bytesPerSecond,
- }
- : item,
- ),
+ current.map((item) => {
+ if (item.id !== itemId) return item;
+
+ const newHistory = [...(item.speedHistory || []), bytesPerSecond];
+ // Keep last 50 data points for the graph
+ if (newHistory.length > 50) newHistory.shift();
+
+ return {
+ ...item,
+ progress: percentage,
+ receivedBytes: received,
+ totalBytes: totalBytes || item.totalBytes,
+ speedBytesPerSecond: bytesPerSecond,
+ speedHistory: newHistory,
+ };
+ }),
);
}
}
@@ -134,7 +104,6 @@ function App() {
response.headers.get("content-type") ?? "application/octet-stream";
const blob = new Blob(chunks, { type: contentType });
- // Resolve nome do arquivo pelo header Content-Disposition ou pela URL.
const disposition = response.headers.get("content-disposition");
const fallbackName = (() => {
try {
@@ -175,7 +144,7 @@ function App() {
);
} catch (err) {
const message =
- err instanceof Error ? err.message : "Erro inesperado durante o download.";
+ err instanceof Error ? err.message : "Unexpected error during download.";
setDownloads((current) =>
current.map((item) =>
item.id === itemId
@@ -186,41 +155,14 @@ function App() {
}
};
- const handleSubmit = (event: FormEvent) => {
- event.preventDefault();
- setError(null);
-
- const urls = urlsText
- .split(/\r?\n/)
- .map((value) => value.trim())
- .filter(Boolean);
-
- if (urls.length === 0) {
- setError("Informe ao menos uma URL de download direto (uma por linha).");
- return;
- }
-
- const invalidUrl = urls.find((value) => {
- try {
- // eslint-disable-next-line no-new
- new URL(value);
- return false;
- } catch {
- return true;
- }
- });
-
- if (invalidUrl) {
- setError(`URL inválida detectada: ${invalidUrl}`);
- return;
- }
-
+ const handleNewDownloads = (urls: string[]) => {
const baseId = Date.now();
- const newItems: DownloadItem[] = urls.map((value, index) => ({
+ const newItems: DownloadItemData[] = urls.map((value, index) => ({
id: baseId + index,
url: value,
status: "pending",
progress: 0,
+ speedHistory: [],
}));
setDownloads((current) => [...newItems, ...current]);
@@ -230,117 +172,58 @@ function App() {
});
};
+ const handleRetry = (id: number, url: string) => {
+ void startDownload(id, url, true);
+ };
+
return (
- <div className="app-root">
- <header className="app-header">
- <h1>Ephemeral Downloader</h1>
- <p>Proxy de download efêmero com streaming direto da origem para você.</p>
- <div className="app-header-meta">
- <span>Use a rota e peering da sua VPS a seu favor.</span>
- <span>Ideal para ROMs, ISOs e arquivos grandes.</span>
+ <Layout>
+ <div className="grid gap-8 lg:grid-cols-[400px_1fr]">
+ <div className="space-y-6">
+ <DownloadForm onSubmit={handleNewDownloads} />
+
+ <Card className="border-border/50 bg-card/50 backdrop-blur-sm hidden lg:block">
+ <CardHeader>
+ <CardTitle className="text-lg">Tips</CardTitle>
+ </CardHeader>
+ <CardContent className="text-sm text-muted-foreground space-y-2">
+ <p>• Use direct links ending in .iso, .zip, .mp4, etc.</p>
+ <p>• Downloads are streamed directly to your browser memory, then saved.</p>
+ <p>• If the tab closes, the download is lost.</p>
+ </CardContent>
+ </Card>
</div>
- </header>
- <main className="app-main">
- <form className="download-form" onSubmit={handleSubmit}>
- <label htmlFor="url-input" className="field-label">
- Links diretos dos arquivos
- </label>
- <p className="field-helper">
- Uma URL por linha. Aceita links HTTP/HTTPS diretos para arquivos.
- </p>
- <textarea
- id="url-input"
- placeholder={
- "https://exemplo.com/arquivo-1.iso\nhttps://exemplo.com/arquivo-2.zip"
- }
- value={urlsText}
- onChange={(event) => setUrlsText(event.target.value)}
- className="url-input url-input--multiline"
- rows={5}
- />
+ <section className="space-y-6">
+ <div className="flex items-center justify-between">
+ <h2 className="text-2xl font-bold tracking-tight">Active Downloads</h2>
+ <span className="text-sm text-muted-foreground">{downloads.length} items</span>
+ </div>
- {error && <p className="error-text">{error}</p>}
-
- <button type="submit" className="primary-button">
- Iniciar download
- </button>
- </form>
-
- <section className="downloads-section" aria-label="Progresso dos downloads">
- <h2 className="downloads-title">Downloads recentes</h2>
-
- {downloads.length === 0 ? (
- <p className="downloads-empty">
- Nenhum download ativo ainda. Cole um ou mais links diretos ao lado e clique em
-
- <strong>Iniciar download</strong>
- para começar.
- </p>
- ) : (
- <ul className="downloads-list">
- {downloads.map((item) => (
- <li key={item.id} className="download-item">
- <div className="download-main">
- <p className="download-url" title={item.url}>
- {item.url}
- </p>
- <span className={`badge badge--${item.status}`}>
- {item.status === "pending" && "Pendente"}
- {item.status === "downloading" && "Baixando"}
- {item.status === "completed" && "Concluído"}
- {item.status === "error" && "Erro"}
- </span>
- </div>
-
- {item.progress !== null && (
- <div className="progress-wrapper">
- <div className="progress-bar">
- <div
- className="progress-bar__fill"
- style={{ width: `${item.progress}%` }}
- />
- </div>
- <span className="progress-label">
- {item.progress}%
- </span>
- </div>
- )}
-
- {(item.receivedBytes ?? 0) > 0 && (
- <p className="download-meta">
- <span>
- {formatBytes(item.receivedBytes)} /{" "}
- {formatBytes(item.totalBytes)}
- </span>
- <span>·</span>
- <span>{formatSpeed(item.speedBytesPerSecond)}</span>
- </p>
- )}
-
- {item.error && (
- <div className="download-footer">
- <p className="download-error">
- {item.error}
- </p>
- <button
- type="button"
- className="secondary-button"
- onClick={() => {
- void startDownload(item.id, item.url, true);
- }}
- >
- Retomar download
- </button>
- </div>
- )}
- </li>
- ))}
- </ul>
- )}
+ <div className="space-y-4">
+ {downloads.length === 0 ? (
+ <div className="flex flex-col items-center justify-center rounded-lg border border-dashed p-12 text-center animate-in fade-in-50">
+ <div className="mb-4 rounded-full bg-secondary/50 p-4">
+ <div className="i-lucide-download size-8 text-muted-foreground" />
+ </div>
+ <h3 className="text-lg font-semibold">No downloads yet</h3>
+ <p className="mt-2 text-sm text-muted-foreground max-w-sm">
+ Paste your links on the left sidebar to get started. The VPS proxy will handle the connection.
+ </p>
+ </div>
+ ) : (
+ downloads.map((item) => (
+ <DownloadItem
+ key={item.id}
+ item={item}
+ onRetry={handleRetry}
+ />
+ ))
+ )}
+ </div>
</section>
- </main>
- </div>
+ </div>
+ </Layout>
);
}
diff --git a/web/src/components/feature/DownloadForm.tsx b/web/src/components/feature/DownloadForm.tsx
new file mode 100644
index 0000000..62d95f4
--- /dev/null
+++ b/web/src/components/feature/DownloadForm.tsx
@@ -0,0 +1,75 @@
+import { useState } from "react";
+import type { FormEvent } from "react";
+import { Download } from "lucide-react";
+import { Button } from "../ui/Button";
+import { Textarea } from "../ui/Textarea";
+import { Card, CardContent, CardDescription, CardHeader, CardTitle } from "../ui/Card";
+
+interface DownloadFormProps {
+ onSubmit: (urls: string[]) => void;
+}
+
+export function DownloadForm({ onSubmit }: DownloadFormProps) {
+ const [text, setText] = useState("");
+ const [error, setError] = useState<string | null>(null);
+
+ const handleSubmit = (e: FormEvent) => {
+ e.preventDefault();
+ setError(null);
+
+ const urls = text
+ .split(/\r?\n/)
+ .map((u) => u.trim())
+ .filter(Boolean);
+
+ if (urls.length === 0) {
+ setError("Please enter at least one URL.");
+ return;
+ }
+
+ const invalidUrl = urls.find((u) => {
+ try {
+ new URL(u);
+ return false;
+ } catch {
+ return true;
+ }
+ });
+
+ if (invalidUrl) {
+ setError(`Invalid URL detected: ${invalidUrl}`);
+ return;
+ }
+
+ onSubmit(urls);
+ setText("");
+ };
+
+ return (
+ <Card className="border-border/50 bg-card/50 backdrop-blur-sm">
+ <CardHeader>
+ <CardTitle>New Download</CardTitle>
+ <CardDescription>
+ Enter direct links (HTTP/HTTPS) to stream via VPS. One URL per line.
+ </CardDescription>
+ </CardHeader>
+ <CardContent>
+ <form onSubmit={handleSubmit} className="space-y-4">
+ <Textarea
+ placeholder="https://example.com/file.iso"
+ className="min-h-[120px] font-mono text-sm"
+ value={text}
+ onChange={(e) => setText(e.target.value)}
+ />
+ {error && <p className="text-sm text-destructive">{error}</p>}
+ <div className="flex justify-end">
+ <Button type="submit" className="w-full sm:w-auto">
+ <Download className="mr-2 size-4" />
+ Start Download
+ </Button>
+ </div>
+ </form>
+ </CardContent>
+ </Card>
+ );
+}
diff --git a/web/src/components/feature/DownloadItem.tsx b/web/src/components/feature/DownloadItem.tsx
new file mode 100644
index 0000000..944b33d
--- /dev/null
+++ b/web/src/components/feature/DownloadItem.tsx
@@ -0,0 +1,156 @@
+import {
+ Download,
+ FileCheck,
+ FileWarning,
+ Loader2,
+ Play,
+} from "lucide-react";
+import { Button } from "../ui/Button";
+import { Card, CardContent } from "../ui/Card";
+import { Progress } from "../ui/ProgressBar";
+import { formatBytes, formatSpeed } from "../../lib/utils";
+
+export type DownloadStatus = "pending" | "downloading" | "completed" | "error";
+
+export type DownloadItemData = {
+ id: number;
+ url: string;
+ status: DownloadStatus;
+ progress: number | null;
+ receivedBytes?: number;
+ totalBytes?: number;
+ speedBytesPerSecond?: number;
+ speedHistory: number[];
+ error?: string;
+};
+
+interface DownloadItemProps {
+ item: DownloadItemData;
+ onRetry: (id: number, url: string) => void;
+}
+
+export function DownloadItem({ item, onRetry }: DownloadItemProps) {
+ const isCompleted = item.status === "completed";
+ const isError = item.status === "error";
+ const isDownloading = item.status === "downloading";
+
+ return (
+ <Card className="overflow-hidden transition-all hover:bg-muted/50">
+ <CardContent className="p-4">
+ <div className="flex items-start justify-between gap-4">
+ <div className="min-w-0 flex-1 space-y-3">
+ <div className="flex items-center gap-2">
+ <div
+ className={`flex size-8 shrink-0 items-center justify-center rounded-full bg-secondary text-muted-foreground ${isCompleted ? "bg-green-500/10 text-green-500" : ""
+ } ${isError ? "bg-red-500/10 text-red-500" : ""} ${isDownloading ? "bg-primary/10 text-primary" : ""
+ }`}
+ >
+ {isCompleted ? (
+ <FileCheck className="size-4" />
+ ) : isError ? (
+ <FileWarning className="size-4" />
+ ) : isDownloading ? (
+ <Download className="size-4 animate-bounce" />
+ ) : (
+ <Loader2 className="size-4 animate-spin" />
+ )}
+ </div>
+ <div className="min-w-0 flex-1">
+ <p className="truncate text-sm font-medium leading-none">
+ {item.url.split("/").pop() || item.url}
+ </p>
+ <p className="mt-1 truncate text-xs text-muted-foreground">
+ {item.url}
+ </p>
+ </div>
+ </div>
+
+ <div className="space-y-1">
+ <div className="flex items-center justify-between text-xs text-muted-foreground">
+ <span>{item.progress ?? 0}%</span>
+ <span>
+ <span>
+ {item.status === "downloading" &&
+ formatSpeed(item.speedBytesPerSecond)}
+ </span>
+ </span>
+ </div>
+ <Progress
+ value={item.progress}
+ className={`h-2 ${isError ? "bg-red-900/20" : ""} ${isCompleted ? "bg-green-900/20" : ""
+ }`}
+ indicatorClassName={`${isError ? "bg-red-500" : ""} ${isCompleted ? "bg-green-500" : ""
+ }`}
+ />
+
+ {/* Sparkline for speed history */}
+ {item.status === "downloading" && item.speedHistory.length > 1 && (
+ <div className="h-8 w-full overflow-hidden opacity-50">
+ <svg
+ className="h-full w-full"
+ viewBox={`0 0 ${item.speedHistory.length - 1} 100`}
+ preserveAspectRatio="none"
+ >
+ <path
+ d={`M 0,100 ${item.speedHistory
+ .map((s, i) => {
+ const max = Math.max(...item.speedHistory);
+ const y = max > 0 ? 100 - (s / max) * 100 : 100;
+ return `L ${i},${y}`;
+ })
+ .join(" ")} L ${item.speedHistory.length - 1},100 Z`}
+ fill="currentColor"
+ className="text-primary/20"
+ />
+ <path
+ d={`M 0,${100 - (item.speedHistory[0] / Math.max(...item.speedHistory)) * 100} ${item.speedHistory
+ .map((s, i) => {
+ const max = Math.max(...item.speedHistory);
+ const y = max > 0 ? 100 - (s / max) * 100 : 100;
+ return `L ${i},${y}`;
+ })
+ .join(" ")}`}
+ fill="none"
+ stroke="currentColor"
+ strokeWidth="1"
+ className="text-primary"
+ vectorEffect="non-scaling-stroke"
+ />
+ </svg>
+ </div>
+ )}
+
+ <div className="flex items-center justify-between text-xs text-muted-foreground">
+ <span>
+ {formatBytes(item.receivedBytes)} /{" "}
+ {formatBytes(item.totalBytes)}
+ </span>
+ <span className="capitalize">{item.status}</span>
+ </div>
+ </div>
+
+ {isError && (
+ <div className="rounded-md bg-destructive/10 p-2 text-xs text-destructive">
+ {item.error}
+ </div>
+ )}
+ </div>
+
+ <div className="flex flex-col gap-2">
+ {isError && (
+ <Button
+ variant="outline"
+ size="icon"
+ onClick={() => onRetry(item.id, item.url)}
+ className="h-8 w-8"
+ >
+ <Play className="size-4" />
+ </Button>
+ )}
+ {/* Placeholder for pause/cancel in future */}
+ </div>
+ </div>
+ </CardContent>
+ </Card>
+ );
+}
diff --git a/web/src/components/ui/Button.tsx b/web/src/components/ui/Button.tsx
new file mode 100644
index 0000000..fbf21ec
--- /dev/null
+++ b/web/src/components/ui/Button.tsx
@@ -0,0 +1,41 @@
+import * as React from "react";
+import { cn } from "../../lib/utils";
+
+export interface ButtonProps
+ extends React.ButtonHTMLAttributes<HTMLButtonElement> {
+ variant?: "default" | "secondary" | "outline" | "ghost" | "destructive";
+ size?: "default" | "sm" | "lg" | "icon";
+}
+
+const Button = React.forwardRef<HTMLButtonElement, ButtonProps>(
+ ({ className, variant = "default", size = "default", ...props }, ref) => {
+ return (
+ <button
+ className={cn(
+ "inline-flex items-center justify-center whitespace-nowrap rounded-md text-sm font-medium ring-offset-background transition-colors focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2 disabled:pointer-events-none disabled:opacity-50",
+ {
+ "bg-primary text-primary-foreground hover:bg-primary/90":
+ variant === "default",
+ "bg-secondary text-secondary-foreground hover:bg-secondary/80":
+ variant === "secondary",
+ "border border-input bg-background hover:bg-accent hover:text-accent-foreground":
+ variant === "outline",
+ "hover:bg-accent hover:text-accent-foreground": variant === "ghost",
+ "bg-destructive text-destructive-foreground hover:bg-destructive/90":
+ variant === "destructive",
+ "h-10 px-4 py-2": size === "default",
+ "h-9 rounded-md px-3": size === "sm",
+ "h-11 rounded-md px-8": size === "lg",
+ "h-10 w-10": size === "icon",
+ },
+ className
+ )}
+ ref={ref}
+ {...props}
+ />
+ );
+ }
+);
+Button.displayName = "Button";
+
+export { Button };
diff --git a/web/src/components/ui/Card.tsx b/web/src/components/ui/Card.tsx
new file mode 100644
index 0000000..b55ec2f
--- /dev/null
+++ b/web/src/components/ui/Card.tsx
@@ -0,0 +1,85 @@
+import * as React from "react";
+import { cn } from "../../lib/utils";
+
+const Card = React.forwardRef<
+ HTMLDivElement,
+ React.HTMLAttributes<HTMLDivElement>
+>(({ className, ...props }, ref) => (
+ <div
+ ref={ref}
+ className={cn(
+ "rounded-lg border bg-card text-card-foreground shadow-sm",
+ className
+ )}
+ {...props}
+ />
+));
+Card.displayName = "Card";
+
+const CardHeader = React.forwardRef<
+ HTMLDivElement,
+ React.HTMLAttributes<HTMLDivElement>
+>(({ className, ...props }, ref) => (
+ <div
+ ref={ref}
+ className={cn("flex flex-col space-y-1.5 p-6", className)}
+ {...props}
+ />
+));
+Card.displayName = "CardHeader";
+
+const CardTitle = React.forwardRef<
+ HTMLParagraphElement,
+ React.HTMLAttributes<HTMLHeadingElement>
+>(({ className, ...props }, ref) => (
+ <h3
+ ref={ref}
+ className={cn(
+ "text-2xl font-semibold leading-none tracking-tight",
+ className
+ )}
+ {...props}
+ />
+));
+CardTitle.displayName = "CardTitle";
+
+const CardDescription = React.forwardRef<
+ HTMLParagraphElement,
+ React.HTMLAttributes<HTMLParagraphElement>
+>(({ className, ...props }, ref) => (
+ <p
+ ref={ref}
+ className={cn("text-sm text-muted-foreground", className)}
+ {...props}
+ />
+));
+CardDescription.displayName = "CardDescription";
+
+const CardContent = React.forwardRef<
+ HTMLDivElement,
+ React.HTMLAttributes<HTMLDivElement>
+>(({ className, ...props }, ref) => (
+ <div ref={ref} className={cn("p-6 pt-0", className)} {...props} />
+));
+CardContent.displayName = "CardContent";
+
+const CardFooter = React.forwardRef<
+ HTMLDivElement,
+ React.HTMLAttributes<HTMLDivElement>
+>(({ className, ...props }, ref) => (
+ <div
+ ref={ref}
+ className={cn("flex items-center p-6 pt-0", className)}
+ {...props}
+ />
+));
+CardFooter.displayName = "CardFooter";
+
+export {
+ Card,
+ CardHeader,
+ CardFooter,
+ CardTitle,
+ CardDescription,
+ CardContent,
+};
diff --git a/web/src/components/ui/Input.tsx b/web/src/components/ui/Input.tsx
new file mode 100644
index 0000000..c7e71f8
--- /dev/null
+++ b/web/src/components/ui/Input.tsx
@@ -0,0 +1,24 @@
+import * as React from "react";
+import { cn } from "../../lib/utils";
+
+export interface InputProps
+ extends React.InputHTMLAttributes<HTMLInputElement> { }
+
+const Input = React.forwardRef<HTMLInputElement, InputProps>(
+ ({ className, type, ...props }, ref) => {
+ return (
+ <input
+ type={type}
+ className={cn(
+ "flex h-10 w-full rounded-md border border-input bg-background px-3 py-2 text-sm ring-offset-background file:border-0 file:bg-transparent file:text-sm file:font-medium placeholder:text-muted-foreground focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2 disabled:cursor-not-allowed disabled:opacity-50",
+ className
+ )}
+ ref={ref}
+ {...props}
+ />
+ );
+ }
+);
+Input.displayName = "Input";
+
+export { Input };
diff --git a/web/src/components/ui/Layout.tsx b/web/src/components/ui/Layout.tsx
new file mode 100644
index 0000000..5ad6390
--- /dev/null
+++ b/web/src/components/ui/Layout.tsx
@@ -0,0 +1,39 @@
+import type { ReactNode } from "react";
+import { MoveDown, Server } from "lucide-react";
+
+type LayoutProps = {
+ children: ReactNode;
+};
+
+export function Layout({ children }: LayoutProps) {
+ return (
+ <div className="min-h-screen bg-background text-foreground font-sans antialiased selection:bg-primary selection:text-primary-foreground">
+ <div className="absolute inset-0 -z-10 h-full w-full bg-background bg-[linear-gradient(to_right,#8080800a_1px,transparent_1px),linear-gradient(to_bottom,#8080800a_1px,transparent_1px)] bg-[size:14px_24px]"></div>
+ <div className="absolute left-0 right-0 top-0 -z-10 m-auto h-[310px] w-[310px] rounded-full bg-primary/20 opacity-20 blur-[100px]"></div>
+
+ <header className="sticky top-0 z-50 w-full border-b border-border/40 bg-background/95 backdrop-blur supports-[backdrop-filter]:bg-background/60">
+ <div className="container flex h-14 max-w-screen-2xl items-center px-4 md:px-8">
+ <div className="mr-4 flex items-center space-x-2">
+ <div className="flex aspect-square size-8 items-center justify-center rounded-lg bg-primary text-primary-foreground">
+ <MoveDown className="size-5" />
+ </div>
+ <span className="hidden font-bold sm:inline-block">
+ Ephemeral Downloader
+ </span>
+ </div>
+ <div className="flex flex-1 items-center justify-end space-x-2 md:justify-end">
+ <nav className="flex items-center space-x-2 text-sm font-medium text-muted-foreground">
+ <div className="flex items-center gap-2 rounded-full border border-border bg-secondary/50 px-3 py-1 text-xs">
+ <Server className="size-3" />
+ <span>VPS Proxy Active</span>
+ </div>
+ </nav>
+ </div>
+ </div>
+ </header>
+ <main className="container max-w-screen-xl py-6 md:py-10 px-4 md:px-8">
+ {children}
+ </main>
+ </div>
+ );
+}
diff --git a/web/src/components/ui/ProgressBar.tsx b/web/src/components/ui/ProgressBar.tsx
new file mode 100644
index 0000000..bcc15bb
--- /dev/null
+++ b/web/src/components/ui/ProgressBar.tsx
@@ -0,0 +1,36 @@
+import * as React from "react";
+import { cn } from "../../lib/utils";
+
+interface ProgressProps extends React.HTMLAttributes<HTMLDivElement> {
+ value?: number | null;
+ max?: number;
+ indicatorClassName?: string;
+}
+
+const Progress = React.forwardRef<HTMLDivElement, ProgressProps>(
+ ({ className, value, max = 100, indicatorClassName, ...props }, ref) => {
+ const percent = Math.min(Math.max(0, value || 0), max);
+
+ return (
+ <div
+ ref={ref}
+ className={cn(
+ "relative h-2 w-full overflow-hidden rounded-full bg-secondary",
+ className
+ )}
+ {...props}
+ >
+ <div
+ className={cn(
+ "h-full w-full flex-1 bg-primary transition-all duration-200 ease-in-out",
+ indicatorClassName
+ )}
+ style={{ transform: `translateX(-${100 - (percent / max) * 100}%)` }}
+ />
+ </div>
+ );
+ }
+);
+Progress.displayName = "Progress";
+
+export { Progress };
diff --git a/web/src/components/ui/Textarea.tsx b/web/src/components/ui/Textarea.tsx
new file mode 100644
index 0000000..816eb73
--- /dev/null
+++ b/web/src/components/ui/Textarea.tsx
@@ -0,0 +1,23 @@
+import * as React from "react";
+import { cn } from "../../lib/utils";
+
+export interface TextareaProps
+ extends React.TextareaHTMLAttributes<HTMLTextAreaElement> { }
+
+const Textarea = React.forwardRef<HTMLTextAreaElement, TextareaProps>(
+ ({ className, ...props }, ref) => {
+ return (
+ <textarea
+ className={cn(
+ "flex min-h-[80px] w-full rounded-md border border-input bg-background px-3 py-2 text-sm ring-offset-background placeholder:text-muted-foreground focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2 disabled:cursor-not-allowed disabled:opacity-50",
+ className
+ )}
+ ref={ref}
+ {...props}
+ />
+ );
+ }
+);
+Textarea.displayName = "Textarea";
+
+export { Textarea };
diff --git a/web/src/index.css b/web/src/index.css
index 3a4c737..583a1de 100644
--- a/web/src/index.css
+++ b/web/src/index.css
@@ -1,68 +1,65 @@
-:root {
- font-family: system-ui, Avenir, Helvetica, Arial, sans-serif;
- line-height: 1.5;
- font-weight: 400;
+@import "tailwindcss";
- color-scheme: light dark;
- color: rgba(255, 255, 255, 0.87);
- background-color: #242424;
+@theme {
+ --color-background: hsl(var(--background));
+ --color-foreground: hsl(var(--foreground));
- font-synthesis: none;
- text-rendering: optimizeLegibility;
- -webkit-font-smoothing: antialiased;
- -moz-osx-font-smoothing: grayscale;
+ --color-primary: hsl(var(--primary));
+ --color-primary-foreground: hsl(var(--primary-foreground));
+
+ --color-secondary: hsl(var(--secondary));
+ --color-secondary-foreground: hsl(var(--secondary-foreground));
+
+ --color-muted: hsl(var(--muted));
+ --color-muted-foreground: hsl(var(--muted-foreground));
+
+ --color-accent: hsl(var(--accent));
+ --color-accent-foreground: hsl(var(--accent-foreground));
+
+ --color-destructive: hsl(var(--destructive));
+ --color-destructive-foreground: hsl(var(--destructive-foreground));
+
+ --color-border: hsl(var(--border));
+ --color-input: hsl(var(--input));
+ --color-ring: hsl(var(--ring));
+
+ --radius-lg: var(--radius);
+ --radius-md: calc(var(--radius) - 2px);
+ --radius-sm: calc(var(--radius) - 4px);
}
-a {
- font-weight: 500;
- color: #646cff;
- text-decoration: inherit;
-}
-a:hover {
- color: #535bf2;
-}
-
-body {
- margin: 0;
- min-width: 320px;
- min-height: 100vh;
- background-color: #020617;
- color: #f9fafb;
-}
-
-h1 {
- font-size: 3.2em;
- line-height: 1.1;
-}
-
-button {
- border-radius: 8px;
- border: 1px solid transparent;
- padding: 0.6em 1.2em;
- font-size: 1em;
- font-weight: 500;
- font-family: inherit;
- background-color: #1a1a1a;
- cursor: pointer;
- transition: border-color 0.25s;
-}
-button:hover {
- border-color: #646cff;
-}
-button:focus,
-button:focus-visible {
- outline: 4px auto -webkit-focus-ring-color;
-}
-
-@media (prefers-color-scheme: light) {
+@layer base {
:root {
- color: #213547;
- background-color: #ffffff;
+ --background: 222.2 84% 4.9%;
+ --foreground: 210 40% 98%;
+
+ --primary: 210 40% 98%;
+ --primary-foreground: 222.2 47.4% 11.2%;
+
+ --secondary: 217.2 32.6% 17.5%;
+ --secondary-foreground: 210 40% 98%;
+
+ --muted: 217.2 32.6% 17.5%;
+ --muted-foreground: 215 20.2% 65.1%;
+
+ --accent: 217.2 32.6% 17.5%;
+ --accent-foreground: 210 40% 98%;
+
+ --destructive: 0 62.8% 30.6%;
+ --destructive-foreground: 210 40% 98%;
+
+ --border: 217.2 32.6% 17.5%;
+ --input: 217.2 32.6% 17.5%;
+ --ring: 212.7 26.8% 83.9%;
+
+ --radius: 0.5rem;
}
- a:hover {
- color: #747bff;
+
+ * {
+ @apply border-border;
}
- button {
- background-color: #f9f9f9;
+
+ body {
+ @apply bg-background text-foreground;
}
-}
+}
\ No newline at end of file
diff --git a/web/src/lib/utils.ts b/web/src/lib/utils.ts
new file mode 100644
index 0000000..815e03d
--- /dev/null
+++ b/web/src/lib/utils.ts
@@ -0,0 +1,27 @@
+import { type ClassValue, clsx } from "clsx";
+import { twMerge } from "tailwind-merge";
+
+export function cn(...inputs: ClassValue[]) {
+ return twMerge(clsx(inputs));
+}
+
+export const formatBytes = (bytes: number | undefined): string => {
+ if (!bytes || !Number.isFinite(bytes)) return "-";
+ const units = ["B", "KB", "MB", "GB", "TB"] as const;
+ let value = bytes;
+ let unitIndex = 0;
+
+ while (value >= 1024 && unitIndex < units.length - 1) {
+ value /= 1024;
+ unitIndex += 1;
+ }
+
+ return `${value.toFixed(1)} ${units[unitIndex]}`;
+};
+
+export const formatSpeed = (bytesPerSecond: number | undefined): string => {
+ if (!bytesPerSecond || !Number.isFinite(bytesPerSecond)) return "- / -";
+ const mbPerSecond = bytesPerSecond / (1024 * 1024);
+ const mbitPerSecond = (bytesPerSecond * 8) / 1_000_000;
+ return `${mbPerSecond.toFixed(2)} MB/s · ${mbitPerSecond.toFixed(2)} Mbps`;
+};
diff --git a/web/tailwind.config.js b/web/tailwind.config.js
new file mode 100644
index 0000000..ad0b813
--- /dev/null
+++ b/web/tailwind.config.js
@@ -0,0 +1,44 @@
+/** @type {import('tailwindcss').Config} */
+export default {
+ content: [
+ "./index.html",
+ "./src/**/*.{js,ts,jsx,tsx}",
+ ],
+ theme: {
+ extend: {
+ colors: {
+ background: "hsl(var(--background))",
+ foreground: "hsl(var(--foreground))",
+ primary: {
+ DEFAULT: "hsl(var(--primary))",
+ foreground: "hsl(var(--primary-foreground))",
+ },
+ secondary: {
+ DEFAULT: "hsl(var(--secondary))",
+ foreground: "hsl(var(--secondary-foreground))",
+ },
+ muted: {
+ DEFAULT: "hsl(var(--muted))",
+ foreground: "hsl(var(--muted-foreground))",
+ },
+ accent: {
+ DEFAULT: "hsl(var(--accent))",
+ foreground: "hsl(var(--accent-foreground))",
+ },
+ destructive: {
+ DEFAULT: "hsl(var(--destructive))",
+ foreground: "hsl(var(--destructive-foreground))",
+ },
+ border: "hsl(var(--border))",
+ input: "hsl(var(--input))",
+ ring: "hsl(var(--ring))",
+ },
+ borderRadius: {
+ lg: "var(--radius)",
+ md: "calc(var(--radius) - 2px)",
+ sm: "calc(var(--radius) - 4px)",
+ },
+ },
+ },
+ plugins: [],
+}
+
+
+ )
+}
+```
+
+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.
+
+---
+
+## Rule 6.2: CSS content-visibility for Long Lists
+
+**Impact:** HIGH
+**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 (
+
+ {messages.map(msg => (
+
+ )
+}
+```
+
+For 1000 messages, browser skips layout/paint for ~990 off-screen items (10× faster initial render).
+
+---
+
+## Rule 6.3: Hoist Static JSX Elements
+
+**Impact:** LOW
+**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
+}
+
+function Container() {
+ return (
+
+
+ ))}
+ {msg.content}
+
+ {loading &&
+ )
+}
+```
+
+**Correct (reuses same element):**
+
+```tsx
+const loadingSkeleton = (
+
+)
+
+function Container() {
+ return (
+
+ {loading && loadingSkeleton}
+
+ )
+}
+```
+
+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.
+
+---
+
+## Rule 6.4: Optimize SVG Precision
+
+**Impact:** LOW
+**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
+
+ {children}
+
+ )
+}
+```
+
+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 (
+
+ {children}
+
+ )
+}
+```
+
+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 (
+ <>
+
+ {children}
+
+
+
+ )
+}
+```
+
+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.
+
+---
+
+## Rule 6.6: Suppress Expected Hydration Mismatches
+
+**Impact:** LOW-MEDIUM
+**Tags:** rendering, hydration, ssr, nextjs
+
+## Suppress Expected Hydration Mismatches
+
+In SSR frameworks (e.g., Next.js), some values are intentionally different on server vs client (random IDs, dates, locale/timezone formatting). For these *expected* mismatches, wrap the dynamic text in an element with `suppressHydrationWarning` to prevent noisy warnings. Do not use this to hide real bugs. Don’t overuse it.
+
+**Incorrect (known mismatch warnings):**
+
+```tsx
+function Timestamp() {
+ return {new Date().toLocaleString()}
+}
+```
+
+**Correct (suppress expected mismatch only):**
+
+```tsx
+function Timestamp() {
+ return (
+
+ {new Date().toLocaleString()}
+
+ )
+}
+```
+
+---
+
+## Rule 6.7: Use Activity Component for Show/Hide
+
+**Impact:** MEDIUM
+**Tags:** rendering, activity, visibility, state-preservation
+
+## Use Activity Component for Show/Hide
+
+Use React's `
+ {count && {count}}
+
+ )
+}
+
+// When count = 0, renders: 0
+// When count = 5, renders: 5
+```
+
+**Correct (renders nothing when count is 0):**
+
+```tsx
+function Badge({ count }: { count: number }) {
+ return (
+
+ {count > 0 ? {count} : null}
+
+ )
+}
+
+// When count = 0, renders:
+// When count = 5, renders: 5
+```
+
+---
+
+## Rule 6.9: Use useTransition Over Manual Loading States
+
+**Impact:** LOW
+**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 (
+ <>
+ handleSearch(e.target.value)} />
+ {isLoading && Content
+}
+
+// Correct: toggle class
+function Box({ isHighlighted }: { isHighlighted: boolean }) {
+ return (
+
+ Content
+
+ )
+}
+```
+
+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.
+
+---
+
+## Rule 7.2: Build Index Maps for Repeated Lookups
+
+**Impact:** LOW-MEDIUM
+**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.
+
+---
+
+## Rule 7.3: Cache Property Access in Loops
+
+**Impact:** LOW-MEDIUM
+**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)
+}
+```
+
+---
+
+## Rule 7.4: Cache Repeated Function Calls
+
+**Impact:** MEDIUM
+**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 (
+
+ {projects.map(project => {
+ // slugify() called 100+ times for same project names
+ const slug = slugify(project.name)
+
+ return
+ )
+}
+```
+
+**Correct (cached results):**
+
+```typescript
+// Module-level cache
+const slugifyCache = new Map
+ {projects.map(project => {
+ // Computed only once per unique project name
+ const slug = cachedSlugify(project.name)
+
+ return
+ )
+}
+```
+
+**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)
+
+---
+
+## Rule 7.5: Cache Storage API Calls
+
+**Impact:** LOW-MEDIUM
+**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{sorted.map(renderUser)}
+}
+```
+
+**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 {sorted.map(renderUser)}
+}
+```
+
+**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/.agent/skills/nextjs-react-expert/8-advanced-advanced-patterns.md b/.agent/skills/nextjs-react-expert/8-advanced-advanced-patterns.md
new file mode 100644
index 0000000..70ec4eb
--- /dev/null
+++ b/.agent/skills/nextjs-react-expert/8-advanced-advanced-patterns.md
@@ -0,0 +1,150 @@
+# 8. Advanced Patterns
+
+> **Impact:** VARIABLE
+> **Focus:** Advanced patterns for specific cases that require careful implementation.
+
+---
+
+## Overview
+
+This section contains **3 rules** focused on advanced patterns.
+
+---
+
+## Rule 8.1: Initialize App Once, Not Per Mount
+
+**Impact:** LOW-MEDIUM
+**Tags:** initialization, useEffect, app-startup, side-effects
+
+## Initialize App Once, Not Per Mount
+
+Do not put app-wide initialization that must run once per app load inside `useEffect([])` of a component. Components can remount and effects will re-run. Use a module-level guard or top-level init in the entry module instead.
+
+**Incorrect (runs twice in dev, re-runs on remount):**
+
+```tsx
+function Comp() {
+ useEffect(() => {
+ loadFromStorage()
+ checkAuthToken()
+ }, [])
+
+ // ...
+}
+```
+
+**Correct (once per app load):**
+
+```tsx
+let didInit = false
+
+function Comp() {
+ useEffect(() => {
+ if (didInit) return
+ didInit = true
+ loadFromStorage()
+ checkAuthToken()
+ }, [])
+
+ // ...
+}
+```
+
+Reference: [Initializing the application](https://react.dev/learn/you-might-not-need-an-effect#initializing-the-application)
+
+---
+
+## Rule 8.2: Store Event Handlers in Refs
+
+**Impact:** LOW
+**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.
+
+---
+
+## Rule 8.3: useEffectEvent for Stable Callback Refs
+
+**Impact:** LOW
+**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/.agent/skills/nextjs-react-expert/SKILL.md b/.agent/skills/nextjs-react-expert/SKILL.md
new file mode 100644
index 0000000..40d20d6
--- /dev/null
+++ b/.agent/skills/nextjs-react-expert/SKILL.md
@@ -0,0 +1,286 @@
+---
+name: react-best-practices
+description: React and Next.js performance optimization from Vercel Engineering. Use when building React components, optimizing performance, eliminating waterfalls, reducing bundle size, reviewing code for performance issues, or implementing server/client-side optimizations.
+allowed-tools: Read, Write, Edit, Glob, Grep, Bash
+---
+
+# Next.js & React Performance Expert
+
+> **From Vercel Engineering** - 57 optimization rules prioritized by impact
+> **Philosophy:** Eliminate waterfalls first, optimize bundles second, then micro-optimize.
+
+---
+
+## 🎯 Selective Reading Rule (MANDATORY)
+
+**Read ONLY sections relevant to your task!** Check the content map below and load what you need.
+
+> 🔴 **For performance reviews: Start with CRITICAL sections (1-2), then move to HIGH/MEDIUM.**
+
+---
+
+## 📑 Content Map
+
+| File | Impact | Rules | When to Read |
+| --------------------------------------- | ------------------ | -------- | --------------------------------------------------------------- |
+| `1-async-eliminating-waterfalls.md` | 🔴 **CRITICAL** | 5 rules | Slow page loads, sequential API calls, data fetching waterfalls |
+| `2-bundle-bundle-size-optimization.md` | 🔴 **CRITICAL** | 5 rules | Large bundle size, slow Time to Interactive, First Load issues |
+| `3-server-server-side-performance.md` | 🟠 **HIGH** | 7 rules | Slow SSR, API route optimization, server-side waterfalls |
+| `4-client-client-side-data-fetching.md` | 🟡 **MEDIUM-HIGH** | 4 rules | Client data management, SWR patterns, deduplication |
+| `5-rerender-re-render-optimization.md` | 🟡 **MEDIUM** | 12 rules | Excessive re-renders, React performance, memoization |
+| `6-rendering-rendering-performance.md` | 🟡 **MEDIUM** | 9 rules | Rendering bottlenecks, virtualization, image optimization |
+| `7-js-javascript-performance.md` | ⚪ **LOW-MEDIUM** | 12 rules | Micro-optimizations, caching, loop performance |
+| `8-advanced-advanced-patterns.md` | 🔵 **VARIABLE** | 3 rules | Advanced React patterns, useLatest, init-once |
+
+**Total: 57 rules across 8 categories**
+
+---
+
+## 🚀 Quick Decision Tree
+
+**What's your performance issue?**
+
+```
+🐌 Slow page loads / Long Time to Interactive
+ → Read Section 1: Eliminating Waterfalls
+ → Read Section 2: Bundle Size Optimization
+
+📦 Large bundle size (> 200KB)
+ → Read Section 2: Bundle Size Optimization
+ → Check: Dynamic imports, barrel imports, tree-shaking
+
+🖥️ Slow Server-Side Rendering
+ → Read Section 3: Server-Side Performance
+ → Check: Parallel data fetching, streaming
+
+🔄 Too many re-renders / UI lag
+ → Read Section 5: Re-render Optimization
+ → Check: React.memo, useMemo, useCallback
+
+🎨 Rendering performance issues
+ → Read Section 6: Rendering Performance
+ → Check: Virtualization, layout thrashing
+
+🌐 Client-side data fetching problems
+ → Read Section 4: Client-Side Data Fetching
+ → Check: SWR deduplication, localStorage
+
+✨ Need advanced patterns
+ → Read Section 8: Advanced Patterns
+```
+
+---
+
+## 📊 Impact Priority Guide
+
+**Use this order when doing comprehensive optimization:**
+
+```
+1️⃣ CRITICAL (Biggest Gains - Do First):
+ ├─ Section 1: Eliminating Waterfalls
+ │ └─ Each waterfall adds full network latency (100-500ms+)
+ └─ Section 2: Bundle Size Optimization
+ └─ Affects Time to Interactive and Largest Contentful Paint
+
+2️⃣ HIGH (Significant Impact - Do Second):
+ └─ Section 3: Server-Side Performance
+ └─ Eliminates server-side waterfalls, faster response times
+
+3️⃣ MEDIUM (Moderate Gains - Do Third):
+ ├─ Section 4: Client-Side Data Fetching
+ ├─ Section 5: Re-render Optimization
+ └─ Section 6: Rendering Performance
+
+4️⃣ LOW (Polish - Do Last):
+ ├─ Section 7: JavaScript Performance
+ └─ Section 8: Advanced Patterns
+```
+
+---
+
+## 🔗 Related Skills
+
+| Need | Skill |
+| ----------------------- | --------------------------------- |
+| API design patterns | `@[skills/api-patterns]` |
+| Database optimization | `@[skills/database-design]` |
+| Testing strategies | `@[skills/testing-patterns]` |
+| UI/UX design principles | `@[skills/frontend-design]` |
+| TypeScript patterns | `@[skills/typescript-expert]` |
+| Deployment & DevOps | `@[skills/deployment-procedures]` |
+
+---
+
+## ✅ Performance Review Checklist
+
+Before shipping to production:
+
+**Critical (Must Fix):**
+
+- [ ] No sequential data fetching (waterfalls eliminated)
+- [ ] Bundle size < 200KB for main bundle
+- [ ] No barrel imports in app code
+- [ ] Dynamic imports used for large components
+- [ ] Parallel data fetching where possible
+
+**High Priority:**
+
+- [ ] Server components used where appropriate
+- [ ] API routes optimized (no N+1 queries)
+- [ ] Suspense boundaries for data fetching
+- [ ] Static generation used where possible
+
+**Medium Priority:**
+
+- [ ] Expensive computations memoized
+- [ ] List rendering virtualized (if > 100 items)
+- [ ] Images optimized with next/image
+- [ ] No unnecessary re-renders
+
+**Low Priority (Polish):**
+
+- [ ] Hot path loops optimized
+- [ ] RegExp patterns hoisted
+- [ ] Property access cached in loops
+
+---
+
+## ❌ Anti-Patterns (Common Mistakes)
+
+**DON'T:**
+
+- ❌ Use sequential `await` for independent operations
+- ❌ Import entire libraries when you need one function
+- ❌ Use barrel exports (`index.ts` re-exports) in app code
+- ❌ Skip dynamic imports for large components/libraries
+- ❌ Fetch data in useEffect without deduplication
+- ❌ Forget to memoize expensive computations
+- ❌ Use client components when server components work
+
+**DO:**
+
+- ✅ Fetch data in parallel with `Promise.all()`
+- ✅ Use dynamic imports: `const Comp = dynamic(() => import('./Heavy'))`
+- ✅ Import directly: `import { specific } from 'library/specific'`
+- ✅ Use Suspense boundaries for better UX
+- ✅ Leverage React Server Components
+- ✅ Measure performance before optimizing
+- ✅ Use Next.js built-in optimizations (next/image, next/font)
+
+---
+
+## 🎯 How to Use This Skill
+
+### For New Features:
+
+1. Check **Section 1 & 2** while building (prevent waterfalls, keep bundle small)
+2. Use server components by default (Section 3)
+3. Apply memoization for expensive operations (Section 5)
+
+### For Performance Reviews:
+
+1. Start with **Section 1** (waterfalls = biggest impact)
+2. Then **Section 2** (bundle size)
+3. Then **Section 3** (server-side)
+4. Finally other sections as needed
+
+### For Debugging Slow Performance:
+
+1. Identify the symptom (slow load, lag, etc.)
+2. Use Quick Decision Tree above
+3. Read relevant section
+4. Apply fixes in priority order
+
+---
+
+## 📚 Learning Path
+
+**Beginner (Focus on Critical):**
+→ Section 1: Eliminating Waterfalls
+→ Section 2: Bundle Size Optimization
+
+**Intermediate (Add High Priority):**
+→ Section 3: Server-Side Performance
+→ Section 5: Re-render Optimization
+
+**Advanced (Full Optimization):**
+→ All sections + Section 8: Advanced Patterns
+
+---
+
+## 🔍 Validation Script
+
+| Script | Purpose | Command |
+| -------------------------------------- | --------------------------- | ------------------------------------------------------------ |
+| `scripts/react_performance_checker.py` | Automated performance audit | `python scripts/react_performance_checker.py