+ {isPending &&
+ );
+}
+
+
+## API Versioning
+
+### 1. URL Versioning
+
+**Version in the URL path**:
+```
+GET /v1/users
+GET /v2/users
+```
+
+**Pros**: Clear, easy to route
+**Cons**: URL changes, harder to maintain multiple versions
+
+### 2. Header Versioning
+
+**Version in Accept header**:
+```
+GET /users
+Accept: application/vnd.myapi.v2+json
+```
+
+**Pros**: Clean URLs, flexible
+**Cons**: Less visible, harder to test
+
+### 3. Deprecation Strategy
+
+**Communicate deprecation clearly**:
+```javascript
+// Response headers
+Deprecation: true
+Sunset: Sat, 31 Dec 2024 23:59:59 GMT
+Link: Loading...
}
+ {error && Error: {error.message}
}
+ {data?.data.map(user =>
+
+
+ )
+ }
+
+ return (
+
+ {/* Sticky Canvas */}
+
+
+ {/* Text Overlays */}
+
+
+
+
+
+
+
+
+
+
+
+
+ )
+}
+```
+
+---
+
+## Key Implementation Details
+
+**Line 15-18**: `useScroll` tracks scroll progress from container start to end
+**Line 21**: `useTransform` maps 0-1 scroll to 0-119 frame index
+**Line 32-46**: Preload all 120 frames using Promise.all
+**Line 49-70**: Draw current frame to canvas, scaled and centered
+**Line 73-76**: Text opacity transforms for fade in/out at specific scroll positions
+
+---
+
+## Usage
+
+1. Install dependencies: `bun --bun install framer-motion`
+2. Place 120 WebP frames in `/public/frames/`
+3. Copy code into respective files
+4. Run: `bun --bun run dev`
+
+---
+
+## Customization
+
+**Change frame count**: Update `FRAME_COUNT` constant (line 7)
+**Adjust scroll length**: Change `h-[400vh]` to `h-[300vh]` or `h-[500vh]` (line 120)
+**Modify text timing**: Update transform ranges in lines 73-76
+**Change colors**: Update `bg-[#050505]` to match your image background
+
+---
+
+## Related
+
+- concepts/scroll-linked-animations.md - Understanding the technique
+- guides/scrollytelling-setup.md - Getting started
+- lookup/scroll-animation-prompts.md - Generating image sequences
+
+---
+
+## References
+
+- [Framer Motion Docs](https://www.framer.com/motion/)
+- [Next.js App Router](https://nextjs.org/docs/app)
diff --git a/.opencode/context/ui/web/design/guides/building-scrollytelling-pages.md b/.opencode/context/ui/web/design/guides/building-scrollytelling-pages.md
new file mode 100644
index 0000000..e6df9a5
--- /dev/null
+++ b/.opencode/context/ui/web/design/guides/building-scrollytelling-pages.md
@@ -0,0 +1,273 @@
+
+
+---
+description: "Step-by-step implementation of scroll-linked image sequence animations"
+---
+
+# Guide: Building Scrollytelling Pages
+
+**Purpose**: Step-by-step implementation of scroll-linked image sequence animations
+
+**Last Updated**: 2026-01-07
+
+---
+
+## Prerequisites
+
+- Next.js 14+ project with App Router
+- Framer Motion installed (`bun --bun i framer-motion`)
+- Tailwind CSS configured
+- Image sequence ready (60-240 WebP frames)
+
+---
+
+## Step 1: Generate Image Sequences
+
+Use nano banana or AI image tools to create start/end frames, then generate interpolation:
+
+**Start frame prompt**:
+```
+Ultra-premium product photography of [product] on matte black surface,
+minimalistic studio shoot, deep black background with subtle gradient,
+soft rim lighting, cinematic, high contrast, luxury aesthetic, sharp focus,
+no clutter, DSLR 85mm f/1.8, photorealistic
+```
+
+**End frame prompt**:
+```
+Exploded technical diagram of same [product], every component separated
+and floating in alignment, against deep black studio background, visible
+internal structure, hyper-realistic, studio rim lighting, cinematic,
+high contrast, no labels, photorealistic
+```
+
+**Generate video**: Use AI video tools (Runway, Pika) to interpolate between frames.
+
+**Export frames**: Use ffmpeg or ezgif to split video into 120+ WebP images.
+
+```bash
+ffmpeg -i animation.mp4 -vf fps=30 frame_%04d.webp
+```
+
+---
+
+## Step 2: Project Structure
+
+```
+app/
+βββ page.tsx # Main landing page
+βββ components/
+β βββ HeadphoneScroll.tsx # Scroll animation component
+βββ globals.css # Dark theme, Inter font
+public/
+βββ frames/
+ βββ frame_0001.webp # 120+ frames
+ βββ frame_0002.webp
+ βββ ...
+```
+
+---
+
+## Step 3: Setup globals.css
+
+```css
+@tailwind base;
+@tailwind components;
+@tailwind utilities;
+
+@layer base {
+ body {
+ @apply bg-[#050505] text-white antialiased;
+ font-family: 'Inter', -apple-system, sans-serif;
+ }
+}
+```
+
+---
+
+## Step 4: Create Scroll Component
+
+**Key patterns**:
+- Container with `h-[400vh]` for long scroll
+- Canvas with `sticky top-0` stays fixed
+- `useScroll` tracks scroll progress (0-1)
+- `useTransform` maps progress to frame index
+- `useEffect` preloads all images
+
+**Core logic**:
+```tsx
+const { scrollYProgress } = useScroll({ target: containerRef })
+const frameIndex = useTransform(scrollYProgress, [0, 1], [0, 119])
+```
+
+---
+
+## Step 5: Implement Preloader
+
+Always preload images before starting animation:
+
+```tsx
+useEffect(() => {
+ const loadImages = async () => {
+ const promises = Array.from({ length: 120 }, (_, i) => {
+ return new Promise((resolve) => {
+ const img = new Image()
+ img.src = `/frames/frame_${String(i + 1).padStart(4, '0')}.webp`
+ img.onload = () => resolve(img)
+ })
+ })
+
+ const loaded = await Promise.all(promises)
+ setImages(loaded)
+ setLoading(false)
+ }
+
+ loadImages()
+}, [])
+```
+
+---
+
+## Step 6: Canvas Rendering
+
+Draw current frame to canvas on every scroll update:
+
+```tsx
+useEffect(() => {
+ if (!canvasRef.current || !images.length) return
+
+ const canvas = canvasRef.current
+ const ctx = canvas.getContext('2d')
+ const img = images[Math.round(currentFrame)]
+
+ // Scale canvas to window
+ canvas.width = window.innerWidth
+ canvas.height = window.innerHeight
+
+ // Draw centered
+ ctx.drawImage(img,
+ (canvas.width - img.width) / 2,
+ (canvas.height - img.height) / 2
+ )
+}, [currentFrame, images])
+```
+
+---
+
+## Step 7: Add Text Overlays
+
+Fade text in/out at specific scroll positions:
+
+```tsx
+
+
+ + Zenith X +
+Pure Sound.
++ Precision Engineering. +
++ Titanium Drivers. +
+
+
+ + Hear Everything. +
+ +
+
+
+)}
+```
+
+---
+
+## Common Issues & Fixes
+
+### Images not loading
+- Check file paths match exactly (case-sensitive)
+- Verify all frames exist in `/public/frames/`
+- Open browser console for 404 errors
+
+### Stuttering animation
+- Ensure all images preloaded before starting
+- Use WebP (not PNG/JPEG)
+- Check canvas size isn't too large
+
+### Visible image edges
+- Background colors don't match exactly
+- Use eyedropper tool, not guessing
+- Check for gradients in image background
+
+### Mobile performance
+- Reduce frame count (use every 2nd frame)
+- Debounce with requestAnimationFrame
+- Consider disabling on small screens
+
+---
+
+## Testing Checklist
+
+- [ ] All frames load without 404s
+- [ ] Animation smooth from 0-100% scroll
+- [ ] Text fades in/out at correct positions
+- [ ] Background seamlessly blends with images
+- [ ] Loading spinner shows before animation
+- [ ] Works on mobile (or gracefully disabled)
+- [ ] No console errors
+
+---
+
+## Related
+
+- concepts/scroll-linked-animations.md - Understanding the technique
+- examples/headphone-scrollytelling.md - Full code example
+- lookup/animation-image-prompts.md - Prompts for frame generation
+
+---
+
+## References
+
+- [Next.js Image Optimization](https://nextjs.org/docs/app/building-your-application/optimizing/images)
+- [Framer Motion useScroll](https://www.framer.com/motion/use-scroll/)
diff --git a/.opencode/context/ui/web/design/lookup/scroll-animation-prompts.md b/.opencode/context/ui/web/design/lookup/scroll-animation-prompts.md
new file mode 100644
index 0000000..c611be0
--- /dev/null
+++ b/.opencode/context/ui/web/design/lookup/scroll-animation-prompts.md
@@ -0,0 +1,215 @@
+
+
+---
+description: "AI prompts for generating start/end frames and video sequences for scrollytelling"
+---
+
+# Lookup: Scroll Animation Image Generation Prompts
+
+**Purpose**: AI prompts for generating start/end frames and video sequences for scrollytelling
+
+**Last Updated**: 2026-01-07
+
+---
+
+## Overview
+
+Use these prompts with nano banana, Runway, Pika, or other AI tools to create image sequences for scroll animations.
+
+**Workflow**: Start frame β End frame β Video interpolation β Frame extraction
+
+---
+
+## Start Frame Prompts
+
+### Product Hero Shot
+
+```
+Ultra-premium product photography of [PRODUCT NAME] placed on a matte black
+surface, minimalistic studio photoshoot. Deep black background (#050505) with
+subtle gradient falloff, soft rim lighting outlining edges, controlled
+reflections on smooth textures. Cinematic lighting, high contrast, luxury tech
+aesthetic, sharp focus, shallow depth of field. No clutter, no text, no logos
+emphasized. Shot with professional DSLR, 85mm lens, f/1.8, ultra-high
+resolution, photorealistic, Apple-level product shoot, dramatic mood, modern
+and elegant.
+```
+
+**Variables**: Replace [PRODUCT NAME] with your product
+**Output**: Starting position, fully assembled, hero angle
+
+---
+
+### Variations by Product Type
+
+| Product Type | Additional Details |
+|--------------|-------------------|
+| **Headphones** | "over-ear headphones with leather cushions and metal headband" |
+| **Smartphone** | "smartphone with edge-to-edge OLED display, aluminum frame" |
+| **Watch** | "luxury smartwatch with titanium case and sapphire crystal" |
+| **Laptop** | "thin laptop with aluminum unibody, open at 45 degrees" |
+| **Camera** | "mirrorless camera with prime lens attached, side profile" |
+
+---
+
+## End Frame Prompts
+
+### Exploded Technical View
+
+```
+Exploded technical diagram view of [PRODUCT NAME], every component precisely
+separated and floating in perfect alignment, suspended in mid-air against deep
+black studio background (#050505). Visible internal structure including
+[INTERNAL COMPONENTS], all parts evenly spaced showing assembly order.
+Hyper-realistic product visualization, ultra-sharp focus, studio rim lighting
+identical to hero shot, soft highlights tracing each component, controlled
+reflections on matte and metal surfaces. Cinematic lighting, high contrast,
+luxury engineering aesthetic, no labels, no annotations, no text.
+Photorealistic, ultra-high resolution, Apple-style industrial design render,
+dramatic and clean.
+```
+
+**Variables**:
+- [PRODUCT NAME]: Your product
+- [INTERNAL COMPONENTS]: Specific parts to show
+
+---
+
+### Internal Components by Product
+
+| Product | Internal Components Examples |
+|---------|------------------------------|
+| **Headphones** | "copper wiring, titanium drivers, magnets, circuit boards, padding layers, metal frame" |
+| **Smartphone** | "battery, logic board, cameras, OLED panel, antenna bands, frame" |
+| **Watch** | "watch movement, gears, battery, sensors, display, crown mechanism" |
+| **Laptop** | "keyboard assembly, trackpad, battery cells, logic board, cooling fans, display panel" |
+| **Camera** | "sensor, shutter mechanism, lens elements, mirror assembly, circuit boards" |
+
+---
+
+## Video Interpolation Prompts
+
+### For Runway/Pika
+
+```
+Smoothly transition from fully assembled [PRODUCT] to exploded view.
+Components separate slowly and precisely, maintaining perfect alignment.
+Camera stays locked, product rotates slightly clockwise. Cinematic motion,
+professional product animation, 4-5 seconds duration, 30fps.
+```
+
+**Settings**:
+- Duration: 4-5 seconds
+- FPS: 30 (yields 120-150 frames)
+- Camera: Static or slow orbit
+- Motion: Smooth, controlled separation
+
+---
+
+## Frame Extraction
+
+### Using ffmpeg
+
+```bash
+# Extract as WebP (best for web)
+ffmpeg -i animation.mp4 -vf fps=30 frame_%04d.webp
+
+# Extract as PNG (higher quality, larger)
+ffmpeg -i animation.mp4 -vf fps=30 frame_%04d.png
+
+# Extract with quality control
+ffmpeg -i animation.mp4 -vf fps=30 -quality 90 frame_%04d.webp
+```
+
+### Using ezgif.com
+
+1. Upload MP4 video
+2. Choose "Video to GIF" β "Split to frames"
+3. Select WebP format
+4. Download all frames as ZIP
+5. Rename: `frame_0001.webp`, `frame_0002.webp`, etc.
+
+---
+
+## Background Color Matching
+
+**CRITICAL**: Page background MUST match image background exactly
+
+### Recommended Dark Backgrounds
+
+| Color Code | Usage |
+|------------|-------|
+| `#050505` | Pure black with slight lift (recommended) |
+| `#0a0a0a` | Slightly lighter, less harsh |
+| `#000000` | True black (only if images are true black) |
+| `#1a1a1a` | Dark gray (for lighter renders) |
+
+**Pro tip**: Use eyedropper tool on first frame background, use exact hex in CSS
+
+---
+
+## Alternative Animation Styles
+
+### Rotation (360Β° spin)
+
+**Start**: Front view
+**End**: Front view (after 360Β° rotation)
+**Prompt**: "Rotate product 360 degrees on turntable, maintain lighting"
+
+### Zoom In (Feature reveal)
+
+**Start**: Full product view
+**End**: Close-up of key feature
+**Prompt**: "Smooth camera push-in focusing on [FEATURE], maintain focus"
+
+### Morph (Color/style change)
+
+**Start**: Product in color A
+**End**: Product in color B
+**Prompt**: "Seamlessly morph product color from [A] to [B], maintain form"
+
+---
+
+## Quality Settings
+
+### For High-End Results
+
+- **Resolution**: 1920x1080 minimum (4K for high-DPI)
+- **Format**: WebP (compression) or PNG (quality)
+- **Frame count**: 90-150 frames (3-5 seconds at 30fps)
+- **Total size**: Target <50MB for all frames combined
+
+### Optimization Tips
+
+1. Use WebP format (70% smaller than PNG)
+2. Compress with quality 85-90
+3. Resize images to max 2000px width
+4. Use consistent aspect ratio (16:9 or 1:1)
+
+---
+
+## Testing Checklist
+
+- [ ] Background color matches exactly (no visible edges)
+- [ ] All frames same dimensions
+- [ ] Smooth motion (no jumps between frames)
+- [ ] Consistent lighting across sequence
+- [ ] File names sequential (`frame_0001` to `frame_0120`)
+- [ ] Total file size reasonable (<50MB)
+
+---
+
+## Related
+
+- concepts/scroll-linked-animations.md - Understanding the technique
+- examples/scrollytelling-headphone.md - Full implementation
+- guides/scrollytelling-setup.md - Setup instructions
+
+---
+
+## Tool References
+
+- [Runway ML](https://runwayml.com) - AI video generation
+- [Pika Labs](https://pika.art) - AI video interpolation
+- [ezgif](https://ezgif.com/split-video) - Frame extraction
+- [FFmpeg](https://ffmpeg.org) - Video processing
diff --git a/.opencode/context/ui/web/design/navigation.md b/.opencode/context/ui/web/design/navigation.md
new file mode 100644
index 0000000..2bb51ec
--- /dev/null
+++ b/.opencode/context/ui/web/design/navigation.md
@@ -0,0 +1,95 @@
+
+
+---
+description: "Advanced web UI patterns - scroll animations, visual effects, and interactive design"
+---
+
+# Web Design Patterns
+
+**Purpose**: Advanced web UI patterns - scroll animations, visual effects, and interactive design
+
+**Last Updated**: 2026-01-31
+
+---
+
+## Quick Navigation
+
+### Concepts
+| File | Description | Priority |
+|------|-------------|----------|
+| [navigation.md](concepts/navigation.md) | Concepts navigation | high |
+| [scroll-linked-animations.md](concepts/scroll-linked-animations.md) | Scroll-synced image sequences (scrollytelling) | high |
+
+### Examples
+| File | Description | Priority |
+|------|-------------|----------|
+| [navigation.md](examples/navigation.md) | Examples navigation | high |
+| [scrollytelling-headphone.md](examples/scrollytelling-headphone.md) | Full Next.js scroll animation example | high |
+
+### Guides
+| File | Description | Priority |
+|------|-------------|----------|
+| [navigation.md](guides/navigation.md) | Guides navigation | high |
+| [building-scrollytelling-pages.md](guides/building-scrollytelling-pages.md) | Complete implementation guide | high |
+| [premium-dark-ui-visual-reference.md](guides/premium-dark-ui-visual-reference.md) | Visual reference for premium dark UI | medium |
+
+### Lookup
+| File | Description | Priority |
+|------|-------------|----------|
+| [navigation.md](lookup/navigation.md) | Lookup navigation | high |
+| [scroll-animation-prompts.md](lookup/scroll-animation-prompts.md) | AI prompts for generating animation sequences | medium |
+
+### Errors
+| File | Description | Priority |
+|------|-------------|----------|
+| _(No error files yet)_ | | |
+
+---
+
+## Loading Strategy
+
+**For scroll animation work**:
+1. Load `concepts/scroll-linked-animations.md` (understand technique)
+2. Load `lookup/scroll-animation-prompts.md` (generate image sequences)
+3. Load `examples/scrollytelling-headphone.md` (see full code)
+4. Reference `guides/building-scrollytelling-pages.md` (step-by-step)
+
+**For premium dark UI design**:
+1. Load `guides/premium-dark-ui-visual-reference.md` (visual patterns and implementation)
+
+---
+
+## Scope
+
+This subcategory covers:
+- β
Scroll-linked animations (scrollytelling)
+- β
Canvas-based rendering
+- β
Framer Motion patterns
+- β
Image sequence generation
+- β
Premium dark UI design system
+- β
Glassmorphism patterns
+- β³ CSS animations (future)
+- β³ SVG animations (future)
+- β³ WebGL effects (future)
+
+---
+
+## Related Categories
+
+- `ui/web/` - Core web UI patterns (parent directory)
+- `ui/web/animation-patterns.md` - CSS animations and transitions
+- `development/` - General development patterns
+
+---
+
+## Used By
+
+**Agents**: frontend-specialist, design-specialist, animation-expert
+
+## Statistics
+- Concepts: 1 + navigation
+- Examples: 1 + navigation
+- Guides: 6 + navigation
+- Lookup: 1 + navigation
+- Errors: 0
+- **Total**: 13 files
diff --git a/.opencode/context/ui/web/navigation.md b/.opencode/context/ui/web/navigation.md
new file mode 100644
index 0000000..63f3842
--- /dev/null
+++ b/.opencode/context/ui/web/navigation.md
@@ -0,0 +1,118 @@
+
+
+# Web UI Context
+
+**Purpose**: Web-based UI patterns, animations, styling standards, and React component design
+
+**Last Updated**: 2026-01-07
+
+---
+
+## Quick Navigation
+
+### Core Files
+
+| File | Description | Priority |
+|------|-------------|----------|
+| [animation-basics.md](animation-basics.md) | Animation fundamentals, timing, easing | high |
+| [animation-components.md](animation-components.md) | Button, card, modal, dropdown animations | high |
+| [animation-chat.md](animation-chat.md) | Chat UI and message animations | medium |
+| [animation-loading.md](animation-loading.md) | Skeleton, spinner, progress animations | medium |
+| [animation-forms.md](animation-forms.md) | Form input and validation animations | medium |
+| [animation-advanced.md](animation-advanced.md) | Recipes, best practices, accessibility | medium |
+| [ui-styling-standards.md](ui-styling-standards.md) | CSS frameworks, Tailwind patterns, styling best practices | high |
+| [react-patterns.md](react-patterns.md) | Modern React patterns, hooks, component design | high |
+| [design-systems.md](design-systems.md) | Design system principles and component libraries | medium |
+| [images-guide.md](images-guide.md) | Placeholder and responsive images | medium |
+| [icons-guide.md](icons-guide.md) | Icon systems (Lucide, Heroicons, FA) | medium |
+| [fonts-guide.md](fonts-guide.md) | Font loading and optimization | medium |
+| [cdn-resources.md](cdn-resources.md) | CDN libraries and resources | medium |
+
+### Subcategories
+
+| Subcategory | Description | Path |
+|-------------|-------------|------|
+| **design/** | Advanced design patterns (scrollytelling, effects) | [design/navigation.md](design/navigation.md) |
+
+---
+
+## Loading Strategy
+
+### For general web UI work:
+1. Load `ui-styling-standards.md` (CSS frameworks, Tailwind)
+2. Load `react-patterns.md` (component patterns)
+3. Reference `animation-patterns.md` (if animations needed)
+
+### For animation work:
+1. Load `animation-basics.md` (fundamentals, timing, easing)
+2. Load `animation-components.md` (UI component animations)
+3. Reference `animation-chat.md` for chat UI patterns
+4. Reference `animation-advanced.md` for recipes and accessibility
+
+### For scroll animations:
+1. Navigate to `design/` subcategory
+2. Load scroll-linked animation guides
+
+---
+
+## Scope
+
+This subcategory covers:
+- β
CSS animations and transitions
+- β
Tailwind CSS and utility-first styling
+- β
React component patterns and hooks
+- β
Design systems and component libraries
+- β
Icon libraries and web fonts
+- β
Scroll-linked animations (scrollytelling)
+- β
Canvas-based rendering
+- β
Framer Motion patterns
+
+---
+
+## File Summaries
+
+### animation-basics.md, animation-components.md, animation-chat.md, animation-loading.md, animation-forms.md, animation-advanced.md
+CSS animations, micro-interactions, and UI transitions split into focused modules.
+
+**Key topics**: Animation micro-syntax, 60fps performance, reduced motion, chat UI animations, component patterns
+
+### ui-styling-standards.md
+CSS framework usage, Tailwind CSS patterns, responsive design, and styling best practices.
+
+**Key topics**: Utility-first CSS, component styling, responsive breakpoints, dark mode
+
+### react-patterns.md
+Modern React patterns including functional components, hooks, state management, and performance optimization.
+
+**Key topics**: Custom hooks, context API, code splitting, memoization
+
+### design-systems.md
+Design system principles, component libraries, and maintaining consistency across applications.
+
+**Key topics**: Design tokens, component APIs, documentation, versioning
+
+### images-guide.md, icons-guide.md, fonts-guide.md, cdn-resources.md
+Managing design assets in web applications - split into focused guides.
+
+**Key topics**: Placeholder images, icon libraries (Lucide, Heroicons), web fonts, CDN resources
+
+---
+
+## Related Categories
+
+- `ui/terminal/` - Terminal UI patterns
+- `development/` - General development patterns
+- `product/` - Product design and UX strategy
+
+---
+
+## Used By
+
+**Agents**: frontend-specialist, design-specialist, ui-developer, react-developer, animation-expert
+
+---
+
+## Statistics
+- Core files: 8
+- Subcategories: 1 (design/)
+- **Total context files**: 8 + design subcategory
diff --git a/.opencode/context/ui/web/react-patterns.md b/.opencode/context/ui/web/react-patterns.md
new file mode 100644
index 0000000..1aeba06
--- /dev/null
+++ b/.opencode/context/ui/web/react-patterns.md
@@ -0,0 +1,330 @@
+
+
+# React Patterns & Best Practices
+
+**Category**: development
+**Purpose**: Modern React patterns, hooks usage, and component design principles
+**Used by**: frontend-specialist
+
+---
+
+## Overview
+
+This guide covers modern React patterns using functional components, hooks, and best practices for building scalable React applications.
+
+## Component Patterns
+
+### 1. Functional Components with Hooks
+
+**Always use functional components**:
+```jsx
+// Good
+function UserProfile({ userId }) {
+ const [user, setUser] = useState(null);
+
+ useEffect(() => {
+ fetchUser(userId).then(setUser);
+ }, [userId]);
+
+ return {user?.name}
;
+}
+```
+
+### 2. Custom Hooks for Reusable Logic
+
+**Extract common logic into custom hooks**:
+```jsx
+// Custom hook
+function useUser(userId) {
+ const [user, setUser] = useState(null);
+ const [loading, setLoading] = useState(true);
+ const [error, setError] = useState(null);
+
+ useEffect(() => {
+ setLoading(true);
+ fetchUser(userId)
+ .then(setUser)
+ .catch(setError)
+ .finally(() => setLoading(false));
+ }, [userId]);
+
+ return { user, loading, error };
+}
+
+// Usage
+function UserProfile({ userId }) {
+ const { user, loading, error } = useUser(userId);
+
+ if (loading) return {user.name}
;
+}
+```
+
+### 3. Composition Over Props Drilling
+
+**Use composition to avoid prop drilling**:
+```jsx
+// Bad - Props drilling
+function App() {
+ const [theme, setTheme] = useState('light');
+ return ...
;
+}
+```
+
+### 4. Compound Components
+
+**For complex, related components**:
+```jsx
+function Tabs({ children }) {
+ const [activeTab, setActiveTab] = useState(0);
+
+ return (
+ {children}
;
+};
+
+Tabs.Tab = function Tab({ index, children }) {
+ const { activeTab, setActiveTab } = useContext(TabsContext);
+ return (
+
+ );
+};
+
+Tabs.Panel = function TabPanel({ index, children }) {
+ const { activeTab } = useContext(TabsContext);
+ return activeTab === index ? {children}
: null;
+};
+
+// Usage
+{items[index].name}
+ );
+
+ return (
+
+
+
+
+Left
+ Right
+
+ Content
+
+```
+
+### Testing Requirements
+
+β
Test at minimum breakpoints: 375px, 768px, 1024px, 1440px
+β
Verify touch targets (min 44x44px)
+β
Check text readability at all sizes
+β
Ensure images scale properly
+β
Test navigation on mobile
+
+---
+
+## Color Palette Guidelines
+
+### Avoid Bootstrap Blue
+
+**Rule**: NEVER use generic Bootstrap blue (#007bff) unless explicitly requested
+
+**Why**: Overused, lacks personality, feels dated
+
+**Alternatives**:
+
+```css
+/* Instead of Bootstrap blue */
+--bootstrap-blue: #007bff; /* β Avoid */
+
+/* Use contextual colors */
+--primary: oklch(0.6489 0.2370 26.9728); /* Vibrant orange */
+--accent: oklch(0.5635 0.2408 260.8178); /* Rich purple */
+--info: oklch(0.6200 0.1900 260); /* Modern blue */
+--success: oklch(0.7323 0.2492 142.4953); /* Fresh green */
+```
+
+### Color Usage Rules
+
+1. **Semantic naming**: Use `--primary`, `--accent`, not `--blue`, `--red`
+2. **Brand alignment**: Choose colors that match project personality
+3. **Contrast testing**: Ensure WCAG AA compliance (4.5:1 minimum)
+4. **Consistency**: Use theme variables throughout
+
+---
+
+## Background/Foreground Contrast
+
+### Contrast Rule
+
+**When designing components or posters**:
+
+- **Light component** β Dark background
+- **Dark component** β Light background
+
+**Why**: Ensures visibility and creates visual hierarchy
+
+**Examples**:
+
+```html
+
+
+
+
+
+
+ Light card content
+
+
+
+```
+
+### Component-Specific Rules
+
+**Posters/Hero Sections**:
+- Use high contrast for readability
+- Consider overlay gradients for text on images
+- Test with actual content
+
+**Cards/Panels**:
+- Subtle elevation with shadows
+- Clear boundary between card and background
+- Consistent padding
+
+---
+
+## CSS Specificity & Overrides
+
+### Using !important
+
+**Rule**: Use `!important` for properties that might be overwritten by Tailwind or Flowbite
+
+**Common Cases**:
+
+```css
+/* Typography overrides */
+h1 {
+ font-size: 2.5rem !important;
+ font-weight: 700 !important;
+ line-height: 1.2 !important;
+}
+
+body {
+ font-family: 'Inter', sans-serif !important;
+ color: var(--foreground) !important;
+}
+
+/* Component overrides */
+.custom-button {
+ background-color: var(--primary) !important;
+ border-radius: var(--radius) !important;
+}
+```
+
+**When NOT to use**:
+
+```css
+/* β Don't use for everything */
+.element {
+ margin: 1rem !important;
+ padding: 1rem !important;
+ display: flex !important;
+}
+
+/* β
Use Tailwind utilities instead */
+
+ Dark card content
+
+
+```
+
+### Specificity Best Practices
+
+1. **Prefer utility classes** over custom CSS
+2. **Use !important sparingly** - only for framework overrides
+3. **Scope custom styles** to avoid conflicts
+4. **Use CSS custom properties** for theming
+
+---
+
+## Layout Patterns
+
+### Flexbox (Preferred for 1D layouts)
+
+```html
+
+
+
+```
+
+---
+
+## Typography Standards
+
+### Hierarchy
+
+```html
+
+...
+
+...
+...
+
+
+
+
+
+```
+
+### Critical CSS
+
+```html
+
+
+
+
+
+```
+
+---
+
+## Best Practices
+
+### Do's β
+
+- Use Tailwind utility classes for rapid development
+- Load Tailwind via script tag for JIT compilation
+- Use Flowbite as default component library
+- Ensure all designs are mobile-first responsive
+- Test at multiple breakpoints
+- Use semantic HTML elements
+- Provide ARIA labels for interactive elements
+- Use CSS custom properties for theming
+- Apply `!important` for framework overrides
+- Ensure proper color contrast (WCAG AA)
+
+### Don'ts β
+
+- Don't use Bootstrap blue without explicit request
+- Don't load Tailwind as a stylesheet
+- Don't skip responsive design
+- Don't use div soup (use semantic HTML)
+- Don't forget focus states
+- Don't hardcode colors (use theme variables)
+- Don't skip accessibility testing
+- Don't use tiny touch targets (<44px)
+- Don't mix color formats
+- Don't over-use `!important`
+
+---
+
+## Framework Alternatives
+
+If user requests a different framework:
+
+**Bootstrap**:
+```html
+
+
+```
+
+**Bulma**:
+```html
+
+```
+
+**Foundation**:
+```html
+
+
+```
+
+---
+
+## References
+
+- [Tailwind CSS Documentation](https://tailwindcss.com/docs)
+- [Flowbite Components](https://flowbite.com/docs/getting-started/introduction/)
+- [WCAG Guidelines](https://www.w3.org/WAI/WCAG21/quickref/)
+- [MDN Web Accessibility](https://developer.mozilla.org/en-US/docs/Web/Accessibility)
diff --git a/.opencode/env.example b/.opencode/env.example
new file mode 100644
index 0000000..ace3b22
--- /dev/null
+++ b/.opencode/env.example
@@ -0,0 +1,28 @@
+# Telegram Bot Configuration
+# Copy this file to .env and fill in your actual values
+
+# Your Telegram bot token (get from @BotFather)
+TELEGRAM_BOT_TOKEN=your_bot_token_here
+
+# Your chat ID (get by messaging your bot and checking the API)
+TELEGRAM_CHAT_ID=your_chat_id_here
+
+# Your bot username (optional, defaults to @OpenCode)
+TELEGRAM_BOT_USERNAME=@YourBotUsername
+
+# Idle timeout in milliseconds (default: 5 minutes = 300000ms)
+TELEGRAM_IDLE_TIMEOUT=300000
+
+# Check interval in milliseconds (default: 30 seconds = 30000ms)
+TELEGRAM_CHECK_INTERVAL=30000
+
+# Enable/disable the plugin (true/false)
+TELEGRAM_ENABLED=true
+
+# Gemini API Configuration
+# Get your API key from https://makersuite.google.com/app/apikey
+GEMINI_API_KEY=your_gemini_api_key_here
+
+# MiniMax API Configuration
+# Get your API key from https://platform.minimax.io
+MINIMAX_API_KEY=your_minimax_api_key_here
diff --git a/.opencode/skills/context7/README.md b/.opencode/skills/context7/README.md
new file mode 100644
index 0000000..bd53d61
--- /dev/null
+++ b/.opencode/skills/context7/README.md
@@ -0,0 +1,102 @@
+# Context7 Skill
+
+## Purpose
+
+Fetches **live, version-specific documentation** for external libraries and frameworks using the Context7 API. Ensures you always get current API patterns instead of potentially outdated training data.
+
+**Golden Rule**: Always fetch live docs for external librariesβtraining data may be outdated.
+
+## Quick Start
+
+### Recommended: Use ExternalScout Subagent
+
+The **ExternalScout** subagent is the recommended way to fetch external documentation. It handles:
+- Library detection
+- Query optimization
+- Documentation filtering and sorting
+- Formatted results with code examples
+
+**Invocation**:
+```
+Use ExternalScout to fetch documentation for [Library Name]: [your specific question]
+```
+
+**Example**:
+```
+Use ExternalScout to fetch documentation for Drizzle ORM: How do I set up modular schemas with PostgreSQL?
+```
+
+### Alternative: Direct Skill Usage
+
+You can also invoke the Context7 skill directly via bash:
+
+```bash
+# Step 1: Search for library
+curl -s "https://context7.com/api/v2/libs/search?libraryName=LIBRARY&query=TOPIC" | jq '.results[0]'
+
+# Step 2: Fetch documentation
+curl -s "https://context7.com/api/v2/context?libraryId=LIBRARY_ID&query=OPTIMIZED_QUERY&type=txt"
+```
+
+See `SKILL.md` for detailed API documentation.
+
+## Supported Libraries
+
+See `library-registry.md` for the complete list of supported libraries including:
+- **Database & ORM**: Drizzle, Prisma
+- **Authentication**: Better Auth, NextAuth.js, Clerk
+- **Frontend**: Next.js, React, TanStack Query/Router/Start
+- **Infrastructure**: Cloudflare Workers, AWS Lambda, Vercel
+- **UI**: Shadcn/ui, Radix UI, Tailwind CSS
+- **State**: Zustand, Jotai
+- **Validation**: Zod, React Hook Form
+- **Testing**: Vitest, Playwright
+
+## Workflow
+
+```
+User Query
+ β
+ContextScout (searches internal context)
+ β
+No internal context found
+ β
+ContextScout recommends ExternalScout
+ β
+ExternalScout invoked
+ ββ Reads library-registry.md
+ ββ Detects library
+ ββ Loads query patterns
+ ββ Fetches from Context7 API
+ ββ Filters & sorts results
+ ββ Returns formatted documentation
+ β
+User receives current, actionable docs
+```
+
+## Files
+
+- **`SKILL.md`** - Context7 API documentation and usage
+- **`library-registry.md`** - Supported libraries, aliases, and query patterns
+- **`README.md`** - This file (overview and quick start)
+
+## Adding New Libraries
+
+To add a new library to the registry:
+
+1. Edit `library-registry.md`
+2. Add entry under appropriate category:
+ ```markdown
+ #### Library Name
+ - **Aliases**: `alias1`, `alias2`, `package-name`
+ - **Docs**: https://example.com/docs
+ - **Context7**: `use context7 for library-name`
+ - **Common topics**: topic1, topic2, topic3
+ ```
+3. (Optional) Add query optimization patterns
+4. ExternalScout will automatically detect the new library
+
+## Related
+
+- **ExternalScout**: `.opencode/agent/subagents/core/externalscout.md`
+- **ContextScout**: `.opencode/agent/subagents/core/contextscout.md`
diff --git a/.opencode/skills/context7/SKILL.md b/.opencode/skills/context7/SKILL.md
new file mode 100644
index 0000000..76160b2
--- /dev/null
+++ b/.opencode/skills/context7/SKILL.md
@@ -0,0 +1,85 @@
+---
+name: context7
+description: Retrieve up-to-date documentation for software libraries, frameworks, and components via the Context7 API. This skill should be used when looking up documentation for any programming library or framework, finding code examples for specific APIs or features, verifying correct usage of library functions, or obtaining current information about library APIs that may have changed since training.
+---
+
+# Context7
+
+## Overview
+
+This skill enables retrieval of current documentation for software libraries and components by querying the Context7 API via curl. Use it instead of relying on potentially outdated training data.
+
+## Workflow
+
+### Step 1: Search for the Library
+
+To find the Context7 library ID, query the search endpoint:
+
+```bash
+curl -s "https://context7.com/api/v2/libs/search?libraryName=LIBRARY_NAME&query=TOPIC" | jq '.results[0]'
+```
+
+**Parameters:**
+- `libraryName` (required): The library name to search for (e.g., "react", "nextjs", "fastapi", "axios")
+- `query` (required): A description of the topic for relevance ranking
+
+**Response fields:**
+- `id`: Library identifier for the context endpoint (e.g., `/websites/react_dev_reference`)
+- `title`: Human-readable library name
+- `description`: Brief description of the library
+- `totalSnippets`: Number of documentation snippets available
+
+### Step 2: Fetch Documentation
+
+To retrieve documentation, use the library ID from step 1:
+
+```bash
+curl -s "https://context7.com/api/v2/context?libraryId=LIBRARY_ID&query=TOPIC&type=txt"
+```
+
+**Parameters:**
+- `libraryId` (required): The library ID from search results
+- `query` (required): The specific topic to retrieve documentation for
+- `type` (optional): Response format - `json` (default) or `txt` (plain text, more readable)
+
+## Examples
+
+### React hooks documentation
+
+```bash
+# Find React library ID
+curl -s "https://context7.com/api/v2/libs/search?libraryName=react&query=hooks" | jq '.results[0].id'
+# Returns: "/websites/react_dev_reference"
+
+# Fetch useState documentation
+curl -s "https://context7.com/api/v2/context?libraryId=/websites/react_dev_reference&query=useState&type=txt"
+```
+
+### Next.js routing documentation
+
+```bash
+# Find Next.js library ID
+curl -s "https://context7.com/api/v2/libs/search?libraryName=nextjs&query=routing" | jq '.results[0].id'
+
+# Fetch app router documentation
+curl -s "https://context7.com/api/v2/context?libraryId=/vercel/next.js&query=app+router&type=txt"
+```
+
+### FastAPI dependency injection
+
+```bash
+# Find FastAPI library ID
+curl -s "https://context7.com/api/v2/libs/search?libraryName=fastapi&query=dependencies" | jq '.results[0].id'
+
+# Fetch dependency injection documentation
+curl -s "https://context7.com/api/v2/context?libraryId=/fastapi/fastapi&query=dependency+injection&type=txt"
+```
+
+## Tips
+
+- Use `type=txt` for more readable output
+- Use `jq` to filter and format JSON responses
+- Be specific with the `query` parameter to improve relevance ranking
+- If the first search result is not correct, check additional results in the array
+- URL-encode query parameters containing spaces (use `+` or `%20`)
+- No API key is required for basic usage (rate-limited)
\ No newline at end of file
diff --git a/.opencode/skills/context7/library-registry.md b/.opencode/skills/context7/library-registry.md
new file mode 100644
index 0000000..4c2f5d4
--- /dev/null
+++ b/.opencode/skills/context7/library-registry.md
@@ -0,0 +1,290 @@
+# External Library Registry
+
+## Purpose
+
+This file lists external libraries/frameworks that should use **ExternalScout** (via Context7) for live documentation instead of relying on potentially outdated training data.
+
+## When to Use This
+
+**ContextScout** checks this list when:
+1. User asks about a library/framework
+2. No internal context exists in `.opencode/context/development/frameworks/`
+3. Query matches a library name below
+
+**Action**: Recommend **ExternalScout** subagent
+
+---
+
+## Supported Libraries
+
+### Database & ORM
+
+#### Drizzle ORM
+- **Aliases**: `drizzle`, `drizzle-orm`, `drizzle orm`
+- **Docs**: https://orm.drizzle.team/
+- **Context7**: `use context7 for drizzle`
+- **Common topics**: schema organization, migrations, relational queries, transactions, TypeScript types
+
+#### Prisma
+- **Aliases**: `prisma`
+- **Docs**: https://www.prisma.io/docs
+- **Context7**: `use context7 for prisma`
+- **Common topics**: schema, migrations, client, relations, TypeScript
+
+---
+
+### Authentication
+
+#### Better Auth
+- **Aliases**: `better-auth`, `better auth`, `betterauth`
+- **Docs**: https://www.better-auth.com/docs
+- **Context7**: `use context7 for better-auth`
+- **Common topics**: Next.js integration, Drizzle adapter, social providers, session management, 2FA
+
+#### NextAuth.js
+- **Aliases**: `nextauth`, `next-auth`, `nextauth.js`
+- **Docs**: https://next-auth.js.org/
+- **Context7**: `use context7 for nextauth`
+- **Common topics**: providers, callbacks, sessions, JWT
+
+#### Clerk
+- **Aliases**: `clerk`
+- **Docs**: https://clerk.com/docs
+- **Context7**: `use context7 for clerk`
+- **Common topics**: authentication, user management, organizations
+
+---
+
+### Frontend Frameworks
+
+#### Next.js
+- **Aliases**: `nextjs`, `next.js`, `next`
+- **Docs**: https://nextjs.org/docs
+- **Context7**: `use context7 for nextjs`
+- **Common topics**: App Router, Server Actions, Server Components, routing, middleware, API routes
+
+#### React
+- **Aliases**: `react`, `reactjs`, `react.js`
+- **Docs**: https://react.dev/
+- **Context7**: `use context7 for react`
+- **Common topics**: hooks, components, state, effects, context
+
+#### TanStack Query
+- **Aliases**: `tanstack query`, `react query`, `@tanstack/react-query`
+- **Docs**: https://tanstack.com/query/latest
+- **Context7**: `use context7 for tanstack query`
+- **Common topics**: useQuery, useMutation, prefetching, caching, Server Components
+
+#### TanStack Router
+- **Aliases**: `tanstack router`, `@tanstack/react-router`
+- **Docs**: https://tanstack.com/router/latest
+- **Context7**: `use context7 for tanstack router`
+- **Common topics**: routing, type-safe routes, loaders, navigation
+
+#### TanStack Start
+- **Aliases**: `tanstack start`, `@tanstack/start`
+- **Docs**: https://tanstack.com/start/latest
+- **Context7**: `use context7 for tanstack start`
+- **Common topics**: full-stack setup, server functions, file routing
+
+---
+
+### Infrastructure & Deployment
+
+#### Cloudflare Workers
+- **Aliases**: `cloudflare workers`, `cloudflare`, `workers`, `cf workers`
+- **Docs**: https://developers.cloudflare.com/workers
+- **Context7**: `use context7 for cloudflare workers`
+- **Common topics**: routing, KV storage, Durable Objects, bindings, middleware
+
+#### AWS Lambda
+- **Aliases**: `aws lambda`, `lambda`, `aws Ξ»`
+- **Docs**: https://docs.aws.amazon.com/lambda
+- **Context7**: `use context7 for aws lambda`
+- **Common topics**: handlers, layers, environment variables, triggers, TypeScript
+
+#### Vercel
+- **Aliases**: `vercel`
+- **Docs**: https://vercel.com/docs
+- **Context7**: `use context7 for vercel`
+- **Common topics**: deployment, environment variables, edge functions, serverless
+
+---
+
+### UI Libraries & Styling
+
+#### Shadcn/ui
+- **Aliases**: `shadcn`, `shadcn/ui`, `shadcn-ui`
+- **Docs**: https://ui.shadcn.com/
+- **Context7**: `use context7 for shadcn`
+- **Common topics**: components, installation, theming, customization
+
+#### Radix UI
+- **Aliases**: `radix`, `radix ui`, `radix-ui`, `@radix-ui`
+- **Docs**: https://www.radix-ui.com/
+- **Context7**: `use context7 for radix`
+- **Common topics**: primitives, accessibility, composition
+
+#### Tailwind CSS
+- **Aliases**: `tailwind`, `tailwindcss`, `tailwind css`
+- **Docs**: https://tailwindcss.com/docs
+- **Context7**: `use context7 for tailwind`
+- **Common topics**: configuration, utilities, responsive design, dark mode
+
+---
+
+### State Management
+
+#### Zustand
+- **Aliases**: `zustand`
+- **Docs**: https://zustand-demo.pmnd.rs/
+- **Context7**: `use context7 for zustand`
+- **Common topics**: store creation, selectors, middleware, TypeScript
+
+#### Jotai
+- **Aliases**: `jotai`
+- **Docs**: https://jotai.org/
+- **Context7**: `use context7 for jotai`
+- **Common topics**: atoms, async atoms, utilities
+
+---
+
+### Validation & Forms
+
+#### Zod
+- **Aliases**: `zod`
+- **Docs**: https://zod.dev/
+- **Context7**: `use context7 for zod`
+- **Common topics**: schema validation, TypeScript inference, parsing, refinements
+
+#### React Hook Form
+- **Aliases**: `react hook form`, `react-hook-form`, `rhf`
+- **Docs**: https://react-hook-form.com/
+- **Context7**: `use context7 for react hook form`
+- **Common topics**: register, validation, errors, TypeScript
+
+---
+
+### Testing
+
+#### Vitest
+- **Aliases**: `vitest`
+- **Docs**: https://vitest.dev/
+- **Context7**: `use context7 for vitest`
+- **Common topics**: configuration, testing, mocking, coverage
+
+#### Playwright
+- **Aliases**: `playwright`
+- **Docs**: https://playwright.dev/
+- **Context7**: `use context7 for playwright`
+- **Common topics**: browser automation, testing, selectors, assertions
+
+---
+
+## Detection Patterns
+
+ContextScout and ExternalScout should match queries containing:
+- Library name (case-insensitive)
+- Common variations (e.g., "next.js" vs "nextjs")
+- Package names (e.g., "@tanstack/react-query")
+
+**Examples**:
+- "How do I use **Drizzle** with PostgreSQL?" β Match: Drizzle ORM
+- "Show me **Next.js** App Router setup" β Match: Next.js
+- "**TanStack Query** with Server Components" β Match: TanStack Query
+- "**Better Auth** integration" β Match: Better Auth
+
+---
+
+## Query Optimization Patterns
+
+### Drizzle ORM
+
+| User Intent | Optimized Query |
+|-------------|-----------------|
+| Setup/Installation | `PostgreSQL+setup+configuration+TypeScript+installation` |
+| Modular schemas | `modular+schema+organization+domain+driven+design` |
+| Relations | `relational+queries+one+to+many+joins+with+relations` |
+| Migrations | `drizzle-kit+migrations+generate+push+PostgreSQL` |
+| Transactions | `database+transactions+patterns+TypeScript` |
+| Type safety | `TypeScript+type+inference+schema+types+inferInsert` |
+
+### Better Auth
+
+| User Intent | Optimized Query |
+|-------------|-----------------|
+| Setup | `setup+configuration+Next.js+TypeScript+installation` |
+| Next.js integration | `Next.js+App+Router+integration+setup+configuration` |
+| Drizzle adapter | `Drizzle+adapter+PostgreSQL+schema+generation+configuration` |
+| Social providers | `social+providers+OAuth+GitHub+Google+setup` |
+| Email/password | `email+password+authentication+signup+signin` |
+| Session management | `session+management+cookies+JWT+middleware` |
+
+### Next.js
+
+| User Intent | Optimized Query |
+|-------------|-----------------|
+| App Router | `App+Router+file+conventions+layouts+pages+routing` |
+| Server Actions | `Server+Actions+form+mutations+revalidation+TypeScript` |
+| Server Components | `React+Server+Components+async+data+fetching+patterns` |
+| Dynamic routes | `dynamic+routes+params+TypeScript+generateStaticParams` |
+| Middleware | `middleware+authentication+redirects+headers+cookies` |
+| API routes | `API+routes+route+handlers+TypeScript+POST+GET` |
+
+### TanStack Query
+
+| User Intent | Optimized Query |
+|-------------|-----------------|
+| Setup | `setup+QueryClient+provider+Next.js+TypeScript` |
+| Data fetching | `useQuery+data+fetching+TypeScript+patterns+async` |
+| Mutations | `useMutation+optimistic+updates+invalidation+TypeScript` |
+| Prefetching | `prefetchQuery+Server+Components+hydration+Next.js` |
+| Caching | `cache+configuration+staleTime+gcTime+invalidation` |
+
+### Cloudflare Workers
+
+| User Intent | Optimized Query |
+|-------------|-----------------|
+| Setup | `getting+started+setup+TypeScript+wrangler+configuration` |
+| Routing | `routing+itty-router+hono+request+handling` |
+| KV storage | `KV+storage+key+value+bindings+TypeScript` |
+| Durable Objects | `Durable+Objects+state+WebSockets+coordination` |
+
+### AWS Lambda
+
+| User Intent | Optimized Query |
+|-------------|-----------------|
+| Setup | `getting+started+setup+TypeScript+handler+configuration` |
+| Handlers | `handler+function+event+context+TypeScript+patterns` |
+| Layers | `layers+dependencies+shared+code+deployment` |
+| Environment variables | `environment+variables+secrets+configuration+SSM` |
+
+---
+
+## Adding New Libraries
+
+To add a new library:
+1. Add entry under appropriate category
+2. Include: Name, aliases, docs link, Context7 command, common topics
+3. (Optional) Add query optimization patterns
+4. Update ExternalScout if needed (usually automatic)
+
+**Template**:
+```markdown
+#### Library Name
+- **Aliases**: `alias1`, `alias2`, `package-name`
+- **Docs**: https://example.com/docs
+- **Context7**: `use context7 for library-name`
+- **Common topics**: topic1, topic2, topic3
+```
+
+---
+
+## Usage by ExternalScout
+
+ExternalScout uses this file to:
+1. **Detect** which library the user is asking about
+2. **Load** query optimization patterns for that library
+3. **Build** optimized Context7 queries
+4. **Fetch** live documentation
+5. **Return** filtered, relevant results
diff --git a/.opencode/skills/context7/navigation.md b/.opencode/skills/context7/navigation.md
new file mode 100644
index 0000000..30f848c
--- /dev/null
+++ b/.opencode/skills/context7/navigation.md
@@ -0,0 +1,51 @@
+# Context7 Skill Navigation
+
+**Purpose**: Live documentation fetching for external libraries via Context7 API
+
+---
+
+## Structure
+
+```
+context7/
+βββ navigation.md # This file
+βββ README.md # Quick start and workflow
+βββ SKILL.md # Context7 API documentation
+βββ library-registry.md # Supported libraries and query patterns
+```
+
+---
+
+## Quick Routes
+
+| Task | Path |
+|------|------|
+| **Quick start** | `README.md` |
+| **API reference** | `SKILL.md` |
+| **Supported libraries** | `library-registry.md` (lines 18-181) |
+| **Query patterns** | `library-registry.md` (lines 199-261) |
+| **Add new library** | `library-registry.md` (lines 264-279) |
+| **ExternalScout integration** | `README.md` (lines 9-26) |
+
+---
+
+## By Purpose
+
+**Using Context7**:
+- Quick start β `README.md`
+- API details β `SKILL.md`
+
+**Adding Libraries**:
+- Template β `library-registry.md` (lines 272-279)
+- Supported list β `library-registry.md` (lines 18-181)
+
+**Integration**:
+- ContextScout workflow β `README.md` (lines 54-73)
+- ExternalScout subagent β `.opencode/agent/subagents/core/externalscout.md`
+
+---
+
+## Related
+
+- **ExternalScout**: `.opencode/agent/subagents/core/externalscout.md`
+- **ContextScout**: `.opencode/agent/subagents/core/contextscout.md`
diff --git a/.opencode/skills/task-management/SKILL.md b/.opencode/skills/task-management/SKILL.md
new file mode 100644
index 0000000..8143066
--- /dev/null
+++ b/.opencode/skills/task-management/SKILL.md
@@ -0,0 +1,399 @@
+---
+name: task-management
+description: Task management CLI for tracking and managing feature subtasks with status, dependencies, and validation
+version: 1.0.0
+author: opencode
+type: skill
+category: development
+tags:
+ - tasks
+ - management
+ - tracking
+ - dependencies
+ - cli
+---
+
+# Task Management Skill
+
+> **Purpose**: Track, manage, and validate feature implementations with atomic task breakdowns, dependency resolution, and progress monitoring.
+
+---
+
+## What I Do
+
+I provide a command-line interface for managing task breakdowns created by the TaskManager subagent. I help you:
+
+- **Track progress** - See status of all features and their subtasks
+- **Find next tasks** - Show eligible tasks (dependencies satisfied)
+- **Identify blocked tasks** - See what's blocked and why
+- **Manage completion** - Mark subtasks as complete with summaries
+- **Validate integrity** - Check JSON files and dependency trees
+
+---
+
+## How to Use Me
+
+### Quick Start
+
+```bash
+# Show all task statuses
+bash .opencode/skills/task-management/router.sh status
+
+# Show next eligible tasks
+bash .opencode/skills/task-management/router.sh next
+
+# Show blocked tasks
+bash .opencode/skills/task-management/router.sh blocked
+
+# Mark a task complete
+bash .opencode/skills/task-management/router.sh complete "summary"
+
+# Validate all tasks
+bash .opencode/skills/task-management/router.sh validate
+```
+
+### Command Reference
+
+| Command | Description |
+|---------|-------------|
+| `status [feature]` | Show task status summary for all features or specific one |
+| `next [feature]` | Show next eligible tasks (dependencies satisfied) |
+| `parallel [feature]` | Show parallelizable tasks ready to run |
+| `deps ` | Show dependency tree for a specific subtask |
+| `blocked [feature]` | Show blocked tasks and why |
+| `complete "summary"` | Mark subtask complete with summary |
+| `validate [feature]` | Validate JSON files and dependencies |
+| `help` | Show help message |
+
+---
+
+## Examples
+
+### Check Overall Progress
+
+```bash
+$ bash .opencode/skills/task-management/router.sh status
+
+[my-feature] My Feature Implementation
+ Status: active | Progress: 45% (5/11)
+ Pending: 3 | In Progress: 2 | Completed: 5 | Blocked: 1
+```
+
+### Find What's Next
+
+```bash
+$ bash .opencode/skills/task-management/router.sh next
+
+=== Ready Tasks (deps satisfied) ===
+
+[my-feature]
+ 06 - Implement API endpoint [sequential]
+ 08 - Write unit tests [parallel]
+```
+
+### Mark Complete
+
+```bash
+$ bash .opencode/skills/task-management/router.sh complete my-feature 05 "Implemented authentication module"
+
+β Marked my-feature/05 as completed
+ Summary: Implemented authentication module
+ Progress: 6/11
+```
+
+### Check Dependencies
+
+```bash
+$ bash .opencode/skills/task-management/router.sh deps my-feature 07
+
+=== Dependency Tree: my-feature/07 ===
+
+07 - Write integration tests [pending]
+ βββ β 05 - Implement authentication module [completed]
+ βββ β 06 - Implement API endpoint [in_progress]
+```
+
+### Validate Everything
+
+```bash
+$ bash .opencode/skills/task-management/router.sh validate
+
+=== Validation Results ===
+
+[my-feature]
+ β All checks passed
+```
+
+---
+
+## Architecture
+
+```
+.opencode/skills/task-management/
+βββ SKILL.md # This file
+βββ router.sh # CLI router (entry point)
+βββ scripts/
+ βββ task-cli.ts # Task management CLI implementation
+```
+
+---
+
+## Task File Structure
+
+Tasks are stored in `.tmp/tasks/` at the project root:
+
+```
+.tmp/tasks/
+βββ {feature-slug}/
+β βββ task.json # Feature-level metadata
+β βββ subtask_01.json # Subtask definitions
+β βββ subtask_02.json
+β βββ ...
+βββ completed/
+ βββ {feature-slug}/ # Completed tasks
+```
+
+### task.json Schema
+
+```json
+{
+ "id": "my-feature",
+ "name": "My Feature",
+ "status": "active",
+ "objective": "Implement X",
+ "context_files": ["docs/spec.md"],
+ "reference_files": ["src/existing.ts"],
+ "exit_criteria": ["Tests pass", "Code reviewed"],
+ "subtask_count": 5,
+ "completed_count": 2,
+ "created_at": "2026-01-11T10:00:00Z",
+ "completed_at": null
+}
+```
+
+### subtask_##.json Schema
+
+```json
+{
+ "id": "my-feature-05",
+ "seq": "05",
+ "title": "Implement authentication",
+ "status": "pending",
+ "depends_on": ["03", "04"],
+ "parallel": false,
+ "suggested_agent": "coder-agent",
+ "context_files": ["docs/auth.md"],
+ "reference_files": ["src/auth-old.ts"],
+ "acceptance_criteria": ["Login works", "JWT tokens valid"],
+ "deliverables": ["auth.ts", "auth.test.ts"],
+ "started_at": null,
+ "completed_at": null,
+ "completion_summary": null
+}
+```
+
+---
+
+## Integration with TaskManager
+
+The TaskManager subagent creates task files using this format. When you delegate to TaskManager:
+
+```javascript
+task(
+ subagent_type="TaskManager",
+ description="Implement feature X",
+ prompt="Break down this feature into atomic subtasks..."
+)
+```
+
+TaskManager creates:
+1. `.tmp/tasks/{feature}/task.json` - Feature metadata
+2. `.tmp/tasks/{feature}/subtask_XX.json` - Individual subtasks
+
+You can then use this skill to track and manage progress.
+
+---
+
+## Key Concepts
+
+### 1. Dependency Resolution
+Subtasks can depend on other subtasks. A task is "ready" only when all its dependencies are complete.
+
+### 2. Parallel Execution
+Set `parallel: true` to indicate a subtask can run alongside other parallel tasks with satisfied dependencies.
+
+### 3. Status Tracking
+- **pending** - Not started, waiting for dependencies
+- **in_progress** - Currently being worked on
+- **completed** - Finished with summary
+- **blocked** - Explicitly blocked (not waiting for deps)
+
+### 4. Exit Criteria
+Each feature has exit_criteria that must be met before marking the feature complete.
+
+### 5. Validation Rules
+
+The `validate` command performs comprehensive checks on task files:
+
+**Task-Level Validation:**
+- β
task.json file exists for the feature
+- β
Task ID matches feature slug
+- β
Subtask count in task.json matches actual subtask files
+- β
All required fields are present
+
+**Subtask-Level Validation:**
+- β
All subtask IDs start with feature name (e.g., "my-feature-01")
+- β
Sequence numbers are unique and properly formatted (01, 02, etc.)
+- β
All dependencies reference existing subtasks
+- β
No circular dependencies exist
+- β
Each subtask has acceptance criteria defined
+- β
Each subtask has deliverables specified
+- β
Status values are valid (pending, in_progress, completed, blocked)
+
+**Dependency Validation:**
+- β
All depends_on references point to existing subtasks
+- β
No task depends on itself
+- β
No circular dependency chains
+- β
Dependency graph is acyclic
+
+Run `validate` regularly to catch issues early:
+```bash
+bash .opencode/skills/task-management/router.sh validate my-feature
+```
+
+### 6. Context and Reference Files
+- **context_files** - Standards, conventions, and guidelines to follow
+- **reference_files** - Existing project files to look at or build upon
+
+---
+
+## Workflow Integration
+
+### With TaskManager Subagent
+
+1. **TaskManager creates tasks** β Generates `.tmp/tasks/{feature}/` structure
+2. **You use this skill to track** β Monitor progress with `status`, `next`, `blocked`
+3. **You mark tasks complete** β Use `complete` command with summaries
+4. **Skill validates integrity** β Use `validate` to check consistency
+
+### With Other Subagents
+
+Working agents (CoderAgent, TestEngineer, etc.) execute subtasks and report completion. Use this skill to:
+- Find next available tasks with `next`
+- Check what's blocking progress with `blocked`
+- Validate task definitions with `validate`
+
+---
+
+## Common Workflows
+
+### Starting a New Feature
+
+```bash
+# 1. TaskManager creates the task structure
+task(subagent_type="TaskManager", description="Implement feature X", ...)
+
+# 2. Check what's ready
+bash .opencode/skills/task-management/router.sh next
+
+# 3. Delegate first task to working agent
+task(subagent_type="CoderAgent", description="Implement subtask 01", ...)
+```
+
+### Tracking Progress
+
+```bash
+# Check overall status
+bash .opencode/skills/task-management/router.sh status my-feature
+
+# See what's next
+bash .opencode/skills/task-management/router.sh next my-feature
+
+# Check what's blocked
+bash .opencode/skills/task-management/router.sh blocked my-feature
+```
+
+### Completing Tasks
+
+```bash
+# After working agent finishes
+bash .opencode/skills/task-management/router.sh complete my-feature 05 "Implemented auth module with JWT support"
+
+# Check progress
+bash .opencode/skills/task-management/router.sh status my-feature
+
+# Find next task
+bash .opencode/skills/task-management/router.sh next my-feature
+```
+
+### Validating Everything
+
+```bash
+# Validate all tasks
+bash .opencode/skills/task-management/router.sh validate
+
+# Validate specific feature
+bash .opencode/skills/task-management/router.sh validate my-feature
+```
+
+---
+
+## Tips & Best Practices
+
+### 1. Use Meaningful Summaries
+When marking tasks complete, provide clear summaries:
+```bash
+# Good
+complete my-feature 05 "Implemented JWT authentication with refresh tokens and error handling"
+
+# Avoid
+complete my-feature 05 "Done"
+```
+
+### 2. Check Dependencies Before Starting
+```bash
+# See what a task depends on
+bash .opencode/skills/task-management/router.sh deps my-feature 07
+```
+
+### 3. Identify Parallelizable Work
+```bash
+# Find tasks that can run in parallel
+bash .opencode/skills/task-management/router.sh parallel my-feature
+```
+
+### 4. Regular Validation
+```bash
+# Validate regularly to catch issues early
+bash .opencode/skills/task-management/router.sh validate
+```
+
+---
+
+## Troubleshooting
+
+### "task-cli.ts not found"
+Make sure you're running from the project root or the router.sh can find it.
+
+### "No tasks found"
+Run `status` to see if any tasks have been created yet. Use TaskManager to create tasks first.
+
+### "Dependency not satisfied"
+Check the dependency tree with `deps` to see what's blocking the task.
+
+### "Validation failed"
+Run `validate` to see specific issues, then check the JSON files in `.tmp/tasks/`.
+
+---
+
+## File Locations
+
+- **Skill**: `.opencode/skills/task-management/`
+- **Router**: `.opencode/skills/task-management/router.sh`
+- **CLI**: `.opencode/skills/task-management/scripts/task-cli.ts`
+- **Tasks**: `.tmp/tasks/` (created by TaskManager)
+- **Documentation**: `.opencode/skills/task-management/SKILL.md` (this file)
+
+---
+
+**Task Management Skill** - Track, manage, and validate your feature implementations!
diff --git a/.opencode/skills/task-management/router.sh b/.opencode/skills/task-management/router.sh
new file mode 100644
index 0000000..c47b9a8
--- /dev/null
+++ b/.opencode/skills/task-management/router.sh
@@ -0,0 +1,108 @@
+#!/usr/bin/env bash
+#############################################################################
+# Task Management Skill Router
+# Routes to task-cli.ts with proper path resolution and command handling
+#############################################################################
+
+set -e
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+CLI_SCRIPT="$SCRIPT_DIR/scripts/task-cli.ts"
+MIGRATE_SCRIPT="$SCRIPT_DIR/scripts/migrate-schema.ts"
+
+# Show help
+show_help() {
+ cat << 'HELP'
+π Task Management Skill
+ββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
+
+Usage: router.sh [COMMAND] [OPTIONS]
+
+COMMANDS:
+ status [feature] Show task status summary
+ next [feature] Show next eligible tasks
+ parallel [feature] Show parallelizable tasks
+ deps Show dependency tree
+ blocked [feature] Show blocked tasks
+ complete "msg" Mark subtask complete
+ validate [feature] Validate JSON files
+ context Show bounded context breakdown
+ contracts Show contract dependencies
+ migrate [options] Migrate to enhanced schema
+ help Show this help message
+
+MIGRATION OPTIONS:
+ --dry-run Preview migration changes
+ --lines-only Add only line-number precision
+
+EXAMPLES:
+ ./router.sh status
+ ./router.sh status my-feature
+ ./router.sh next
+ ./router.sh deps my-feature 05
+ ./router.sh complete my-feature 05 "Implemented auth module"
+ ./router.sh validate
+ ./router.sh context my-feature
+ ./router.sh contracts my-feature
+ ./router.sh migrate my-feature
+ ./router.sh migrate my-feature --dry-run
+
+FEATURES:
+ β Track progress across all features
+ β Find next eligible tasks (dependencies satisfied)
+ β Identify blocked tasks
+ β Mark subtasks complete with summaries
+ β Validate task integrity
+ β Show bounded context breakdown
+ β Show contract dependencies
+ β Migrate to enhanced schema
+
+For more info, see: .opencode/skills/task-management/SKILL.md
+HELP
+}
+
+# Check if CLI script exists
+if [ ! -f "$CLI_SCRIPT" ]; then
+ echo "β Error: task-cli.ts not found at $CLI_SCRIPT"
+ exit 1
+fi
+
+# Find project root
+find_project_root() {
+ local dir
+ dir="$(pwd)"
+ while [ "$dir" != "/" ]; do
+ if [ -d "$dir/.git" ] || [ -f "$dir/package.json" ]; then
+ echo "$dir"
+ return 0
+ fi
+ dir="$(dirname "$dir")"
+ done
+ pwd
+ return 1
+}
+
+# Handle help
+if [ "$1" = "help" ] || [ "$1" = "-h" ] || [ "$1" = "--help" ]; then
+ show_help
+ exit 0
+fi
+
+# If no arguments, show help
+if [ $# -eq 0 ]; then
+ show_help
+ exit 0
+fi
+
+PROJECT_ROOT="$(find_project_root)"
+
+# Route commands
+case "$1" in
+ migrate)
+ cd "$PROJECT_ROOT" && bunx --bun ts-node "$MIGRATE_SCRIPT" "$@"
+ ;;
+ *)
+ # Run the task CLI with all arguments
+ cd "$PROJECT_ROOT" && bunx --bun ts-node "$CLI_SCRIPT" "$@"
+ ;;
+esac
diff --git a/.opencode/skills/task-management/scripts/task-cli.ts b/.opencode/skills/task-management/scripts/task-cli.ts
new file mode 100644
index 0000000..957e1bd
--- /dev/null
+++ b/.opencode/skills/task-management/scripts/task-cli.ts
@@ -0,0 +1,553 @@
+#!/usr/bin/env bunx --bun ts-node
+/**
+ * Task Management CLI
+ *
+ * Usage: bunx --bun ts-node task-cli.ts [feature] [args...]
+ *
+ * Commands:
+ * status [feature] - Show task status summary
+ * next [feature] - Show next eligible tasks
+ * parallel [feature] - Show parallelizable tasks ready to run
+ * deps - Show dependency tree for a task
+ * blocked [feature] - Show blocked tasks and why
+ * complete "summary" - Mark task completed
+ * validate [feature] - Validate JSON files and dependencies
+ *
+ * Task files are stored in .tmp/tasks/ at the project root:
+ * .tmp/tasks/{feature-slug}/task.json
+ * .tmp/tasks/{feature-slug}/subtask_01.json
+ * .tmp/tasks/completed/{feature-slug}/
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+// Find project root (look for .git or package.json)
+function findProjectRoot(): string {
+ let dir = process.cwd();
+ while (dir !== path.dirname(dir)) {
+ if (fs.existsSync(path.join(dir, '.git')) || fs.existsSync(path.join(dir, 'package.json'))) {
+ return dir;
+ }
+ dir = path.dirname(dir);
+ }
+ return process.cwd();
+}
+
+const PROJECT_ROOT = findProjectRoot();
+const TASKS_DIR = path.join(PROJECT_ROOT, '.tmp', 'tasks');
+const COMPLETED_DIR = path.join(TASKS_DIR, 'completed');
+
+interface Task {
+ id: string;
+ name: string;
+ status: 'active' | 'completed' | 'blocked' | 'archived';
+ objective: string;
+ context_files: string[];
+ reference_files?: string[];
+ exit_criteria: string[];
+ subtask_count: number;
+ completed_count: number;
+ created_at: string;
+ completed_at: string | null;
+}
+
+interface Subtask {
+ id: string;
+ seq: string;
+ title: string;
+ status: 'pending' | 'in_progress' | 'completed' | 'blocked';
+ depends_on: string[];
+ parallel: boolean;
+ context_files: string[];
+ reference_files?: string[];
+ acceptance_criteria: string[];
+ deliverables: string[];
+ agent_id: string | null;
+ suggested_agent?: string;
+ started_at: string | null;
+ completed_at: string | null;
+ completion_summary: string | null;
+}
+
+// Helpers
+function getFeatureDirs(): string[] {
+ if (!fs.existsSync(TASKS_DIR)) return [];
+ return fs.readdirSync(TASKS_DIR).filter((f: string) => {
+ const fullPath = path.join(TASKS_DIR, f);
+ return fs.statSync(fullPath).isDirectory() && f !== 'completed';
+ });
+}
+
+function loadTask(feature: string): Task | null {
+ const taskPath = path.join(TASKS_DIR, feature, 'task.json');
+ if (!fs.existsSync(taskPath)) return null;
+ return JSON.parse(fs.readFileSync(taskPath, 'utf-8'));
+}
+
+function loadSubtasks(feature: string): Subtask[] {
+ const featureDir = path.join(TASKS_DIR, feature);
+ if (!fs.existsSync(featureDir)) return [];
+
+ const files = fs.readdirSync(featureDir)
+ .filter((f: string) => f.match(/^subtask_\d{2}\.json$/))
+ .sort();
+
+ return files.map((f: string) => JSON.parse(fs.readFileSync(path.join(featureDir, f), 'utf-8')));
+}
+
+function saveSubtask(feature: string, subtask: Subtask): void {
+ const subtaskPath = path.join(TASKS_DIR, feature, `subtask_${subtask.seq}.json`);
+ fs.writeFileSync(subtaskPath, JSON.stringify(subtask, null, 2));
+}
+
+function saveTask(feature: string, task: Task): void {
+ const taskPath = path.join(TASKS_DIR, feature, 'task.json');
+ fs.writeFileSync(taskPath, JSON.stringify(task, null, 2));
+}
+
+// Commands
+function cmdStatus(feature?: string): void {
+ const features = feature ? [feature] : getFeatureDirs();
+
+ if (features.length === 0) {
+ console.log('No active features found.');
+ return;
+ }
+
+ for (const f of features) {
+ const task = loadTask(f);
+ const subtasks = loadSubtasks(f);
+
+ if (!task) {
+ console.log(`\n[${f}] - No task.json found`);
+ continue;
+ }
+
+ const counts = {
+ pending: subtasks.filter(s => s.status === 'pending').length,
+ in_progress: subtasks.filter(s => s.status === 'in_progress').length,
+ completed: subtasks.filter(s => s.status === 'completed').length,
+ blocked: subtasks.filter(s => s.status === 'blocked').length,
+ };
+
+ const progress = subtasks.length > 0
+ ? Math.round((counts.completed / subtasks.length) * 100)
+ : 0;
+
+ console.log(`\n[${f}] ${task.name}`);
+ console.log(` Status: ${task.status} | Progress: ${progress}% (${counts.completed}/${subtasks.length})`);
+ console.log(` Pending: ${counts.pending} | In Progress: ${counts.in_progress} | Completed: ${counts.completed} | Blocked: ${counts.blocked}`);
+ }
+}
+
+function cmdNext(feature?: string): void {
+ const features = feature ? [feature] : getFeatureDirs();
+
+ console.log('\n=== Ready Tasks (deps satisfied) ===\n');
+
+ for (const f of features) {
+ const subtasks = loadSubtasks(f);
+ const completedSeqs = new Set(subtasks.filter(s => s.status === 'completed').map(s => s.seq));
+
+ const ready = subtasks.filter(s => {
+ if (s.status !== 'pending') return false;
+ return s.depends_on.every(dep => completedSeqs.has(dep));
+ });
+
+ if (ready.length > 0) {
+ console.log(`[${f}]`);
+ for (const s of ready) {
+ const parallel = s.parallel ? '[parallel]' : '[sequential]';
+ console.log(` ${s.seq} - ${s.title} ${parallel}`);
+ }
+ console.log();
+ }
+ }
+}
+
+function cmdParallel(feature?: string): void {
+ const features = feature ? [feature] : getFeatureDirs();
+
+ console.log('\n=== Parallelizable Tasks Ready Now ===\n');
+
+ for (const f of features) {
+ const subtasks = loadSubtasks(f);
+ const completedSeqs = new Set(subtasks.filter(s => s.status === 'completed').map(s => s.seq));
+
+ const parallel = subtasks.filter(s => {
+ if (s.status !== 'pending') return false;
+ if (!s.parallel) return false;
+ return s.depends_on.every(dep => completedSeqs.has(dep));
+ });
+
+ if (parallel.length > 0) {
+ console.log(`[${f}] - ${parallel.length} parallel tasks:`);
+ for (const s of parallel) {
+ console.log(` ${s.seq} - ${s.title}`);
+ }
+ console.log();
+ }
+ }
+}
+
+function cmdDeps(feature: string, seq: string): void {
+ const subtasks = loadSubtasks(feature);
+ const target = subtasks.find(s => s.seq === seq);
+
+ if (!target) {
+ console.log(`Task ${seq} not found in ${feature}`);
+ return;
+ }
+
+ console.log(`\n=== Dependency Tree: ${feature}/${seq} ===\n`);
+ console.log(`${seq} - ${target.title} [${target.status}]`);
+
+ if (target.depends_on.length === 0) {
+ console.log(' βββ (no dependencies)');
+ return;
+ }
+
+ const printDeps = (seqs: string[], indent: string = ' '): void => {
+ for (let i = 0; i < seqs.length; i++) {
+ const depSeq = seqs[i];
+ const dep = subtasks.find(s => s.seq === depSeq);
+ const isLast = i === seqs.length - 1;
+ const branch = isLast ? 'βββ' : 'βββ';
+
+ if (dep) {
+ const statusIcon = dep.status === 'completed' ? 'β' : dep.status === 'in_progress' ? '~' : 'β';
+ console.log(`${indent}${branch} ${statusIcon} ${depSeq} - ${dep.title} [${dep.status}]`);
+ if (dep.depends_on.length > 0) {
+ const newIndent = indent + (isLast ? ' ' : 'β ');
+ printDeps(dep.depends_on, newIndent);
+ }
+ } else {
+ console.log(`${indent}${branch} ? ${depSeq} - NOT FOUND`);
+ }
+ }
+ };
+
+ printDeps(target.depends_on);
+}
+
+function cmdBlocked(feature?: string): void {
+ const features = feature ? [feature] : getFeatureDirs();
+
+ console.log('\n=== Blocked Tasks ===\n');
+
+ for (const f of features) {
+ const subtasks = loadSubtasks(f);
+ const completedSeqs = new Set(subtasks.filter(s => s.status === 'completed').map(s => s.seq));
+
+ const blocked = subtasks.filter(s => {
+ if (s.status === 'blocked') return true;
+ if (s.status !== 'pending') return false;
+ return !s.depends_on.every(dep => completedSeqs.has(dep));
+ });
+
+ if (blocked.length > 0) {
+ console.log(`[${f}]`);
+ for (const s of blocked) {
+ const waitingFor = s.depends_on.filter(dep => !completedSeqs.has(dep));
+ const reason = s.status === 'blocked'
+ ? 'explicitly blocked'
+ : `waiting: ${waitingFor.join(', ')}`;
+ console.log(` ${s.seq} - ${s.title} (${reason})`);
+ }
+ console.log();
+ }
+ }
+}
+
+function cmdComplete(feature: string, seq: string, summary: string): void {
+ if (summary.length > 200) {
+ console.log('Error: Summary must be max 200 characters');
+ process.exit(1);
+ }
+
+ const subtasks = loadSubtasks(feature);
+ const subtask = subtasks.find(s => s.seq === seq);
+
+ if (!subtask) {
+ console.log(`Task ${seq} not found in ${feature}`);
+ process.exit(1);
+ }
+
+ subtask.status = 'completed';
+ subtask.completed_at = new Date().toISOString();
+ subtask.completion_summary = summary;
+
+ saveSubtask(feature, subtask);
+
+ // Update task.json counts
+ const task = loadTask(feature);
+ if (task) {
+ const newSubtasks = loadSubtasks(feature);
+ task.completed_count = newSubtasks.filter(s => s.status === 'completed').length;
+ saveTask(feature, task);
+ }
+
+ console.log(`\nβ Marked ${feature}/${seq} as completed`);
+ console.log(` Summary: ${summary}`);
+
+ if (task) {
+ console.log(` Progress: ${task.completed_count}/${task.subtask_count}`);
+ }
+}
+
+function cmdValidate(feature?: string): void {
+ const features = feature ? [feature] : getFeatureDirs();
+ let hasErrors = false;
+
+ const validTaskStatuses = new Set(['active', 'completed', 'blocked', 'archived']);
+ const validSubtaskStatuses = new Set(['pending', 'in_progress', 'completed', 'blocked']);
+
+ const requiredTaskFields = [
+ 'id',
+ 'name',
+ 'status',
+ 'objective',
+ 'context_files',
+ 'exit_criteria',
+ 'subtask_count',
+ 'completed_count',
+ 'created_at',
+ 'completed_at',
+ ];
+
+ const requiredSubtaskFields = [
+ 'id',
+ 'seq',
+ 'title',
+ 'status',
+ 'depends_on',
+ 'parallel',
+ 'context_files',
+ 'acceptance_criteria',
+ 'deliverables',
+ 'agent_id',
+ 'started_at',
+ 'completed_at',
+ 'completion_summary',
+ ];
+
+ const hasField = (obj: any, field: string): boolean => Object.prototype.hasOwnProperty.call(obj, field);
+ const isStringArray = (value: any): boolean => Array.isArray(value) && value.every(v => typeof v === 'string');
+
+ console.log('\n=== Validation Results ===\n');
+
+ for (const f of features) {
+ const errors: string[] = [];
+
+ // Check task.json exists
+ const task = loadTask(f);
+ if (!task) {
+ errors.push('Missing task.json');
+ }
+
+ // Load and validate subtasks
+ const subtasks = loadSubtasks(f);
+ const seqCounts = new Map();
+ for (const s of subtasks) {
+ const seq = typeof s.seq === 'string' ? s.seq : '';
+ seqCounts.set(seq, (seqCounts.get(seq) || 0) + 1);
+ }
+ const seqs = new Set(subtasks.map(s => s.seq));
+
+ if (task) {
+ // Required fields in task.json
+ for (const field of requiredTaskFields) {
+ if (!hasField(task, field)) {
+ errors.push(`task.json: missing required field '${field}'`);
+ }
+ }
+
+ // Task ID should match feature slug
+ if (task.id !== f) {
+ errors.push(`task.json id ('${task.id}') should match feature slug ('${f}')`);
+ }
+
+ // Task status should be valid
+ if (!validTaskStatuses.has(task.status)) {
+ errors.push(`task.json: invalid status '${task.status}'`);
+ }
+
+ // Basic type checks for key task fields
+ if (!isStringArray(task.context_files)) {
+ errors.push('task.json: context_files must be string[]');
+ }
+ if (hasField(task, 'reference_files') && task.reference_files !== undefined && !isStringArray(task.reference_files)) {
+ errors.push('task.json: reference_files must be string[] when present');
+ }
+ if (!isStringArray(task.exit_criteria)) {
+ errors.push('task.json: exit_criteria must be string[]');
+ }
+ if (typeof task.subtask_count !== 'number') {
+ errors.push('task.json: subtask_count must be number');
+ }
+ if (typeof task.completed_count !== 'number') {
+ errors.push('task.json: completed_count must be number');
+ }
+ }
+
+ for (const s of subtasks) {
+ // Required fields in subtask files
+ for (const field of requiredSubtaskFields) {
+ if (!hasField(s, field)) {
+ errors.push(`${s.seq || '??'}: missing required field '${field}'`);
+ }
+ }
+
+ // Sequence format and uniqueness
+ if (!/^\d{2}$/.test(s.seq)) {
+ errors.push(`${s.seq}: sequence must be 2 digits (e.g., 01, 02)`);
+ }
+ if ((seqCounts.get(s.seq) || 0) > 1) {
+ errors.push(`${s.seq}: duplicate sequence number`);
+ }
+
+ // Check ID format
+ if (!s.id.startsWith(f)) {
+ errors.push(`${s.seq}: ID should start with feature name`);
+ }
+
+ // Status should be valid
+ if (!validSubtaskStatuses.has(s.status)) {
+ errors.push(`${s.seq}: invalid status '${s.status}'`);
+ }
+
+ // Type checks
+ if (!isStringArray(s.depends_on)) {
+ errors.push(`${s.seq}: depends_on must be string[]`);
+ }
+ if (typeof s.parallel !== 'boolean') {
+ errors.push(`${s.seq}: parallel must be boolean`);
+ }
+ if (!isStringArray(s.context_files)) {
+ errors.push(`${s.seq}: context_files must be string[]`);
+ }
+ if (hasField(s, 'reference_files') && s.reference_files !== undefined && !isStringArray(s.reference_files)) {
+ errors.push(`${s.seq}: reference_files must be string[] when present`);
+ }
+ if (!isStringArray(s.acceptance_criteria)) {
+ errors.push(`${s.seq}: acceptance_criteria must be string[]`);
+ } else if (s.acceptance_criteria.length === 0) {
+ errors.push(`${s.seq}: No acceptance criteria defined`);
+ }
+ if (!isStringArray(s.deliverables)) {
+ errors.push(`${s.seq}: deliverables must be string[]`);
+ } else if (s.deliverables.length === 0) {
+ errors.push(`${s.seq}: No deliverables defined`);
+ }
+
+ // Self dependency is invalid
+ if (Array.isArray(s.depends_on) && s.depends_on.includes(s.seq)) {
+ errors.push(`${s.seq}: task cannot depend on itself`);
+ }
+
+ // Check for missing dependencies
+ for (const dep of (Array.isArray(s.depends_on) ? s.depends_on : [])) {
+ if (!seqs.has(dep)) {
+ errors.push(`${s.seq}: depends on non-existent task ${dep}`);
+ }
+ }
+
+ // Check for circular dependencies
+ const visited = new Set();
+ const checkCircular = (seq: string, path: string[]): boolean => {
+ if (path.includes(seq)) {
+ errors.push(`${s.seq}: circular dependency detected: ${[...path, seq].join(' -> ')}`);
+ return true;
+ }
+ if (visited.has(seq)) return false;
+ visited.add(seq);
+
+ const task = subtasks.find(t => t.seq === seq);
+ if (task) {
+ for (const dep of task.depends_on) {
+ if (checkCircular(dep, [...path, seq])) return true;
+ }
+ }
+ return false;
+ };
+ checkCircular(s.seq, []);
+ }
+
+ // Check counts match
+ if (task && task.subtask_count !== subtasks.length) {
+ errors.push(`task.json subtask_count (${task.subtask_count}) doesn't match actual count (${subtasks.length})`);
+ }
+
+ // Print results
+ console.log(`[${f}]`);
+ if (errors.length === 0) {
+ console.log(' β All checks passed');
+ } else {
+ for (const e of errors) {
+ console.log(` β ERROR: ${e}`);
+ hasErrors = true;
+ }
+ }
+ console.log();
+ }
+
+ process.exit(hasErrors ? 1 : 0);
+}
+
+// Main
+const [,, command, ...args] = process.argv;
+
+switch (command) {
+ case 'status':
+ cmdStatus(args[0]);
+ break;
+ case 'next':
+ cmdNext(args[0]);
+ break;
+ case 'parallel':
+ cmdParallel(args[0]);
+ break;
+ case 'deps':
+ if (args.length < 2) {
+ console.log('Usage: deps ');
+ process.exit(1);
+ }
+ cmdDeps(args[0], args[1]);
+ break;
+ case 'blocked':
+ cmdBlocked(args[0]);
+ break;
+ case 'complete':
+ if (args.length < 3) {
+ console.log('Usage: complete "summary"');
+ process.exit(1);
+ }
+ cmdComplete(args[0], args[1], args.slice(2).join(' '));
+ break;
+ case 'validate':
+ cmdValidate(args[0]);
+ break;
+ default:
+ console.log(`
+Task Management CLI
+
+Usage: bunx --bun ts-node task-cli.ts [feature] [args...]
+
+Task files are stored in: .tmp/tasks/{feature-slug}/
+
+Commands:
+ status [feature] Show task status summary
+ next [feature] Show next eligible tasks (deps satisfied)
+ parallel [feature] Show parallelizable tasks ready to run
+ deps Show dependency tree for a task
+ blocked [feature] Show blocked tasks and why
+ complete "summary" Mark task completed with summary
+ validate [feature] Validate JSON files and dependencies
+
+Examples:
+ bunx --bun ts-node task-cli.ts status
+ bunx --bun ts-node task-cli.ts next my-feature
+ bunx --bun ts-node task-cli.ts complete my-feature 02 "Implemented auth module"
+`);
+}
diff --git a/.opencode/tool/env/index.ts b/.opencode/tool/env/index.ts
new file mode 100644
index 0000000..8ff2ac9
--- /dev/null
+++ b/.opencode/tool/env/index.ts
@@ -0,0 +1,168 @@
+import { readFile } from "fs/promises"
+import { resolve } from "path"
+
+/**
+ * Configuration for environment variable loading
+ */
+export interface EnvLoaderConfig {
+ /** Custom paths to search for .env files (relative to current working directory) */
+ searchPaths?: string[]
+ /** Whether to log when environment variables are loaded */
+ verbose?: boolean
+ /** Whether to override existing environment variables */
+ override?: boolean
+}
+
+/**
+ * Default search paths for .env files
+ */
+const DEFAULT_ENV_PATHS = [
+ './.env',
+ '../.env',
+ '../../.env',
+ '../plugin/.env',
+ '../../../.env'
+]
+
+/**
+ * Load environment variables from .env files
+ * Searches multiple common locations for .env files and loads them into process.env
+ *
+ * @param config Configuration options
+ * @returns Object containing loaded environment variables
+ */
+export async function loadEnvVariables(config: EnvLoaderConfig = {}): Promise> {
+ const {
+ searchPaths = DEFAULT_ENV_PATHS,
+ verbose = false,
+ override = false
+ } = config
+
+ const loadedVars: Record = {}
+
+ for (const envPath of searchPaths) {
+ try {
+ const fullPath = resolve(envPath)
+ const content = await readFile(fullPath, 'utf8')
+
+ if (verbose) {
+ console.log(`Checking .env file: ${envPath}`)
+ }
+
+ // Parse .env file content
+ const lines = content.split('\n')
+ for (const line of lines) {
+ const trimmed = line.trim()
+ if (trimmed && !trimmed.startsWith('#') && trimmed.includes('=')) {
+ const [key, ...valueParts] = trimmed.split('=')
+ const value = valueParts.join('=').trim()
+
+ // Remove quotes if present
+ const cleanValue = value.replace(/^["']|["']$/g, '')
+
+ if (key && cleanValue && (override || !process.env[key])) {
+ process.env[key] = cleanValue
+ loadedVars[key] = cleanValue
+
+ if (verbose) {
+ console.log(`Loaded ${key} from ${envPath}`)
+ }
+ }
+ }
+ }
+ } catch (error) {
+ // File doesn't exist or can't be read, continue to next
+ if (verbose) {
+ console.log(`Could not read ${envPath}: ${error.message}`)
+ }
+ }
+ }
+
+ return loadedVars
+}
+
+/**
+ * Get a specific environment variable with automatic .env file loading
+ *
+ * @param varName Name of the environment variable
+ * @param config Configuration options
+ * @returns The environment variable value or null if not found
+ */
+export async function getEnvVariable(varName: string, config: EnvLoaderConfig = {}): Promise {
+ // First check if it's already in the environment
+ let value = process.env[varName]
+
+ if (!value) {
+ // Try to load from .env files
+ const loadedVars = await loadEnvVariables(config)
+ value = loadedVars[varName] || process.env[varName]
+ }
+
+ return value || null
+}
+
+/**
+ * Get a required environment variable with automatic .env file loading
+ * Throws an error if the variable is not found
+ *
+ * @param varName Name of the environment variable
+ * @param config Configuration options
+ * @returns The environment variable value
+ * @throws Error if the variable is not found
+ */
+export async function getRequiredEnvVariable(varName: string, config: EnvLoaderConfig = {}): Promise {
+ const value = await getEnvVariable(varName, config)
+
+ if (!value) {
+ const searchPaths = config.searchPaths || DEFAULT_ENV_PATHS
+ throw new Error(`${varName} not found. Please set it in your environment or .env file.
+
+To fix this:
+1. Add to .env file: ${varName}=your_value_here
+2. Or export it: export ${varName}=your_value_here
+
+Current working directory: ${process.cwd()}
+Searched paths: ${searchPaths.join(', ')}
+Environment variables available: ${Object.keys(process.env).filter(k => k.includes(varName.split('_')[0])).join(', ') || 'none matching'}`)
+ }
+
+ return value
+}
+
+/**
+ * Load multiple required environment variables at once
+ *
+ * @param varNames Array of environment variable names
+ * @param config Configuration options
+ * @returns Object with variable names as keys and values as values
+ * @throws Error if any variable is not found
+ */
+export async function getRequiredEnvVariables(varNames: string[], config: EnvLoaderConfig = {}): Promise> {
+ const result: Record = {}
+
+ // Load all .env files first
+ await loadEnvVariables(config)
+
+ // Check each required variable
+ for (const varName of varNames) {
+ const value = process.env[varName]
+ if (!value) {
+ throw new Error(`Required environment variable ${varName} not found. Please set it in your environment or .env file.`)
+ }
+ result[varName] = value
+ }
+
+ return result
+}
+
+/**
+ * Utility function specifically for API keys
+ *
+ * @param apiKeyName Name of the API key environment variable
+ * @param config Configuration options
+ * @returns The API key value
+ * @throws Error if the API key is not found
+ */
+export async function getApiKey(apiKeyName: string, config: EnvLoaderConfig = {}): Promise {
+ return getRequiredEnvVariable(apiKeyName, config)
+}
\ No newline at end of file
+
+
+
+Item 1
+ Item 2
+
+
+
+
+Item 1
+ Item 2
+
+
+```
+
+### Grid (Preferred for 2D layouts)
+
+```html
+
+Centered content
+
+
+
+
+Card 1
+ Card 2
+ Card 3
+
+
+ Content
+
+```
+
+### Container Patterns
+
+```html
+
+
+ Content
+
+
+
+
+ Content
+
+Main Heading
+Section Heading
+Subsection
+Minor Heading
+ + +Body text
+Secondary text
+Caption text
+``` + +### Font Loading + +**Always use Google Fonts**: + +```html + + + +``` + +**Apply in CSS**: + +```css +body { + font-family: 'Inter', sans-serif !important; +} +``` + +### Readability + +- **Line length**: 60-80 characters optimal +- **Line height**: 1.5-1.75 for body text +- **Font size**: Minimum 16px for body text +- **Contrast**: 4.5:1 minimum for normal text + +--- + +## Component Styling Patterns + +### Buttons + +```html + + + + + + + + +``` + +### Cards + +```html + +
+
+
+
+Card Title
+Card content
+
+
+```
+
+### Forms
+
+```html
+
+Interactive Card
+Hover for effect
+
+
+
+
+
+
+
+
+
+
+```
+
+---
+
+## Accessibility Standards
+
+### ARIA Labels
+
+```html
+
+
+
+
+
+```
+
+### Semantic HTML
+
+```html
+
+...
+
+...
+```
+
+### Focus States
+
+```css
+/* Always provide visible focus states */
+button:focus-visible {
+ outline: 2px solid var(--ring);
+ outline-offset: 2px;
+}
+
+/* Tailwind utility */
+
+```
+
+---
+
+## Performance Optimization
+
+### CSS Loading
+
+```html
+
+
+
+
+
+
+```
+
+### Image Optimization
+
+```html
+
+
+```
+
+### Critical CSS
+
+```html
+
+
+
+
+
+```
+
+---
+
+## Best Practices
+
+### Do's β
+
+- Use Tailwind utility classes for rapid development
+- Load Tailwind via script tag for JIT compilation
+- Use Flowbite as default component library
+- Ensure all designs are mobile-first responsive
+- Test at multiple breakpoints
+- Use semantic HTML elements
+- Provide ARIA labels for interactive elements
+- Use CSS custom properties for theming
+- Apply `!important` for framework overrides
+- Ensure proper color contrast (WCAG AA)
+
+### Don'ts β
+
+- Don't use Bootstrap blue without explicit request
+- Don't load Tailwind as a stylesheet
+- Don't skip responsive design
+- Don't use div soup (use semantic HTML)
+- Don't forget focus states
+- Don't hardcode colors (use theme variables)
+- Don't skip accessibility testing
+- Don't use tiny touch targets (<44px)
+- Don't mix color formats
+- Don't over-use `!important`
+
+---
+
+## Framework Alternatives
+
+If user requests a different framework:
+
+**Bootstrap**:
+```html
+
+
+```
+
+**Bulma**:
+```html
+
+```
+
+**Foundation**:
+```html
+
+
+```
+
+---
+
+## References
+
+- [Tailwind CSS Documentation](https://tailwindcss.com/docs)
+- [Flowbite Components](https://flowbite.com/docs/getting-started/introduction/)
+- [WCAG Guidelines](https://www.w3.org/WAI/WCAG21/quickref/)
+- [MDN Web Accessibility](https://developer.mozilla.org/en-US/docs/Web/Accessibility)
diff --git a/.opencode/env.example b/.opencode/env.example
new file mode 100644
index 0000000..ace3b22
--- /dev/null
+++ b/.opencode/env.example
@@ -0,0 +1,28 @@
+# Telegram Bot Configuration
+# Copy this file to .env and fill in your actual values
+
+# Your Telegram bot token (get from @BotFather)
+TELEGRAM_BOT_TOKEN=your_bot_token_here
+
+# Your chat ID (get by messaging your bot and checking the API)
+TELEGRAM_CHAT_ID=your_chat_id_here
+
+# Your bot username (optional, defaults to @OpenCode)
+TELEGRAM_BOT_USERNAME=@YourBotUsername
+
+# Idle timeout in milliseconds (default: 5 minutes = 300000ms)
+TELEGRAM_IDLE_TIMEOUT=300000
+
+# Check interval in milliseconds (default: 30 seconds = 30000ms)
+TELEGRAM_CHECK_INTERVAL=30000
+
+# Enable/disable the plugin (true/false)
+TELEGRAM_ENABLED=true
+
+# Gemini API Configuration
+# Get your API key from https://makersuite.google.com/app/apikey
+GEMINI_API_KEY=your_gemini_api_key_here
+
+# MiniMax API Configuration
+# Get your API key from https://platform.minimax.io
+MINIMAX_API_KEY=your_minimax_api_key_here
diff --git a/.opencode/skills/context7/README.md b/.opencode/skills/context7/README.md
new file mode 100644
index 0000000..bd53d61
--- /dev/null
+++ b/.opencode/skills/context7/README.md
@@ -0,0 +1,102 @@
+# Context7 Skill
+
+## Purpose
+
+Fetches **live, version-specific documentation** for external libraries and frameworks using the Context7 API. Ensures you always get current API patterns instead of potentially outdated training data.
+
+**Golden Rule**: Always fetch live docs for external librariesβtraining data may be outdated.
+
+## Quick Start
+
+### Recommended: Use ExternalScout Subagent
+
+The **ExternalScout** subagent is the recommended way to fetch external documentation. It handles:
+- Library detection
+- Query optimization
+- Documentation filtering and sorting
+- Formatted results with code examples
+
+**Invocation**:
+```
+Use ExternalScout to fetch documentation for [Library Name]: [your specific question]
+```
+
+**Example**:
+```
+Use ExternalScout to fetch documentation for Drizzle ORM: How do I set up modular schemas with PostgreSQL?
+```
+
+### Alternative: Direct Skill Usage
+
+You can also invoke the Context7 skill directly via bash:
+
+```bash
+# Step 1: Search for library
+curl -s "https://context7.com/api/v2/libs/search?libraryName=LIBRARY&query=TOPIC" | jq '.results[0]'
+
+# Step 2: Fetch documentation
+curl -s "https://context7.com/api/v2/context?libraryId=LIBRARY_ID&query=OPTIMIZED_QUERY&type=txt"
+```
+
+See `SKILL.md` for detailed API documentation.
+
+## Supported Libraries
+
+See `library-registry.md` for the complete list of supported libraries including:
+- **Database & ORM**: Drizzle, Prisma
+- **Authentication**: Better Auth, NextAuth.js, Clerk
+- **Frontend**: Next.js, React, TanStack Query/Router/Start
+- **Infrastructure**: Cloudflare Workers, AWS Lambda, Vercel
+- **UI**: Shadcn/ui, Radix UI, Tailwind CSS
+- **State**: Zustand, Jotai
+- **Validation**: Zod, React Hook Form
+- **Testing**: Vitest, Playwright
+
+## Workflow
+
+```
+User Query
+ β
+ContextScout (searches internal context)
+ β
+No internal context found
+ β
+ContextScout recommends ExternalScout
+ β
+ExternalScout invoked
+ ββ Reads library-registry.md
+ ββ Detects library
+ ββ Loads query patterns
+ ββ Fetches from Context7 API
+ ββ Filters & sorts results
+ ββ Returns formatted documentation
+ β
+User receives current, actionable docs
+```
+
+## Files
+
+- **`SKILL.md`** - Context7 API documentation and usage
+- **`library-registry.md`** - Supported libraries, aliases, and query patterns
+- **`README.md`** - This file (overview and quick start)
+
+## Adding New Libraries
+
+To add a new library to the registry:
+
+1. Edit `library-registry.md`
+2. Add entry under appropriate category:
+ ```markdown
+ #### Library Name
+ - **Aliases**: `alias1`, `alias2`, `package-name`
+ - **Docs**: https://example.com/docs
+ - **Context7**: `use context7 for library-name`
+ - **Common topics**: topic1, topic2, topic3
+ ```
+3. (Optional) Add query optimization patterns
+4. ExternalScout will automatically detect the new library
+
+## Related
+
+- **ExternalScout**: `.opencode/agent/subagents/core/externalscout.md`
+- **ContextScout**: `.opencode/agent/subagents/core/contextscout.md`
diff --git a/.opencode/skills/context7/SKILL.md b/.opencode/skills/context7/SKILL.md
new file mode 100644
index 0000000..76160b2
--- /dev/null
+++ b/.opencode/skills/context7/SKILL.md
@@ -0,0 +1,85 @@
+---
+name: context7
+description: Retrieve up-to-date documentation for software libraries, frameworks, and components via the Context7 API. This skill should be used when looking up documentation for any programming library or framework, finding code examples for specific APIs or features, verifying correct usage of library functions, or obtaining current information about library APIs that may have changed since training.
+---
+
+# Context7
+
+## Overview
+
+This skill enables retrieval of current documentation for software libraries and components by querying the Context7 API via curl. Use it instead of relying on potentially outdated training data.
+
+## Workflow
+
+### Step 1: Search for the Library
+
+To find the Context7 library ID, query the search endpoint:
+
+```bash
+curl -s "https://context7.com/api/v2/libs/search?libraryName=LIBRARY_NAME&query=TOPIC" | jq '.results[0]'
+```
+
+**Parameters:**
+- `libraryName` (required): The library name to search for (e.g., "react", "nextjs", "fastapi", "axios")
+- `query` (required): A description of the topic for relevance ranking
+
+**Response fields:**
+- `id`: Library identifier for the context endpoint (e.g., `/websites/react_dev_reference`)
+- `title`: Human-readable library name
+- `description`: Brief description of the library
+- `totalSnippets`: Number of documentation snippets available
+
+### Step 2: Fetch Documentation
+
+To retrieve documentation, use the library ID from step 1:
+
+```bash
+curl -s "https://context7.com/api/v2/context?libraryId=LIBRARY_ID&query=TOPIC&type=txt"
+```
+
+**Parameters:**
+- `libraryId` (required): The library ID from search results
+- `query` (required): The specific topic to retrieve documentation for
+- `type` (optional): Response format - `json` (default) or `txt` (plain text, more readable)
+
+## Examples
+
+### React hooks documentation
+
+```bash
+# Find React library ID
+curl -s "https://context7.com/api/v2/libs/search?libraryName=react&query=hooks" | jq '.results[0].id'
+# Returns: "/websites/react_dev_reference"
+
+# Fetch useState documentation
+curl -s "https://context7.com/api/v2/context?libraryId=/websites/react_dev_reference&query=useState&type=txt"
+```
+
+### Next.js routing documentation
+
+```bash
+# Find Next.js library ID
+curl -s "https://context7.com/api/v2/libs/search?libraryName=nextjs&query=routing" | jq '.results[0].id'
+
+# Fetch app router documentation
+curl -s "https://context7.com/api/v2/context?libraryId=/vercel/next.js&query=app+router&type=txt"
+```
+
+### FastAPI dependency injection
+
+```bash
+# Find FastAPI library ID
+curl -s "https://context7.com/api/v2/libs/search?libraryName=fastapi&query=dependencies" | jq '.results[0].id'
+
+# Fetch dependency injection documentation
+curl -s "https://context7.com/api/v2/context?libraryId=/fastapi/fastapi&query=dependency+injection&type=txt"
+```
+
+## Tips
+
+- Use `type=txt` for more readable output
+- Use `jq` to filter and format JSON responses
+- Be specific with the `query` parameter to improve relevance ranking
+- If the first search result is not correct, check additional results in the array
+- URL-encode query parameters containing spaces (use `+` or `%20`)
+- No API key is required for basic usage (rate-limited)
\ No newline at end of file
diff --git a/.opencode/skills/context7/library-registry.md b/.opencode/skills/context7/library-registry.md
new file mode 100644
index 0000000..4c2f5d4
--- /dev/null
+++ b/.opencode/skills/context7/library-registry.md
@@ -0,0 +1,290 @@
+# External Library Registry
+
+## Purpose
+
+This file lists external libraries/frameworks that should use **ExternalScout** (via Context7) for live documentation instead of relying on potentially outdated training data.
+
+## When to Use This
+
+**ContextScout** checks this list when:
+1. User asks about a library/framework
+2. No internal context exists in `.opencode/context/development/frameworks/`
+3. Query matches a library name below
+
+**Action**: Recommend **ExternalScout** subagent
+
+---
+
+## Supported Libraries
+
+### Database & ORM
+
+#### Drizzle ORM
+- **Aliases**: `drizzle`, `drizzle-orm`, `drizzle orm`
+- **Docs**: https://orm.drizzle.team/
+- **Context7**: `use context7 for drizzle`
+- **Common topics**: schema organization, migrations, relational queries, transactions, TypeScript types
+
+#### Prisma
+- **Aliases**: `prisma`
+- **Docs**: https://www.prisma.io/docs
+- **Context7**: `use context7 for prisma`
+- **Common topics**: schema, migrations, client, relations, TypeScript
+
+---
+
+### Authentication
+
+#### Better Auth
+- **Aliases**: `better-auth`, `better auth`, `betterauth`
+- **Docs**: https://www.better-auth.com/docs
+- **Context7**: `use context7 for better-auth`
+- **Common topics**: Next.js integration, Drizzle adapter, social providers, session management, 2FA
+
+#### NextAuth.js
+- **Aliases**: `nextauth`, `next-auth`, `nextauth.js`
+- **Docs**: https://next-auth.js.org/
+- **Context7**: `use context7 for nextauth`
+- **Common topics**: providers, callbacks, sessions, JWT
+
+#### Clerk
+- **Aliases**: `clerk`
+- **Docs**: https://clerk.com/docs
+- **Context7**: `use context7 for clerk`
+- **Common topics**: authentication, user management, organizations
+
+---
+
+### Frontend Frameworks
+
+#### Next.js
+- **Aliases**: `nextjs`, `next.js`, `next`
+- **Docs**: https://nextjs.org/docs
+- **Context7**: `use context7 for nextjs`
+- **Common topics**: App Router, Server Actions, Server Components, routing, middleware, API routes
+
+#### React
+- **Aliases**: `react`, `reactjs`, `react.js`
+- **Docs**: https://react.dev/
+- **Context7**: `use context7 for react`
+- **Common topics**: hooks, components, state, effects, context
+
+#### TanStack Query
+- **Aliases**: `tanstack query`, `react query`, `@tanstack/react-query`
+- **Docs**: https://tanstack.com/query/latest
+- **Context7**: `use context7 for tanstack query`
+- **Common topics**: useQuery, useMutation, prefetching, caching, Server Components
+
+#### TanStack Router
+- **Aliases**: `tanstack router`, `@tanstack/react-router`
+- **Docs**: https://tanstack.com/router/latest
+- **Context7**: `use context7 for tanstack router`
+- **Common topics**: routing, type-safe routes, loaders, navigation
+
+#### TanStack Start
+- **Aliases**: `tanstack start`, `@tanstack/start`
+- **Docs**: https://tanstack.com/start/latest
+- **Context7**: `use context7 for tanstack start`
+- **Common topics**: full-stack setup, server functions, file routing
+
+---
+
+### Infrastructure & Deployment
+
+#### Cloudflare Workers
+- **Aliases**: `cloudflare workers`, `cloudflare`, `workers`, `cf workers`
+- **Docs**: https://developers.cloudflare.com/workers
+- **Context7**: `use context7 for cloudflare workers`
+- **Common topics**: routing, KV storage, Durable Objects, bindings, middleware
+
+#### AWS Lambda
+- **Aliases**: `aws lambda`, `lambda`, `aws Ξ»`
+- **Docs**: https://docs.aws.amazon.com/lambda
+- **Context7**: `use context7 for aws lambda`
+- **Common topics**: handlers, layers, environment variables, triggers, TypeScript
+
+#### Vercel
+- **Aliases**: `vercel`
+- **Docs**: https://vercel.com/docs
+- **Context7**: `use context7 for vercel`
+- **Common topics**: deployment, environment variables, edge functions, serverless
+
+---
+
+### UI Libraries & Styling
+
+#### Shadcn/ui
+- **Aliases**: `shadcn`, `shadcn/ui`, `shadcn-ui`
+- **Docs**: https://ui.shadcn.com/
+- **Context7**: `use context7 for shadcn`
+- **Common topics**: components, installation, theming, customization
+
+#### Radix UI
+- **Aliases**: `radix`, `radix ui`, `radix-ui`, `@radix-ui`
+- **Docs**: https://www.radix-ui.com/
+- **Context7**: `use context7 for radix`
+- **Common topics**: primitives, accessibility, composition
+
+#### Tailwind CSS
+- **Aliases**: `tailwind`, `tailwindcss`, `tailwind css`
+- **Docs**: https://tailwindcss.com/docs
+- **Context7**: `use context7 for tailwind`
+- **Common topics**: configuration, utilities, responsive design, dark mode
+
+---
+
+### State Management
+
+#### Zustand
+- **Aliases**: `zustand`
+- **Docs**: https://zustand-demo.pmnd.rs/
+- **Context7**: `use context7 for zustand`
+- **Common topics**: store creation, selectors, middleware, TypeScript
+
+#### Jotai
+- **Aliases**: `jotai`
+- **Docs**: https://jotai.org/
+- **Context7**: `use context7 for jotai`
+- **Common topics**: atoms, async atoms, utilities
+
+---
+
+### Validation & Forms
+
+#### Zod
+- **Aliases**: `zod`
+- **Docs**: https://zod.dev/
+- **Context7**: `use context7 for zod`
+- **Common topics**: schema validation, TypeScript inference, parsing, refinements
+
+#### React Hook Form
+- **Aliases**: `react hook form`, `react-hook-form`, `rhf`
+- **Docs**: https://react-hook-form.com/
+- **Context7**: `use context7 for react hook form`
+- **Common topics**: register, validation, errors, TypeScript
+
+---
+
+### Testing
+
+#### Vitest
+- **Aliases**: `vitest`
+- **Docs**: https://vitest.dev/
+- **Context7**: `use context7 for vitest`
+- **Common topics**: configuration, testing, mocking, coverage
+
+#### Playwright
+- **Aliases**: `playwright`
+- **Docs**: https://playwright.dev/
+- **Context7**: `use context7 for playwright`
+- **Common topics**: browser automation, testing, selectors, assertions
+
+---
+
+## Detection Patterns
+
+ContextScout and ExternalScout should match queries containing:
+- Library name (case-insensitive)
+- Common variations (e.g., "next.js" vs "nextjs")
+- Package names (e.g., "@tanstack/react-query")
+
+**Examples**:
+- "How do I use **Drizzle** with PostgreSQL?" β Match: Drizzle ORM
+- "Show me **Next.js** App Router setup" β Match: Next.js
+- "**TanStack Query** with Server Components" β Match: TanStack Query
+- "**Better Auth** integration" β Match: Better Auth
+
+---
+
+## Query Optimization Patterns
+
+### Drizzle ORM
+
+| User Intent | Optimized Query |
+|-------------|-----------------|
+| Setup/Installation | `PostgreSQL+setup+configuration+TypeScript+installation` |
+| Modular schemas | `modular+schema+organization+domain+driven+design` |
+| Relations | `relational+queries+one+to+many+joins+with+relations` |
+| Migrations | `drizzle-kit+migrations+generate+push+PostgreSQL` |
+| Transactions | `database+transactions+patterns+TypeScript` |
+| Type safety | `TypeScript+type+inference+schema+types+inferInsert` |
+
+### Better Auth
+
+| User Intent | Optimized Query |
+|-------------|-----------------|
+| Setup | `setup+configuration+Next.js+TypeScript+installation` |
+| Next.js integration | `Next.js+App+Router+integration+setup+configuration` |
+| Drizzle adapter | `Drizzle+adapter+PostgreSQL+schema+generation+configuration` |
+| Social providers | `social+providers+OAuth+GitHub+Google+setup` |
+| Email/password | `email+password+authentication+signup+signin` |
+| Session management | `session+management+cookies+JWT+middleware` |
+
+### Next.js
+
+| User Intent | Optimized Query |
+|-------------|-----------------|
+| App Router | `App+Router+file+conventions+layouts+pages+routing` |
+| Server Actions | `Server+Actions+form+mutations+revalidation+TypeScript` |
+| Server Components | `React+Server+Components+async+data+fetching+patterns` |
+| Dynamic routes | `dynamic+routes+params+TypeScript+generateStaticParams` |
+| Middleware | `middleware+authentication+redirects+headers+cookies` |
+| API routes | `API+routes+route+handlers+TypeScript+POST+GET` |
+
+### TanStack Query
+
+| User Intent | Optimized Query |
+|-------------|-----------------|
+| Setup | `setup+QueryClient+provider+Next.js+TypeScript` |
+| Data fetching | `useQuery+data+fetching+TypeScript+patterns+async` |
+| Mutations | `useMutation+optimistic+updates+invalidation+TypeScript` |
+| Prefetching | `prefetchQuery+Server+Components+hydration+Next.js` |
+| Caching | `cache+configuration+staleTime+gcTime+invalidation` |
+
+### Cloudflare Workers
+
+| User Intent | Optimized Query |
+|-------------|-----------------|
+| Setup | `getting+started+setup+TypeScript+wrangler+configuration` |
+| Routing | `routing+itty-router+hono+request+handling` |
+| KV storage | `KV+storage+key+value+bindings+TypeScript` |
+| Durable Objects | `Durable+Objects+state+WebSockets+coordination` |
+
+### AWS Lambda
+
+| User Intent | Optimized Query |
+|-------------|-----------------|
+| Setup | `getting+started+setup+TypeScript+handler+configuration` |
+| Handlers | `handler+function+event+context+TypeScript+patterns` |
+| Layers | `layers+dependencies+shared+code+deployment` |
+| Environment variables | `environment+variables+secrets+configuration+SSM` |
+
+---
+
+## Adding New Libraries
+
+To add a new library:
+1. Add entry under appropriate category
+2. Include: Name, aliases, docs link, Context7 command, common topics
+3. (Optional) Add query optimization patterns
+4. Update ExternalScout if needed (usually automatic)
+
+**Template**:
+```markdown
+#### Library Name
+- **Aliases**: `alias1`, `alias2`, `package-name`
+- **Docs**: https://example.com/docs
+- **Context7**: `use context7 for library-name`
+- **Common topics**: topic1, topic2, topic3
+```
+
+---
+
+## Usage by ExternalScout
+
+ExternalScout uses this file to:
+1. **Detect** which library the user is asking about
+2. **Load** query optimization patterns for that library
+3. **Build** optimized Context7 queries
+4. **Fetch** live documentation
+5. **Return** filtered, relevant results
diff --git a/.opencode/skills/context7/navigation.md b/.opencode/skills/context7/navigation.md
new file mode 100644
index 0000000..30f848c
--- /dev/null
+++ b/.opencode/skills/context7/navigation.md
@@ -0,0 +1,51 @@
+# Context7 Skill Navigation
+
+**Purpose**: Live documentation fetching for external libraries via Context7 API
+
+---
+
+## Structure
+
+```
+context7/
+βββ navigation.md # This file
+βββ README.md # Quick start and workflow
+βββ SKILL.md # Context7 API documentation
+βββ library-registry.md # Supported libraries and query patterns
+```
+
+---
+
+## Quick Routes
+
+| Task | Path |
+|------|------|
+| **Quick start** | `README.md` |
+| **API reference** | `SKILL.md` |
+| **Supported libraries** | `library-registry.md` (lines 18-181) |
+| **Query patterns** | `library-registry.md` (lines 199-261) |
+| **Add new library** | `library-registry.md` (lines 264-279) |
+| **ExternalScout integration** | `README.md` (lines 9-26) |
+
+---
+
+## By Purpose
+
+**Using Context7**:
+- Quick start β `README.md`
+- API details β `SKILL.md`
+
+**Adding Libraries**:
+- Template β `library-registry.md` (lines 272-279)
+- Supported list β `library-registry.md` (lines 18-181)
+
+**Integration**:
+- ContextScout workflow β `README.md` (lines 54-73)
+- ExternalScout subagent β `.opencode/agent/subagents/core/externalscout.md`
+
+---
+
+## Related
+
+- **ExternalScout**: `.opencode/agent/subagents/core/externalscout.md`
+- **ContextScout**: `.opencode/agent/subagents/core/contextscout.md`
diff --git a/.opencode/skills/task-management/SKILL.md b/.opencode/skills/task-management/SKILL.md
new file mode 100644
index 0000000..8143066
--- /dev/null
+++ b/.opencode/skills/task-management/SKILL.md
@@ -0,0 +1,399 @@
+---
+name: task-management
+description: Task management CLI for tracking and managing feature subtasks with status, dependencies, and validation
+version: 1.0.0
+author: opencode
+type: skill
+category: development
+tags:
+ - tasks
+ - management
+ - tracking
+ - dependencies
+ - cli
+---
+
+# Task Management Skill
+
+> **Purpose**: Track, manage, and validate feature implementations with atomic task breakdowns, dependency resolution, and progress monitoring.
+
+---
+
+## What I Do
+
+I provide a command-line interface for managing task breakdowns created by the TaskManager subagent. I help you:
+
+- **Track progress** - See status of all features and their subtasks
+- **Find next tasks** - Show eligible tasks (dependencies satisfied)
+- **Identify blocked tasks** - See what's blocked and why
+- **Manage completion** - Mark subtasks as complete with summaries
+- **Validate integrity** - Check JSON files and dependency trees
+
+---
+
+## How to Use Me
+
+### Quick Start
+
+```bash
+# Show all task statuses
+bash .opencode/skills/task-management/router.sh status
+
+# Show next eligible tasks
+bash .opencode/skills/task-management/router.sh next
+
+# Show blocked tasks
+bash .opencode/skills/task-management/router.sh blocked
+
+# Mark a task complete
+bash .opencode/skills/task-management/router.sh complete