` and animate the wrapper instead.
+
+**Incorrect (animating SVG directly - no hardware acceleration):**
+
+```tsx
+function LoadingSpinner() {
+ return (
+
+
+ )
+}
+```
+
+**Correct (animating wrapper div - hardware accelerated):**
+
+```tsx
+function LoadingSpinner() {
+ return (
+
+
+
+
+ )
+}
+```
+
+This applies to all CSS transforms and transitions (`transform`, `opacity`, `translate`, `scale`, `rotate`). The wrapper div allows browsers to use GPU acceleration for smoother animations.
diff --git a/.github/skills/vercel-react-best-practices/rules/rendering-conditional-render.md b/.github/skills/vercel-react-best-practices/rules/rendering-conditional-render.md
new file mode 100644
index 0000000..7e866f5
--- /dev/null
+++ b/.github/skills/vercel-react-best-practices/rules/rendering-conditional-render.md
@@ -0,0 +1,40 @@
+---
+title: Use Explicit Conditional Rendering
+impact: LOW
+impactDescription: prevents rendering 0 or NaN
+tags: rendering, conditional, jsx, falsy-values
+---
+
+## Use Explicit Conditional Rendering
+
+Use explicit ternary operators (`? :`) instead of `&&` for conditional rendering when the condition can be `0`, `NaN`, or other falsy values that render.
+
+**Incorrect (renders "0" when count is 0):**
+
+```tsx
+function Badge({ count }: { count: number }) {
+ return (
+
+ {count && {count} }
+
+ )
+}
+
+// When count = 0, renders:
0
+// When count = 5, renders:
5
+```
+
+**Correct (renders nothing when count is 0):**
+
+```tsx
+function Badge({ count }: { count: number }) {
+ return (
+
+ {count > 0 ? {count} : null}
+
+ )
+}
+
+// When count = 0, renders:
+// When count = 5, renders:
5
+```
diff --git a/.github/skills/vercel-react-best-practices/rules/rendering-content-visibility.md b/.github/skills/vercel-react-best-practices/rules/rendering-content-visibility.md
new file mode 100644
index 0000000..aa66563
--- /dev/null
+++ b/.github/skills/vercel-react-best-practices/rules/rendering-content-visibility.md
@@ -0,0 +1,38 @@
+---
+title: CSS content-visibility for Long Lists
+impact: HIGH
+impactDescription: faster initial render
+tags: rendering, css, content-visibility, long-lists
+---
+
+## CSS content-visibility for Long Lists
+
+Apply `content-visibility: auto` to defer off-screen rendering.
+
+**CSS:**
+
+```css
+.message-item {
+ content-visibility: auto;
+ contain-intrinsic-size: 0 80px;
+}
+```
+
+**Example:**
+
+```tsx
+function MessageList({ messages }: { messages: Message[] }) {
+ return (
+
+ {messages.map(msg => (
+
+ ))}
+
+ )
+}
+```
+
+For 1000 messages, browser skips layout/paint for ~990 off-screen items (10× faster initial render).
diff --git a/.github/skills/vercel-react-best-practices/rules/rendering-hoist-jsx.md b/.github/skills/vercel-react-best-practices/rules/rendering-hoist-jsx.md
new file mode 100644
index 0000000..32d2f3f
--- /dev/null
+++ b/.github/skills/vercel-react-best-practices/rules/rendering-hoist-jsx.md
@@ -0,0 +1,46 @@
+---
+title: Hoist Static JSX Elements
+impact: LOW
+impactDescription: avoids re-creation
+tags: rendering, jsx, static, optimization
+---
+
+## Hoist Static JSX Elements
+
+Extract static JSX outside components to avoid re-creation.
+
+**Incorrect (recreates element every render):**
+
+```tsx
+function LoadingSkeleton() {
+ return
+}
+
+function Container() {
+ return (
+
+ {loading &&
+ )
+}
+```
+
+**Correct (reuses same element):**
+
+```tsx
+const loadingSkeleton = (
+
+)
+
+function Container() {
+ return (
+
+ {loading && loadingSkeleton}
+
+ )
+}
+```
+
+This is especially helpful for large and static SVG nodes, which can be expensive to recreate on every render.
+
+**Note:** If your project has [React Compiler](https://react.dev/learn/react-compiler) enabled, the compiler automatically hoists static JSX elements and optimizes component re-renders, making manual hoisting unnecessary.
diff --git a/.github/skills/vercel-react-best-practices/rules/rendering-hydration-no-flicker.md b/.github/skills/vercel-react-best-practices/rules/rendering-hydration-no-flicker.md
new file mode 100644
index 0000000..5cf0e79
--- /dev/null
+++ b/.github/skills/vercel-react-best-practices/rules/rendering-hydration-no-flicker.md
@@ -0,0 +1,82 @@
+---
+title: Prevent Hydration Mismatch Without Flickering
+impact: MEDIUM
+impactDescription: avoids visual flicker and hydration errors
+tags: rendering, ssr, hydration, localStorage, flicker
+---
+
+## Prevent Hydration Mismatch Without Flickering
+
+When rendering content that depends on client-side storage (localStorage, cookies), avoid both SSR breakage and post-hydration flickering by injecting a synchronous script that updates the DOM before React hydrates.
+
+**Incorrect (breaks SSR):**
+
+```tsx
+function ThemeWrapper({ children }: { children: ReactNode }) {
+ // localStorage is not available on server - throws error
+ const theme = localStorage.getItem('theme') || 'light'
+
+ return (
+
+ {children}
+
+ )
+}
+```
+
+Server-side rendering will fail because `localStorage` is undefined.
+
+**Incorrect (visual flickering):**
+
+```tsx
+function ThemeWrapper({ children }: { children: ReactNode }) {
+ const [theme, setTheme] = useState('light')
+
+ useEffect(() => {
+ // Runs after hydration - causes visible flash
+ const stored = localStorage.getItem('theme')
+ if (stored) {
+ setTheme(stored)
+ }
+ }, [])
+
+ return (
+
+ {children}
+
+ )
+}
+```
+
+Component first renders with default value (`light`), then updates after hydration, causing a visible flash of incorrect content.
+
+**Correct (no flicker, no hydration mismatch):**
+
+```tsx
+function ThemeWrapper({ children }: { children: ReactNode }) {
+ return (
+ <>
+
+ {children}
+
+
+
+ )
+}
+```
+
+The inline script executes synchronously before showing the element, ensuring the DOM already has the correct value. No flickering, no hydration mismatch.
+
+This pattern is especially useful for theme toggles, user preferences, authentication states, and any client-only data that should render immediately without flashing default values.
diff --git a/.github/skills/vercel-react-best-practices/rules/rendering-hydration-suppress-warning.md b/.github/skills/vercel-react-best-practices/rules/rendering-hydration-suppress-warning.md
new file mode 100644
index 0000000..24ba251
--- /dev/null
+++ b/.github/skills/vercel-react-best-practices/rules/rendering-hydration-suppress-warning.md
@@ -0,0 +1,30 @@
+---
+title: Suppress Expected Hydration Mismatches
+impact: LOW-MEDIUM
+impactDescription: avoids noisy hydration warnings for known differences
+tags: rendering, hydration, ssr, nextjs
+---
+
+## Suppress Expected Hydration Mismatches
+
+In SSR frameworks (e.g., Next.js), some values are intentionally different on server vs client (random IDs, dates, locale/timezone formatting). For these *expected* mismatches, wrap the dynamic text in an element with `suppressHydrationWarning` to prevent noisy warnings. Do not use this to hide real bugs. Don’t overuse it.
+
+**Incorrect (known mismatch warnings):**
+
+```tsx
+function Timestamp() {
+ return
{new Date().toLocaleString()}
+}
+```
+
+**Correct (suppress expected mismatch only):**
+
+```tsx
+function Timestamp() {
+ return (
+
+ {new Date().toLocaleString()}
+
+ )
+}
+```
diff --git a/.github/skills/vercel-react-best-practices/rules/rendering-svg-precision.md b/.github/skills/vercel-react-best-practices/rules/rendering-svg-precision.md
new file mode 100644
index 0000000..6d77128
--- /dev/null
+++ b/.github/skills/vercel-react-best-practices/rules/rendering-svg-precision.md
@@ -0,0 +1,28 @@
+---
+title: Optimize SVG Precision
+impact: LOW
+impactDescription: reduces file size
+tags: rendering, svg, optimization, svgo
+---
+
+## Optimize SVG Precision
+
+Reduce SVG coordinate precision to decrease file size. The optimal precision depends on the viewBox size, but in general reducing precision should be considered.
+
+**Incorrect (excessive precision):**
+
+```svg
+
+```
+
+**Correct (1 decimal place):**
+
+```svg
+
+```
+
+**Automate with SVGO:**
+
+```bash
+npx svgo --precision=1 --multipass icon.svg
+```
diff --git a/.github/skills/vercel-react-best-practices/rules/rendering-usetransition-loading.md b/.github/skills/vercel-react-best-practices/rules/rendering-usetransition-loading.md
new file mode 100644
index 0000000..0c1b0b9
--- /dev/null
+++ b/.github/skills/vercel-react-best-practices/rules/rendering-usetransition-loading.md
@@ -0,0 +1,75 @@
+---
+title: Use useTransition Over Manual Loading States
+impact: LOW
+impactDescription: reduces re-renders and improves code clarity
+tags: rendering, transitions, useTransition, loading, state
+---
+
+## Use useTransition Over Manual Loading States
+
+Use `useTransition` instead of manual `useState` for loading states. This provides built-in `isPending` state and automatically manages transitions.
+
+**Incorrect (manual loading state):**
+
+```tsx
+function SearchResults() {
+ const [query, setQuery] = useState('')
+ const [results, setResults] = useState([])
+ const [isLoading, setIsLoading] = useState(false)
+
+ const handleSearch = async (value: string) => {
+ setIsLoading(true)
+ setQuery(value)
+ const data = await fetchResults(value)
+ setResults(data)
+ setIsLoading(false)
+ }
+
+ return (
+ <>
+
handleSearch(e.target.value)} />
+ {isLoading &&
}
+
+
+ )
+}
+```
+
+**Correct (useTransition with built-in pending state):**
+
+```tsx
+import { useTransition, useState } from 'react'
+
+function SearchResults() {
+ const [query, setQuery] = useState('')
+ const [results, setResults] = useState([])
+ const [isPending, startTransition] = useTransition()
+
+ const handleSearch = (value: string) => {
+ setQuery(value) // Update input immediately
+
+ startTransition(async () => {
+ // Fetch and update results
+ const data = await fetchResults(value)
+ setResults(data)
+ })
+ }
+
+ return (
+ <>
+
handleSearch(e.target.value)} />
+ {isPending &&
}
+
+
+ )
+}
+```
+
+**Benefits:**
+
+- **Automatic pending state**: No need to manually manage `setIsLoading(true/false)`
+- **Error resilience**: Pending state correctly resets even if the transition throws
+- **Better responsiveness**: Keeps the UI responsive during updates
+- **Interrupt handling**: New transitions automatically cancel pending ones
+
+Reference: [useTransition](https://react.dev/reference/react/useTransition)
diff --git a/.github/skills/vercel-react-best-practices/rules/rerender-defer-reads.md b/.github/skills/vercel-react-best-practices/rules/rerender-defer-reads.md
new file mode 100644
index 0000000..e867c95
--- /dev/null
+++ b/.github/skills/vercel-react-best-practices/rules/rerender-defer-reads.md
@@ -0,0 +1,39 @@
+---
+title: Defer State Reads to Usage Point
+impact: MEDIUM
+impactDescription: avoids unnecessary subscriptions
+tags: rerender, searchParams, localStorage, optimization
+---
+
+## Defer State Reads to Usage Point
+
+Don't subscribe to dynamic state (searchParams, localStorage) if you only read it inside callbacks.
+
+**Incorrect (subscribes to all searchParams changes):**
+
+```tsx
+function ShareButton({ chatId }: { chatId: string }) {
+ const searchParams = useSearchParams()
+
+ const handleShare = () => {
+ const ref = searchParams.get('ref')
+ shareChat(chatId, { ref })
+ }
+
+ return
Share
+}
+```
+
+**Correct (reads on demand, no subscription):**
+
+```tsx
+function ShareButton({ chatId }: { chatId: string }) {
+ const handleShare = () => {
+ const params = new URLSearchParams(window.location.search)
+ const ref = params.get('ref')
+ shareChat(chatId, { ref })
+ }
+
+ return
Share
+}
+```
diff --git a/.github/skills/vercel-react-best-practices/rules/rerender-dependencies.md b/.github/skills/vercel-react-best-practices/rules/rerender-dependencies.md
new file mode 100644
index 0000000..47a4d92
--- /dev/null
+++ b/.github/skills/vercel-react-best-practices/rules/rerender-dependencies.md
@@ -0,0 +1,45 @@
+---
+title: Narrow Effect Dependencies
+impact: LOW
+impactDescription: minimizes effect re-runs
+tags: rerender, useEffect, dependencies, optimization
+---
+
+## Narrow Effect Dependencies
+
+Specify primitive dependencies instead of objects to minimize effect re-runs.
+
+**Incorrect (re-runs on any user field change):**
+
+```tsx
+useEffect(() => {
+ console.log(user.id)
+}, [user])
+```
+
+**Correct (re-runs only when id changes):**
+
+```tsx
+useEffect(() => {
+ console.log(user.id)
+}, [user.id])
+```
+
+**For derived state, compute outside effect:**
+
+```tsx
+// Incorrect: runs on width=767, 766, 765...
+useEffect(() => {
+ if (width < 768) {
+ enableMobileMode()
+ }
+}, [width])
+
+// Correct: runs only on boolean transition
+const isMobile = width < 768
+useEffect(() => {
+ if (isMobile) {
+ enableMobileMode()
+ }
+}, [isMobile])
+```
diff --git a/.github/skills/vercel-react-best-practices/rules/rerender-derived-state-no-effect.md b/.github/skills/vercel-react-best-practices/rules/rerender-derived-state-no-effect.md
new file mode 100644
index 0000000..3d9fe40
--- /dev/null
+++ b/.github/skills/vercel-react-best-practices/rules/rerender-derived-state-no-effect.md
@@ -0,0 +1,40 @@
+---
+title: Calculate Derived State During Rendering
+impact: MEDIUM
+impactDescription: avoids redundant renders and state drift
+tags: rerender, derived-state, useEffect, state
+---
+
+## Calculate Derived State During Rendering
+
+If a value can be computed from current props/state, do not store it in state or update it in an effect. Derive it during render to avoid extra renders and state drift. Do not set state in effects solely in response to prop changes; prefer derived values or keyed resets instead.
+
+**Incorrect (redundant state and effect):**
+
+```tsx
+function Form() {
+ const [firstName, setFirstName] = useState('First')
+ const [lastName, setLastName] = useState('Last')
+ const [fullName, setFullName] = useState('')
+
+ useEffect(() => {
+ setFullName(firstName + ' ' + lastName)
+ }, [firstName, lastName])
+
+ return
{fullName}
+}
+```
+
+**Correct (derive during render):**
+
+```tsx
+function Form() {
+ const [firstName, setFirstName] = useState('First')
+ const [lastName, setLastName] = useState('Last')
+ const fullName = firstName + ' ' + lastName
+
+ return
{fullName}
+}
+```
+
+References: [You Might Not Need an Effect](https://react.dev/learn/you-might-not-need-an-effect)
diff --git a/.github/skills/vercel-react-best-practices/rules/rerender-derived-state.md b/.github/skills/vercel-react-best-practices/rules/rerender-derived-state.md
new file mode 100644
index 0000000..e5c899f
--- /dev/null
+++ b/.github/skills/vercel-react-best-practices/rules/rerender-derived-state.md
@@ -0,0 +1,29 @@
+---
+title: Subscribe to Derived State
+impact: MEDIUM
+impactDescription: reduces re-render frequency
+tags: rerender, derived-state, media-query, optimization
+---
+
+## Subscribe to Derived State
+
+Subscribe to derived boolean state instead of continuous values to reduce re-render frequency.
+
+**Incorrect (re-renders on every pixel change):**
+
+```tsx
+function Sidebar() {
+ const width = useWindowWidth() // updates continuously
+ const isMobile = width < 768
+ return
+}
+```
+
+**Correct (re-renders only when boolean changes):**
+
+```tsx
+function Sidebar() {
+ const isMobile = useMediaQuery('(max-width: 767px)')
+ return
+}
+```
diff --git a/.github/skills/vercel-react-best-practices/rules/rerender-functional-setstate.md b/.github/skills/vercel-react-best-practices/rules/rerender-functional-setstate.md
new file mode 100644
index 0000000..b004ef4
--- /dev/null
+++ b/.github/skills/vercel-react-best-practices/rules/rerender-functional-setstate.md
@@ -0,0 +1,74 @@
+---
+title: Use Functional setState Updates
+impact: MEDIUM
+impactDescription: prevents stale closures and unnecessary callback recreations
+tags: react, hooks, useState, useCallback, callbacks, closures
+---
+
+## Use Functional setState Updates
+
+When updating state based on the current state value, use the functional update form of setState instead of directly referencing the state variable. This prevents stale closures, eliminates unnecessary dependencies, and creates stable callback references.
+
+**Incorrect (requires state as dependency):**
+
+```tsx
+function TodoList() {
+ const [items, setItems] = useState(initialItems)
+
+ // Callback must depend on items, recreated on every items change
+ const addItems = useCallback((newItems: Item[]) => {
+ setItems([...items, ...newItems])
+ }, [items]) // ❌ items dependency causes recreations
+
+ // Risk of stale closure if dependency is forgotten
+ const removeItem = useCallback((id: string) => {
+ setItems(items.filter(item => item.id !== id))
+ }, []) // ❌ Missing items dependency - will use stale items!
+
+ return
+}
+```
+
+The first callback is recreated every time `items` changes, which can cause child components to re-render unnecessarily. The second callback has a stale closure bug—it will always reference the initial `items` value.
+
+**Correct (stable callbacks, no stale closures):**
+
+```tsx
+function TodoList() {
+ const [items, setItems] = useState(initialItems)
+
+ // Stable callback, never recreated
+ const addItems = useCallback((newItems: Item[]) => {
+ setItems(curr => [...curr, ...newItems])
+ }, []) // ✅ No dependencies needed
+
+ // Always uses latest state, no stale closure risk
+ const removeItem = useCallback((id: string) => {
+ setItems(curr => curr.filter(item => item.id !== id))
+ }, []) // ✅ Safe and stable
+
+ return
+}
+```
+
+**Benefits:**
+
+1. **Stable callback references** - Callbacks don't need to be recreated when state changes
+2. **No stale closures** - Always operates on the latest state value
+3. **Fewer dependencies** - Simplifies dependency arrays and reduces memory leaks
+4. **Prevents bugs** - Eliminates the most common source of React closure bugs
+
+**When to use functional updates:**
+
+- Any setState that depends on the current state value
+- Inside useCallback/useMemo when state is needed
+- Event handlers that reference state
+- Async operations that update state
+
+**When direct updates are fine:**
+
+- Setting state to a static value: `setCount(0)`
+- Setting state from props/arguments only: `setName(newName)`
+- State doesn't depend on previous value
+
+**Note:** If your project has [React Compiler](https://react.dev/learn/react-compiler) enabled, the compiler can automatically optimize some cases, but functional updates are still recommended for correctness and to prevent stale closure bugs.
diff --git a/.github/skills/vercel-react-best-practices/rules/rerender-lazy-state-init.md b/.github/skills/vercel-react-best-practices/rules/rerender-lazy-state-init.md
new file mode 100644
index 0000000..4ecb350
--- /dev/null
+++ b/.github/skills/vercel-react-best-practices/rules/rerender-lazy-state-init.md
@@ -0,0 +1,58 @@
+---
+title: Use Lazy State Initialization
+impact: MEDIUM
+impactDescription: wasted computation on every render
+tags: react, hooks, useState, performance, initialization
+---
+
+## Use Lazy State Initialization
+
+Pass a function to `useState` for expensive initial values. Without the function form, the initializer runs on every render even though the value is only used once.
+
+**Incorrect (runs on every render):**
+
+```tsx
+function FilteredList({ items }: { items: Item[] }) {
+ // buildSearchIndex() runs on EVERY render, even after initialization
+ const [searchIndex, setSearchIndex] = useState(buildSearchIndex(items))
+ const [query, setQuery] = useState('')
+
+ // When query changes, buildSearchIndex runs again unnecessarily
+ return
+}
+
+function UserProfile() {
+ // JSON.parse runs on every render
+ const [settings, setSettings] = useState(
+ JSON.parse(localStorage.getItem('settings') || '{}')
+ )
+
+ return
+}
+```
+
+**Correct (runs only once):**
+
+```tsx
+function FilteredList({ items }: { items: Item[] }) {
+ // buildSearchIndex() runs ONLY on initial render
+ const [searchIndex, setSearchIndex] = useState(() => buildSearchIndex(items))
+ const [query, setQuery] = useState('')
+
+ return
+}
+
+function UserProfile() {
+ // JSON.parse runs only on initial render
+ const [settings, setSettings] = useState(() => {
+ const stored = localStorage.getItem('settings')
+ return stored ? JSON.parse(stored) : {}
+ })
+
+ return
+}
+```
+
+Use lazy initialization when computing initial values from localStorage/sessionStorage, building data structures (indexes, maps), reading from the DOM, or performing heavy transformations.
+
+For simple primitives (`useState(0)`), direct references (`useState(props.value)`), or cheap literals (`useState({})`), the function form is unnecessary.
diff --git a/.github/skills/vercel-react-best-practices/rules/rerender-memo-with-default-value.md b/.github/skills/vercel-react-best-practices/rules/rerender-memo-with-default-value.md
new file mode 100644
index 0000000..6357049
--- /dev/null
+++ b/.github/skills/vercel-react-best-practices/rules/rerender-memo-with-default-value.md
@@ -0,0 +1,38 @@
+---
+
+title: Extract Default Non-primitive Parameter Value from Memoized Component to Constant
+impact: MEDIUM
+impactDescription: restores memoization by using a constant for default value
+tags: rerender, memo, optimization
+
+---
+
+## Extract Default Non-primitive Parameter Value from Memoized Component to Constant
+
+When memoized component has a default value for some non-primitive optional parameter, such as an array, function, or object, calling the component without that parameter results in broken memoization. This is because new value instances are created on every rerender, and they do not pass strict equality comparison in `memo()`.
+
+To address this issue, extract the default value into a constant.
+
+**Incorrect (`onClick` has different values on every rerender):**
+
+```tsx
+const UserAvatar = memo(function UserAvatar({ onClick = () => {} }: { onClick?: () => void }) {
+ // ...
+})
+
+// Used without optional onClick
+
+```
+
+**Correct (stable default value):**
+
+```tsx
+const NOOP = () => {};
+
+const UserAvatar = memo(function UserAvatar({ onClick = NOOP }: { onClick?: () => void }) {
+ // ...
+})
+
+// Used without optional onClick
+
+```
diff --git a/.github/skills/vercel-react-best-practices/rules/rerender-memo.md b/.github/skills/vercel-react-best-practices/rules/rerender-memo.md
new file mode 100644
index 0000000..f8982ab
--- /dev/null
+++ b/.github/skills/vercel-react-best-practices/rules/rerender-memo.md
@@ -0,0 +1,44 @@
+---
+title: Extract to Memoized Components
+impact: MEDIUM
+impactDescription: enables early returns
+tags: rerender, memo, useMemo, optimization
+---
+
+## Extract to Memoized Components
+
+Extract expensive work into memoized components to enable early returns before computation.
+
+**Incorrect (computes avatar even when loading):**
+
+```tsx
+function Profile({ user, loading }: Props) {
+ const avatar = useMemo(() => {
+ const id = computeAvatarId(user)
+ return
+ }, [user])
+
+ if (loading) return
+ return
{avatar}
+}
+```
+
+**Correct (skips computation when loading):**
+
+```tsx
+const UserAvatar = memo(function UserAvatar({ user }: { user: User }) {
+ const id = useMemo(() => computeAvatarId(user), [user])
+ return
+})
+
+function Profile({ user, loading }: Props) {
+ if (loading) return
+ return (
+
+
+ )
+}
+```
+
+**Note:** If your project has [React Compiler](https://react.dev/learn/react-compiler) enabled, manual memoization with `memo()` and `useMemo()` is not necessary. The compiler automatically optimizes re-renders.
diff --git a/.github/skills/vercel-react-best-practices/rules/rerender-move-effect-to-event.md b/.github/skills/vercel-react-best-practices/rules/rerender-move-effect-to-event.md
new file mode 100644
index 0000000..dd58a1a
--- /dev/null
+++ b/.github/skills/vercel-react-best-practices/rules/rerender-move-effect-to-event.md
@@ -0,0 +1,45 @@
+---
+title: Put Interaction Logic in Event Handlers
+impact: MEDIUM
+impactDescription: avoids effect re-runs and duplicate side effects
+tags: rerender, useEffect, events, side-effects, dependencies
+---
+
+## Put Interaction Logic in Event Handlers
+
+If a side effect is triggered by a specific user action (submit, click, drag), run it in that event handler. Do not model the action as state + effect; it makes effects re-run on unrelated changes and can duplicate the action.
+
+**Incorrect (event modeled as state + effect):**
+
+```tsx
+function Form() {
+ const [submitted, setSubmitted] = useState(false)
+ const theme = useContext(ThemeContext)
+
+ useEffect(() => {
+ if (submitted) {
+ post('/api/register')
+ showToast('Registered', theme)
+ }
+ }, [submitted, theme])
+
+ return
setSubmitted(true)}>Submit
+}
+```
+
+**Correct (do it in the handler):**
+
+```tsx
+function Form() {
+ const theme = useContext(ThemeContext)
+
+ function handleSubmit() {
+ post('/api/register')
+ showToast('Registered', theme)
+ }
+
+ return
Submit
+}
+```
+
+Reference: [Should this code move to an event handler?](https://react.dev/learn/removing-effect-dependencies#should-this-code-move-to-an-event-handler)
diff --git a/.github/skills/vercel-react-best-practices/rules/rerender-simple-expression-in-memo.md b/.github/skills/vercel-react-best-practices/rules/rerender-simple-expression-in-memo.md
new file mode 100644
index 0000000..59dfab0
--- /dev/null
+++ b/.github/skills/vercel-react-best-practices/rules/rerender-simple-expression-in-memo.md
@@ -0,0 +1,35 @@
+---
+title: Do not wrap a simple expression with a primitive result type in useMemo
+impact: LOW-MEDIUM
+impactDescription: wasted computation on every render
+tags: rerender, useMemo, optimization
+---
+
+## Do not wrap a simple expression with a primitive result type in useMemo
+
+When an expression is simple (few logical or arithmetical operators) and has a primitive result type (boolean, number, string), do not wrap it in `useMemo`.
+Calling `useMemo` and comparing hook dependencies may consume more resources than the expression itself.
+
+**Incorrect:**
+
+```tsx
+function Header({ user, notifications }: Props) {
+ const isLoading = useMemo(() => {
+ return user.isLoading || notifications.isLoading
+ }, [user.isLoading, notifications.isLoading])
+
+ if (isLoading) return
+ // return some markup
+}
+```
+
+**Correct:**
+
+```tsx
+function Header({ user, notifications }: Props) {
+ const isLoading = user.isLoading || notifications.isLoading
+
+ if (isLoading) return
+ // return some markup
+}
+```
diff --git a/.github/skills/vercel-react-best-practices/rules/rerender-transitions.md b/.github/skills/vercel-react-best-practices/rules/rerender-transitions.md
new file mode 100644
index 0000000..d99f43f
--- /dev/null
+++ b/.github/skills/vercel-react-best-practices/rules/rerender-transitions.md
@@ -0,0 +1,40 @@
+---
+title: Use Transitions for Non-Urgent Updates
+impact: MEDIUM
+impactDescription: maintains UI responsiveness
+tags: rerender, transitions, startTransition, performance
+---
+
+## Use Transitions for Non-Urgent Updates
+
+Mark frequent, non-urgent state updates as transitions to maintain UI responsiveness.
+
+**Incorrect (blocks UI on every scroll):**
+
+```tsx
+function ScrollTracker() {
+ const [scrollY, setScrollY] = useState(0)
+ useEffect(() => {
+ const handler = () => setScrollY(window.scrollY)
+ window.addEventListener('scroll', handler, { passive: true })
+ return () => window.removeEventListener('scroll', handler)
+ }, [])
+}
+```
+
+**Correct (non-blocking updates):**
+
+```tsx
+import { startTransition } from 'react'
+
+function ScrollTracker() {
+ const [scrollY, setScrollY] = useState(0)
+ useEffect(() => {
+ const handler = () => {
+ startTransition(() => setScrollY(window.scrollY))
+ }
+ window.addEventListener('scroll', handler, { passive: true })
+ return () => window.removeEventListener('scroll', handler)
+ }, [])
+}
+```
diff --git a/.github/skills/vercel-react-best-practices/rules/rerender-use-ref-transient-values.md b/.github/skills/vercel-react-best-practices/rules/rerender-use-ref-transient-values.md
new file mode 100644
index 0000000..cf04b81
--- /dev/null
+++ b/.github/skills/vercel-react-best-practices/rules/rerender-use-ref-transient-values.md
@@ -0,0 +1,73 @@
+---
+title: Use useRef for Transient Values
+impact: MEDIUM
+impactDescription: avoids unnecessary re-renders on frequent updates
+tags: rerender, useref, state, performance
+---
+
+## Use useRef for Transient Values
+
+When a value changes frequently and you don't want a re-render on every update (e.g., mouse trackers, intervals, transient flags), store it in `useRef` instead of `useState`. Keep component state for UI; use refs for temporary DOM-adjacent values. Updating a ref does not trigger a re-render.
+
+**Incorrect (renders every update):**
+
+```tsx
+function Tracker() {
+ const [lastX, setLastX] = useState(0)
+
+ useEffect(() => {
+ const onMove = (e: MouseEvent) => setLastX(e.clientX)
+ window.addEventListener('mousemove', onMove)
+ return () => window.removeEventListener('mousemove', onMove)
+ }, [])
+
+ return (
+
+ )
+}
+```
+
+**Correct (no re-render for tracking):**
+
+```tsx
+function Tracker() {
+ const lastXRef = useRef(0)
+ const dotRef = useRef
(null)
+
+ useEffect(() => {
+ const onMove = (e: MouseEvent) => {
+ lastXRef.current = e.clientX
+ const node = dotRef.current
+ if (node) {
+ node.style.transform = `translateX(${e.clientX}px)`
+ }
+ }
+ window.addEventListener('mousemove', onMove)
+ return () => window.removeEventListener('mousemove', onMove)
+ }, [])
+
+ return (
+
+ )
+}
+```
diff --git a/.github/skills/vercel-react-best-practices/rules/server-after-nonblocking.md b/.github/skills/vercel-react-best-practices/rules/server-after-nonblocking.md
new file mode 100644
index 0000000..e8f5b26
--- /dev/null
+++ b/.github/skills/vercel-react-best-practices/rules/server-after-nonblocking.md
@@ -0,0 +1,73 @@
+---
+title: Use after() for Non-Blocking Operations
+impact: MEDIUM
+impactDescription: faster response times
+tags: server, async, logging, analytics, side-effects
+---
+
+## Use after() for Non-Blocking Operations
+
+Use Next.js's `after()` to schedule work that should execute after a response is sent. This prevents logging, analytics, and other side effects from blocking the response.
+
+**Incorrect (blocks response):**
+
+```tsx
+import { logUserAction } from '@/app/utils'
+
+export async function POST(request: Request) {
+ // Perform mutation
+ await updateDatabase(request)
+
+ // Logging blocks the response
+ const userAgent = request.headers.get('user-agent') || 'unknown'
+ await logUserAction({ userAgent })
+
+ return new Response(JSON.stringify({ status: 'success' }), {
+ status: 200,
+ headers: { 'Content-Type': 'application/json' }
+ })
+}
+```
+
+**Correct (non-blocking):**
+
+```tsx
+import { after } from 'next/server'
+import { headers, cookies } from 'next/headers'
+import { logUserAction } from '@/app/utils'
+
+export async function POST(request: Request) {
+ // Perform mutation
+ await updateDatabase(request)
+
+ // Log after response is sent
+ after(async () => {
+ const userAgent = (await headers()).get('user-agent') || 'unknown'
+ const sessionCookie = (await cookies()).get('session-id')?.value || 'anonymous'
+
+ logUserAction({ sessionCookie, userAgent })
+ })
+
+ return new Response(JSON.stringify({ status: 'success' }), {
+ status: 200,
+ headers: { 'Content-Type': 'application/json' }
+ })
+}
+```
+
+The response is sent immediately while logging happens in the background.
+
+**Common use cases:**
+
+- Analytics tracking
+- Audit logging
+- Sending notifications
+- Cache invalidation
+- Cleanup tasks
+
+**Important notes:**
+
+- `after()` runs even if the response fails or redirects
+- Works in Server Actions, Route Handlers, and Server Components
+
+Reference: [https://nextjs.org/docs/app/api-reference/functions/after](https://nextjs.org/docs/app/api-reference/functions/after)
diff --git a/.github/skills/vercel-react-best-practices/rules/server-auth-actions.md b/.github/skills/vercel-react-best-practices/rules/server-auth-actions.md
new file mode 100644
index 0000000..ee82c04
--- /dev/null
+++ b/.github/skills/vercel-react-best-practices/rules/server-auth-actions.md
@@ -0,0 +1,96 @@
+---
+title: Authenticate Server Actions Like API Routes
+impact: CRITICAL
+impactDescription: prevents unauthorized access to server mutations
+tags: server, server-actions, authentication, security, authorization
+---
+
+## Authenticate Server Actions Like API Routes
+
+**Impact: CRITICAL (prevents unauthorized access to server mutations)**
+
+Server Actions (functions with `"use server"`) are exposed as public endpoints, just like API routes. Always verify authentication and authorization **inside** each Server Action—do not rely solely on middleware, layout guards, or page-level checks, as Server Actions can be invoked directly.
+
+Next.js documentation explicitly states: "Treat Server Actions with the same security considerations as public-facing API endpoints, and verify if the user is allowed to perform a mutation."
+
+**Incorrect (no authentication check):**
+
+```typescript
+'use server'
+
+export async function deleteUser(userId: string) {
+ // Anyone can call this! No auth check
+ await db.user.delete({ where: { id: userId } })
+ return { success: true }
+}
+```
+
+**Correct (authentication inside the action):**
+
+```typescript
+'use server'
+
+import { verifySession } from '@/lib/auth'
+import { unauthorized } from '@/lib/errors'
+
+export async function deleteUser(userId: string) {
+ // Always check auth inside the action
+ const session = await verifySession()
+
+ if (!session) {
+ throw unauthorized('Must be logged in')
+ }
+
+ // Check authorization too
+ if (session.user.role !== 'admin' && session.user.id !== userId) {
+ throw unauthorized('Cannot delete other users')
+ }
+
+ await db.user.delete({ where: { id: userId } })
+ return { success: true }
+}
+```
+
+**With input validation:**
+
+```typescript
+'use server'
+
+import { verifySession } from '@/lib/auth'
+import { z } from 'zod'
+
+const updateProfileSchema = z.object({
+ userId: z.string().uuid(),
+ name: z.string().min(1).max(100),
+ email: z.string().email()
+})
+
+export async function updateProfile(data: unknown) {
+ // Validate input first
+ const validated = updateProfileSchema.parse(data)
+
+ // Then authenticate
+ const session = await verifySession()
+ if (!session) {
+ throw new Error('Unauthorized')
+ }
+
+ // Then authorize
+ if (session.user.id !== validated.userId) {
+ throw new Error('Can only update own profile')
+ }
+
+ // Finally perform the mutation
+ await db.user.update({
+ where: { id: validated.userId },
+ data: {
+ name: validated.name,
+ email: validated.email
+ }
+ })
+
+ return { success: true }
+}
+```
+
+Reference: [https://nextjs.org/docs/app/guides/authentication](https://nextjs.org/docs/app/guides/authentication)
diff --git a/.github/skills/vercel-react-best-practices/rules/server-cache-lru.md b/.github/skills/vercel-react-best-practices/rules/server-cache-lru.md
new file mode 100644
index 0000000..ef6938a
--- /dev/null
+++ b/.github/skills/vercel-react-best-practices/rules/server-cache-lru.md
@@ -0,0 +1,41 @@
+---
+title: Cross-Request LRU Caching
+impact: HIGH
+impactDescription: caches across requests
+tags: server, cache, lru, cross-request
+---
+
+## Cross-Request LRU Caching
+
+`React.cache()` only works within one request. For data shared across sequential requests (user clicks button A then button B), use an LRU cache.
+
+**Implementation:**
+
+```typescript
+import { LRUCache } from 'lru-cache'
+
+const cache = new LRUCache({
+ max: 1000,
+ ttl: 5 * 60 * 1000 // 5 minutes
+})
+
+export async function getUser(id: string) {
+ const cached = cache.get(id)
+ if (cached) return cached
+
+ const user = await db.user.findUnique({ where: { id } })
+ cache.set(id, user)
+ return user
+}
+
+// Request 1: DB query, result cached
+// Request 2: cache hit, no DB query
+```
+
+Use when sequential user actions hit multiple endpoints needing the same data within seconds.
+
+**With Vercel's [Fluid Compute](https://vercel.com/docs/fluid-compute):** LRU caching is especially effective because multiple concurrent requests can share the same function instance and cache. This means the cache persists across requests without needing external storage like Redis.
+
+**In traditional serverless:** Each invocation runs in isolation, so consider Redis for cross-process caching.
+
+Reference: [https://github.com/isaacs/node-lru-cache](https://github.com/isaacs/node-lru-cache)
diff --git a/.github/skills/vercel-react-best-practices/rules/server-cache-react.md b/.github/skills/vercel-react-best-practices/rules/server-cache-react.md
new file mode 100644
index 0000000..87c9ca3
--- /dev/null
+++ b/.github/skills/vercel-react-best-practices/rules/server-cache-react.md
@@ -0,0 +1,76 @@
+---
+title: Per-Request Deduplication with React.cache()
+impact: MEDIUM
+impactDescription: deduplicates within request
+tags: server, cache, react-cache, deduplication
+---
+
+## Per-Request Deduplication with React.cache()
+
+Use `React.cache()` for server-side request deduplication. Authentication and database queries benefit most.
+
+**Usage:**
+
+```typescript
+import { cache } from 'react'
+
+export const getCurrentUser = cache(async () => {
+ const session = await auth()
+ if (!session?.user?.id) return null
+ return await db.user.findUnique({
+ where: { id: session.user.id }
+ })
+})
+```
+
+Within a single request, multiple calls to `getCurrentUser()` execute the query only once.
+
+**Avoid inline objects as arguments:**
+
+`React.cache()` uses shallow equality (`Object.is`) to determine cache hits. Inline objects create new references each call, preventing cache hits.
+
+**Incorrect (always cache miss):**
+
+```typescript
+const getUser = cache(async (params: { uid: number }) => {
+ return await db.user.findUnique({ where: { id: params.uid } })
+})
+
+// Each call creates new object, never hits cache
+getUser({ uid: 1 })
+getUser({ uid: 1 }) // Cache miss, runs query again
+```
+
+**Correct (cache hit):**
+
+```typescript
+const getUser = cache(async (uid: number) => {
+ return await db.user.findUnique({ where: { id: uid } })
+})
+
+// Primitive args use value equality
+getUser(1)
+getUser(1) // Cache hit, returns cached result
+```
+
+If you must pass objects, pass the same reference:
+
+```typescript
+const params = { uid: 1 }
+getUser(params) // Query runs
+getUser(params) // Cache hit (same reference)
+```
+
+**Next.js-Specific Note:**
+
+In Next.js, the `fetch` API is automatically extended with request memoization. Requests with the same URL and options are automatically deduplicated within a single request, so you don't need `React.cache()` for `fetch` calls. However, `React.cache()` is still essential for other async tasks:
+
+- Database queries (Prisma, Drizzle, etc.)
+- Heavy computations
+- Authentication checks
+- File system operations
+- Any non-fetch async work
+
+Use `React.cache()` to deduplicate these operations across your component tree.
+
+Reference: [React.cache documentation](https://react.dev/reference/react/cache)
diff --git a/.github/skills/vercel-react-best-practices/rules/server-dedup-props.md b/.github/skills/vercel-react-best-practices/rules/server-dedup-props.md
new file mode 100644
index 0000000..fb24a25
--- /dev/null
+++ b/.github/skills/vercel-react-best-practices/rules/server-dedup-props.md
@@ -0,0 +1,65 @@
+---
+title: Avoid Duplicate Serialization in RSC Props
+impact: LOW
+impactDescription: reduces network payload by avoiding duplicate serialization
+tags: server, rsc, serialization, props, client-components
+---
+
+## Avoid Duplicate Serialization in RSC Props
+
+**Impact: LOW (reduces network payload by avoiding duplicate serialization)**
+
+RSC→client serialization deduplicates by object reference, not value. Same reference = serialized once; new reference = serialized again. Do transformations (`.toSorted()`, `.filter()`, `.map()`) in client, not server.
+
+**Incorrect (duplicates array):**
+
+```tsx
+// RSC: sends 6 strings (2 arrays × 3 items)
+ u.active)} />
+{items.map(renderItem)}
+}
+```
+
+**Correct (both fetch simultaneously):**
+
+```tsx
+async function Header() {
+ const data = await fetchHeader()
+ return {data}
+}
+
+async function Sidebar() {
+ const items = await fetchSidebarItems()
+ return {items.map(renderItem)}
+}
+
+export default function Page() {
+ return (
+
+
+
+ )
+}
+```
+
+**Alternative with children prop:**
+
+```tsx
+async function Header() {
+ const data = await fetchHeader()
+ return {data}
+}
+
+async function Sidebar() {
+ const items = await fetchSidebarItems()
+ return {items.map(renderItem)}
+}
+
+function Layout({ children }: { children: ReactNode }) {
+ return (
+
+
+ {children}
+
+ )
+}
+
+export default function Page() {
+ return (
+
+
+ )
+}
+```
diff --git a/.github/skills/vercel-react-best-practices/rules/server-serialization.md b/.github/skills/vercel-react-best-practices/rules/server-serialization.md
new file mode 100644
index 0000000..39c5c41
--- /dev/null
+++ b/.github/skills/vercel-react-best-practices/rules/server-serialization.md
@@ -0,0 +1,38 @@
+---
+title: Minimize Serialization at RSC Boundaries
+impact: HIGH
+impactDescription: reduces data transfer size
+tags: server, rsc, serialization, props
+---
+
+## Minimize Serialization at RSC Boundaries
+
+The React Server/Client boundary serializes all object properties into strings and embeds them in the HTML response and subsequent RSC requests. This serialized data directly impacts page weight and load time, so **size matters a lot**. Only pass fields that the client actually uses.
+
+**Incorrect (serializes all 50 fields):**
+
+```tsx
+async function Page() {
+ const user = await fetchUser() // 50 fields
+ return {user.name}
// uses 1 field
+}
+```
+
+**Correct (serializes only 1 field):**
+
+```tsx
+async function Page() {
+ const user = await fetchUser()
+ return {name}
+}
+```
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index 2a1b594..fa3ae5f 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -19,6 +19,28 @@ jobs:
# STAGE 1: CODE QUALITY & LINTING
# ============================================================================
+ spec-drift-check:
+ name: '[*] Spec Drift Check (TS canonical)'
+ runs-on: ubuntu-latest
+ steps:
+ - uses: actions/checkout@v4
+
+ - name: Set up Node.js
+ uses: actions/setup-node@v4
+ with:
+ node-version: '20'
+ cache: 'npm'
+
+ - name: Set up Python
+ uses: actions/setup-python@v4
+ with:
+ python-version: ${{ env.PYTHON_VERSION }}
+ cache: 'pip'
+
+ - name: Run spec drift check
+ run: |
+ bash scripts/spec/check_spec_drift.sh
+
lint-and-format:
name: '[*] Code Quality Checks'
runs-on: ubuntu-latest
@@ -37,13 +59,14 @@ jobs:
pip install flake8 black isort mypy bandit
- name: Run Black formatter check
- run: black --check hyperagent/
+ run: black --check apps/api/hyperagent/
- name: Run isort import check
- run: isort --check-only hyperagent/
+ run: isort --check-only apps/api/hyperagent/
- name: Run MyPy type checking
- run: mypy hyperagent/
+ run: mypy apps/api/hyperagent/
+ continue-on-error: true
# ============================================================================
# STAGE 2: SECURITY SCANNING
@@ -58,8 +81,8 @@ jobs:
- name: Run Bandit security linter
run: |
pip install bandit
- bandit -r hyperagent/ -f json -o bandit-report.json || true
- bandit -r hyperagent/ || true
+ bandit -r apps/api/hyperagent/ -f json -o bandit-report.json || true
+ bandit -r apps/api/hyperagent/ || true
- name: Run Trivy vulnerability scanner
uses: aquasecurity/trivy-action@master
@@ -71,7 +94,7 @@ jobs:
severity: 'CRITICAL,HIGH'
- name: Upload Trivy results to GitHub Security
- uses: github/codeql-action/upload-sarif@v3
+ uses: github/codeql-action/upload-sarif@v4
if: always()
with:
sarif_file: 'trivy-results.sarif'
@@ -120,21 +143,25 @@ jobs:
- name: Install dependencies
run: |
python -m pip install --upgrade pip
- pip install -r requirements.txt
+ pip install -r apps/api/requirements.txt
pip install pytest pytest-asyncio pytest-cov pytest-mock
- name: Set up database
run: |
- PGPASSWORD=test_password psql -h localhost -U test_user -d hyperagent_test -c "CREATE EXTENSION IF NOT EXISTS vector;"
+ PGPASSWORD=test_password psql -h localhost -U test_user -d hyperagent_test -c "CREATE EXTENSION IF NOT EXISTS vector;" || echo "Vector extension not available, skipping"
env:
PGHOST: localhost
PGPORT: 5432
PGUSER: test_user
PGDATABASE: hyperagent_test
+ continue-on-error: true
- name: Run unit tests
run: |
- pytest tests/unit/ -v --cov=hyperagent --cov-report=xml --cov-report=term --cov-report=html
+ pytest tests/unit/ -v --cov=apps.api.hyperagent --cov-report=xml --cov-report=term --cov-report=html -p no:web3.tools.pytest_ethereum
+ # Also add apps/api to Python path for imports
+ env:
+ PYTHONPATH: apps/api:${{ env.PYTHONPATH }}
env:
DATABASE_URL: postgresql://test_user:test_password@localhost:5432/hyperagent_test
REDIS_URL: redis://localhost:6379/0
@@ -171,20 +198,20 @@ jobs:
- name: Set up Node.js
uses: actions/setup-node@v4
with:
- node-version: '18'
+ node-version: '20'
cache: 'npm'
- cache-dependency-path: frontend/package-lock.json
+ cache-dependency-path: apps/web/package-lock.json
- name: Install dependencies
- working-directory: ./frontend
+ working-directory: ./apps/web
run: npm ci
- name: Run ESLint
- working-directory: ./frontend
+ working-directory: ./apps/web
run: npm run lint
- name: Check code formatting
- working-directory: ./frontend
+ working-directory: ./apps/web
run: npm run format:check || echo "Format check skipped (Prettier not configured)"
continue-on-error: true
@@ -197,16 +224,16 @@ jobs:
- name: Set up Node.js
uses: actions/setup-node@v4
with:
- node-version: '18'
+ node-version: '20'
cache: 'npm'
- cache-dependency-path: frontend/package-lock.json
+ cache-dependency-path: apps/web/package-lock.json
- name: Install dependencies
- working-directory: ./frontend
+ working-directory: ./apps/web
run: npm ci
- name: Run tests
- working-directory: ./frontend
+ working-directory: ./apps/web
run: npm test
continue-on-error: true
@@ -252,12 +279,12 @@ jobs:
- name: Install dependencies
run: |
- pip install -r requirements.txt
+ pip install -r apps/api/requirements.txt
pip install pytest pytest-asyncio
- name: Run integration tests
run: |
- pytest tests/integration/ -v
+ pytest tests/integration/ -v -p no:web3.tools.pytest_ethereum
env:
DATABASE_URL: postgresql://test_user:test_password@localhost:5432/hyperagent_test
REDIS_URL: redis://localhost:6379/0
@@ -302,7 +329,7 @@ jobs:
uses: docker/build-push-action@v4
with:
context: .
- file: ./Dockerfile
+ file: ./infra/docker/Dockerfile
push: ${{ github.event_name != 'pull_request' }}
tags: ${{ steps.meta.outputs.tags }}
labels: ${{ steps.meta.outputs.labels }}
@@ -326,12 +353,12 @@ jobs:
- name: Start services with Docker Compose
run: |
- docker-compose up -d
+ docker-compose -f infra/docker/docker-compose.yml up -d
sleep 10
- name: Wait for services to be healthy
run: |
- timeout 60 bash -c 'until docker-compose ps | grep -q "healthy"; do sleep 2; done'
+ timeout 60 bash -c 'until docker-compose -f infra/docker/docker-compose.yml ps | grep -q "healthy"; do sleep 2; done'
- name: Test API health endpoint
run: |
@@ -340,7 +367,7 @@ jobs:
- name: Stop services
if: always()
run: |
- docker-compose down -v
+ docker-compose -f infra/docker/docker-compose.yml down -v
# ============================================================================
# STAGE 7: NOTIFICATIONS
diff --git a/.github/workflows/deploy-staging.yml b/.github/workflows/deploy-staging.yml
new file mode 100644
index 0000000..40555c2
--- /dev/null
+++ b/.github/workflows/deploy-staging.yml
@@ -0,0 +1,196 @@
+name: Deploy to Staging
+
+on:
+ push:
+ branches: [develop]
+
+jobs:
+ build-and-push:
+ name: Build and Push Docker Images
+ runs-on: ubuntu-latest
+ permissions:
+ contents: read
+ packages: write
+ outputs:
+ image_tag: ${{ steps.meta.outputs.tags }}
+
+ steps:
+ - uses: actions/checkout@v4
+
+ - name: Set up Docker Buildx
+ uses: docker/setup-buildx-action@v3
+
+ - name: Log in to GitHub Container Registry
+ uses: docker/login-action@v3
+ with:
+ registry: ghcr.io
+ username: ${{ github.actor }}
+ password: ${{ secrets.GITHUB_TOKEN }}
+
+ - name: Extract metadata
+ id: meta
+ uses: docker/metadata-action@v5
+ with:
+ images: ghcr.io/${{ github.repository }}/backend
+ tags: |
+ type=ref,event=branch
+ type=sha,prefix={{branch}}-
+
+ - name: Build and push backend image
+ uses: docker/build-push-action@v5
+ with:
+ context: .
+ file: ./docker/Dockerfile.backend
+ push: true
+ tags: ${{ steps.meta.outputs.tags }}
+ labels: ${{ steps.meta.outputs.labels }}
+ cache-from: type=gha
+ cache-to: type=gha,mode=max
+
+ - name: Build and push frontend image
+ uses: docker/build-push-action@v5
+ with:
+ context: ./apps/web
+ file: ./apps/web/Dockerfile
+ push: true
+ tags: ghcr.io/${{ github.repository }}/frontend:develop-${{ github.sha }}
+ cache-from: type=gha
+ cache-to: type=gha,mode=max
+
+ deploy-to-staging:
+ name: Deploy to Staging Environment
+ runs-on: ubuntu-latest
+ needs: build-and-push
+ environment:
+ name: staging
+ url: https://staging.hyperagent.io
+
+ steps:
+ - uses: actions/checkout@v4
+
+ - name: Update image tags in manifests
+ run: |
+ # Update k8s manifests with new image tags
+ cd k8s/overlays/staging
+
+ # Update backend image
+ kustomize edit set image \
+ hyperagent-backend=ghcr.io/${{ github.repository }}/backend:develop-${{ github.sha }}
+
+ # Update frontend image
+ kustomize edit set image \
+ hyperagent-frontend=ghcr.io/${{ github.repository }}/frontend:develop-${{ github.sha }}
+
+ - name: Commit and push manifest updates
+ run: |
+ git config user.name "github-actions[bot]"
+ git config user.email "github-actions[bot]@users.noreply.github.com"
+
+ git add k8s/overlays/staging/
+ git commit -m "chore(deploy): update staging images to ${{ github.sha }}"
+ git push origin develop
+
+ - name: Install ArgoCD CLI
+ run: |
+ curl -sSL -o /usr/local/bin/argocd https://github.com/argoproj/argo-cd/releases/latest/download/argocd-linux-amd64
+ chmod +x /usr/local/bin/argocd
+
+ - name: Trigger ArgoCD Sync
+ run: |
+ argocd login ${{ secrets.ARGOCD_SERVER }} \
+ --username admin \
+ --password ${{ secrets.ARGOCD_PASSWORD }} \
+ --grpc-web
+
+ argocd app sync hyperagent-staging \
+ --prune \
+ --timeout 600
+
+ - name: Wait for deployment
+ run: |
+ argocd app wait hyperagent-staging \
+ --health \
+ --timeout 600
+
+ - name: Run smoke tests
+ run: |
+ # Wait for services to be ready
+ sleep 30
+
+ # Health check
+ curl -f https://staging-api.hyperagent.io/health || exit 1
+
+ # Verify frontend
+ curl -f https://staging.hyperagent.io || exit 1
+
+ - name: Notify on success
+ if: success()
+ uses: slackapi/slack-github-action@v1
+ with:
+ payload: |
+ {
+ "text": "✅ Staging deployment successful",
+ "blocks": [
+ {
+ "type": "section",
+ "text": {
+ "type": "mrkdwn",
+ "text": "*Staging Deployment Successful*\n• Environment: https://staging.hyperagent.io\n• Commit: \n• Author: ${{ github.actor }}\n• Branch: ${{ github.ref_name }}"
+ }
+ }
+ ]
+ }
+ env:
+ SLACK_WEBHOOK_URL: ${{ secrets.SLACK_WEBHOOK }}
+
+ - name: Notify on failure
+ if: failure()
+ uses: slackapi/slack-github-action@v1
+ with:
+ payload: |
+ {
+ "text": "❌ Staging deployment failed",
+ "blocks": [
+ {
+ "type": "section",
+ "text": {
+ "type": "mrkdwn",
+ "text": "*Staging Deployment Failed*\n• Commit: \n• Author: ${{ github.actor }}\n• Logs: "
+ }
+ }
+ ]
+ }
+ env:
+ SLACK_WEBHOOK_URL: ${{ secrets.SLACK_WEBHOOK }}
+
+ rollback-on-failure:
+ name: Rollback on Failure
+ runs-on: ubuntu-latest
+ needs: deploy-to-staging
+ if: failure()
+
+ steps:
+ - uses: actions/checkout@v4
+ with:
+ fetch-depth: 0
+
+ - name: Find last successful deployment
+ id: last-success
+ run: |
+ # Find last successful workflow run
+ last_success=$(gh run list \
+ --workflow=deploy-staging.yml \
+ --status=success \
+ --limit 1 \
+ --json databaseId \
+ --jq '.[0].databaseId')
+
+ echo "run_id=$last_success" >> $GITHUB_OUTPUT
+ env:
+ GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+
+ - name: Trigger rollback
+ run: |
+ echo "Rolling back to last successful deployment: ${{ steps.last-success.outputs.run_id }}"
+ # Implement rollback logic here
+ # This would typically revert the k8s manifests and trigger ArgoCD sync
diff --git a/.github/workflows/deploy.yml b/.github/workflows/deploy.yml
deleted file mode 100644
index 1556f4f..0000000
--- a/.github/workflows/deploy.yml
+++ /dev/null
@@ -1,118 +0,0 @@
-# HyperAgent Deployment Workflow
-name: Deploy to Production
-
-on:
- push:
- branches: [main]
- tags:
- - 'v*'
- workflow_dispatch:
- inputs:
- environment:
- description: 'Deployment environment'
- required: true
- default: 'staging'
- type: choice
- options:
- - staging
- - production
-
-env:
- REGISTRY: ghcr.io
- IMAGE_NAME: ${{ github.repository }}
-
-jobs:
- # ============================================================================
- # STAGE 1: PRE-DEPLOYMENT CHECKS
- # ============================================================================
-
- pre-deployment:
- name: '[*] Pre-Deployment Checks'
- runs-on: ubuntu-latest
- steps:
- - uses: actions/checkout@v4
-
- - name: Validate environment variables
- run: |
- echo "[*] Validating deployment configuration..."
- # Check required secrets are set
- required_vars=("DATABASE_URL" "REDIS_URL" "GEMINI_API_KEY")
- for var in "${required_vars[@]}"; do
- if [ -z "${!var}" ]; then
- echo "[-] Missing required variable: $var"
- exit 1
- fi
- done
- echo "[+] All required variables present"
-
- - name: Check Docker image exists
- run: |
- echo "[*] Verifying Docker image availability..."
- # Image should be built in CI workflow
- echo "[+] Image verification complete"
-
- # ============================================================================
- # STAGE 2: STAGING DEPLOYMENT
- # ============================================================================
-
- deploy-staging:
- name: '[>] Deploy to Staging'
- runs-on: ubuntu-latest
- needs: [pre-deployment]
- if: github.ref == 'refs/heads/main' || github.event.inputs.environment == 'staging'
- environment:
- name: staging
- url: https://staging.hyperagent.dev
-
- steps:
- - uses: actions/checkout@v4
-
- - name: Deploy to staging
- run: |
- echo "[*] Deploying to staging environment..."
- # Deployment commands would go here
- # Example: kubectl apply, docker-compose up, etc.
- echo "[+] Staging deployment initiated"
-
- - name: Verify staging deployment
- run: |
- echo "[*] Verifying staging deployment..."
- sleep 30
- curl -f https://staging.hyperagent.dev/api/v1/health/basic || exit 1
- echo "[+] Staging deployment verified"
-
- # ============================================================================
- # STAGE 3: PRODUCTION DEPLOYMENT
- # ============================================================================
-
- deploy-production:
- name: '[>] Deploy to Production'
- runs-on: ubuntu-latest
- needs: [deploy-staging]
- if: github.ref == 'refs/heads/main' || (github.event_name == 'workflow_dispatch' && github.event.inputs.environment == 'production')
- environment:
- name: production
- url: https://hyperagent.dev
-
- steps:
- - uses: actions/checkout@v4
-
- - name: Deploy to production
- run: |
- echo "[*] Deploying to production environment..."
- # Production deployment commands
- echo "[+] Production deployment initiated"
-
- - name: Verify production deployment
- run: |
- echo "[*] Verifying production deployment..."
- sleep 60
- curl -f https://hyperagent.dev/api/v1/health/basic || exit 1
- echo "[+] Production deployment verified"
-
- - name: Notify deployment success
- if: success()
- run: |
- echo "[+] Production deployment completed successfully"
- # Add notification logic (Slack, email, etc.)
-
diff --git a/.github/workflows/pr-validation.yml b/.github/workflows/pr-validation.yml
new file mode 100644
index 0000000..a202c74
--- /dev/null
+++ b/.github/workflows/pr-validation.yml
@@ -0,0 +1,343 @@
+name: PR Validation
+
+on:
+ pull_request:
+ branches: [develop, main]
+ types: [opened, synchronize, reopened]
+
+concurrency:
+ group: ${{ github.workflow }}-${{ github.ref }}
+ cancel-in-progress: true
+
+jobs:
+ lint-python:
+ name: Lint Python Code
+ runs-on: ubuntu-latest
+ steps:
+ - uses: actions/checkout@v4
+
+ - name: Setup Python
+ uses: actions/setup-python@v5
+ with:
+ python-version: '3.12'
+ cache: 'pip'
+
+ - name: Install linting tools
+ run: |
+ pip install ruff black isort
+
+ - name: Run ruff
+ run: ruff check .
+
+ - name: Check black formatting
+ run: black --check .
+
+ - name: Check import sorting
+ run: isort --check-only .
+
+ lint-typescript:
+ name: Lint TypeScript/JavaScript
+ runs-on: ubuntu-latest
+ if: contains(github.event.pull_request.changed_files, 'apps/web/') || contains(github.event.pull_request.changed_files, '.tsx') || contains(github.event.pull_request.changed_files, '.ts')
+ steps:
+ - uses: actions/checkout@v4
+
+ - name: Setup Node
+ uses: actions/setup-node@v4
+ with:
+ node-version: '20'
+ cache: 'npm'
+ cache-dependency-path: apps/web/package-lock.json
+
+ - name: Install dependencies
+ run: |
+ cd apps/web
+ npm ci
+
+ - name: Run ESLint
+ run: |
+ cd apps/web
+ npm run lint
+
+ - name: Check TypeScript types
+ run: |
+ cd apps/web
+ npm run type-check
+
+ test-backend:
+ name: Backend Tests
+ runs-on: ubuntu-latest
+ services:
+ postgres:
+ image: postgres:15
+ env:
+ POSTGRES_USER: postgres
+ POSTGRES_PASSWORD: postgres
+ POSTGRES_DB: hyperagent_test
+ ports:
+ - 5432:5432
+ options: >-
+ --health-cmd pg_isready
+ --health-interval 10s
+ --health-timeout 5s
+ --health-retries 5
+
+ redis:
+ image: redis:7-alpine
+ ports:
+ - 6379:6379
+ options: >-
+ --health-cmd "redis-cli ping"
+ --health-interval 10s
+ --health-timeout 5s
+ --health-retries 5
+
+ steps:
+ - uses: actions/checkout@v4
+
+ - name: Setup Python
+ uses: actions/setup-python@v5
+ with:
+ python-version: '3.12'
+ cache: 'pip'
+
+ - name: Install dependencies
+ run: |
+ pip install -r requirements.txt
+ pip install -r requirements-dev.txt
+
+ - name: Run pytest
+ run: |
+ pytest \
+ --cov=hyperagent \
+ --cov-report=xml \
+ --cov-report=term-missing \
+ --junitxml=junit.xml \
+ tests/
+ env:
+ DATABASE_URL: postgresql://postgres:postgres@localhost:5432/hyperagent_test
+ REDIS_URL: redis://localhost:6379/0
+ ENVIRONMENT: test
+
+ - name: Upload coverage to Codecov
+ uses: codecov/codecov-action@v4
+ with:
+ file: ./coverage.xml
+ flags: backend
+
+ - name: Publish test results
+ uses: EnricoMi/publish-unit-test-result-action@v2
+ if: always()
+ with:
+ files: junit.xml
+
+ test-frontend:
+ name: Frontend Tests
+ runs-on: ubuntu-latest
+ if: contains(github.event.pull_request.changed_files, 'apps/web/')
+ steps:
+ - uses: actions/checkout@v4
+
+ - name: Setup Node
+ uses: actions/setup-node@v4
+ with:
+ node-version: '20'
+ cache: 'npm'
+ cache-dependency-path: apps/web/package-lock.json
+
+ - name: Install dependencies
+ run: |
+ cd apps/web
+ npm ci
+
+ - name: Run tests
+ run: |
+ cd apps/web
+ npm test -- --coverage --watchAll=false
+
+ - name: Upload coverage
+ uses: codecov/codecov-action@v4
+ with:
+ directory: ./apps/web/coverage
+ flags: frontend
+
+ test-contracts:
+ name: Smart Contract Tests
+ runs-on: ubuntu-latest
+ if: contains(github.event.pull_request.changed_files, 'contracts/')
+ steps:
+ - uses: actions/checkout@v4
+ with:
+ submodules: recursive
+
+ - name: Setup Foundry
+ uses: foundry-rs/foundry-toolchain@v1
+
+ - name: Run Foundry tests
+ run: |
+ cd contracts
+ forge test -vvv --gas-report
+
+ - name: Run coverage
+ run: |
+ cd contracts
+ forge coverage --report lcov
+
+ - name: Upload coverage
+ uses: codecov/codecov-action@v4
+ with:
+ directory: ./contracts
+ flags: contracts
+
+ security-scan:
+ name: Security Scan
+ runs-on: ubuntu-latest
+ steps:
+ - uses: actions/checkout@v4
+
+ - name: Run Slither (Smart Contracts)
+ if: contains(github.event.pull_request.changed_files, 'contracts/')
+ uses: crytic/slither-action@v0.3.0
+ continue-on-error: true
+ with:
+ target: contracts/
+ slither-args: --filter-paths "lib|test" --exclude-dependencies
+ fail-on: high
+
+ - name: Run Trivy (Dependencies & IaC)
+ uses: aquasecurity/trivy-action@master
+ with:
+ scan-type: 'fs'
+ scan-ref: '.'
+ severity: 'CRITICAL,HIGH'
+ format: 'sarif'
+ output: 'trivy-results.sarif'
+
+ - name: Upload Trivy results to GitHub Security
+ uses: github/codeql-action/upload-sarif@v3
+ if: always()
+ with:
+ sarif_file: 'trivy-results.sarif'
+
+ - name: Run Bandit (Python)
+ run: |
+ pip install bandit
+ bandit -r hyperagent/ -f json -o bandit-report.json || true
+
+ - name: Upload Bandit results
+ uses: actions/upload-artifact@v4
+ if: always()
+ with:
+ name: bandit-report
+ path: bandit-report.json
+
+ pr-size-check:
+ name: PR Size Check
+ runs-on: ubuntu-latest
+ steps:
+ - uses: actions/checkout@v4
+ with:
+ fetch-depth: 0
+
+ - name: Check PR size
+ run: |
+ files_changed=$(git diff --name-only origin/${{ github.base_ref }}...HEAD | wc -l)
+ lines_changed=$(git diff --shortstat origin/${{ github.base_ref }}...HEAD | awk '{print $4+$6}')
+
+ echo "Files changed: $files_changed"
+ echo "Lines changed: $lines_changed"
+
+ if [ "$files_changed" -gt 50 ]; then
+ echo "::warning::PR modifies $files_changed files. Consider breaking into smaller PRs."
+ fi
+
+ if [ "$lines_changed" -gt 1000 ]; then
+ echo "::warning::PR changes $lines_changed lines. Consider breaking into smaller PRs."
+ fi
+
+ conventional-commits:
+ name: Validate Commit Messages
+ runs-on: ubuntu-latest
+ steps:
+ - uses: actions/checkout@v4
+ with:
+ fetch-depth: 0
+
+ - name: Check commit messages
+ run: |
+ pip install gitlint
+
+ # Check all commits in this PR
+ git log --format=%B origin/${{ github.base_ref }}..HEAD | \
+ gitlint --config .gitlint || true
+
+ build-docker:
+ name: Build Docker Images
+ runs-on: ubuntu-latest
+ steps:
+ - uses: actions/checkout@v4
+
+ - name: Set up Docker Buildx
+ uses: docker/setup-buildx-action@v3
+
+ - name: Build backend image
+ uses: docker/build-push-action@v5
+ with:
+ context: .
+ file: ./docker/Dockerfile.backend
+ push: false
+ tags: hyperagent-backend:pr-${{ github.event.pull_request.number }}
+ cache-from: type=gha
+ cache-to: type=gha,mode=max
+
+ - name: Build frontend image
+ uses: docker/build-push-action@v5
+ with:
+ context: ./apps/web
+ file: ./apps/web/Dockerfile
+ push: false
+ tags: hyperagent-frontend:pr-${{ github.event.pull_request.number }}
+ cache-from: type=gha
+ cache-to: type=gha,mode=max
+
+ label-pr:
+ name: Auto-label PR
+ runs-on: ubuntu-latest
+ permissions:
+ pull-requests: write
+ steps:
+ - uses: actions/labeler@v5
+ with:
+ repo-token: ${{ secrets.GITHUB_TOKEN }}
+ configuration-path: .github/labeler.yml
+
+ pr-comment-summary:
+ name: PR Summary Comment
+ runs-on: ubuntu-latest
+ needs: [lint-python, test-backend, security-scan]
+ if: always()
+ permissions:
+ pull-requests: write
+ steps:
+ - name: Comment PR
+ uses: actions/github-script@v7
+ with:
+ script: |
+ const summary = `## PR Validation Summary
+
+ | Check | Status |
+ |-------|--------|
+ | Lint Python | ${{ needs.lint-python.result == 'success' && '✅' || '❌' }} |
+ | Backend Tests | ${{ needs.test-backend.result == 'success' && '✅' || '❌' }} |
+ | Security Scan | ${{ needs.security-scan.result == 'success' && '✅' || '❌' }} |
+
+ ${needs.test-backend.result !== 'success' ? '⚠️ **Backend tests failed. Please review the logs.**' : ''}
+ ${needs.security-scan.result !== 'success' ? '⚠️ **Security scan found issues. Please address them.**' : ''}
+ `;
+
+ github.rest.issues.createComment({
+ owner: context.repo.owner,
+ repo: context.repo.repo,
+ issue_number: context.issue.number,
+ body: summary
+ });
diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
index 9ea57a5..1f2eab3 100644
--- a/.github/workflows/release.yml
+++ b/.github/workflows/release.yml
@@ -1,277 +1,305 @@
-# Semantic Versioning Release Workflow
-name: Release
+name: Create Release
on:
push:
tags:
- - 'v*.*.*' # Trigger on semantic version tags (e.g., v1.0.0, v1.2.3)
+ - 'v*'
-env:
- REGISTRY: ghcr.io
- IMAGE_NAME: ${{ github.repository }}
- PYTHON_VERSION: '3.10'
+permissions:
+ contents: write
+ packages: write
jobs:
- # ============================================================================
- # STAGE 1: VALIDATE TAG
- # ============================================================================
-
validate-tag:
- name: '[*] Validate Release Tag'
+ name: Validate Tag Format
runs-on: ubuntu-latest
steps:
- - uses: actions/checkout@v4
- with:
- fetch-depth: 0 # Fetch all history for changelog generation
-
- - name: Extract version from tag
- id: version
+ - name: Validate semver tag
run: |
- VERSION=${GITHUB_REF#refs/tags/v}
- echo "version=$VERSION" >> $GITHUB_OUTPUT
- echo "Version: $VERSION"
-
- - name: Validate semantic version format
- run: |
- VERSION="${{ steps.version.outputs.version }}"
- if [[ ! $VERSION =~ ^[0-9]+\.[0-9]+\.[0-9]+$ ]]; then
- echo "Error: Invalid semantic version format: $VERSION"
- echo "Expected format: MAJOR.MINOR.PATCH (e.g., 1.0.0)"
+ if [[ ! "${{ github.ref_name }}" =~ ^v[0-9]+\.[0-9]+\.[0-9]+(-[a-zA-Z0-9.]+)?$ ]]; then
+ echo "Invalid tag format. Must be vX.Y.Z or vX.Y.Z-prerelease"
exit 1
fi
- echo "✓ Valid semantic version: $VERSION"
- # ============================================================================
- # STAGE 2: BUILD AND TEST
- # ============================================================================
-
- build-and-test:
- name: '[BUILD] Build and Test Release'
+ build-and-push-release:
+ name: Build and Push Release Images
runs-on: ubuntu-latest
needs: validate-tag
- services:
- postgres:
- image: postgres:15-alpine
- env:
- POSTGRES_DB: hyperagent_test
- POSTGRES_USER: test_user
- POSTGRES_PASSWORD: test_password
- options: >-
- --health-cmd pg_isready
- --health-interval 10s
- --health-timeout 5s
- --health-retries 5
- ports:
- - 5432:5432
-
- redis:
- image: redis:7-alpine
- options: >-
- --health-cmd "redis-cli ping"
- --health-interval 10s
- --health-timeout 5s
- --health-retries 5
- ports:
- - 6379:6379
+ outputs:
+ backend_image: ${{ steps.backend-meta.outputs.tags }}
+ frontend_image: ${{ steps.frontend-meta.outputs.tags }}
steps:
- uses: actions/checkout@v4
- - name: Set up Python
- uses: actions/setup-python@v4
- with:
- python-version: ${{ env.PYTHON_VERSION }}
- cache: 'pip'
-
- - name: Set up Node.js
- uses: actions/setup-node@v4
- with:
- node-version: '18'
- cache: 'npm'
- cache-dependency-path: frontend/package-lock.json
-
- - name: Install Python dependencies
- run: |
- python -m pip install --upgrade pip
- pip install -r requirements.txt
- pip install pytest pytest-asyncio pytest-cov
-
- - name: Install frontend dependencies
- working-directory: ./frontend
- run: npm ci
-
- - name: Set up database
- run: |
- PGPASSWORD=test_password psql -h localhost -U test_user -d hyperagent_test -c "CREATE EXTENSION IF NOT EXISTS vector;"
- env:
- PGHOST: localhost
- PGPORT: 5432
- PGUSER: test_user
- PGDATABASE: hyperagent_test
-
- - name: Run Python tests
- run: |
- pytest tests/ -v --cov=hyperagent --cov-report=xml --cov-report=term
- env:
- DATABASE_URL: postgresql://test_user:test_password@localhost:5432/hyperagent_test
- REDIS_URL: redis://localhost:6379/0
- GEMINI_API_KEY: ${{ secrets.GEMINI_API_KEY }}
-
- - name: Check test coverage
- run: |
- coverage report --fail-under=80
-
- - name: Run frontend tests
- working-directory: ./frontend
- run: npm test
-
- - name: Run frontend lint
- working-directory: ./frontend
- run: npm run lint
-
- # ============================================================================
- # STAGE 3: BUILD DOCKER IMAGE
- # ============================================================================
-
- build-docker:
- name: '[BUILD] Docker Image'
- runs-on: ubuntu-latest
- needs: [validate-tag, build-and-test]
- permissions:
- contents: read
- packages: write
-
- steps:
- - uses: actions/checkout@v4
-
- - name: Extract version from tag
- id: version
- run: |
- VERSION=${GITHUB_REF#refs/tags/v}
- echo "version=$VERSION" >> $GITHUB_OUTPUT
-
- name: Set up Docker Buildx
uses: docker/setup-buildx-action@v3
- - name: Log in to Container Registry
+ - name: Log in to GitHub Container Registry
uses: docker/login-action@v3
with:
- registry: ${{ env.REGISTRY }}
+ registry: ghcr.io
username: ${{ github.actor }}
password: ${{ secrets.GITHUB_TOKEN }}
- - name: Extract metadata
- id: meta
- uses: docker/metadata-action@v4
+ - name: Backend metadata
+ id: backend-meta
+ uses: docker/metadata-action@v5
+ with:
+ images: ghcr.io/${{ github.repository }}/backend
+ tags: |
+ type=semver,pattern={{version}}
+ type=semver,pattern={{major}}.{{minor}}
+ type=semver,pattern={{major}}
+
+ - name: Frontend metadata
+ id: frontend-meta
+ uses: docker/metadata-action@v5
with:
- images: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}
+ images: ghcr.io/${{ github.repository }}/frontend
tags: |
type=semver,pattern={{version}}
type=semver,pattern={{major}}.{{minor}}
type=semver,pattern={{major}}
- type=raw,value=latest
- - name: Build and push Docker image
- uses: docker/build-push-action@v4
+ - name: Build and push backend
+ uses: docker/build-push-action@v5
with:
context: .
- file: ./Dockerfile
+ file: ./docker/Dockerfile.backend
push: true
- tags: ${{ steps.meta.outputs.tags }}
- labels: ${{ steps.meta.outputs.labels }}
+ tags: ${{ steps.backend-meta.outputs.tags }}
+ labels: ${{ steps.backend-meta.outputs.labels }}
cache-from: type=gha
cache-to: type=gha,mode=max
- platforms: linux/amd64,linux/arm64
build-args: |
- BUILDKIT_INLINE_CACHE=1
- VERSION=${{ steps.version.outputs.version }}
+ VERSION=${{ github.ref_name }}
+ COMMIT_SHA=${{ github.sha }}
+
+ - name: Build and push frontend
+ uses: docker/build-push-action@v5
+ with:
+ context: ./apps/web
+ file: ./apps/web/Dockerfile
+ push: true
+ tags: ${{ steps.frontend-meta.outputs.tags }}
+ labels: ${{ steps.frontend-meta.outputs.labels }}
+ cache-from: type=gha
+ cache-to: type=gha,mode=max
+ build-args: |
+ VERSION=${{ github.ref_name }}
- # ============================================================================
- # STAGE 4: CREATE GITHUB RELEASE
- # ============================================================================
-
- create-release:
- name: '[RELEASE] Create GitHub Release'
+ generate-changelog:
+ name: Generate Changelog
runs-on: ubuntu-latest
- needs: [validate-tag, build-docker]
- permissions:
- contents: write
+ needs: validate-tag
+ outputs:
+ changelog: ${{ steps.changelog.outputs.content }}
steps:
- uses: actions/checkout@v4
with:
fetch-depth: 0
- - name: Extract version from tag
- id: version
- run: |
- VERSION=${GITHUB_REF#refs/tags/v}
- echo "version=$VERSION" >> $GITHUB_OUTPUT
- echo "tag=v$VERSION" >> $GITHUB_OUTPUT
-
- name: Generate changelog
id: changelog
run: |
- TAG="${{ steps.version.outputs.tag }}"
- PREVIOUS_TAG=$(git describe --tags --abbrev=0 HEAD^ 2>/dev/null || echo "")
+ # Get previous tag
+ previous_tag=$(git describe --tags --abbrev=0 HEAD^ 2>/dev/null || echo "")
+
+ echo "Previous tag: $previous_tag"
+ echo "Current tag: ${{ github.ref_name }}"
+
+ # Generate changelog sections
+ changelog="## What's Changed\n\n"
- if [ -z "$PREVIOUS_TAG" ]; then
- echo "No previous tag found, generating full changelog"
- CHANGELOG=$(git log --pretty=format:"- %s (%h)" --no-merges)
- else
- echo "Generating changelog from $PREVIOUS_TAG to $TAG"
- CHANGELOG=$(git log --pretty=format:"- %s (%h)" --no-merges ${PREVIOUS_TAG}..${TAG})
+ # Features
+ features=$(git log --pretty=format:"* %s (%h)" $previous_tag..HEAD --grep="^feat" || echo "")
+ if [ -n "$features" ]; then
+ changelog+="### ✨ Features\n\n$features\n\n"
fi
- # Escape newlines for GitHub output
- CHANGELOG="${CHANGELOG//$'\n'/'%0A'}"
- echo "changelog<> $GITHUB_OUTPUT
- echo "$CHANGELOG" >> $GITHUB_OUTPUT
+ # Fixes
+ fixes=$(git log --pretty=format:"* %s (%h)" $previous_tag..HEAD --grep="^fix" || echo "")
+ if [ -n "$fixes" ]; then
+ changelog+="### 🐛 Bug Fixes\n\n$fixes\n\n"
+ fi
+
+ # Breaking changes
+ breaking=$(git log --pretty=format:"* %s (%h)" $previous_tag..HEAD --grep="BREAKING" || echo "")
+ if [ -n "$breaking" ]; then
+ changelog+="### ⚠️ BREAKING CHANGES\n\n$breaking\n\n"
+ fi
+
+ # Other changes
+ others=$(git log --pretty=format:"* %s (%h)" $previous_tag..HEAD --grep="^chore\|^docs\|^refactor" || echo "")
+ if [ -n "$others" ]; then
+ changelog+="### 🔧 Other Changes\n\n$others\n\n"
+ fi
+
+ # Save to output
+ echo "content<> $GITHUB_OUTPUT
+ echo -e "$changelog" >> $GITHUB_OUTPUT
echo "EOF" >> $GITHUB_OUTPUT
+
+ create-github-release:
+ name: Create GitHub Release
+ runs-on: ubuntu-latest
+ needs: [build-and-push-release, generate-changelog]
+
+ steps:
+ - uses: actions/checkout@v4
- - name: Create GitHub Release
- uses: softprops/action-gh-release@v1
+ - name: Create Release
+ uses: actions/create-release@v1
+ env:
+ GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
with:
- tag_name: ${{ steps.version.outputs.tag }}
- name: Release ${{ steps.version.outputs.tag }}
+ tag_name: ${{ github.ref_name }}
+ release_name: Release ${{ github.ref_name }}
body: |
- ## Release ${{ steps.version.outputs.tag }}
+ # HyperAgent ${{ github.ref_name }}
+
+ ${{ needs.generate-changelog.outputs.changelog }}
+
+ ## 🚀 Deployment
- ### Changes
- ${{ steps.changelog.outputs.changelog }}
+ This release is ready for production deployment.
- ### Docker Image
- ```bash
- docker pull ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}:${{ steps.version.outputs.version }}
- docker pull ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}:latest
- ```
+ **Docker Images:**
+ - Backend: `${{ needs.build-and-push-release.outputs.backend_image }}`
+ - Frontend: `${{ needs.build-and-push-release.outputs.frontend_image }}`
- ### Installation
- See [Installation Guide](./GUIDE/GETTING_STARTED.md) for setup instructions.
+ **Deployment Steps:**
+ 1. Update ArgoCD Application to target revision `${{ github.ref_name }}`
+ 2. Manually sync in ArgoCD dashboard
+ 3. Monitor deployment health
+
+ **Approval Required:** @JustineDevs or @ArhonJay
+
+ ## 📝 Documentation
+
+ - [Release Notes](https://github.com/${{ github.repository }}/releases/tag/${{ github.ref_name }})
+ - [Deployment Guide](https://github.com/${{ github.repository }}/blob/main/docs/DEPLOYMENT.md)
draft: false
- prerelease: false
+ prerelease: ${{ contains(github.ref_name, 'rc') || contains(github.ref_name, 'beta') || contains(github.ref_name, 'alpha') }}
+
+ update-argocd-production:
+ name: Update ArgoCD Production Target
+ runs-on: ubuntu-latest
+ needs: create-github-release
+ environment:
+ name: production
+ url: https://hyperagent.io
+
+ steps:
+ - uses: actions/checkout@v4
- - name: Update CHANGELOG.md
+ - name: Update production manifests
run: |
- VERSION="${{ steps.version.outputs.version }}"
- TAG="${{ steps.version.outputs.tag }}"
- DATE=$(date +"%Y-%m-%d")
+ # Update k8s production overlay to point to new tag
+ cd k8s/overlays/production
- # Create or update CHANGELOG.md
- if [ ! -f CHANGELOG.md ]; then
- echo "# Changelog" > CHANGELOG.md
- echo "" >> CHANGELOG.md
- echo "All notable changes to this project will be documented in this file." >> CHANGELOG.md
- echo "" >> CHANGELOG.md
- fi
-
- # Add new release section at the top
- sed -i "1i\\\n## [$TAG] - $DATE\n\n### Added\n- Release $TAG\n\n### Changed\n\n### Fixed\n\n" CHANGELOG.md
+ kustomize edit set image \
+ hyperagent-backend=${{ needs.build-and-push-release.outputs.backend_image }}
- # Commit and push CHANGELOG.md update
+ kustomize edit set image \
+ hyperagent-frontend=${{ needs.build-and-push-release.outputs.frontend_image }}
+
+ - name: Create PR to main with manifest updates
+ run: |
git config user.name "github-actions[bot]"
git config user.email "github-actions[bot]@users.noreply.github.com"
- git add CHANGELOG.md
- git commit -m "chore: update CHANGELOG.md for $TAG" || echo "No changes to commit"
- git push || echo "Nothing to push"
- continue-on-error: true
+
+ git checkout -b release/deploy-${{ github.ref_name }}
+ git add k8s/overlays/production/
+ git commit -m "chore(release): update production images to ${{ github.ref_name }}"
+ git push origin release/deploy-${{ github.ref_name }}
+
+ gh pr create \
+ --base main \
+ --title "Deploy ${{ github.ref_name }} to Production" \
+ --body "Automated PR to update production manifests for release ${{ github.ref_name }}" \
+ --label "deployment,production"
+ env:
+ GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+
+ - name: Install ArgoCD CLI
+ run: |
+ curl -sSL -o /usr/local/bin/argocd https://github.com/argoproj/argo-cd/releases/latest/download/argocd-linux-amd64
+ chmod +x /usr/local/bin/argocd
+
+ - name: Update ArgoCD app (manual sync required)
+ run: |
+ argocd login ${{ secrets.ARGOCD_SERVER }} \
+ --username admin \
+ --password ${{ secrets.ARGOCD_PASSWORD }} \
+ --grpc-web
+
+ # Update target revision (but don't auto-sync)
+ argocd app set hyperagent-production --revision ${{ github.ref_name }}
+
+ echo "Production app updated to track ${{ github.ref_name }}"
+ echo "Manual sync required in ArgoCD dashboard"
+
+ notify-release:
+ name: Notify Team
+ runs-on: ubuntu-latest
+ needs: [create-github-release, update-argocd-production]
+ if: always()
+
+ steps:
+ - name: Notify Slack
+ uses: slackapi/slack-github-action@v1
+ with:
+ payload: |
+ {
+ "text": "🎉 New release ${{ github.ref_name }} is ready for production deployment",
+ "blocks": [
+ {
+ "type": "header",
+ "text": {
+ "type": "plain_text",
+ "text": "🚀 Release ${{ github.ref_name }}"
+ }
+ },
+ {
+ "type": "section",
+ "text": {
+ "type": "mrkdwn",
+ "text": "*Status:* Ready for Production Deployment\n*Release:* \n*ArgoCD:* "
+ }
+ },
+ {
+ "type": "section",
+ "text": {
+ "type": "mrkdwn",
+ "text": "⚠️ *Approval Required:* @JustineDevs or @ArhonJay must approve production deployment in ArgoCD"
+ }
+ },
+ {
+ "type": "actions",
+ "elements": [
+ {
+ "type": "button",
+ "text": {
+ "type": "plain_text",
+ "text": "View Release"
+ },
+ "url": "https://github.com/${{ github.repository }}/releases/tag/${{ github.ref_name }}"
+ },
+ {
+ "type": "button",
+ "text": {
+ "type": "plain_text",
+ "text": "ArgoCD Dashboard"
+ },
+ "url": "https://argocd.hyperagent.io/applications/hyperagent-production",
+ "style": "primary"
+ }
+ ]
+ }
+ ]
+ }
+ env:
+ SLACK_WEBHOOK_URL: ${{ secrets.SLACK_WEBHOOK }}
diff --git a/.gitignore b/.gitignore
index 5a30226..fc3dc6c 100644
--- a/.gitignore
+++ b/.gitignore
@@ -1,234 +1,456 @@
-# Byte-compiled / optimized / DLL files
+# ============================================================
+# AI Agent Directories
+# ============================================================
+.agent/
+.agents/
+.claude/
+.cline/
+.codebuddy/
+.commandcode/
+.continue/
+.crush/
+.factory/
+.goose/
+.kilocode/
+.kiro/
+.mcpjam/
+.mux/
+.neovate/
+.openhands/
+.pi/
+.qoder/
+.qwen/
+.roo/
+.trae/
+.windsurf/
+.zencoder/
+skills/
+!.cursor/skills/
+
+# ============================================================
+# SECURITY & CREDENTIALS (CRITICAL - Never commit these!)
+# ============================================================
+# Environment variables and secrets
+.env
+.env.*
+!.env.example
+!.env.template
+!.env.*.example
+.env.local
+.env.*.local
+.env.development
+.env.production
+.env.staging
+.env.test
+*.env
+# Per-app env files (only .example files are tracked)
+apps/*/.env.local
+apps/*/.env.*.local
+apps/*/.env.issue.local
+secrets/
+secrets.yaml
+secrets.yml
+*.secret
+*.key
+*.pem
+*.p12
+*.pfx
+*.jks
+*.keystore
+*.crt
+*.cer
+*.p7b
+*.p7c
+*.p7m
+*.p7s
+*.p8
+*.p8e
+*.p10
+*.p12
+*.pfx
+*.keytab
+*.kdb
+*.kdbx
+*.kwallet
+*.kwallet5
+*.kwallet6
+credentials/
+credentials.json
+credentials.yaml
+credentials.yml
+*.credentials
+*.token
+*.tokens
+*.auth
+*.authz
+*.passwd
+*.password
+*.pwd
+*.priv
+*.private
+*.privkey
+*.secretkey
+*.apikey
+*.api_key
+*.api-key
+*.access_token
+*.access-token
+*.refresh_token
+*.refresh-token
+*.session
+*.sessions
+*.cookie
+*.cookies
+*.jwt
+*.jwks
+config/secrets.*
+config/*.secret
+config/*.key
+config/*.token
+
+# GitHub tokens and keys
+*.gh_token
+*.github_token
+*.ghp_*
+gh_token.txt
+github_token.txt
+
+# AWS credentials
+.aws/
+aws-credentials
+*.aws
+*.awscredentials
+
+# Google Cloud credentials
+.gcloud/
+*.gcp
+*.gcloud
+gcp-key.json
+service-account*.json
+
+# Azure credentials
+.azure/
+*.azure
+azure-credentials
+
+# Database credentials
+*.db.password
+*.db.pass
+database.credentials
+db.secret
+
+# API keys and tokens
+api_keys.txt
+api-keys.txt
+*.apikey
+*.api_key
+tokens.txt
+*.token.txt
+
+# ============================================================
+# BUILD ARTIFACTS & COMPILED FILES
+# ============================================================
+# Python
__pycache__/
*.py[cod]
*$py.class
-
-# C extensions
*.so
-
-# Distribution / packaging
.Python
-build/
-develop-eggs/
-dist/
-downloads/
-eggs/
-.eggs/
-lib/
-lib64/
-parts/
-sdist/
-var/
-wheels/
-pip-wheel-metadata/
-share/python-wheels/
*.egg-info/
-.installed.cfg
+dist/
+build/
*.egg
-MANIFEST
-
-# PyInstaller
-*.manifest
-*.spec
-
-# Installer logs
+*.whl
+.eggs/
pip-log.txt
pip-delete-this-directory.txt
-
-# Unit test / coverage reports
+.pytest_cache/
+.coverage
htmlcov/
.tox/
-.nox/
-.coverage
-.coverage.*
-.cache
-nosetests.xml
-coverage.xml
*.cover
-*.py,cover
.hypothesis/
-.pytest_cache/
-
-# Translations
-*.mo
-*.pot
-
-# Django stuff:
-*.log
-local_settings.py
-db.sqlite3
-db.sqlite3-journal
-
-# Flask stuff:
-instance/
-.webassets-cache
-
-# Scrapy stuff:
-.scrapy
-
-# Sphinx documentation
-docs/_build/
-
-# PyBuilder
-target/
-
-# Jupyter Notebook
-.ipynb_checkpoints
-
-# IPython
-profile_default/
-ipython_config.py
-
-# pyenv
-.python-version
-
-# pipenv
-Pipfile.lock
-
-# PEP 582
-__pypackages__/
-
-# Celery stuff
-celerybeat-schedule
-celerybeat.pid
-
-# SageMath parsed files
-*.sage.py
-
-# Environments
-.env
-.venv
-env/
-venv/
-ENV/
-env.bak/
-venv.bak/
-
-# Spyder project settings
-.spyderproject
-.spyproject
-
-# Rope project settings
-.ropeproject
-
-# mkdocs documentation
-/site
-
-# mypy
.mypy_cache/
.dmypy.json
dmypy.json
+.pytype/
+cython_debug/
-# Pyre type checker
-.pyre/
+# Node.js
+node_modules/
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+lerna-debug.log*
+.pnpm-debug.log*
+.npm
+.eslintcache
+.node_repl_history
+*.tgz
+.yarn-integrity
+.yarn/cache
+.yarn/unplugged
+.yarn/build-state.yml
+.yarn/install-state.gz
+.pnp.*
+.next/
+out/
+.nuxt/
+.cache/
+.parcel-cache/
+.vuepress/dist/
+.serverless/
+.fusebox/
+.dynamodb/
+.tern-port
+*.tsbuildinfo
+
+# TypeScript
+*.tsbuildinfo
+.tsbuildinfo
+
+# Rust
+target/
+Cargo.lock
+**/*.rs.bk
-# IDEs
+# Go
+*.exe
+*.exe~
+*.dll
+*.so
+*.dylib
+*.test
+*.out
+go.work
+
+# Java
+*.class
+*.jar
+*.war
+*.ear
+*.nar
+hs_err_pid*
+replay_pid*
+
+# ============================================================
+# IDE & EDITOR FILES
+# ============================================================
+# VSCode
.vscode/
+!.vscode/settings.json
+!.vscode/tasks.json
+!.vscode/launch.json
+!.vscode/extensions.json
+*.code-workspace
+
+# JetBrains IDEs
.idea/
+*.iml
+*.iws
+*.ipr
+out/
+
+# Sublime Text
+*.sublime-project
+*.sublime-workspace
+
+# Vim
*.swp
*.swo
*~
-.DS_Store
+.vim/
+.netrwhist
-# Project specific
-logs/
+# Emacs
+*~
+\#*\#
+/.emacs.desktop
+/.emacs.desktop.lock
+*.elc
+auto-save-list
+tramp
+.\#*
+
+# ============================================================
+# OS FILES
+# ============================================================
+# macOS
+.DS_Store
+.AppleDouble
+.LSOverride
+Icon
+._*
+.DocumentRevisions-V100
+.fseventsd
+.Spotlight-V100
+.TemporaryItems
+.Trashes
+.VolumeIcon.icns
+.com.apple.timemachine.donotpresent
+.AppleDB
+.AppleDesktop
+Network Trash Folder
+Temporary Items
+.apdisk
+
+# Windows
+Thumbs.db
+Thumbs.db:encryptable
+ehthumbs.db
+ehthumbs_vista.db
+*.stackdump
+[Dd]esktop.ini
+$RECYCLE.BIN/
+*.cab
+*.msi
+*.msix
+*.msm
+*.msp
+*.lnk
+
+# Linux
+*~
+.fuse_hidden*
+.directory
+.Trash-*
+.nfs*
+
+# ============================================================
+# LOGS & TEMPORARY FILES
+# ============================================================
*.log
-.env.local
-.env.*.local
-.env.production
-.env.development
-
-# Database
-*.db
-*.sqlite
-*.sqlite3
-
-# Docker
-.dockerignore
-
-# Secrets
-secrets/
-*.pem
-*.key
-*.crt
-
-# Temporary files
+*.log.*
+logs/
+*.log.*
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+lerna-debug.log*
+.pnpm-debug.log*
+*.tmp
+*.temp
+*.bak
+*.backup
+*.swp
+*.swo
+*.orig
+*.save
+*.old
+*.cache
+.cache/
tmp/
temp/
-*.tmp
+.tmp/
+.temp/
+# ============================================================
+# TESTING & COVERAGE
+# ============================================================
# Coverage reports
+coverage/
+.nyc_output/
.coverage
+*.cover
+.hypothesis/
+.pytest_cache/
htmlcov/
+.tox/
+.coverage.*
coverage.xml
+*.lcov
+.coveragerc
+
+# Test results
+test-results/
+test-results.xml
+junit.xml
+*.test.xml
+
+# ============================================================
+# DOCKER & CONTAINERS
+# ============================================================
+.dockerignore
+docker-compose.override.yml
+*.dockerignore
-# Build artifacts
-build/
-dist/
-*.whl
-
-# Alembic
-alembic/versions/*.pyc
-
-# Redis dumps
-dump.rdb
-
-# Node modules (if any)
-node_modules/
-
-# Contract artifacts
-artifacts/
-contracts/artifacts/
-contracts/cache/
-
-# Hardhat/Foundry
-cache/
-out/
-broadcast/
-
-# Additional generated files
-*.pyc
-*.pyo
-*.pyd
-hyperagent.egg-info/
-
-# Test artifacts
-.pytest_cache/
-test_output/
-test_results/
-*.test.log
-
-# Workflow reports (if auto-generated)
-# examples/report.md
-# examples/*_workflow.json
+# ============================================================
+# DATABASES
+# ============================================================
+*.db
+*.sqlite
+*.sqlite3
+*.db-shm
+*.db-wal
+*.db-journal
+*.s3db
+*.sl3
+*.db3
+
+# ============================================================
+# DOCUMENTATION BUILDS
+# ============================================================
+docs/_build/
+docs/.doctrees/
+site/
+_site/
+.jekyll-cache/
+.jekyll-metadata
+
+# ============================================================
+# MISC
+# ============================================================
+# Archives
+*.zip
+*.tar
+*.tar.gz
+*.rar
+*.7z
+*.gz
+*.bz2
+*.xz
+
+# Lock files (keep package-lock.json but ignore others)
+yarn.lock
+pnpm-lock.yaml
+poetry.lock
+Pipfile.lock
+Gemfile.lock
-# Version files (if auto-generated)
-# VERSION
+# Local configuration
+local/
+.local/
+*.local
-# Cursor/IDE specific
-.cursor/
-.cursorrules
+# Backup files
+*.bak
+*.backup
+*.old
+*.orig
-# OS-specific
-Thumbs.db
-.AppleDouble
-.LSOverride
+# System files
+.directory
+.Trash-*
+.nfs*
-# Virtual environment (should not be committed)
-venv/
-env/
-ENV/
-.venv/
-
-# Frontend (Next.js)
-frontend/.next/
-frontend/out/
-frontend/node_modules/
-frontend/.env.local
-frontend/.env*.local
-frontend/.vercel
-frontend/.swc/
-
-reference/
-.cursor/
-.cursor/rules
\ No newline at end of file
+# Project specific
+.vercel
+.netlify
+.railway
+.now
+.turbo
+
+# ============================================================
+# DOCUMENTATION & SCRIPTS (Project-specific ignores)
+# ============================================================
+# Planning documents
+docs/plan/
+
+# Compliance documentation
+scripts/docs/compliance/
+
+# GitHub automation documentation
+scripts/docs/github-automation/
+
+# GitHub automation scripts
+scripts/github/
\ No newline at end of file
diff --git a/.gitlint b/.gitlint
new file mode 100644
index 0000000..3c2c7e7
--- /dev/null
+++ b/.gitlint
@@ -0,0 +1,37 @@
+# gitlint configuration
+# https://jorisroovers.com/gitlint/
+
+[general]
+# Enable all default rules
+ignore=
+# Ignore merge commits, fixup commits, squash commits
+ignore-merge-commits=true
+ignore-fixup-commits=true
+ignore-squash-commits=true
+# Use Python regex
+regex-style-search=true
+
+[title-max-length]
+line-length=72
+
+[title-must-not-contain-word]
+# Words that should not appear in title
+words=wip,WIP,fixup,squash
+
+[title-match-regex]
+# Conventional Commits format
+regex=^(feat|fix|docs|style|refactor|perf|test|chore|ci|build|revert)(\([\w-]+\))?!?: .+
+
+[body-max-line-length]
+line-length=100
+
+[body-min-length]
+min-length=0
+
+[body-is-missing]
+# Allow commits without body
+ignore-merge-commits=true
+
+[body-changed-file-mention]
+# Don't require file mentions in body
+enabled=false
diff --git a/.gitmessage b/.gitmessage
deleted file mode 100644
index c93764d..0000000
--- a/.gitmessage
+++ /dev/null
@@ -1,21 +0,0 @@
-# HyperAgent Commit Message Template
-
-# Type: feat, fix, docs, style, refactor, test, chore
-# Scope: component or module (optional)
-# Subject: brief description (50 chars max)
-
-# Body: detailed explanation (optional)
-# - What changed
-# - Why it changed
-# - How it changed
-
-# Footer: references and breaking changes (optional)
-# Fixes #123
-# Breaking change: description
-
-# Examples:
-# feat(workflow): add constructor argument generation
-# fix(deployment): resolve constructor argument validation issue
-# docs(readme): update prerequisites section
-# chore: update .gitignore for branch management
-
diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml
deleted file mode 100644
index fd1f49c..0000000
--- a/.pre-commit-config.yaml
+++ /dev/null
@@ -1,60 +0,0 @@
-# Pre-commit hooks for HyperAgent
-# Install with: pip install pre-commit && pre-commit install
-# Run manually: pre-commit run --all-files
-
-repos:
- - repo: https://github.com/pre-commit/pre-commit-hooks
- rev: v4.5.0
- hooks:
- - id: trailing-whitespace
- - id: end-of-file-fixer
- - id: check-yaml
- - id: check-json
- - id: check-toml
- - id: check-added-large-files
- args: ['--maxkb=1000']
- - id: check-merge-conflict
- - id: detect-private-key
- - id: check-case-conflict
- - id: check-docstring-first
-
- - repo: https://github.com/psf/black
- rev: 24.1.1
- hooks:
- - id: black
- language_version: python3.10
- args: ['--line-length=100']
-
- - repo: https://github.com/pycqa/isort
- rev: 5.13.2
- hooks:
- - id: isort
- args: ['--profile=black', '--line-length=100']
-
- - repo: https://github.com/pre-commit/mirrors-mypy
- rev: v1.8.0
- hooks:
- - id: mypy
- additional_dependencies: [types-all]
- args: ['--ignore-missing-imports']
- exclude: ^(tests/|alembic/|scripts/)
-
- - repo: https://github.com/PyCQA/bandit
- rev: 1.7.6
- hooks:
- - id: bandit
- args: ['-r', 'hyperagent/', '-f', 'json', '-o', 'bandit-report.json']
- exclude: ^tests/
-
- - repo: https://github.com/pre-commit/mirrors-eslint
- rev: v9.0.0
- hooks:
- - id: eslint
- files: ^frontend/.*\.(js|jsx|ts|tsx)$
- additional_dependencies:
- - eslint@9
- - '@typescript-eslint/eslint-plugin@^7.0.0'
- - '@typescript-eslint/parser@^7.0.0'
- - eslint-config-next@16.0.3
- args: ['--fix']
-
diff --git a/.windsurf/skills/find-skills/SKILL.md b/.windsurf/skills/find-skills/SKILL.md
new file mode 100644
index 0000000..c797184
--- /dev/null
+++ b/.windsurf/skills/find-skills/SKILL.md
@@ -0,0 +1,133 @@
+---
+name: find-skills
+description: Helps users discover and install agent skills when they ask questions like "how do I do X", "find a skill for X", "is there a skill that can...", or express interest in extending capabilities. This skill should be used when the user is looking for functionality that might exist as an installable skill.
+---
+
+# Find Skills
+
+This skill helps you discover and install skills from the open agent skills ecosystem.
+
+## When to Use This Skill
+
+Use this skill when the user:
+
+- Asks "how do I do X" where X might be a common task with an existing skill
+- Says "find a skill for X" or "is there a skill for X"
+- Asks "can you do X" where X is a specialized capability
+- Expresses interest in extending agent capabilities
+- Wants to search for tools, templates, or workflows
+- Mentions they wish they had help with a specific domain (design, testing, deployment, etc.)
+
+## What is the Skills CLI?
+
+The Skills CLI (`npx skills`) is the package manager for the open agent skills ecosystem. Skills are modular packages that extend agent capabilities with specialized knowledge, workflows, and tools.
+
+**Key commands:**
+
+- `npx skills find [query]` - Search for skills interactively or by keyword
+- `npx skills add ` - Install a skill from GitHub or other sources
+- `npx skills check` - Check for skill updates
+- `npx skills update` - Update all installed skills
+
+**Browse skills at:** https://skills.sh/
+
+## How to Help Users Find Skills
+
+### Step 1: Understand What They Need
+
+When a user asks for help with something, identify:
+
+1. The domain (e.g., React, testing, design, deployment)
+2. The specific task (e.g., writing tests, creating animations, reviewing PRs)
+3. Whether this is a common enough task that a skill likely exists
+
+### Step 2: Search for Skills
+
+Run the find command with a relevant query:
+
+```bash
+npx skills find [query]
+```
+
+For example:
+
+- User asks "how do I make my React app faster?" → `npx skills find react performance`
+- User asks "can you help me with PR reviews?" → `npx skills find pr review`
+- User asks "I need to create a changelog" → `npx skills find changelog`
+
+The command will return results like:
+
+```
+Install with npx skills add
+
+vercel-labs/agent-skills@vercel-react-best-practices
+└ https://skills.sh/vercel-labs/agent-skills/vercel-react-best-practices
+```
+
+### Step 3: Present Options to the User
+
+When you find relevant skills, present them to the user with:
+
+1. The skill name and what it does
+2. The install command they can run
+3. A link to learn more at skills.sh
+
+Example response:
+
+```
+I found a skill that might help! The "vercel-react-best-practices" skill provides
+React and Next.js performance optimization guidelines from Vercel Engineering.
+
+To install it:
+npx skills add vercel-labs/agent-skills@vercel-react-best-practices
+
+Learn more: https://skills.sh/vercel-labs/agent-skills/vercel-react-best-practices
+```
+
+### Step 4: Offer to Install
+
+If the user wants to proceed, you can install the skill for them:
+
+```bash
+npx skills add -g -y
+```
+
+The `-g` flag installs globally (user-level) and `-y` skips confirmation prompts.
+
+## Common Skill Categories
+
+When searching, consider these common categories:
+
+| Category | Example Queries |
+| --------------- | ---------------------------------------- |
+| Web Development | react, nextjs, typescript, css, tailwind |
+| Testing | testing, jest, playwright, e2e |
+| DevOps | deploy, docker, kubernetes, ci-cd |
+| Documentation | docs, readme, changelog, api-docs |
+| Code Quality | review, lint, refactor, best-practices |
+| Design | ui, ux, design-system, accessibility |
+| Productivity | workflow, automation, git |
+
+## Tips for Effective Searches
+
+1. **Use specific keywords**: "react testing" is better than just "testing"
+2. **Try alternative terms**: If "deploy" doesn't work, try "deployment" or "ci-cd"
+3. **Check popular sources**: Many skills come from `vercel-labs/agent-skills` or `ComposioHQ/awesome-claude-skills`
+
+## When No Skills Are Found
+
+If no relevant skills exist:
+
+1. Acknowledge that no existing skill was found
+2. Offer to help with the task directly using your general capabilities
+3. Suggest the user could create their own skill with `npx skills init`
+
+Example:
+
+```
+I searched for skills related to "xyz" but didn't find any matches.
+I can still help you with this task directly! Would you like me to proceed?
+
+If this is something you do often, you could create your own skill:
+npx skills init my-xyz-skill
+```
diff --git a/.windsurf/skills/ui-ux-pro-max/SKILL.md b/.windsurf/skills/ui-ux-pro-max/SKILL.md
new file mode 100644
index 0000000..e58d618
--- /dev/null
+++ b/.windsurf/skills/ui-ux-pro-max/SKILL.md
@@ -0,0 +1,386 @@
+---
+name: ui-ux-pro-max
+description: "UI/UX design intelligence. 50 styles, 21 palettes, 50 font pairings, 20 charts, 9 stacks (React, Next.js, Vue, Svelte, SwiftUI, React Native, Flutter, Tailwind, shadcn/ui). Actions: plan, build, create, design, implement, review, fix, improve, optimize, enhance, refactor, check UI/UX code. Projects: website, landing page, dashboard, admin panel, e-commerce, SaaS, portfolio, blog, mobile app, .html, .tsx, .vue, .svelte. Elements: button, modal, navbar, sidebar, card, table, form, chart. Styles: glassmorphism, claymorphism, minimalism, brutalism, neumorphism, bento grid, dark mode, responsive, skeuomorphism, flat design. Topics: color palette, accessibility, animation, layout, typography, font pairing, spacing, hover, shadow, gradient. Integrations: shadcn/ui MCP for component search and examples."
+---
+
+# UI/UX Pro Max - Design Intelligence
+
+Comprehensive design guide for web and mobile applications. Contains 50+ styles, 97 color palettes, 57 font pairings, 99 UX guidelines, and 25 chart types across 9 technology stacks. Searchable database with priority-based recommendations.
+
+## When to Apply
+
+Reference these guidelines when:
+- Designing new UI components or pages
+- Choosing color palettes and typography
+- Reviewing code for UX issues
+- Building landing pages or dashboards
+- Implementing accessibility requirements
+
+## Rule Categories by Priority
+
+| Priority | Category | Impact | Domain |
+|----------|----------|--------|--------|
+| 1 | Accessibility | CRITICAL | `ux` |
+| 2 | Touch & Interaction | CRITICAL | `ux` |
+| 3 | Performance | HIGH | `ux` |
+| 4 | Layout & Responsive | HIGH | `ux` |
+| 5 | Typography & Color | MEDIUM | `typography`, `color` |
+| 6 | Animation | MEDIUM | `ux` |
+| 7 | Style Selection | MEDIUM | `style`, `product` |
+| 8 | Charts & Data | LOW | `chart` |
+
+## Quick Reference
+
+### 1. Accessibility (CRITICAL)
+
+- `color-contrast` - Minimum 4.5:1 ratio for normal text
+- `focus-states` - Visible focus rings on interactive elements
+- `alt-text` - Descriptive alt text for meaningful images
+- `aria-labels` - aria-label for icon-only buttons
+- `keyboard-nav` - Tab order matches visual order
+- `form-labels` - Use label with for attribute
+
+### 2. Touch & Interaction (CRITICAL)
+
+- `touch-target-size` - Minimum 44x44px touch targets
+- `hover-vs-tap` - Use click/tap for primary interactions
+- `loading-buttons` - Disable button during async operations
+- `error-feedback` - Clear error messages near problem
+- `cursor-pointer` - Add cursor-pointer to clickable elements
+
+### 3. Performance (HIGH)
+
+- `image-optimization` - Use WebP, srcset, lazy loading
+- `reduced-motion` - Check prefers-reduced-motion
+- `content-jumping` - Reserve space for async content
+
+### 4. Layout & Responsive (HIGH)
+
+- `viewport-meta` - width=device-width initial-scale=1
+- `readable-font-size` - Minimum 16px body text on mobile
+- `horizontal-scroll` - Ensure content fits viewport width
+- `z-index-management` - Define z-index scale (10, 20, 30, 50)
+
+### 5. Typography & Color (MEDIUM)
+
+- `line-height` - Use 1.5-1.75 for body text
+- `line-length` - Limit to 65-75 characters per line
+- `font-pairing` - Match heading/body font personalities
+
+### 6. Animation (MEDIUM)
+
+- `duration-timing` - Use 150-300ms for micro-interactions
+- `transform-performance` - Use transform/opacity, not width/height
+- `loading-states` - Skeleton screens or spinners
+
+### 7. Style Selection (MEDIUM)
+
+- `style-match` - Match style to product type
+- `consistency` - Use same style across all pages
+- `no-emoji-icons` - Use SVG icons, not emojis
+
+### 8. Charts & Data (LOW)
+
+- `chart-type` - Match chart type to data type
+- `color-guidance` - Use accessible color palettes
+- `data-table` - Provide table alternative for accessibility
+
+## How to Use
+
+Search specific domains using the CLI tool below.
+
+---
+
+## Prerequisites
+
+Check if Python is installed:
+
+```bash
+python3 --version || python --version
+```
+
+If Python is not installed, install it based on user's OS:
+
+**macOS:**
+```bash
+brew install python3
+```
+
+**Ubuntu/Debian:**
+```bash
+sudo apt update && sudo apt install python3
+```
+
+**Windows:**
+```powershell
+winget install Python.Python.3.12
+```
+
+---
+
+## How to Use This Skill
+
+When user requests UI/UX work (design, build, create, implement, review, fix, improve), follow this workflow:
+
+### Step 1: Analyze User Requirements
+
+Extract key information from user request:
+- **Product type**: SaaS, e-commerce, portfolio, dashboard, landing page, etc.
+- **Style keywords**: minimal, playful, professional, elegant, dark mode, etc.
+- **Industry**: healthcare, fintech, gaming, education, etc.
+- **Stack**: React, Vue, Next.js, or default to `html-tailwind`
+
+### Step 2: Generate Design System (REQUIRED)
+
+**Always start with `--design-system`** to get comprehensive recommendations with reasoning:
+
+```bash
+python3 skills/ui-ux-pro-max/scripts/search.py " " --design-system [-p "Project Name"]
+```
+
+This command:
+1. Searches 5 domains in parallel (product, style, color, landing, typography)
+2. Applies reasoning rules from `ui-reasoning.csv` to select best matches
+3. Returns complete design system: pattern, style, colors, typography, effects
+4. Includes anti-patterns to avoid
+
+**Example:**
+```bash
+python3 skills/ui-ux-pro-max/scripts/search.py "beauty spa wellness service" --design-system -p "Serenity Spa"
+```
+
+### Step 2b: Persist Design System (Master + Overrides Pattern)
+
+To save the design system for **hierarchical retrieval across sessions**, add `--persist`:
+
+```bash
+python3 skills/ui-ux-pro-max/scripts/search.py "" --design-system --persist -p "Project Name"
+```
+
+This creates:
+- `design-system/MASTER.md` — Global Source of Truth with all design rules
+- `design-system/pages/` — Folder for page-specific overrides
+
+**With page-specific override:**
+```bash
+python3 skills/ui-ux-pro-max/scripts/search.py "" --design-system --persist -p "Project Name" --page "dashboard"
+```
+
+This also creates:
+- `design-system/pages/dashboard.md` — Page-specific deviations from Master
+
+**How hierarchical retrieval works:**
+1. When building a specific page (e.g., "Checkout"), first check `design-system/pages/checkout.md`
+2. If the page file exists, its rules **override** the Master file
+3. If not, use `design-system/MASTER.md` exclusively
+
+**Context-aware retrieval prompt:**
+```
+I am building the [Page Name] page. Please read design-system/MASTER.md.
+Also check if design-system/pages/[page-name].md exists.
+If the page file exists, prioritize its rules.
+If not, use the Master rules exclusively.
+Now, generate the code...
+```
+
+### Step 3: Supplement with Detailed Searches (as needed)
+
+After getting the design system, use domain searches to get additional details:
+
+```bash
+python3 skills/ui-ux-pro-max/scripts/search.py "" --domain [-n ]
+```
+
+**When to use detailed searches:**
+
+| Need | Domain | Example |
+|------|--------|---------|
+| More style options | `style` | `--domain style "glassmorphism dark"` |
+| Chart recommendations | `chart` | `--domain chart "real-time dashboard"` |
+| UX best practices | `ux` | `--domain ux "animation accessibility"` |
+| Alternative fonts | `typography` | `--domain typography "elegant luxury"` |
+| Landing structure | `landing` | `--domain landing "hero social-proof"` |
+
+### Step 4: Stack Guidelines (Default: html-tailwind)
+
+Get implementation-specific best practices. If user doesn't specify a stack, **default to `html-tailwind`**.
+
+```bash
+python3 skills/ui-ux-pro-max/scripts/search.py "" --stack html-tailwind
+```
+
+Available stacks: `html-tailwind`, `react`, `nextjs`, `vue`, `svelte`, `swiftui`, `react-native`, `flutter`, `shadcn`, `jetpack-compose`
+
+---
+
+## Search Reference
+
+### Available Domains
+
+| Domain | Use For | Example Keywords |
+|--------|---------|------------------|
+| `product` | Product type recommendations | SaaS, e-commerce, portfolio, healthcare, beauty, service |
+| `style` | UI styles, colors, effects | glassmorphism, minimalism, dark mode, brutalism |
+| `typography` | Font pairings, Google Fonts | elegant, playful, professional, modern |
+| `color` | Color palettes by product type | saas, ecommerce, healthcare, beauty, fintech, service |
+| `landing` | Page structure, CTA strategies | hero, hero-centric, testimonial, pricing, social-proof |
+| `chart` | Chart types, library recommendations | trend, comparison, timeline, funnel, pie |
+| `ux` | Best practices, anti-patterns | animation, accessibility, z-index, loading |
+| `react` | React/Next.js performance | waterfall, bundle, suspense, memo, rerender, cache |
+| `web` | Web interface guidelines | aria, focus, keyboard, semantic, virtualize |
+| `prompt` | AI prompts, CSS keywords | (style name) |
+
+### Available Stacks
+
+| Stack | Focus |
+|-------|-------|
+| `html-tailwind` | Tailwind utilities, responsive, a11y (DEFAULT) |
+| `react` | State, hooks, performance, patterns |
+| `nextjs` | SSR, routing, images, API routes |
+| `vue` | Composition API, Pinia, Vue Router |
+| `svelte` | Runes, stores, SvelteKit |
+| `swiftui` | Views, State, Navigation, Animation |
+| `react-native` | Components, Navigation, Lists |
+| `flutter` | Widgets, State, Layout, Theming |
+| `shadcn` | shadcn/ui components, theming, forms, patterns |
+| `jetpack-compose` | Composables, Modifiers, State Hoisting, Recomposition |
+
+---
+
+## Example Workflow
+
+**User request:** "Làm landing page cho dịch vụ chăm sóc da chuyên nghiệp"
+
+### Step 1: Analyze Requirements
+- Product type: Beauty/Spa service
+- Style keywords: elegant, professional, soft
+- Industry: Beauty/Wellness
+- Stack: html-tailwind (default)
+
+### Step 2: Generate Design System (REQUIRED)
+
+```bash
+python3 skills/ui-ux-pro-max/scripts/search.py "beauty spa wellness service elegant" --design-system -p "Serenity Spa"
+```
+
+**Output:** Complete design system with pattern, style, colors, typography, effects, and anti-patterns.
+
+### Step 3: Supplement with Detailed Searches (as needed)
+
+```bash
+# Get UX guidelines for animation and accessibility
+python3 skills/ui-ux-pro-max/scripts/search.py "animation accessibility" --domain ux
+
+# Get alternative typography options if needed
+python3 skills/ui-ux-pro-max/scripts/search.py "elegant luxury serif" --domain typography
+```
+
+### Step 4: Stack Guidelines
+
+```bash
+python3 skills/ui-ux-pro-max/scripts/search.py "layout responsive form" --stack html-tailwind
+```
+
+**Then:** Synthesize design system + detailed searches and implement the design.
+
+---
+
+## Output Formats
+
+The `--design-system` flag supports two output formats:
+
+```bash
+# ASCII box (default) - best for terminal display
+python3 skills/ui-ux-pro-max/scripts/search.py "fintech crypto" --design-system
+
+# Markdown - best for documentation
+python3 skills/ui-ux-pro-max/scripts/search.py "fintech crypto" --design-system -f markdown
+```
+
+---
+
+## Tips for Better Results
+
+1. **Be specific with keywords** - "healthcare SaaS dashboard" > "app"
+2. **Search multiple times** - Different keywords reveal different insights
+3. **Combine domains** - Style + Typography + Color = Complete design system
+4. **Always check UX** - Search "animation", "z-index", "accessibility" for common issues
+5. **Use stack flag** - Get implementation-specific best practices
+6. **Iterate** - If first search doesn't match, try different keywords
+
+---
+
+## Common Rules for Professional UI
+
+These are frequently overlooked issues that make UI look unprofessional:
+
+### Icons & Visual Elements
+
+| Rule | Do | Don't |
+|------|----|----- |
+| **No emoji icons** | Use SVG icons (Heroicons, Lucide, Simple Icons) | Use emojis like 🎨 🚀 ⚙️ as UI icons |
+| **Stable hover states** | Use color/opacity transitions on hover | Use scale transforms that shift layout |
+| **Correct brand logos** | Research official SVG from Simple Icons | Guess or use incorrect logo paths |
+| **Consistent icon sizing** | Use fixed viewBox (24x24) with w-6 h-6 | Mix different icon sizes randomly |
+
+### Interaction & Cursor
+
+| Rule | Do | Don't |
+|------|----|----- |
+| **Cursor pointer** | Add `cursor-pointer` to all clickable/hoverable cards | Leave default cursor on interactive elements |
+| **Hover feedback** | Provide visual feedback (color, shadow, border) | No indication element is interactive |
+| **Smooth transitions** | Use `transition-colors duration-200` | Instant state changes or too slow (>500ms) |
+
+### Light/Dark Mode Contrast
+
+| Rule | Do | Don't |
+|------|----|----- |
+| **Glass card light mode** | Use `bg-white/80` or higher opacity | Use `bg-white/10` (too transparent) |
+| **Text contrast light** | Use `#0F172A` (slate-900) for text | Use `#94A3B8` (slate-400) for body text |
+| **Muted text light** | Use `#475569` (slate-600) minimum | Use gray-400 or lighter |
+| **Border visibility** | Use `border-gray-200` in light mode | Use `border-white/10` (invisible) |
+
+### Layout & Spacing
+
+| Rule | Do | Don't |
+|------|----|----- |
+| **Floating navbar** | Add `top-4 left-4 right-4` spacing | Stick navbar to `top-0 left-0 right-0` |
+| **Content padding** | Account for fixed navbar height | Let content hide behind fixed elements |
+| **Consistent max-width** | Use same `max-w-6xl` or `max-w-7xl` | Mix different container widths |
+
+---
+
+## Pre-Delivery Checklist
+
+Before delivering UI code, verify these items:
+
+### Visual Quality
+- [ ] No emojis used as icons (use SVG instead)
+- [ ] All icons from consistent icon set (Heroicons/Lucide)
+- [ ] Brand logos are correct (verified from Simple Icons)
+- [ ] Hover states don't cause layout shift
+- [ ] Use theme colors directly (bg-primary) not var() wrapper
+
+### Interaction
+- [ ] All clickable elements have `cursor-pointer`
+- [ ] Hover states provide clear visual feedback
+- [ ] Transitions are smooth (150-300ms)
+- [ ] Focus states visible for keyboard navigation
+
+### Light/Dark Mode
+- [ ] Light mode text has sufficient contrast (4.5:1 minimum)
+- [ ] Glass/transparent elements visible in light mode
+- [ ] Borders visible in both modes
+- [ ] Test both modes before delivery
+
+### Layout
+- [ ] Floating elements have proper spacing from edges
+- [ ] No content hidden behind fixed navbars
+- [ ] Responsive at 375px, 768px, 1024px, 1440px
+- [ ] No horizontal scroll on mobile
+
+### Accessibility
+- [ ] All images have alt text
+- [ ] Form inputs have labels
+- [ ] Color is not the only indicator
+- [ ] `prefers-reduced-motion` respected
diff --git a/.windsurf/skills/ui-ux-pro-max/data b/.windsurf/skills/ui-ux-pro-max/data
new file mode 100644
index 0000000..e5b9469
--- /dev/null
+++ b/.windsurf/skills/ui-ux-pro-max/data
@@ -0,0 +1 @@
+../../../src/ui-ux-pro-max/data
\ No newline at end of file
diff --git a/.windsurf/skills/ui-ux-pro-max/scripts b/.windsurf/skills/ui-ux-pro-max/scripts
new file mode 100644
index 0000000..ccb93f7
--- /dev/null
+++ b/.windsurf/skills/ui-ux-pro-max/scripts
@@ -0,0 +1 @@
+../../../src/ui-ux-pro-max/scripts
\ No newline at end of file
diff --git a/.windsurf/skills/vercel-react-best-practices/AGENTS.md b/.windsurf/skills/vercel-react-best-practices/AGENTS.md
new file mode 100644
index 0000000..db951ab
--- /dev/null
+++ b/.windsurf/skills/vercel-react-best-practices/AGENTS.md
@@ -0,0 +1,2934 @@
+# React Best Practices
+
+**Version 1.0.0**
+Vercel Engineering
+January 2026
+
+> **Note:**
+> This document is mainly for agents and LLMs to follow when maintaining,
+> generating, or refactoring React and Next.js codebases. Humans
+> may also find it useful, but guidance here is optimized for automation
+> and consistency by AI-assisted workflows.
+
+---
+
+## Abstract
+
+Comprehensive performance optimization guide for React and Next.js applications, designed for AI agents and LLMs. Contains 40+ rules across 8 categories, prioritized by impact from critical (eliminating waterfalls, reducing bundle size) to incremental (advanced patterns). Each rule includes detailed explanations, real-world examples comparing incorrect vs. correct implementations, and specific impact metrics to guide automated refactoring and code generation.
+
+---
+
+## Table of Contents
+
+1. [Eliminating Waterfalls](#1-eliminating-waterfalls) — **CRITICAL**
+ - 1.1 [Defer Await Until Needed](#11-defer-await-until-needed)
+ - 1.2 [Dependency-Based Parallelization](#12-dependency-based-parallelization)
+ - 1.3 [Prevent Waterfall Chains in API Routes](#13-prevent-waterfall-chains-in-api-routes)
+ - 1.4 [Promise.all() for Independent Operations](#14-promiseall-for-independent-operations)
+ - 1.5 [Strategic Suspense Boundaries](#15-strategic-suspense-boundaries)
+2. [Bundle Size Optimization](#2-bundle-size-optimization) — **CRITICAL**
+ - 2.1 [Avoid Barrel File Imports](#21-avoid-barrel-file-imports)
+ - 2.2 [Conditional Module Loading](#22-conditional-module-loading)
+ - 2.3 [Defer Non-Critical Third-Party Libraries](#23-defer-non-critical-third-party-libraries)
+ - 2.4 [Dynamic Imports for Heavy Components](#24-dynamic-imports-for-heavy-components)
+ - 2.5 [Preload Based on User Intent](#25-preload-based-on-user-intent)
+3. [Server-Side Performance](#3-server-side-performance) — **HIGH**
+ - 3.1 [Authenticate Server Actions Like API Routes](#31-authenticate-server-actions-like-api-routes)
+ - 3.2 [Avoid Duplicate Serialization in RSC Props](#32-avoid-duplicate-serialization-in-rsc-props)
+ - 3.3 [Cross-Request LRU Caching](#33-cross-request-lru-caching)
+ - 3.4 [Minimize Serialization at RSC Boundaries](#34-minimize-serialization-at-rsc-boundaries)
+ - 3.5 [Parallel Data Fetching with Component Composition](#35-parallel-data-fetching-with-component-composition)
+ - 3.6 [Per-Request Deduplication with React.cache()](#36-per-request-deduplication-with-reactcache)
+ - 3.7 [Use after() for Non-Blocking Operations](#37-use-after-for-non-blocking-operations)
+4. [Client-Side Data Fetching](#4-client-side-data-fetching) — **MEDIUM-HIGH**
+ - 4.1 [Deduplicate Global Event Listeners](#41-deduplicate-global-event-listeners)
+ - 4.2 [Use Passive Event Listeners for Scrolling Performance](#42-use-passive-event-listeners-for-scrolling-performance)
+ - 4.3 [Use SWR for Automatic Deduplication](#43-use-swr-for-automatic-deduplication)
+ - 4.4 [Version and Minimize localStorage Data](#44-version-and-minimize-localstorage-data)
+5. [Re-render Optimization](#5-re-render-optimization) — **MEDIUM**
+ - 5.1 [Calculate Derived State During Rendering](#51-calculate-derived-state-during-rendering)
+ - 5.2 [Defer State Reads to Usage Point](#52-defer-state-reads-to-usage-point)
+ - 5.3 [Do not wrap a simple expression with a primitive result type in useMemo](#53-do-not-wrap-a-simple-expression-with-a-primitive-result-type-in-usememo)
+ - 5.4 [Extract Default Non-primitive Parameter Value from Memoized Component to Constant](#54-extract-default-non-primitive-parameter-value-from-memoized-component-to-constant)
+ - 5.5 [Extract to Memoized Components](#55-extract-to-memoized-components)
+ - 5.6 [Narrow Effect Dependencies](#56-narrow-effect-dependencies)
+ - 5.7 [Put Interaction Logic in Event Handlers](#57-put-interaction-logic-in-event-handlers)
+ - 5.8 [Subscribe to Derived State](#58-subscribe-to-derived-state)
+ - 5.9 [Use Functional setState Updates](#59-use-functional-setstate-updates)
+ - 5.10 [Use Lazy State Initialization](#510-use-lazy-state-initialization)
+ - 5.11 [Use Transitions for Non-Urgent Updates](#511-use-transitions-for-non-urgent-updates)
+ - 5.12 [Use useRef for Transient Values](#512-use-useref-for-transient-values)
+6. [Rendering Performance](#6-rendering-performance) — **MEDIUM**
+ - 6.1 [Animate SVG Wrapper Instead of SVG Element](#61-animate-svg-wrapper-instead-of-svg-element)
+ - 6.2 [CSS content-visibility for Long Lists](#62-css-content-visibility-for-long-lists)
+ - 6.3 [Hoist Static JSX Elements](#63-hoist-static-jsx-elements)
+ - 6.4 [Optimize SVG Precision](#64-optimize-svg-precision)
+ - 6.5 [Prevent Hydration Mismatch Without Flickering](#65-prevent-hydration-mismatch-without-flickering)
+ - 6.6 [Suppress Expected Hydration Mismatches](#66-suppress-expected-hydration-mismatches)
+ - 6.7 [Use Activity Component for Show/Hide](#67-use-activity-component-for-showhide)
+ - 6.8 [Use Explicit Conditional Rendering](#68-use-explicit-conditional-rendering)
+ - 6.9 [Use useTransition Over Manual Loading States](#69-use-usetransition-over-manual-loading-states)
+7. [JavaScript Performance](#7-javascript-performance) — **LOW-MEDIUM**
+ - 7.1 [Avoid Layout Thrashing](#71-avoid-layout-thrashing)
+ - 7.2 [Build Index Maps for Repeated Lookups](#72-build-index-maps-for-repeated-lookups)
+ - 7.3 [Cache Property Access in Loops](#73-cache-property-access-in-loops)
+ - 7.4 [Cache Repeated Function Calls](#74-cache-repeated-function-calls)
+ - 7.5 [Cache Storage API Calls](#75-cache-storage-api-calls)
+ - 7.6 [Combine Multiple Array Iterations](#76-combine-multiple-array-iterations)
+ - 7.7 [Early Length Check for Array Comparisons](#77-early-length-check-for-array-comparisons)
+ - 7.8 [Early Return from Functions](#78-early-return-from-functions)
+ - 7.9 [Hoist RegExp Creation](#79-hoist-regexp-creation)
+ - 7.10 [Use Loop for Min/Max Instead of Sort](#710-use-loop-for-minmax-instead-of-sort)
+ - 7.11 [Use Set/Map for O(1) Lookups](#711-use-setmap-for-o1-lookups)
+ - 7.12 [Use toSorted() Instead of sort() for Immutability](#712-use-tosorted-instead-of-sort-for-immutability)
+8. [Advanced Patterns](#8-advanced-patterns) — **LOW**
+ - 8.1 [Initialize App Once, Not Per Mount](#81-initialize-app-once-not-per-mount)
+ - 8.2 [Store Event Handlers in Refs](#82-store-event-handlers-in-refs)
+ - 8.3 [useEffectEvent for Stable Callback Refs](#83-useeffectevent-for-stable-callback-refs)
+
+---
+
+## 1. Eliminating Waterfalls
+
+**Impact: CRITICAL**
+
+Waterfalls are the #1 performance killer. Each sequential await adds full network latency. Eliminating them yields the largest gains.
+
+### 1.1 Defer Await Until Needed
+
+**Impact: HIGH (avoids blocking unused code paths)**
+
+Move `await` operations into the branches where they're actually used to avoid blocking code paths that don't need them.
+
+**Incorrect: blocks both branches**
+
+```typescript
+async function handleRequest(userId: string, skipProcessing: boolean) {
+ const userData = await fetchUserData(userId)
+
+ if (skipProcessing) {
+ // Returns immediately but still waited for userData
+ return { skipped: true }
+ }
+
+ // Only this branch uses userData
+ return processUserData(userData)
+}
+```
+
+**Correct: only blocks when needed**
+
+```typescript
+async function handleRequest(userId: string, skipProcessing: boolean) {
+ if (skipProcessing) {
+ // Returns immediately without waiting
+ return { skipped: true }
+ }
+
+ // Fetch only when needed
+ const userData = await fetchUserData(userId)
+ return processUserData(userData)
+}
+```
+
+**Another example: early return optimization**
+
+```typescript
+// Incorrect: always fetches permissions
+async function updateResource(resourceId: string, userId: string) {
+ const permissions = await fetchPermissions(userId)
+ const resource = await getResource(resourceId)
+
+ if (!resource) {
+ return { error: 'Not found' }
+ }
+
+ if (!permissions.canEdit) {
+ return { error: 'Forbidden' }
+ }
+
+ return await updateResourceData(resource, permissions)
+}
+
+// Correct: fetches only when needed
+async function updateResource(resourceId: string, userId: string) {
+ const resource = await getResource(resourceId)
+
+ if (!resource) {
+ return { error: 'Not found' }
+ }
+
+ const permissions = await fetchPermissions(userId)
+
+ if (!permissions.canEdit) {
+ return { error: 'Forbidden' }
+ }
+
+ return await updateResourceData(resource, permissions)
+}
+```
+
+This optimization is especially valuable when the skipped branch is frequently taken, or when the deferred operation is expensive.
+
+### 1.2 Dependency-Based Parallelization
+
+**Impact: CRITICAL (2-10× improvement)**
+
+For operations with partial dependencies, use `better-all` to maximize parallelism. It automatically starts each task at the earliest possible moment.
+
+**Incorrect: profile waits for config unnecessarily**
+
+```typescript
+const [user, config] = await Promise.all([
+ fetchUser(),
+ fetchConfig()
+])
+const profile = await fetchProfile(user.id)
+```
+
+**Correct: config and profile run in parallel**
+
+```typescript
+import { all } from 'better-all'
+
+const { user, config, profile } = await all({
+ async user() { return fetchUser() },
+ async config() { return fetchConfig() },
+ async profile() {
+ return fetchProfile((await this.$.user).id)
+ }
+})
+```
+
+**Alternative without extra dependencies:**
+
+```typescript
+const userPromise = fetchUser()
+const profilePromise = userPromise.then(user => fetchProfile(user.id))
+
+const [user, config, profile] = await Promise.all([
+ userPromise,
+ fetchConfig(),
+ profilePromise
+])
+```
+
+We can also create all the promises first, and do `Promise.all()` at the end.
+
+Reference: [https://github.com/shuding/better-all](https://github.com/shuding/better-all)
+
+### 1.3 Prevent Waterfall Chains in API Routes
+
+**Impact: CRITICAL (2-10× improvement)**
+
+In API routes and Server Actions, start independent operations immediately, even if you don't await them yet.
+
+**Incorrect: config waits for auth, data waits for both**
+
+```typescript
+export async function GET(request: Request) {
+ const session = await auth()
+ const config = await fetchConfig()
+ const data = await fetchData(session.user.id)
+ return Response.json({ data, config })
+}
+```
+
+**Correct: auth and config start immediately**
+
+```typescript
+export async function GET(request: Request) {
+ const sessionPromise = auth()
+ const configPromise = fetchConfig()
+ const session = await sessionPromise
+ const [config, data] = await Promise.all([
+ configPromise,
+ fetchData(session.user.id)
+ ])
+ return Response.json({ data, config })
+}
+```
+
+For operations with more complex dependency chains, use `better-all` to automatically maximize parallelism (see Dependency-Based Parallelization).
+
+### 1.4 Promise.all() for Independent Operations
+
+**Impact: CRITICAL (2-10× improvement)**
+
+When async operations have no interdependencies, execute them concurrently using `Promise.all()`.
+
+**Incorrect: sequential execution, 3 round trips**
+
+```typescript
+const user = await fetchUser()
+const posts = await fetchPosts()
+const comments = await fetchComments()
+```
+
+**Correct: parallel execution, 1 round trip**
+
+```typescript
+const [user, posts, comments] = await Promise.all([
+ fetchUser(),
+ fetchPosts(),
+ fetchComments()
+])
+```
+
+### 1.5 Strategic Suspense Boundaries
+
+**Impact: HIGH (faster initial paint)**
+
+Instead of awaiting data in async components before returning JSX, use Suspense boundaries to show the wrapper UI faster while data loads.
+
+**Incorrect: wrapper blocked by data fetching**
+
+```tsx
+async function Page() {
+ const data = await fetchData() // Blocks entire page
+
+ return (
+
+
Sidebar
+
Header
+
+
+
Footer
+
+
Sidebar
+
Header
+
+
+
Footer
+
{data.content}
+}
+```
+
+Sidebar, Header, and Footer render immediately. Only DataDisplay waits for data.
+
+**Alternative: share promise across components**
+
+```tsx
+function Page() {
+ // Start fetch immediately, but don't await
+ const dataPromise = fetchData()
+
+ return (
+
+
Sidebar
+
Header
+
}>
+
+
+
+
Footer
+
}) {
+ const data = use(dataPromise) // Unwraps the promise
+ return {data.content}
+}
+
+function DataSummary({ dataPromise }: { dataPromise: Promise }) {
+ const data = use(dataPromise) // Reuses the same promise
+ return {data.summary}
+}
+```
+
+Both components share the same promise, so only one fetch occurs. Layout renders immediately while both components wait together.
+
+**When NOT to use this pattern:**
+
+- Critical data needed for layout decisions (affects positioning)
+
+- SEO-critical content above the fold
+
+- Small, fast queries where suspense overhead isn't worth it
+
+- When you want to avoid layout shift (loading → content jump)
+
+**Trade-off:** Faster initial paint vs potential layout shift. Choose based on your UX priorities.
+
+---
+
+## 2. Bundle Size Optimization
+
+**Impact: CRITICAL**
+
+Reducing initial bundle size improves Time to Interactive and Largest Contentful Paint.
+
+### 2.1 Avoid Barrel File Imports
+
+**Impact: CRITICAL (200-800ms import cost, slow builds)**
+
+Import directly from source files instead of barrel files to avoid loading thousands of unused modules. **Barrel files** are entry points that re-export multiple modules (e.g., `index.js` that does `export * from './module'`).
+
+Popular icon and component libraries can have **up to 10,000 re-exports** in their entry file. For many React packages, **it takes 200-800ms just to import them**, affecting both development speed and production cold starts.
+
+**Why tree-shaking doesn't help:** When a library is marked as external (not bundled), the bundler can't optimize it. If you bundle it to enable tree-shaking, builds become substantially slower analyzing the entire module graph.
+
+**Incorrect: imports entire library**
+
+```tsx
+import { Check, X, Menu } from 'lucide-react'
+// Loads 1,583 modules, takes ~2.8s extra in dev
+// Runtime cost: 200-800ms on every cold start
+
+import { Button, TextField } from '@mui/material'
+// Loads 2,225 modules, takes ~4.2s extra in dev
+```
+
+**Correct: imports only what you need**
+
+```tsx
+import Check from 'lucide-react/dist/esm/icons/check'
+import X from 'lucide-react/dist/esm/icons/x'
+import Menu from 'lucide-react/dist/esm/icons/menu'
+// Loads only 3 modules (~2KB vs ~1MB)
+
+import Button from '@mui/material/Button'
+import TextField from '@mui/material/TextField'
+// Loads only what you use
+```
+
+**Alternative: Next.js 13.5+**
+
+```js
+// next.config.js - use optimizePackageImports
+module.exports = {
+ experimental: {
+ optimizePackageImports: ['lucide-react', '@mui/material']
+ }
+}
+
+// Then you can keep the ergonomic barrel imports:
+import { Check, X, Menu } from 'lucide-react'
+// Automatically transformed to direct imports at build time
+```
+
+Direct imports provide 15-70% faster dev boot, 28% faster builds, 40% faster cold starts, and significantly faster HMR.
+
+Libraries commonly affected: `lucide-react`, `@mui/material`, `@mui/icons-material`, `@tabler/icons-react`, `react-icons`, `@headlessui/react`, `@radix-ui/react-*`, `lodash`, `ramda`, `date-fns`, `rxjs`, `react-use`.
+
+Reference: [https://vercel.com/blog/how-we-optimized-package-imports-in-next-js](https://vercel.com/blog/how-we-optimized-package-imports-in-next-js)
+
+### 2.2 Conditional Module Loading
+
+**Impact: HIGH (loads large data only when needed)**
+
+Load large data or modules only when a feature is activated.
+
+**Example: lazy-load animation frames**
+
+```tsx
+function AnimationPlayer({ enabled, setEnabled }: { enabled: boolean; setEnabled: React.Dispatch> }) {
+ const [frames, setFrames] = useState(null)
+
+ useEffect(() => {
+ if (enabled && !frames && typeof window !== 'undefined') {
+ import('./animation-frames.js')
+ .then(mod => setFrames(mod.frames))
+ .catch(() => setEnabled(false))
+ }
+ }, [enabled, frames, setEnabled])
+
+ if (!frames) return
+ Open Editor
+
+ )
+}
+```
+
+**Example: preload when feature flag is enabled**
+
+```tsx
+function FlagsProvider({ children, flags }: Props) {
+ useEffect(() => {
+ if (flags.editorEnabled && typeof window !== 'undefined') {
+ void import('./monaco-editor').then(mod => mod.init())
+ }
+ }, [flags.editorEnabled])
+
+ return
+ {children}
+
+}
+```
+
+The `typeof window !== 'undefined'` check prevents bundling preloaded modules for SSR, optimizing server bundle size and build speed.
+
+---
+
+## 3. Server-Side Performance
+
+**Impact: HIGH**
+
+Optimizing server-side rendering and data fetching eliminates server-side waterfalls and reduces response times.
+
+### 3.1 Authenticate Server Actions Like API Routes
+
+**Impact: CRITICAL (prevents unauthorized access to server mutations)**
+
+Server Actions (functions with `"use server"`) are exposed as public endpoints, just like API routes. Always verify authentication and authorization **inside** each Server Action—do not rely solely on middleware, layout guards, or page-level checks, as Server Actions can be invoked directly.
+
+Next.js documentation explicitly states: "Treat Server Actions with the same security considerations as public-facing API endpoints, and verify if the user is allowed to perform a mutation."
+
+**Incorrect: no authentication check**
+
+```typescript
+'use server'
+
+export async function deleteUser(userId: string) {
+ // Anyone can call this! No auth check
+ await db.user.delete({ where: { id: userId } })
+ return { success: true }
+}
+```
+
+**Correct: authentication inside the action**
+
+```typescript
+'use server'
+
+import { verifySession } from '@/lib/auth'
+import { unauthorized } from '@/lib/errors'
+
+export async function deleteUser(userId: string) {
+ // Always check auth inside the action
+ const session = await verifySession()
+
+ if (!session) {
+ throw unauthorized('Must be logged in')
+ }
+
+ // Check authorization too
+ if (session.user.role !== 'admin' && session.user.id !== userId) {
+ throw unauthorized('Cannot delete other users')
+ }
+
+ await db.user.delete({ where: { id: userId } })
+ return { success: true }
+}
+```
+
+**With input validation:**
+
+```typescript
+'use server'
+
+import { verifySession } from '@/lib/auth'
+import { z } from 'zod'
+
+const updateProfileSchema = z.object({
+ userId: z.string().uuid(),
+ name: z.string().min(1).max(100),
+ email: z.string().email()
+})
+
+export async function updateProfile(data: unknown) {
+ // Validate input first
+ const validated = updateProfileSchema.parse(data)
+
+ // Then authenticate
+ const session = await verifySession()
+ if (!session) {
+ throw new Error('Unauthorized')
+ }
+
+ // Then authorize
+ if (session.user.id !== validated.userId) {
+ throw new Error('Can only update own profile')
+ }
+
+ // Finally perform the mutation
+ await db.user.update({
+ where: { id: validated.userId },
+ data: {
+ name: validated.name,
+ email: validated.email
+ }
+ })
+
+ return { success: true }
+}
+```
+
+Reference: [https://nextjs.org/docs/app/guides/authentication](https://nextjs.org/docs/app/guides/authentication)
+
+### 3.2 Avoid Duplicate Serialization in RSC Props
+
+**Impact: LOW (reduces network payload by avoiding duplicate serialization)**
+
+RSC→client serialization deduplicates by object reference, not value. Same reference = serialized once; new reference = serialized again. Do transformations (`.toSorted()`, `.filter()`, `.map()`) in client, not server.
+
+**Incorrect: duplicates array**
+
+```tsx
+// RSC: sends 6 strings (2 arrays × 3 items)
+ u.active)} />
+({
+ max: 1000,
+ ttl: 5 * 60 * 1000 // 5 minutes
+})
+
+export async function getUser(id: string) {
+ const cached = cache.get(id)
+ if (cached) return cached
+
+ const user = await db.user.findUnique({ where: { id } })
+ cache.set(id, user)
+ return user
+}
+
+// Request 1: DB query, result cached
+// Request 2: cache hit, no DB query
+```
+
+Use when sequential user actions hit multiple endpoints needing the same data within seconds.
+
+**With Vercel's [Fluid Compute](https://vercel.com/docs/fluid-compute):** LRU caching is especially effective because multiple concurrent requests can share the same function instance and cache. This means the cache persists across requests without needing external storage like Redis.
+
+**In traditional serverless:** Each invocation runs in isolation, so consider Redis for cross-process caching.
+
+Reference: [https://github.com/isaacs/node-lru-cache](https://github.com/isaacs/node-lru-cache)
+
+### 3.4 Minimize Serialization at RSC Boundaries
+
+**Impact: HIGH (reduces data transfer size)**
+
+The React Server/Client boundary serializes all object properties into strings and embeds them in the HTML response and subsequent RSC requests. This serialized data directly impacts page weight and load time, so **size matters a lot**. Only pass fields that the client actually uses.
+
+**Incorrect: serializes all 50 fields**
+
+```tsx
+async function Page() {
+ const user = await fetchUser() // 50 fields
+ return {user.name}
// uses 1 field
+}
+```
+
+**Correct: serializes only 1 field**
+
+```tsx
+async function Page() {
+ const user = await fetchUser()
+ return {name}
+}
+```
+
+### 3.5 Parallel Data Fetching with Component Composition
+
+**Impact: CRITICAL (eliminates server-side waterfalls)**
+
+React Server Components execute sequentially within a tree. Restructure with composition to parallelize data fetching.
+
+**Incorrect: Sidebar waits for Page's fetch to complete**
+
+```tsx
+export default async function Page() {
+ const header = await fetchHeader()
+ return (
+
+ )
+}
+
+async function Sidebar() {
+ const items = await fetchSidebarItems()
+ return {items.map(renderItem)}
+}
+```
+
+**Correct: both fetch simultaneously**
+
+```tsx
+async function Header() {
+ const data = await fetchHeader()
+ return {data}
+}
+
+async function Sidebar() {
+ const items = await fetchSidebarItems()
+ return {items.map(renderItem)}
+}
+
+export default function Page() {
+ return (
+
+
+
+ )
+}
+```
+
+**Alternative with children prop:**
+
+```tsx
+async function Header() {
+ const data = await fetchHeader()
+ return {data}
+}
+
+async function Sidebar() {
+ const items = await fetchSidebarItems()
+ return {items.map(renderItem)}
+}
+
+function Layout({ children }: { children: ReactNode }) {
+ return (
+
+
+ {children}
+
+ )
+}
+
+export default function Page() {
+ return (
+
+
+ )
+}
+```
+
+### 3.6 Per-Request Deduplication with React.cache()
+
+**Impact: MEDIUM (deduplicates within request)**
+
+Use `React.cache()` for server-side request deduplication. Authentication and database queries benefit most.
+
+**Usage:**
+
+```typescript
+import { cache } from 'react'
+
+export const getCurrentUser = cache(async () => {
+ const session = await auth()
+ if (!session?.user?.id) return null
+ return await db.user.findUnique({
+ where: { id: session.user.id }
+ })
+})
+```
+
+Within a single request, multiple calls to `getCurrentUser()` execute the query only once.
+
+**Avoid inline objects as arguments:**
+
+`React.cache()` uses shallow equality (`Object.is`) to determine cache hits. Inline objects create new references each call, preventing cache hits.
+
+**Incorrect: always cache miss**
+
+```typescript
+const getUser = cache(async (params: { uid: number }) => {
+ return await db.user.findUnique({ where: { id: params.uid } })
+})
+
+// Each call creates new object, never hits cache
+getUser({ uid: 1 })
+getUser({ uid: 1 }) // Cache miss, runs query again
+```
+
+**Correct: cache hit**
+
+```typescript
+const params = { uid: 1 }
+getUser(params) // Query runs
+getUser(params) // Cache hit (same reference)
+```
+
+If you must pass objects, pass the same reference:
+
+**Next.js-Specific Note:**
+
+In Next.js, the `fetch` API is automatically extended with request memoization. Requests with the same URL and options are automatically deduplicated within a single request, so you don't need `React.cache()` for `fetch` calls. However, `React.cache()` is still essential for other async tasks:
+
+- Database queries (Prisma, Drizzle, etc.)
+
+- Heavy computations
+
+- Authentication checks
+
+- File system operations
+
+- Any non-fetch async work
+
+Use `React.cache()` to deduplicate these operations across your component tree.
+
+Reference: [https://react.dev/reference/react/cache](https://react.dev/reference/react/cache)
+
+### 3.7 Use after() for Non-Blocking Operations
+
+**Impact: MEDIUM (faster response times)**
+
+Use Next.js's `after()` to schedule work that should execute after a response is sent. This prevents logging, analytics, and other side effects from blocking the response.
+
+**Incorrect: blocks response**
+
+```tsx
+import { logUserAction } from '@/app/utils'
+
+export async function POST(request: Request) {
+ // Perform mutation
+ await updateDatabase(request)
+
+ // Logging blocks the response
+ const userAgent = request.headers.get('user-agent') || 'unknown'
+ await logUserAction({ userAgent })
+
+ return new Response(JSON.stringify({ status: 'success' }), {
+ status: 200,
+ headers: { 'Content-Type': 'application/json' }
+ })
+}
+```
+
+**Correct: non-blocking**
+
+```tsx
+import { after } from 'next/server'
+import { headers, cookies } from 'next/headers'
+import { logUserAction } from '@/app/utils'
+
+export async function POST(request: Request) {
+ // Perform mutation
+ await updateDatabase(request)
+
+ // Log after response is sent
+ after(async () => {
+ const userAgent = (await headers()).get('user-agent') || 'unknown'
+ const sessionCookie = (await cookies()).get('session-id')?.value || 'anonymous'
+
+ logUserAction({ sessionCookie, userAgent })
+ })
+
+ return new Response(JSON.stringify({ status: 'success' }), {
+ status: 200,
+ headers: { 'Content-Type': 'application/json' }
+ })
+}
+```
+
+The response is sent immediately while logging happens in the background.
+
+**Common use cases:**
+
+- Analytics tracking
+
+- Audit logging
+
+- Sending notifications
+
+- Cache invalidation
+
+- Cleanup tasks
+
+**Important notes:**
+
+- `after()` runs even if the response fails or redirects
+
+- Works in Server Actions, Route Handlers, and Server Components
+
+Reference: [https://nextjs.org/docs/app/api-reference/functions/after](https://nextjs.org/docs/app/api-reference/functions/after)
+
+---
+
+## 4. Client-Side Data Fetching
+
+**Impact: MEDIUM-HIGH**
+
+Automatic deduplication and efficient data fetching patterns reduce redundant network requests.
+
+### 4.1 Deduplicate Global Event Listeners
+
+**Impact: LOW (single listener for N components)**
+
+Use `useSWRSubscription()` to share global event listeners across component instances.
+
+**Incorrect: N instances = N listeners**
+
+```tsx
+function useKeyboardShortcut(key: string, callback: () => void) {
+ useEffect(() => {
+ const handler = (e: KeyboardEvent) => {
+ if (e.metaKey && e.key === key) {
+ callback()
+ }
+ }
+ window.addEventListener('keydown', handler)
+ return () => window.removeEventListener('keydown', handler)
+ }, [key, callback])
+}
+```
+
+When using the `useKeyboardShortcut` hook multiple times, each instance will register a new listener.
+
+**Correct: N instances = 1 listener**
+
+```tsx
+import useSWRSubscription from 'swr/subscription'
+
+// Module-level Map to track callbacks per key
+const keyCallbacks = new Map void>>()
+
+function useKeyboardShortcut(key: string, callback: () => void) {
+ // Register this callback in the Map
+ useEffect(() => {
+ if (!keyCallbacks.has(key)) {
+ keyCallbacks.set(key, new Set())
+ }
+ keyCallbacks.get(key)!.add(callback)
+
+ return () => {
+ const set = keyCallbacks.get(key)
+ if (set) {
+ set.delete(callback)
+ if (set.size === 0) {
+ keyCallbacks.delete(key)
+ }
+ }
+ }
+ }, [key, callback])
+
+ useSWRSubscription('global-keydown', () => {
+ const handler = (e: KeyboardEvent) => {
+ if (e.metaKey && keyCallbacks.has(e.key)) {
+ keyCallbacks.get(e.key)!.forEach(cb => cb())
+ }
+ }
+ window.addEventListener('keydown', handler)
+ return () => window.removeEventListener('keydown', handler)
+ })
+}
+
+function Profile() {
+ // Multiple shortcuts will share the same listener
+ useKeyboardShortcut('p', () => { /* ... */ })
+ useKeyboardShortcut('k', () => { /* ... */ })
+ // ...
+}
+```
+
+### 4.2 Use Passive Event Listeners for Scrolling Performance
+
+**Impact: MEDIUM (eliminates scroll delay caused by event listeners)**
+
+Add `{ passive: true }` to touch and wheel event listeners to enable immediate scrolling. Browsers normally wait for listeners to finish to check if `preventDefault()` is called, causing scroll delay.
+
+**Incorrect:**
+
+```typescript
+useEffect(() => {
+ const handleTouch = (e: TouchEvent) => console.log(e.touches[0].clientX)
+ const handleWheel = (e: WheelEvent) => console.log(e.deltaY)
+
+ document.addEventListener('touchstart', handleTouch)
+ document.addEventListener('wheel', handleWheel)
+
+ return () => {
+ document.removeEventListener('touchstart', handleTouch)
+ document.removeEventListener('wheel', handleWheel)
+ }
+}, [])
+```
+
+**Correct:**
+
+```typescript
+useEffect(() => {
+ const handleTouch = (e: TouchEvent) => console.log(e.touches[0].clientX)
+ const handleWheel = (e: WheelEvent) => console.log(e.deltaY)
+
+ document.addEventListener('touchstart', handleTouch, { passive: true })
+ document.addEventListener('wheel', handleWheel, { passive: true })
+
+ return () => {
+ document.removeEventListener('touchstart', handleTouch)
+ document.removeEventListener('wheel', handleWheel)
+ }
+}, [])
+```
+
+**Use passive when:** tracking/analytics, logging, any listener that doesn't call `preventDefault()`.
+
+**Don't use passive when:** implementing custom swipe gestures, custom zoom controls, or any listener that needs `preventDefault()`.
+
+### 4.3 Use SWR for Automatic Deduplication
+
+**Impact: MEDIUM-HIGH (automatic deduplication)**
+
+SWR enables request deduplication, caching, and revalidation across component instances.
+
+**Incorrect: no deduplication, each instance fetches**
+
+```tsx
+function UserList() {
+ const [users, setUsers] = useState([])
+ useEffect(() => {
+ fetch('/api/users')
+ .then(r => r.json())
+ .then(setUsers)
+ }, [])
+}
+```
+
+**Correct: multiple instances share one request**
+
+```tsx
+import useSWR from 'swr'
+
+function UserList() {
+ const { data: users } = useSWR('/api/users', fetcher)
+}
+```
+
+**For immutable data:**
+
+```tsx
+import { useImmutableSWR } from '@/lib/swr'
+
+function StaticContent() {
+ const { data } = useImmutableSWR('/api/config', fetcher)
+}
+```
+
+**For mutations:**
+
+```tsx
+import { useSWRMutation } from 'swr/mutation'
+
+function UpdateButton() {
+ const { trigger } = useSWRMutation('/api/user', updateUser)
+ return trigger()}>Update
+}
+```
+
+Reference: [https://swr.vercel.app](https://swr.vercel.app)
+
+### 4.4 Version and Minimize localStorage Data
+
+**Impact: MEDIUM (prevents schema conflicts, reduces storage size)**
+
+Add version prefix to keys and store only needed fields. Prevents schema conflicts and accidental storage of sensitive data.
+
+**Incorrect:**
+
+```typescript
+// No version, stores everything, no error handling
+localStorage.setItem('userConfig', JSON.stringify(fullUserObject))
+const data = localStorage.getItem('userConfig')
+```
+
+**Correct:**
+
+```typescript
+const VERSION = 'v2'
+
+function saveConfig(config: { theme: string; language: string }) {
+ try {
+ localStorage.setItem(`userConfig:${VERSION}`, JSON.stringify(config))
+ } catch {
+ // Throws in incognito/private browsing, quota exceeded, or disabled
+ }
+}
+
+function loadConfig() {
+ try {
+ const data = localStorage.getItem(`userConfig:${VERSION}`)
+ return data ? JSON.parse(data) : null
+ } catch {
+ return null
+ }
+}
+
+// Migration from v1 to v2
+function migrate() {
+ try {
+ const v1 = localStorage.getItem('userConfig:v1')
+ if (v1) {
+ const old = JSON.parse(v1)
+ saveConfig({ theme: old.darkMode ? 'dark' : 'light', language: old.lang })
+ localStorage.removeItem('userConfig:v1')
+ }
+ } catch {}
+}
+```
+
+**Store minimal fields from server responses:**
+
+```typescript
+// User object has 20+ fields, only store what UI needs
+function cachePrefs(user: FullUser) {
+ try {
+ localStorage.setItem('prefs:v1', JSON.stringify({
+ theme: user.preferences.theme,
+ notifications: user.preferences.notifications
+ }))
+ } catch {}
+}
+```
+
+**Always wrap in try-catch:** `getItem()` and `setItem()` throw in incognito/private browsing (Safari, Firefox), when quota exceeded, or when disabled.
+
+**Benefits:** Schema evolution via versioning, reduced storage size, prevents storing tokens/PII/internal flags.
+
+---
+
+## 5. Re-render Optimization
+
+**Impact: MEDIUM**
+
+Reducing unnecessary re-renders minimizes wasted computation and improves UI responsiveness.
+
+### 5.1 Calculate Derived State During Rendering
+
+**Impact: MEDIUM (avoids redundant renders and state drift)**
+
+If a value can be computed from current props/state, do not store it in state or update it in an effect. Derive it during render to avoid extra renders and state drift. Do not set state in effects solely in response to prop changes; prefer derived values or keyed resets instead.
+
+**Incorrect: redundant state and effect**
+
+```tsx
+function Form() {
+ const [firstName, setFirstName] = useState('First')
+ const [lastName, setLastName] = useState('Last')
+ const [fullName, setFullName] = useState('')
+
+ useEffect(() => {
+ setFullName(firstName + ' ' + lastName)
+ }, [firstName, lastName])
+
+ return {fullName}
+}
+```
+
+**Correct: derive during render**
+
+```tsx
+function Form() {
+ const [firstName, setFirstName] = useState('First')
+ const [lastName, setLastName] = useState('Last')
+ const fullName = firstName + ' ' + lastName
+
+ return {fullName}
+}
+```
+
+Reference: [https://react.dev/learn/you-might-not-need-an-effect](https://react.dev/learn/you-might-not-need-an-effect)
+
+### 5.2 Defer State Reads to Usage Point
+
+**Impact: MEDIUM (avoids unnecessary subscriptions)**
+
+Don't subscribe to dynamic state (searchParams, localStorage) if you only read it inside callbacks.
+
+**Incorrect: subscribes to all searchParams changes**
+
+```tsx
+function ShareButton({ chatId }: { chatId: string }) {
+ const searchParams = useSearchParams()
+
+ const handleShare = () => {
+ const ref = searchParams.get('ref')
+ shareChat(chatId, { ref })
+ }
+
+ return Share
+}
+```
+
+**Correct: reads on demand, no subscription**
+
+```tsx
+function ShareButton({ chatId }: { chatId: string }) {
+ const handleShare = () => {
+ const params = new URLSearchParams(window.location.search)
+ const ref = params.get('ref')
+ shareChat(chatId, { ref })
+ }
+
+ return Share
+}
+```
+
+### 5.3 Do not wrap a simple expression with a primitive result type in useMemo
+
+**Impact: LOW-MEDIUM (wasted computation on every render)**
+
+When an expression is simple (few logical or arithmetical operators) and has a primitive result type (boolean, number, string), do not wrap it in `useMemo`.
+
+Calling `useMemo` and comparing hook dependencies may consume more resources than the expression itself.
+
+**Incorrect:**
+
+```tsx
+function Header({ user, notifications }: Props) {
+ const isLoading = useMemo(() => {
+ return user.isLoading || notifications.isLoading
+ }, [user.isLoading, notifications.isLoading])
+
+ if (isLoading) return {avatar}
+}
+```
+
+**Correct: skips computation when loading**
+
+```tsx
+const UserAvatar = memo(function UserAvatar({ user }: { user: User }) {
+ const id = useMemo(() => computeAvatarId(user), [user])
+ return
+
+ )
+}
+```
+
+**Note:** If your project has [React Compiler](https://react.dev/learn/react-compiler) enabled, manual memoization with `memo()` and `useMemo()` is not necessary. The compiler automatically optimizes re-renders.
+
+### 5.6 Narrow Effect Dependencies
+
+**Impact: LOW (minimizes effect re-runs)**
+
+Specify primitive dependencies instead of objects to minimize effect re-runs.
+
+**Incorrect: re-runs on any user field change**
+
+```tsx
+useEffect(() => {
+ console.log(user.id)
+}, [user])
+```
+
+**Correct: re-runs only when id changes**
+
+```tsx
+useEffect(() => {
+ console.log(user.id)
+}, [user.id])
+```
+
+**For derived state, compute outside effect:**
+
+```tsx
+// Incorrect: runs on width=767, 766, 765...
+useEffect(() => {
+ if (width < 768) {
+ enableMobileMode()
+ }
+}, [width])
+
+// Correct: runs only on boolean transition
+const isMobile = width < 768
+useEffect(() => {
+ if (isMobile) {
+ enableMobileMode()
+ }
+}, [isMobile])
+```
+
+### 5.7 Put Interaction Logic in Event Handlers
+
+**Impact: MEDIUM (avoids effect re-runs and duplicate side effects)**
+
+If a side effect is triggered by a specific user action (submit, click, drag), run it in that event handler. Do not model the action as state + effect; it makes effects re-run on unrelated changes and can duplicate the action.
+
+**Incorrect: event modeled as state + effect**
+
+```tsx
+function Form() {
+ const [submitted, setSubmitted] = useState(false)
+ const theme = useContext(ThemeContext)
+
+ useEffect(() => {
+ if (submitted) {
+ post('/api/register')
+ showToast('Registered', theme)
+ }
+ }, [submitted, theme])
+
+ return setSubmitted(true)}>Submit
+}
+```
+
+**Correct: do it in the handler**
+
+```tsx
+function Form() {
+ const theme = useContext(ThemeContext)
+
+ function handleSubmit() {
+ post('/api/register')
+ showToast('Registered', theme)
+ }
+
+ return Submit
+}
+```
+
+Reference: [https://react.dev/learn/removing-effect-dependencies#should-this-code-move-to-an-event-handler](https://react.dev/learn/removing-effect-dependencies#should-this-code-move-to-an-event-handler)
+
+### 5.8 Subscribe to Derived State
+
+**Impact: MEDIUM (reduces re-render frequency)**
+
+Subscribe to derived boolean state instead of continuous values to reduce re-render frequency.
+
+**Incorrect: re-renders on every pixel change**
+
+```tsx
+function Sidebar() {
+ const width = useWindowWidth() // updates continuously
+ const isMobile = width < 768
+ return
+ )
+}
+```
+
+**Correct: no re-render for tracking**
+
+```tsx
+function Tracker() {
+ const lastXRef = useRef(0)
+ const dotRef = useRef(null)
+
+ useEffect(() => {
+ const onMove = (e: MouseEvent) => {
+ lastXRef.current = e.clientX
+ const node = dotRef.current
+ if (node) {
+ node.style.transform = `translateX(${e.clientX}px)`
+ }
+ }
+ window.addEventListener('mousemove', onMove)
+ return () => window.removeEventListener('mousemove', onMove)
+ }, [])
+
+ return (
+
+ )
+}
+```
+
+---
+
+## 6. Rendering Performance
+
+**Impact: MEDIUM**
+
+Optimizing the rendering process reduces the work the browser needs to do.
+
+### 6.1 Animate SVG Wrapper Instead of SVG Element
+
+**Impact: LOW (enables hardware acceleration)**
+
+Many browsers don't have hardware acceleration for CSS3 animations on SVG elements. Wrap SVG in a `` and animate the wrapper instead.
+
+**Incorrect: animating SVG directly - no hardware acceleration**
+
+```tsx
+function LoadingSpinner() {
+ return (
+
+
+ )
+}
+```
+
+**Correct: animating wrapper div - hardware accelerated**
+
+```tsx
+function LoadingSpinner() {
+ return (
+
+
+
+
+ )
+}
+```
+
+This applies to all CSS transforms and transitions (`transform`, `opacity`, `translate`, `scale`, `rotate`). The wrapper div allows browsers to use GPU acceleration for smoother animations.
+
+### 6.2 CSS content-visibility for Long Lists
+
+**Impact: HIGH (faster initial render)**
+
+Apply `content-visibility: auto` to defer off-screen rendering.
+
+**CSS:**
+
+```css
+.message-item {
+ content-visibility: auto;
+ contain-intrinsic-size: 0 80px;
+}
+```
+
+**Example:**
+
+```tsx
+function MessageList({ messages }: { messages: Message[] }) {
+ return (
+
+ {messages.map(msg => (
+
+ ))}
+
+ )
+}
+```
+
+For 1000 messages, browser skips layout/paint for ~990 off-screen items (10× faster initial render).
+
+### 6.3 Hoist Static JSX Elements
+
+**Impact: LOW (avoids re-creation)**
+
+Extract static JSX outside components to avoid re-creation.
+
+**Incorrect: recreates element every render**
+
+```tsx
+function LoadingSkeleton() {
+ return
+}
+
+function Container() {
+ return (
+
+ {loading &&
+ )
+}
+```
+
+**Correct: reuses same element**
+
+```tsx
+const loadingSkeleton = (
+
+)
+
+function Container() {
+ return (
+
+ {loading && loadingSkeleton}
+
+ )
+}
+```
+
+This is especially helpful for large and static SVG nodes, which can be expensive to recreate on every render.
+
+**Note:** If your project has [React Compiler](https://react.dev/learn/react-compiler) enabled, the compiler automatically hoists static JSX elements and optimizes component re-renders, making manual hoisting unnecessary.
+
+### 6.4 Optimize SVG Precision
+
+**Impact: LOW (reduces file size)**
+
+Reduce SVG coordinate precision to decrease file size. The optimal precision depends on the viewBox size, but in general reducing precision should be considered.
+
+**Incorrect: excessive precision**
+
+```svg
+
+```
+
+**Correct: 1 decimal place**
+
+```svg
+
+```
+
+**Automate with SVGO:**
+
+```bash
+npx svgo --precision=1 --multipass icon.svg
+```
+
+### 6.5 Prevent Hydration Mismatch Without Flickering
+
+**Impact: MEDIUM (avoids visual flicker and hydration errors)**
+
+When rendering content that depends on client-side storage (localStorage, cookies), avoid both SSR breakage and post-hydration flickering by injecting a synchronous script that updates the DOM before React hydrates.
+
+**Incorrect: breaks SSR**
+
+```tsx
+function ThemeWrapper({ children }: { children: ReactNode }) {
+ // localStorage is not available on server - throws error
+ const theme = localStorage.getItem('theme') || 'light'
+
+ return (
+
+ {children}
+
+ )
+}
+```
+
+Server-side rendering will fail because `localStorage` is undefined.
+
+**Incorrect: visual flickering**
+
+```tsx
+function ThemeWrapper({ children }: { children: ReactNode }) {
+ const [theme, setTheme] = useState('light')
+
+ useEffect(() => {
+ // Runs after hydration - causes visible flash
+ const stored = localStorage.getItem('theme')
+ if (stored) {
+ setTheme(stored)
+ }
+ }, [])
+
+ return (
+
+ {children}
+
+ )
+}
+```
+
+Component first renders with default value (`light`), then updates after hydration, causing a visible flash of incorrect content.
+
+**Correct: no flicker, no hydration mismatch**
+
+```tsx
+function ThemeWrapper({ children }: { children: ReactNode }) {
+ return (
+ <>
+
+ {children}
+
+
+
+ )
+}
+```
+
+The inline script executes synchronously before showing the element, ensuring the DOM already has the correct value. No flickering, no hydration mismatch.
+
+This pattern is especially useful for theme toggles, user preferences, authentication states, and any client-only data that should render immediately without flashing default values.
+
+### 6.6 Suppress Expected Hydration Mismatches
+
+**Impact: LOW-MEDIUM (avoids noisy hydration warnings for known differences)**
+
+In SSR frameworks (e.g., Next.js), some values are intentionally different on server vs client (random IDs, dates, locale/timezone formatting). For these *expected* mismatches, wrap the dynamic text in an element with `suppressHydrationWarning` to prevent noisy warnings. Do not use this to hide real bugs. Don’t overuse it.
+
+**Incorrect: known mismatch warnings**
+
+```tsx
+function Timestamp() {
+ return
{new Date().toLocaleString()}
+}
+```
+
+**Correct: suppress expected mismatch only**
+
+```tsx
+function Timestamp() {
+ return (
+
+ {new Date().toLocaleString()}
+
+ )
+}
+```
+
+### 6.7 Use Activity Component for Show/Hide
+
+**Impact: MEDIUM (preserves state/DOM)**
+
+Use React's `
` to preserve state/DOM for expensive components that frequently toggle visibility.
+
+**Usage:**
+
+```tsx
+import { Activity } from 'react'
+
+function Dropdown({ isOpen }: Props) {
+ return (
+
+
+ )
+}
+```
+
+Avoids expensive re-renders and state loss.
+
+### 6.8 Use Explicit Conditional Rendering
+
+**Impact: LOW (prevents rendering 0 or NaN)**
+
+Use explicit ternary operators (`? :`) instead of `&&` for conditional rendering when the condition can be `0`, `NaN`, or other falsy values that render.
+
+**Incorrect: renders "0" when count is 0**
+
+```tsx
+function Badge({ count }: { count: number }) {
+ return (
+
+ {count && {count} }
+
+ )
+}
+
+// When count = 0, renders: 0
+// When count = 5, renders: 5
+```
+
+**Correct: renders nothing when count is 0**
+
+```tsx
+function Badge({ count }: { count: number }) {
+ return (
+
+ {count > 0 ? {count} : null}
+
+ )
+}
+
+// When count = 0, renders:
+// When count = 5, renders: 5
+```
+
+### 6.9 Use useTransition Over Manual Loading States
+
+**Impact: LOW (reduces re-renders and improves code clarity)**
+
+Use `useTransition` instead of manual `useState` for loading states. This provides built-in `isPending` state and automatically manages transitions.
+
+**Incorrect: manual loading state**
+
+```tsx
+function SearchResults() {
+ const [query, setQuery] = useState('')
+ const [results, setResults] = useState([])
+ const [isLoading, setIsLoading] = useState(false)
+
+ const handleSearch = async (value: string) => {
+ setIsLoading(true)
+ setQuery(value)
+ const data = await fetchResults(value)
+ setResults(data)
+ setIsLoading(false)
+ }
+
+ return (
+ <>
+ (null)
+
+ useEffect(() => {
+ if (ref.current && isHighlighted) {
+ ref.current.style.width = '100px'
+ const width = ref.current.offsetWidth // Forces layout
+ ref.current.style.height = '200px'
+ }
+ }, [isHighlighted])
+
+ return Content
+}
+
+// Correct: toggle class
+function Box({ isHighlighted }: { isHighlighted: boolean }) {
+ return (
+
+ Content
+
+ )
+}
+```
+
+Prefer CSS classes over inline styles when possible. CSS files are cached by the browser, and classes provide better separation of concerns and are easier to maintain.
+
+See [this gist](https://gist.github.com/paulirish/5d52fb081b3570c81e3a) and [CSS Triggers](https://csstriggers.com/) for more information on layout-forcing operations.
+
+### 7.2 Build Index Maps for Repeated Lookups
+
+**Impact: LOW-MEDIUM (1M ops to 2K ops)**
+
+Multiple `.find()` calls by the same key should use a Map.
+
+**Incorrect (O(n) per lookup):**
+
+```typescript
+function processOrders(orders: Order[], users: User[]) {
+ return orders.map(order => ({
+ ...order,
+ user: users.find(u => u.id === order.userId)
+ }))
+}
+```
+
+**Correct (O(1) per lookup):**
+
+```typescript
+function processOrders(orders: Order[], users: User[]) {
+ const userById = new Map(users.map(u => [u.id, u]))
+
+ return orders.map(order => ({
+ ...order,
+ user: userById.get(order.userId)
+ }))
+}
+```
+
+Build map once (O(n)), then all lookups are O(1).
+
+For 1000 orders × 1000 users: 1M ops → 2K ops.
+
+### 7.3 Cache Property Access in Loops
+
+**Impact: LOW-MEDIUM (reduces lookups)**
+
+Cache object property lookups in hot paths.
+
+**Incorrect: 3 lookups × N iterations**
+
+```typescript
+for (let i = 0; i < arr.length; i++) {
+ process(obj.config.settings.value)
+}
+```
+
+**Correct: 1 lookup total**
+
+```typescript
+const value = obj.config.settings.value
+const len = arr.length
+for (let i = 0; i < len; i++) {
+ process(value)
+}
+```
+
+### 7.4 Cache Repeated Function Calls
+
+**Impact: MEDIUM (avoid redundant computation)**
+
+Use a module-level Map to cache function results when the same function is called repeatedly with the same inputs during render.
+
+**Incorrect: redundant computation**
+
+```typescript
+function ProjectList({ projects }: { projects: Project[] }) {
+ return (
+
+ {projects.map(project => {
+ // slugify() called 100+ times for same project names
+ const slug = slugify(project.name)
+
+ return
+ })}
+
()
+
+function cachedSlugify(text: string): string {
+ if (slugifyCache.has(text)) {
+ return slugifyCache.get(text)!
+ }
+ const result = slugify(text)
+ slugifyCache.set(text, result)
+ return result
+}
+
+function ProjectList({ projects }: { projects: Project[] }) {
+ return (
+
+ {projects.map(project => {
+ // Computed only once per unique project name
+ const slug = cachedSlugify(project.name)
+
+ return
+ })}
+
()
+
+function getLocalStorage(key: string) {
+ if (!storageCache.has(key)) {
+ storageCache.set(key, localStorage.getItem(key))
+ }
+ return storageCache.get(key)
+}
+
+function setLocalStorage(key: string, value: string) {
+ localStorage.setItem(key, value)
+ storageCache.set(key, value) // keep cache in sync
+}
+```
+
+Use a Map (not a hook) so it works everywhere: utilities, event handlers, not just React components.
+
+**Cookie caching:**
+
+```typescript
+let cookieCache: Record | null = null
+
+function getCookie(name: string) {
+ if (!cookieCache) {
+ cookieCache = Object.fromEntries(
+ document.cookie.split('; ').map(c => c.split('='))
+ )
+ }
+ return cookieCache[name]
+}
+```
+
+**Important: invalidate on external changes**
+
+```typescript
+window.addEventListener('storage', (e) => {
+ if (e.key) storageCache.delete(e.key)
+})
+
+document.addEventListener('visibilitychange', () => {
+ if (document.visibilityState === 'visible') {
+ storageCache.clear()
+ }
+})
+```
+
+If storage can change externally (another tab, server-set cookies), invalidate cache:
+
+### 7.6 Combine Multiple Array Iterations
+
+**Impact: LOW-MEDIUM (reduces iterations)**
+
+Multiple `.filter()` or `.map()` calls iterate the array multiple times. Combine into one loop.
+
+**Incorrect: 3 iterations**
+
+```typescript
+const admins = users.filter(u => u.isAdmin)
+const testers = users.filter(u => u.isTester)
+const inactive = users.filter(u => !u.isActive)
+```
+
+**Correct: 1 iteration**
+
+```typescript
+const admins: User[] = []
+const testers: User[] = []
+const inactive: User[] = []
+
+for (const user of users) {
+ if (user.isAdmin) admins.push(user)
+ if (user.isTester) testers.push(user)
+ if (!user.isActive) inactive.push(user)
+}
+```
+
+### 7.7 Early Length Check for Array Comparisons
+
+**Impact: MEDIUM-HIGH (avoids expensive operations when lengths differ)**
+
+When comparing arrays with expensive operations (sorting, deep equality, serialization), check lengths first. If lengths differ, the arrays cannot be equal.
+
+In real-world applications, this optimization is especially valuable when the comparison runs in hot paths (event handlers, render loops).
+
+**Incorrect: always runs expensive comparison**
+
+```typescript
+function hasChanges(current: string[], original: string[]) {
+ // Always sorts and joins, even when lengths differ
+ return current.sort().join() !== original.sort().join()
+}
+```
+
+Two O(n log n) sorts run even when `current.length` is 5 and `original.length` is 100. There is also overhead of joining the arrays and comparing the strings.
+
+**Correct (O(1) length check first):**
+
+```typescript
+function hasChanges(current: string[], original: string[]) {
+ // Early return if lengths differ
+ if (current.length !== original.length) {
+ return true
+ }
+ // Only sort when lengths match
+ const currentSorted = current.toSorted()
+ const originalSorted = original.toSorted()
+ for (let i = 0; i < currentSorted.length; i++) {
+ if (currentSorted[i] !== originalSorted[i]) {
+ return true
+ }
+ }
+ return false
+}
+```
+
+This new approach is more efficient because:
+
+- It avoids the overhead of sorting and joining the arrays when lengths differ
+
+- It avoids consuming memory for the joined strings (especially important for large arrays)
+
+- It avoids mutating the original arrays
+
+- It returns early when a difference is found
+
+### 7.8 Early Return from Functions
+
+**Impact: LOW-MEDIUM (avoids unnecessary computation)**
+
+Return early when result is determined to skip unnecessary processing.
+
+**Incorrect: processes all items even after finding answer**
+
+```typescript
+function validateUsers(users: User[]) {
+ let hasError = false
+ let errorMessage = ''
+
+ for (const user of users) {
+ if (!user.email) {
+ hasError = true
+ errorMessage = 'Email required'
+ }
+ if (!user.name) {
+ hasError = true
+ errorMessage = 'Name required'
+ }
+ // Continues checking all users even after error found
+ }
+
+ return hasError ? { valid: false, error: errorMessage } : { valid: true }
+}
+```
+
+**Correct: returns immediately on first error**
+
+```typescript
+function validateUsers(users: User[]) {
+ for (const user of users) {
+ if (!user.email) {
+ return { valid: false, error: 'Email required' }
+ }
+ if (!user.name) {
+ return { valid: false, error: 'Name required' }
+ }
+ }
+
+ return { valid: true }
+}
+```
+
+### 7.9 Hoist RegExp Creation
+
+**Impact: LOW-MEDIUM (avoids recreation)**
+
+Don't create RegExp inside render. Hoist to module scope or memoize with `useMemo()`.
+
+**Incorrect: new RegExp every render**
+
+```tsx
+function Highlighter({ text, query }: Props) {
+ const regex = new RegExp(`(${query})`, 'gi')
+ const parts = text.split(regex)
+ return <>{parts.map((part, i) => ...)}
+}
+```
+
+**Correct: memoize or hoist**
+
+```tsx
+const EMAIL_REGEX = /^[^\s@]+@[^\s@]+\.[^\s@]+$/
+
+function Highlighter({ text, query }: Props) {
+ const regex = useMemo(
+ () => new RegExp(`(${escapeRegex(query)})`, 'gi'),
+ [query]
+ )
+ const parts = text.split(regex)
+ return <>{parts.map((part, i) => ...)}
+}
+```
+
+**Warning: global regex has mutable state**
+
+```typescript
+const regex = /foo/g
+regex.test('foo') // true, lastIndex = 3
+regex.test('foo') // false, lastIndex = 0
+```
+
+Global regex (`/g`) has mutable `lastIndex` state:
+
+### 7.10 Use Loop for Min/Max Instead of Sort
+
+**Impact: LOW (O(n) instead of O(n log n))**
+
+Finding the smallest or largest element only requires a single pass through the array. Sorting is wasteful and slower.
+
+**Incorrect (O(n log n) - sort to find latest):**
+
+```typescript
+interface Project {
+ id: string
+ name: string
+ updatedAt: number
+}
+
+function getLatestProject(projects: Project[]) {
+ const sorted = [...projects].sort((a, b) => b.updatedAt - a.updatedAt)
+ return sorted[0]
+}
+```
+
+Sorts the entire array just to find the maximum value.
+
+**Incorrect (O(n log n) - sort for oldest and newest):**
+
+```typescript
+function getOldestAndNewest(projects: Project[]) {
+ const sorted = [...projects].sort((a, b) => a.updatedAt - b.updatedAt)
+ return { oldest: sorted[0], newest: sorted[sorted.length - 1] }
+}
+```
+
+Still sorts unnecessarily when only min/max are needed.
+
+**Correct (O(n) - single loop):**
+
+```typescript
+function getLatestProject(projects: Project[]) {
+ if (projects.length === 0) return null
+
+ let latest = projects[0]
+
+ for (let i = 1; i < projects.length; i++) {
+ if (projects[i].updatedAt > latest.updatedAt) {
+ latest = projects[i]
+ }
+ }
+
+ return latest
+}
+
+function getOldestAndNewest(projects: Project[]) {
+ if (projects.length === 0) return { oldest: null, newest: null }
+
+ let oldest = projects[0]
+ let newest = projects[0]
+
+ for (let i = 1; i < projects.length; i++) {
+ if (projects[i].updatedAt < oldest.updatedAt) oldest = projects[i]
+ if (projects[i].updatedAt > newest.updatedAt) newest = projects[i]
+ }
+
+ return { oldest, newest }
+}
+```
+
+Single pass through the array, no copying, no sorting.
+
+**Alternative: Math.min/Math.max for small arrays**
+
+```typescript
+const numbers = [5, 2, 8, 1, 9]
+const min = Math.min(...numbers)
+const max = Math.max(...numbers)
+```
+
+This works for small arrays, but can be slower or just throw an error for very large arrays due to spread operator limitations. Maximal array length is approximately 124000 in Chrome 143 and 638000 in Safari 18; exact numbers may vary - see [the fiddle](https://jsfiddle.net/qw1jabsx/4/). Use the loop approach for reliability.
+
+### 7.11 Use Set/Map for O(1) Lookups
+
+**Impact: LOW-MEDIUM (O(n) to O(1))**
+
+Convert arrays to Set/Map for repeated membership checks.
+
+**Incorrect (O(n) per check):**
+
+```typescript
+const allowedIds = ['a', 'b', 'c', ...]
+items.filter(item => allowedIds.includes(item.id))
+```
+
+**Correct (O(1) per check):**
+
+```typescript
+const allowedIds = new Set(['a', 'b', 'c', ...])
+items.filter(item => allowedIds.has(item.id))
+```
+
+### 7.12 Use toSorted() Instead of sort() for Immutability
+
+**Impact: MEDIUM-HIGH (prevents mutation bugs in React state)**
+
+`.sort()` mutates the array in place, which can cause bugs with React state and props. Use `.toSorted()` to create a new sorted array without mutation.
+
+**Incorrect: mutates original array**
+
+```typescript
+function UserList({ users }: { users: User[] }) {
+ // Mutates the users prop array!
+ const sorted = useMemo(
+ () => users.sort((a, b) => a.name.localeCompare(b.name)),
+ [users]
+ )
+ return {sorted.map(renderUser)}
+}
+```
+
+**Correct: creates new array**
+
+```typescript
+function UserList({ users }: { users: User[] }) {
+ // Creates new sorted array, original unchanged
+ const sorted = useMemo(
+ () => users.toSorted((a, b) => a.name.localeCompare(b.name)),
+ [users]
+ )
+ return {sorted.map(renderUser)}
+}
+```
+
+**Why this matters in React:**
+
+1. Props/state mutations break React's immutability model - React expects props and state to be treated as read-only
+
+2. Causes stale closure bugs - Mutating arrays inside closures (callbacks, effects) can lead to unexpected behavior
+
+**Browser support: fallback for older browsers**
+
+```typescript
+// Fallback for older browsers
+const sorted = [...items].sort((a, b) => a.value - b.value)
+```
+
+`.toSorted()` is available in all modern browsers (Chrome 110+, Safari 16+, Firefox 115+, Node.js 20+). For older environments, use spread operator:
+
+**Other immutable array methods:**
+
+- `.toSorted()` - immutable sort
+
+- `.toReversed()` - immutable reverse
+
+- `.toSpliced()` - immutable splice
+
+- `.with()` - immutable element replacement
+
+---
+
+## 8. Advanced Patterns
+
+**Impact: LOW**
+
+Advanced patterns for specific cases that require careful implementation.
+
+### 8.1 Initialize App Once, Not Per Mount
+
+**Impact: LOW-MEDIUM (avoids duplicate init in development)**
+
+Do not put app-wide initialization that must run once per app load inside `useEffect([])` of a component. Components can remount and effects will re-run. Use a module-level guard or top-level init in the entry module instead.
+
+**Incorrect: runs twice in dev, re-runs on remount**
+
+```tsx
+function Comp() {
+ useEffect(() => {
+ loadFromStorage()
+ checkAuthToken()
+ }, [])
+
+ // ...
+}
+```
+
+**Correct: once per app load**
+
+```tsx
+let didInit = false
+
+function Comp() {
+ useEffect(() => {
+ if (didInit) return
+ didInit = true
+ loadFromStorage()
+ checkAuthToken()
+ }, [])
+
+ // ...
+}
+```
+
+Reference: [https://react.dev/learn/you-might-not-need-an-effect#initializing-the-application](https://react.dev/learn/you-might-not-need-an-effect#initializing-the-application)
+
+### 8.2 Store Event Handlers in Refs
+
+**Impact: LOW (stable subscriptions)**
+
+Store callbacks in refs when used in effects that shouldn't re-subscribe on callback changes.
+
+**Incorrect: re-subscribes on every render**
+
+```tsx
+function useWindowEvent(event: string, handler: (e) => void) {
+ useEffect(() => {
+ window.addEventListener(event, handler)
+ return () => window.removeEventListener(event, handler)
+ }, [event, handler])
+}
+```
+
+**Correct: stable subscription**
+
+```tsx
+import { useEffectEvent } from 'react'
+
+function useWindowEvent(event: string, handler: (e) => void) {
+ const onEvent = useEffectEvent(handler)
+
+ useEffect(() => {
+ window.addEventListener(event, onEvent)
+ return () => window.removeEventListener(event, onEvent)
+ }, [event])
+}
+```
+
+**Alternative: use `useEffectEvent` if you're on latest React:**
+
+`useEffectEvent` provides a cleaner API for the same pattern: it creates a stable function reference that always calls the latest version of the handler.
+
+### 8.3 useEffectEvent for Stable Callback Refs
+
+**Impact: LOW (prevents effect re-runs)**
+
+Access latest values in callbacks without adding them to dependency arrays. Prevents effect re-runs while avoiding stale closures.
+
+**Incorrect: effect re-runs on every callback change**
+
+```tsx
+function SearchInput({ onSearch }: { onSearch: (q: string) => void }) {
+ const [query, setQuery] = useState('')
+
+ useEffect(() => {
+ const timeout = setTimeout(() => onSearch(query), 300)
+ return () => clearTimeout(timeout)
+ }, [query, onSearch])
+}
+```
+
+**Correct: using React's useEffectEvent**
+
+```tsx
+import { useEffectEvent } from 'react';
+
+function SearchInput({ onSearch }: { onSearch: (q: string) => void }) {
+ const [query, setQuery] = useState('')
+ const onSearchEvent = useEffectEvent(onSearch)
+
+ useEffect(() => {
+ const timeout = setTimeout(() => onSearchEvent(query), 300)
+ return () => clearTimeout(timeout)
+ }, [query])
+}
+```
+
+---
+
+## References
+
+1. [https://react.dev](https://react.dev)
+2. [https://nextjs.org](https://nextjs.org)
+3. [https://swr.vercel.app](https://swr.vercel.app)
+4. [https://github.com/shuding/better-all](https://github.com/shuding/better-all)
+5. [https://github.com/isaacs/node-lru-cache](https://github.com/isaacs/node-lru-cache)
+6. [https://vercel.com/blog/how-we-optimized-package-imports-in-next-js](https://vercel.com/blog/how-we-optimized-package-imports-in-next-js)
+7. [https://vercel.com/blog/how-we-made-the-vercel-dashboard-twice-as-fast](https://vercel.com/blog/how-we-made-the-vercel-dashboard-twice-as-fast)
diff --git a/.windsurf/skills/vercel-react-best-practices/SKILL.md b/.windsurf/skills/vercel-react-best-practices/SKILL.md
new file mode 100644
index 0000000..1ad7750
--- /dev/null
+++ b/.windsurf/skills/vercel-react-best-practices/SKILL.md
@@ -0,0 +1,136 @@
+---
+name: vercel-react-best-practices
+description: React and Next.js performance optimization guidelines from Vercel Engineering. This skill should be used when writing, reviewing, or refactoring React/Next.js code to ensure optimal performance patterns. Triggers on tasks involving React components, Next.js pages, data fetching, bundle optimization, or performance improvements.
+license: MIT
+metadata:
+ author: vercel
+ version: "1.0.0"
+---
+
+# Vercel React Best Practices
+
+Comprehensive performance optimization guide for React and Next.js applications, maintained by Vercel. Contains 57 rules across 8 categories, prioritized by impact to guide automated refactoring and code generation.
+
+## When to Apply
+
+Reference these guidelines when:
+- Writing new React components or Next.js pages
+- Implementing data fetching (client or server-side)
+- Reviewing code for performance issues
+- Refactoring existing React/Next.js code
+- Optimizing bundle size or load times
+
+## Rule Categories by Priority
+
+| Priority | Category | Impact | Prefix |
+|----------|----------|--------|--------|
+| 1 | Eliminating Waterfalls | CRITICAL | `async-` |
+| 2 | Bundle Size Optimization | CRITICAL | `bundle-` |
+| 3 | Server-Side Performance | HIGH | `server-` |
+| 4 | Client-Side Data Fetching | MEDIUM-HIGH | `client-` |
+| 5 | Re-render Optimization | MEDIUM | `rerender-` |
+| 6 | Rendering Performance | MEDIUM | `rendering-` |
+| 7 | JavaScript Performance | LOW-MEDIUM | `js-` |
+| 8 | Advanced Patterns | LOW | `advanced-` |
+
+## Quick Reference
+
+### 1. Eliminating Waterfalls (CRITICAL)
+
+- `async-defer-await` - Move await into branches where actually used
+- `async-parallel` - Use Promise.all() for independent operations
+- `async-dependencies` - Use better-all for partial dependencies
+- `async-api-routes` - Start promises early, await late in API routes
+- `async-suspense-boundaries` - Use Suspense to stream content
+
+### 2. Bundle Size Optimization (CRITICAL)
+
+- `bundle-barrel-imports` - Import directly, avoid barrel files
+- `bundle-dynamic-imports` - Use next/dynamic for heavy components
+- `bundle-defer-third-party` - Load analytics/logging after hydration
+- `bundle-conditional` - Load modules only when feature is activated
+- `bundle-preload` - Preload on hover/focus for perceived speed
+
+### 3. Server-Side Performance (HIGH)
+
+- `server-auth-actions` - Authenticate server actions like API routes
+- `server-cache-react` - Use React.cache() for per-request deduplication
+- `server-cache-lru` - Use LRU cache for cross-request caching
+- `server-dedup-props` - Avoid duplicate serialization in RSC props
+- `server-serialization` - Minimize data passed to client components
+- `server-parallel-fetching` - Restructure components to parallelize fetches
+- `server-after-nonblocking` - Use after() for non-blocking operations
+
+### 4. Client-Side Data Fetching (MEDIUM-HIGH)
+
+- `client-swr-dedup` - Use SWR for automatic request deduplication
+- `client-event-listeners` - Deduplicate global event listeners
+- `client-passive-event-listeners` - Use passive listeners for scroll
+- `client-localstorage-schema` - Version and minimize localStorage data
+
+### 5. Re-render Optimization (MEDIUM)
+
+- `rerender-defer-reads` - Don't subscribe to state only used in callbacks
+- `rerender-memo` - Extract expensive work into memoized components
+- `rerender-memo-with-default-value` - Hoist default non-primitive props
+- `rerender-dependencies` - Use primitive dependencies in effects
+- `rerender-derived-state` - Subscribe to derived booleans, not raw values
+- `rerender-derived-state-no-effect` - Derive state during render, not effects
+- `rerender-functional-setstate` - Use functional setState for stable callbacks
+- `rerender-lazy-state-init` - Pass function to useState for expensive values
+- `rerender-simple-expression-in-memo` - Avoid memo for simple primitives
+- `rerender-move-effect-to-event` - Put interaction logic in event handlers
+- `rerender-transitions` - Use startTransition for non-urgent updates
+- `rerender-use-ref-transient-values` - Use refs for transient frequent values
+
+### 6. Rendering Performance (MEDIUM)
+
+- `rendering-animate-svg-wrapper` - Animate div wrapper, not SVG element
+- `rendering-content-visibility` - Use content-visibility for long lists
+- `rendering-hoist-jsx` - Extract static JSX outside components
+- `rendering-svg-precision` - Reduce SVG coordinate precision
+- `rendering-hydration-no-flicker` - Use inline script for client-only data
+- `rendering-hydration-suppress-warning` - Suppress expected mismatches
+- `rendering-activity` - Use Activity component for show/hide
+- `rendering-conditional-render` - Use ternary, not && for conditionals
+- `rendering-usetransition-loading` - Prefer useTransition for loading state
+
+### 7. JavaScript Performance (LOW-MEDIUM)
+
+- `js-batch-dom-css` - Group CSS changes via classes or cssText
+- `js-index-maps` - Build Map for repeated lookups
+- `js-cache-property-access` - Cache object properties in loops
+- `js-cache-function-results` - Cache function results in module-level Map
+- `js-cache-storage` - Cache localStorage/sessionStorage reads
+- `js-combine-iterations` - Combine multiple filter/map into one loop
+- `js-length-check-first` - Check array length before expensive comparison
+- `js-early-exit` - Return early from functions
+- `js-hoist-regexp` - Hoist RegExp creation outside loops
+- `js-min-max-loop` - Use loop for min/max instead of sort
+- `js-set-map-lookups` - Use Set/Map for O(1) lookups
+- `js-tosorted-immutable` - Use toSorted() for immutability
+
+### 8. Advanced Patterns (LOW)
+
+- `advanced-event-handler-refs` - Store event handlers in refs
+- `advanced-init-once` - Initialize app once per app load
+- `advanced-use-latest` - useLatest for stable callback refs
+
+## How to Use
+
+Read individual rule files for detailed explanations and code examples:
+
+```
+rules/async-parallel.md
+rules/bundle-barrel-imports.md
+```
+
+Each rule file contains:
+- Brief explanation of why it matters
+- Incorrect code example with explanation
+- Correct code example with explanation
+- Additional context and references
+
+## Full Compiled Document
+
+For the complete guide with all rules expanded: `AGENTS.md`
diff --git a/.windsurf/skills/vercel-react-best-practices/rules/advanced-event-handler-refs.md b/.windsurf/skills/vercel-react-best-practices/rules/advanced-event-handler-refs.md
new file mode 100644
index 0000000..97e7ade
--- /dev/null
+++ b/.windsurf/skills/vercel-react-best-practices/rules/advanced-event-handler-refs.md
@@ -0,0 +1,55 @@
+---
+title: Store Event Handlers in Refs
+impact: LOW
+impactDescription: stable subscriptions
+tags: advanced, hooks, refs, event-handlers, optimization
+---
+
+## Store Event Handlers in Refs
+
+Store callbacks in refs when used in effects that shouldn't re-subscribe on callback changes.
+
+**Incorrect (re-subscribes on every render):**
+
+```tsx
+function useWindowEvent(event: string, handler: (e) => void) {
+ useEffect(() => {
+ window.addEventListener(event, handler)
+ return () => window.removeEventListener(event, handler)
+ }, [event, handler])
+}
+```
+
+**Correct (stable subscription):**
+
+```tsx
+function useWindowEvent(event: string, handler: (e) => void) {
+ const handlerRef = useRef(handler)
+ useEffect(() => {
+ handlerRef.current = handler
+ }, [handler])
+
+ useEffect(() => {
+ const listener = (e) => handlerRef.current(e)
+ window.addEventListener(event, listener)
+ return () => window.removeEventListener(event, listener)
+ }, [event])
+}
+```
+
+**Alternative: use `useEffectEvent` if you're on latest React:**
+
+```tsx
+import { useEffectEvent } from 'react'
+
+function useWindowEvent(event: string, handler: (e) => void) {
+ const onEvent = useEffectEvent(handler)
+
+ useEffect(() => {
+ window.addEventListener(event, onEvent)
+ return () => window.removeEventListener(event, onEvent)
+ }, [event])
+}
+```
+
+`useEffectEvent` provides a cleaner API for the same pattern: it creates a stable function reference that always calls the latest version of the handler.
diff --git a/.windsurf/skills/vercel-react-best-practices/rules/advanced-init-once.md b/.windsurf/skills/vercel-react-best-practices/rules/advanced-init-once.md
new file mode 100644
index 0000000..73ee38e
--- /dev/null
+++ b/.windsurf/skills/vercel-react-best-practices/rules/advanced-init-once.md
@@ -0,0 +1,42 @@
+---
+title: Initialize App Once, Not Per Mount
+impact: LOW-MEDIUM
+impactDescription: avoids duplicate init in development
+tags: initialization, useEffect, app-startup, side-effects
+---
+
+## Initialize App Once, Not Per Mount
+
+Do not put app-wide initialization that must run once per app load inside `useEffect([])` of a component. Components can remount and effects will re-run. Use a module-level guard or top-level init in the entry module instead.
+
+**Incorrect (runs twice in dev, re-runs on remount):**
+
+```tsx
+function Comp() {
+ useEffect(() => {
+ loadFromStorage()
+ checkAuthToken()
+ }, [])
+
+ // ...
+}
+```
+
+**Correct (once per app load):**
+
+```tsx
+let didInit = false
+
+function Comp() {
+ useEffect(() => {
+ if (didInit) return
+ didInit = true
+ loadFromStorage()
+ checkAuthToken()
+ }, [])
+
+ // ...
+}
+```
+
+Reference: [Initializing the application](https://react.dev/learn/you-might-not-need-an-effect#initializing-the-application)
diff --git a/.windsurf/skills/vercel-react-best-practices/rules/advanced-use-latest.md b/.windsurf/skills/vercel-react-best-practices/rules/advanced-use-latest.md
new file mode 100644
index 0000000..9c7cb50
--- /dev/null
+++ b/.windsurf/skills/vercel-react-best-practices/rules/advanced-use-latest.md
@@ -0,0 +1,39 @@
+---
+title: useEffectEvent for Stable Callback Refs
+impact: LOW
+impactDescription: prevents effect re-runs
+tags: advanced, hooks, useEffectEvent, refs, optimization
+---
+
+## useEffectEvent for Stable Callback Refs
+
+Access latest values in callbacks without adding them to dependency arrays. Prevents effect re-runs while avoiding stale closures.
+
+**Incorrect (effect re-runs on every callback change):**
+
+```tsx
+function SearchInput({ onSearch }: { onSearch: (q: string) => void }) {
+ const [query, setQuery] = useState('')
+
+ useEffect(() => {
+ const timeout = setTimeout(() => onSearch(query), 300)
+ return () => clearTimeout(timeout)
+ }, [query, onSearch])
+}
+```
+
+**Correct (using React's useEffectEvent):**
+
+```tsx
+import { useEffectEvent } from 'react';
+
+function SearchInput({ onSearch }: { onSearch: (q: string) => void }) {
+ const [query, setQuery] = useState('')
+ const onSearchEvent = useEffectEvent(onSearch)
+
+ useEffect(() => {
+ const timeout = setTimeout(() => onSearchEvent(query), 300)
+ return () => clearTimeout(timeout)
+ }, [query])
+}
+```
diff --git a/.windsurf/skills/vercel-react-best-practices/rules/async-api-routes.md b/.windsurf/skills/vercel-react-best-practices/rules/async-api-routes.md
new file mode 100644
index 0000000..6feda1e
--- /dev/null
+++ b/.windsurf/skills/vercel-react-best-practices/rules/async-api-routes.md
@@ -0,0 +1,38 @@
+---
+title: Prevent Waterfall Chains in API Routes
+impact: CRITICAL
+impactDescription: 2-10× improvement
+tags: api-routes, server-actions, waterfalls, parallelization
+---
+
+## Prevent Waterfall Chains in API Routes
+
+In API routes and Server Actions, start independent operations immediately, even if you don't await them yet.
+
+**Incorrect (config waits for auth, data waits for both):**
+
+```typescript
+export async function GET(request: Request) {
+ const session = await auth()
+ const config = await fetchConfig()
+ const data = await fetchData(session.user.id)
+ return Response.json({ data, config })
+}
+```
+
+**Correct (auth and config start immediately):**
+
+```typescript
+export async function GET(request: Request) {
+ const sessionPromise = auth()
+ const configPromise = fetchConfig()
+ const session = await sessionPromise
+ const [config, data] = await Promise.all([
+ configPromise,
+ fetchData(session.user.id)
+ ])
+ return Response.json({ data, config })
+}
+```
+
+For operations with more complex dependency chains, use `better-all` to automatically maximize parallelism (see Dependency-Based Parallelization).
diff --git a/.windsurf/skills/vercel-react-best-practices/rules/async-defer-await.md b/.windsurf/skills/vercel-react-best-practices/rules/async-defer-await.md
new file mode 100644
index 0000000..ea7082a
--- /dev/null
+++ b/.windsurf/skills/vercel-react-best-practices/rules/async-defer-await.md
@@ -0,0 +1,80 @@
+---
+title: Defer Await Until Needed
+impact: HIGH
+impactDescription: avoids blocking unused code paths
+tags: async, await, conditional, optimization
+---
+
+## Defer Await Until Needed
+
+Move `await` operations into the branches where they're actually used to avoid blocking code paths that don't need them.
+
+**Incorrect (blocks both branches):**
+
+```typescript
+async function handleRequest(userId: string, skipProcessing: boolean) {
+ const userData = await fetchUserData(userId)
+
+ if (skipProcessing) {
+ // Returns immediately but still waited for userData
+ return { skipped: true }
+ }
+
+ // Only this branch uses userData
+ return processUserData(userData)
+}
+```
+
+**Correct (only blocks when needed):**
+
+```typescript
+async function handleRequest(userId: string, skipProcessing: boolean) {
+ if (skipProcessing) {
+ // Returns immediately without waiting
+ return { skipped: true }
+ }
+
+ // Fetch only when needed
+ const userData = await fetchUserData(userId)
+ return processUserData(userData)
+}
+```
+
+**Another example (early return optimization):**
+
+```typescript
+// Incorrect: always fetches permissions
+async function updateResource(resourceId: string, userId: string) {
+ const permissions = await fetchPermissions(userId)
+ const resource = await getResource(resourceId)
+
+ if (!resource) {
+ return { error: 'Not found' }
+ }
+
+ if (!permissions.canEdit) {
+ return { error: 'Forbidden' }
+ }
+
+ return await updateResourceData(resource, permissions)
+}
+
+// Correct: fetches only when needed
+async function updateResource(resourceId: string, userId: string) {
+ const resource = await getResource(resourceId)
+
+ if (!resource) {
+ return { error: 'Not found' }
+ }
+
+ const permissions = await fetchPermissions(userId)
+
+ if (!permissions.canEdit) {
+ return { error: 'Forbidden' }
+ }
+
+ return await updateResourceData(resource, permissions)
+}
+```
+
+This optimization is especially valuable when the skipped branch is frequently taken, or when the deferred operation is expensive.
diff --git a/.windsurf/skills/vercel-react-best-practices/rules/async-dependencies.md b/.windsurf/skills/vercel-react-best-practices/rules/async-dependencies.md
new file mode 100644
index 0000000..0484eba
--- /dev/null
+++ b/.windsurf/skills/vercel-react-best-practices/rules/async-dependencies.md
@@ -0,0 +1,51 @@
+---
+title: Dependency-Based Parallelization
+impact: CRITICAL
+impactDescription: 2-10× improvement
+tags: async, parallelization, dependencies, better-all
+---
+
+## Dependency-Based Parallelization
+
+For operations with partial dependencies, use `better-all` to maximize parallelism. It automatically starts each task at the earliest possible moment.
+
+**Incorrect (profile waits for config unnecessarily):**
+
+```typescript
+const [user, config] = await Promise.all([
+ fetchUser(),
+ fetchConfig()
+])
+const profile = await fetchProfile(user.id)
+```
+
+**Correct (config and profile run in parallel):**
+
+```typescript
+import { all } from 'better-all'
+
+const { user, config, profile } = await all({
+ async user() { return fetchUser() },
+ async config() { return fetchConfig() },
+ async profile() {
+ return fetchProfile((await this.$.user).id)
+ }
+})
+```
+
+**Alternative without extra dependencies:**
+
+We can also create all the promises first, and do `Promise.all()` at the end.
+
+```typescript
+const userPromise = fetchUser()
+const profilePromise = userPromise.then(user => fetchProfile(user.id))
+
+const [user, config, profile] = await Promise.all([
+ userPromise,
+ fetchConfig(),
+ profilePromise
+])
+```
+
+Reference: [https://github.com/shuding/better-all](https://github.com/shuding/better-all)
diff --git a/.windsurf/skills/vercel-react-best-practices/rules/async-parallel.md b/.windsurf/skills/vercel-react-best-practices/rules/async-parallel.md
new file mode 100644
index 0000000..64133f6
--- /dev/null
+++ b/.windsurf/skills/vercel-react-best-practices/rules/async-parallel.md
@@ -0,0 +1,28 @@
+---
+title: Promise.all() for Independent Operations
+impact: CRITICAL
+impactDescription: 2-10× improvement
+tags: async, parallelization, promises, waterfalls
+---
+
+## Promise.all() for Independent Operations
+
+When async operations have no interdependencies, execute them concurrently using `Promise.all()`.
+
+**Incorrect (sequential execution, 3 round trips):**
+
+```typescript
+const user = await fetchUser()
+const posts = await fetchPosts()
+const comments = await fetchComments()
+```
+
+**Correct (parallel execution, 1 round trip):**
+
+```typescript
+const [user, posts, comments] = await Promise.all([
+ fetchUser(),
+ fetchPosts(),
+ fetchComments()
+])
+```
diff --git a/.windsurf/skills/vercel-react-best-practices/rules/async-suspense-boundaries.md b/.windsurf/skills/vercel-react-best-practices/rules/async-suspense-boundaries.md
new file mode 100644
index 0000000..1fbc05b
--- /dev/null
+++ b/.windsurf/skills/vercel-react-best-practices/rules/async-suspense-boundaries.md
@@ -0,0 +1,99 @@
+---
+title: Strategic Suspense Boundaries
+impact: HIGH
+impactDescription: faster initial paint
+tags: async, suspense, streaming, layout-shift
+---
+
+## Strategic Suspense Boundaries
+
+Instead of awaiting data in async components before returning JSX, use Suspense boundaries to show the wrapper UI faster while data loads.
+
+**Incorrect (wrapper blocked by data fetching):**
+
+```tsx
+async function Page() {
+ const data = await fetchData() // Blocks entire page
+
+ return (
+
+
Sidebar
+
Header
+
+
+
Footer
+
+
Sidebar
+
Header
+
+
+
Footer
+
{data.content}
+}
+```
+
+Sidebar, Header, and Footer render immediately. Only DataDisplay waits for data.
+
+**Alternative (share promise across components):**
+
+```tsx
+function Page() {
+ // Start fetch immediately, but don't await
+ const dataPromise = fetchData()
+
+ return (
+
+
Sidebar
+
Header
+
}>
+
+
+
+
Footer
+
}) {
+ const data = use(dataPromise) // Unwraps the promise
+ return {data.content}
+}
+
+function DataSummary({ dataPromise }: { dataPromise: Promise }) {
+ const data = use(dataPromise) // Reuses the same promise
+ return {data.summary}
+}
+```
+
+Both components share the same promise, so only one fetch occurs. Layout renders immediately while both components wait together.
+
+**When NOT to use this pattern:**
+
+- Critical data needed for layout decisions (affects positioning)
+- SEO-critical content above the fold
+- Small, fast queries where suspense overhead isn't worth it
+- When you want to avoid layout shift (loading → content jump)
+
+**Trade-off:** Faster initial paint vs potential layout shift. Choose based on your UX priorities.
diff --git a/.windsurf/skills/vercel-react-best-practices/rules/bundle-barrel-imports.md b/.windsurf/skills/vercel-react-best-practices/rules/bundle-barrel-imports.md
new file mode 100644
index 0000000..ee48f32
--- /dev/null
+++ b/.windsurf/skills/vercel-react-best-practices/rules/bundle-barrel-imports.md
@@ -0,0 +1,59 @@
+---
+title: Avoid Barrel File Imports
+impact: CRITICAL
+impactDescription: 200-800ms import cost, slow builds
+tags: bundle, imports, tree-shaking, barrel-files, performance
+---
+
+## Avoid Barrel File Imports
+
+Import directly from source files instead of barrel files to avoid loading thousands of unused modules. **Barrel files** are entry points that re-export multiple modules (e.g., `index.js` that does `export * from './module'`).
+
+Popular icon and component libraries can have **up to 10,000 re-exports** in their entry file. For many React packages, **it takes 200-800ms just to import them**, affecting both development speed and production cold starts.
+
+**Why tree-shaking doesn't help:** When a library is marked as external (not bundled), the bundler can't optimize it. If you bundle it to enable tree-shaking, builds become substantially slower analyzing the entire module graph.
+
+**Incorrect (imports entire library):**
+
+```tsx
+import { Check, X, Menu } from 'lucide-react'
+// Loads 1,583 modules, takes ~2.8s extra in dev
+// Runtime cost: 200-800ms on every cold start
+
+import { Button, TextField } from '@mui/material'
+// Loads 2,225 modules, takes ~4.2s extra in dev
+```
+
+**Correct (imports only what you need):**
+
+```tsx
+import Check from 'lucide-react/dist/esm/icons/check'
+import X from 'lucide-react/dist/esm/icons/x'
+import Menu from 'lucide-react/dist/esm/icons/menu'
+// Loads only 3 modules (~2KB vs ~1MB)
+
+import Button from '@mui/material/Button'
+import TextField from '@mui/material/TextField'
+// Loads only what you use
+```
+
+**Alternative (Next.js 13.5+):**
+
+```js
+// next.config.js - use optimizePackageImports
+module.exports = {
+ experimental: {
+ optimizePackageImports: ['lucide-react', '@mui/material']
+ }
+}
+
+// Then you can keep the ergonomic barrel imports:
+import { Check, X, Menu } from 'lucide-react'
+// Automatically transformed to direct imports at build time
+```
+
+Direct imports provide 15-70% faster dev boot, 28% faster builds, 40% faster cold starts, and significantly faster HMR.
+
+Libraries commonly affected: `lucide-react`, `@mui/material`, `@mui/icons-material`, `@tabler/icons-react`, `react-icons`, `@headlessui/react`, `@radix-ui/react-*`, `lodash`, `ramda`, `date-fns`, `rxjs`, `react-use`.
+
+Reference: [How we optimized package imports in Next.js](https://vercel.com/blog/how-we-optimized-package-imports-in-next-js)
diff --git a/.windsurf/skills/vercel-react-best-practices/rules/bundle-conditional.md b/.windsurf/skills/vercel-react-best-practices/rules/bundle-conditional.md
new file mode 100644
index 0000000..99d6fc9
--- /dev/null
+++ b/.windsurf/skills/vercel-react-best-practices/rules/bundle-conditional.md
@@ -0,0 +1,31 @@
+---
+title: Conditional Module Loading
+impact: HIGH
+impactDescription: loads large data only when needed
+tags: bundle, conditional-loading, lazy-loading
+---
+
+## Conditional Module Loading
+
+Load large data or modules only when a feature is activated.
+
+**Example (lazy-load animation frames):**
+
+```tsx
+function AnimationPlayer({ enabled, setEnabled }: { enabled: boolean; setEnabled: React.Dispatch> }) {
+ const [frames, setFrames] = useState(null)
+
+ useEffect(() => {
+ if (enabled && !frames && typeof window !== 'undefined') {
+ import('./animation-frames.js')
+ .then(mod => setFrames(mod.frames))
+ .catch(() => setEnabled(false))
+ }
+ }, [enabled, frames, setEnabled])
+
+ if (!frames) return
+ Open Editor
+
+ )
+}
+```
+
+**Example (preload when feature flag is enabled):**
+
+```tsx
+function FlagsProvider({ children, flags }: Props) {
+ useEffect(() => {
+ if (flags.editorEnabled && typeof window !== 'undefined') {
+ void import('./monaco-editor').then(mod => mod.init())
+ }
+ }, [flags.editorEnabled])
+
+ return
+ {children}
+
+}
+```
+
+The `typeof window !== 'undefined'` check prevents bundling preloaded modules for SSR, optimizing server bundle size and build speed.
diff --git a/.windsurf/skills/vercel-react-best-practices/rules/client-event-listeners.md b/.windsurf/skills/vercel-react-best-practices/rules/client-event-listeners.md
new file mode 100644
index 0000000..aad4ae9
--- /dev/null
+++ b/.windsurf/skills/vercel-react-best-practices/rules/client-event-listeners.md
@@ -0,0 +1,74 @@
+---
+title: Deduplicate Global Event Listeners
+impact: LOW
+impactDescription: single listener for N components
+tags: client, swr, event-listeners, subscription
+---
+
+## Deduplicate Global Event Listeners
+
+Use `useSWRSubscription()` to share global event listeners across component instances.
+
+**Incorrect (N instances = N listeners):**
+
+```tsx
+function useKeyboardShortcut(key: string, callback: () => void) {
+ useEffect(() => {
+ const handler = (e: KeyboardEvent) => {
+ if (e.metaKey && e.key === key) {
+ callback()
+ }
+ }
+ window.addEventListener('keydown', handler)
+ return () => window.removeEventListener('keydown', handler)
+ }, [key, callback])
+}
+```
+
+When using the `useKeyboardShortcut` hook multiple times, each instance will register a new listener.
+
+**Correct (N instances = 1 listener):**
+
+```tsx
+import useSWRSubscription from 'swr/subscription'
+
+// Module-level Map to track callbacks per key
+const keyCallbacks = new Map void>>()
+
+function useKeyboardShortcut(key: string, callback: () => void) {
+ // Register this callback in the Map
+ useEffect(() => {
+ if (!keyCallbacks.has(key)) {
+ keyCallbacks.set(key, new Set())
+ }
+ keyCallbacks.get(key)!.add(callback)
+
+ return () => {
+ const set = keyCallbacks.get(key)
+ if (set) {
+ set.delete(callback)
+ if (set.size === 0) {
+ keyCallbacks.delete(key)
+ }
+ }
+ }
+ }, [key, callback])
+
+ useSWRSubscription('global-keydown', () => {
+ const handler = (e: KeyboardEvent) => {
+ if (e.metaKey && keyCallbacks.has(e.key)) {
+ keyCallbacks.get(e.key)!.forEach(cb => cb())
+ }
+ }
+ window.addEventListener('keydown', handler)
+ return () => window.removeEventListener('keydown', handler)
+ })
+}
+
+function Profile() {
+ // Multiple shortcuts will share the same listener
+ useKeyboardShortcut('p', () => { /* ... */ })
+ useKeyboardShortcut('k', () => { /* ... */ })
+ // ...
+}
+```
diff --git a/.windsurf/skills/vercel-react-best-practices/rules/client-localstorage-schema.md b/.windsurf/skills/vercel-react-best-practices/rules/client-localstorage-schema.md
new file mode 100644
index 0000000..d30a1a7
--- /dev/null
+++ b/.windsurf/skills/vercel-react-best-practices/rules/client-localstorage-schema.md
@@ -0,0 +1,71 @@
+---
+title: Version and Minimize localStorage Data
+impact: MEDIUM
+impactDescription: prevents schema conflicts, reduces storage size
+tags: client, localStorage, storage, versioning, data-minimization
+---
+
+## Version and Minimize localStorage Data
+
+Add version prefix to keys and store only needed fields. Prevents schema conflicts and accidental storage of sensitive data.
+
+**Incorrect:**
+
+```typescript
+// No version, stores everything, no error handling
+localStorage.setItem('userConfig', JSON.stringify(fullUserObject))
+const data = localStorage.getItem('userConfig')
+```
+
+**Correct:**
+
+```typescript
+const VERSION = 'v2'
+
+function saveConfig(config: { theme: string; language: string }) {
+ try {
+ localStorage.setItem(`userConfig:${VERSION}`, JSON.stringify(config))
+ } catch {
+ // Throws in incognito/private browsing, quota exceeded, or disabled
+ }
+}
+
+function loadConfig() {
+ try {
+ const data = localStorage.getItem(`userConfig:${VERSION}`)
+ return data ? JSON.parse(data) : null
+ } catch {
+ return null
+ }
+}
+
+// Migration from v1 to v2
+function migrate() {
+ try {
+ const v1 = localStorage.getItem('userConfig:v1')
+ if (v1) {
+ const old = JSON.parse(v1)
+ saveConfig({ theme: old.darkMode ? 'dark' : 'light', language: old.lang })
+ localStorage.removeItem('userConfig:v1')
+ }
+ } catch {}
+}
+```
+
+**Store minimal fields from server responses:**
+
+```typescript
+// User object has 20+ fields, only store what UI needs
+function cachePrefs(user: FullUser) {
+ try {
+ localStorage.setItem('prefs:v1', JSON.stringify({
+ theme: user.preferences.theme,
+ notifications: user.preferences.notifications
+ }))
+ } catch {}
+}
+```
+
+**Always wrap in try-catch:** `getItem()` and `setItem()` throw in incognito/private browsing (Safari, Firefox), when quota exceeded, or when disabled.
+
+**Benefits:** Schema evolution via versioning, reduced storage size, prevents storing tokens/PII/internal flags.
diff --git a/.windsurf/skills/vercel-react-best-practices/rules/client-passive-event-listeners.md b/.windsurf/skills/vercel-react-best-practices/rules/client-passive-event-listeners.md
new file mode 100644
index 0000000..ce39a88
--- /dev/null
+++ b/.windsurf/skills/vercel-react-best-practices/rules/client-passive-event-listeners.md
@@ -0,0 +1,48 @@
+---
+title: Use Passive Event Listeners for Scrolling Performance
+impact: MEDIUM
+impactDescription: eliminates scroll delay caused by event listeners
+tags: client, event-listeners, scrolling, performance, touch, wheel
+---
+
+## Use Passive Event Listeners for Scrolling Performance
+
+Add `{ passive: true }` to touch and wheel event listeners to enable immediate scrolling. Browsers normally wait for listeners to finish to check if `preventDefault()` is called, causing scroll delay.
+
+**Incorrect:**
+
+```typescript
+useEffect(() => {
+ const handleTouch = (e: TouchEvent) => console.log(e.touches[0].clientX)
+ const handleWheel = (e: WheelEvent) => console.log(e.deltaY)
+
+ document.addEventListener('touchstart', handleTouch)
+ document.addEventListener('wheel', handleWheel)
+
+ return () => {
+ document.removeEventListener('touchstart', handleTouch)
+ document.removeEventListener('wheel', handleWheel)
+ }
+}, [])
+```
+
+**Correct:**
+
+```typescript
+useEffect(() => {
+ const handleTouch = (e: TouchEvent) => console.log(e.touches[0].clientX)
+ const handleWheel = (e: WheelEvent) => console.log(e.deltaY)
+
+ document.addEventListener('touchstart', handleTouch, { passive: true })
+ document.addEventListener('wheel', handleWheel, { passive: true })
+
+ return () => {
+ document.removeEventListener('touchstart', handleTouch)
+ document.removeEventListener('wheel', handleWheel)
+ }
+}, [])
+```
+
+**Use passive when:** tracking/analytics, logging, any listener that doesn't call `preventDefault()`.
+
+**Don't use passive when:** implementing custom swipe gestures, custom zoom controls, or any listener that needs `preventDefault()`.
diff --git a/.windsurf/skills/vercel-react-best-practices/rules/client-swr-dedup.md b/.windsurf/skills/vercel-react-best-practices/rules/client-swr-dedup.md
new file mode 100644
index 0000000..2a430f2
--- /dev/null
+++ b/.windsurf/skills/vercel-react-best-practices/rules/client-swr-dedup.md
@@ -0,0 +1,56 @@
+---
+title: Use SWR for Automatic Deduplication
+impact: MEDIUM-HIGH
+impactDescription: automatic deduplication
+tags: client, swr, deduplication, data-fetching
+---
+
+## Use SWR for Automatic Deduplication
+
+SWR enables request deduplication, caching, and revalidation across component instances.
+
+**Incorrect (no deduplication, each instance fetches):**
+
+```tsx
+function UserList() {
+ const [users, setUsers] = useState([])
+ useEffect(() => {
+ fetch('/api/users')
+ .then(r => r.json())
+ .then(setUsers)
+ }, [])
+}
+```
+
+**Correct (multiple instances share one request):**
+
+```tsx
+import useSWR from 'swr'
+
+function UserList() {
+ const { data: users } = useSWR('/api/users', fetcher)
+}
+```
+
+**For immutable data:**
+
+```tsx
+import { useImmutableSWR } from '@/lib/swr'
+
+function StaticContent() {
+ const { data } = useImmutableSWR('/api/config', fetcher)
+}
+```
+
+**For mutations:**
+
+```tsx
+import { useSWRMutation } from 'swr/mutation'
+
+function UpdateButton() {
+ const { trigger } = useSWRMutation('/api/user', updateUser)
+ return 
+
+**Features demonstrated**:
+- Real-time vulnerability scanning
+- Severity-based categorization
+- Code suggestion recommendations
+```
+
+**File Organization**:
+```
+repository-root/
+├── README.md
+├── assets/
+│ └── images/
+│ ├── dashboard.png
+│ ├── audit-flow.gif
+│ └── architecture.png
+```
+
+### 7. Quick Start / Installation
+
+**Purpose**: Minimize friction for new users to get started immediately.
+
+**Requirements**:
+- Assume minimal prior knowledge but not zero knowledge
+- Keep to 5-10 steps maximum
+- Include expected output or success indicator
+- Link to detailed setup guide for complex projects
+- Provide platform-specific instructions if applicable
+
+**Standard Structure**:
+
+```markdown
+## Quick Start
+
+### Prerequisites
+
+- Node.js 18.0 or higher
+- npm 8.0 or higher
+- Git
+
+### Installation
+
+1. **Clone the repository**
+ ```bash
+ git clone https://github.com/username/hyperkit.git
+ cd hyperkit
+ ```
+
+2. **Install dependencies**
+ ```bash
+ npm install
+ ```
+
+3. **Set up environment variables**
+ ```bash
+ cp .env.example .env
+ # Edit .env with your configuration
+ ```
+
+4. **Start development server**
+ ```bash
+ npm run dev
+ ```
+
+5. **Verify installation**
+ Open http://localhost:3000 in your browser. You should see the Hyperkit dashboard.
+
+For detailed setup instructions, see [Installation Guide](./docs/installation.md).
+```
+
+**Best Practices**:
+- Show exact commands users can copy-paste
+- Explain each step briefly
+- Show expected output: "You should see..."
+- Provide success confirmation
+- Mention common issues and solutions
+- Link to detailed documentation
+
+### 8. Usage Examples
+
+**Purpose**: Show how to use the project for common scenarios.
+
+**Requirements**:
+- Provide 2-4 clear, working examples
+- Progress from simple to complex
+- Use realistic, meaningful data (not `foo`, `bar`, `baz`)
+- Show complete code including imports
+- Include expected output or console results
+- Comment only on non-obvious lines (not line-by-line)
+
+**Example**:
+
+```markdown
+## Usage
+
+### Basic Smart Contract Audit
+
+```python
+from hyperkit import SmartContractAuditor
+
+# Initialize auditor
+auditor = SmartContractAuditor(
+ model="gpt-4",
+ chains=["ethereum", "polygon"]
+)
+
+# Audit a contract
+results = auditor.audit("path/to/contract.sol")
+
+# View findings
+for finding in results.vulnerabilities:
+ print(f"[{finding.severity}] {finding.title}")
+ print(f" Details: {finding.description}")
+```
+
+Output:
+```
+[HIGH] Unprotected reentrancy attack
+ Details: Function transfers funds before updating state...
+
+[MEDIUM] Missing input validation
+ Details: Function accepts user input without validation...
+```
+
+### Multi-Chain Deployment
+
+```bash
+hyperkit deploy \
+ --contract=./contracts/Token.sol \
+ --networks=ethereum,polygon,avalanche \
+ --report=detailed
+```
+
+### Integration with Existing Tools
+
+See [Examples Directory](./docs/examples/) for more advanced use cases.
+```
+
+### 9. Documentation Links
+
+**Purpose**: Guide users to comprehensive documentation for topics beyond the README scope.
+
+**Structure**:
+
+```markdown
+## Documentation
+
+For more information, visit:
+
+- **[User Guide](./docs/user-guide.md)** - Complete feature documentation
+- **[API Reference](./docs/api/)** - Detailed API documentation
+- **[Developer Setup](./docs/development/setup.md)** - Development environment setup
+- **[Architecture](./docs/architecture.md)** - System design and component overview
+- **[FAQ](./docs/faq.md)** - Frequently asked questions
+- **[Changelog](./CHANGELOG.md)** - Version history and updates
+```
+
+### 10. Contributing
+
+**Purpose**: Welcome and guide potential contributors.
+
+**Minimum Content**:
+
+```markdown
+## Contributing
+
+We welcome contributions! To contribute:
+
+1. **Fork** the repository
+2. **Create a feature branch** (`git checkout -b feature/amazing-feature`)
+3. **Make your changes** and commit (`git commit -m 'Add amazing feature'`)
+4. **Push to your branch** (`git push origin feature/amazing-feature`)
+5. **Open a Pull Request**
+
+For detailed contribution guidelines, see [CONTRIBUTING.md](./CONTRIBUTING.md).
+
+### Code of Conduct
+
+Please note we have a [Code of Conduct](./CODE_OF_CONDUCT.md).
+By participating, you are expected to uphold this code.
+```
+
+**Best Practices**:
+- Link to detailed CONTRIBUTING.md for full guidelines
+- Make contribution process obvious and welcoming
+- Mention code of conduct
+- Provide multiple ways to contribute (code, docs, testing, issues)
+
+### 11. License
+
+**Purpose**: Clarify intellectual property and usage rights.
+
+**Standard Format**:
+
+```markdown
+## License
+
+This project is licensed under the [MIT License](./LICENSE) -
+see the LICENSE file for details.
+
+Contributions to this project are accepted under the same license.
+```
+
+**Recommended Licenses** (by use case):
+
+| License | Best For |
+|---------|----------|
+| **MIT** | Permissive, most popular for open source |
+| **Apache 2.0** | Commercial-friendly with patent protection |
+| **GPL-3.0** | Copyleft; ensures derived works remain open |
+| **AGPL-3.0** | Network copyleft for SaaS/cloud services |
+| **ISC** | Minimal, simple permissive license |
+
+**License File**:
+- Always include a separate `LICENSE` file in repository root
+- Use exact license text from [choosealicense.com](https://choosealicense.com)
+- Do not modify license text
+
+### 12. Citation (Optional)
+
+**When to Include**:
+- Academic or research-focused projects
+- Projects that should be cited in published work
+- Projects with published papers or documentation
+
+**Format** (BibTeX):
+
+```markdown
+## Citation
+
+If you use Hyperkit in your research, please cite:
+
+```bibtex
+@software{hyperkit2025,
+ author = {Your Name},
+ title = {Hyperkit: AI-Powered Smart Contract Auditing},
+ year = {2025},
+ url = {https://github.com/username/hyperkit}
+}
+```
+
+Or use this APA format:
+
+Your Name. (2025). Hyperkit: AI-powered smart contract auditing platform.
+Retrieved from https://github.com/username/hyperkit
+```
+
+### 13. Authors & Acknowledgments
+
+**Purpose**: Credit creators, contributors, and inspirations. Build community.
+
+**Structure**:
+
+```markdown
+## Authors
+
+- **[Your Name](https://github.com/yourname)** - Creator and Maintainer
+- **[Contributor Name](https://github.com/contributor)** - Major Contributions
+
+## Acknowledgments
+
+Special thanks to:
+
+- [Project Inspiration](https://github.com/inspiration) for the original concept
+- [Library/Tool Name](https://github.com/library) for core functionality
+- All [contributors](./CONTRIBUTORS.md) who have helped improve this project
+
+### Contributors
+
+See [CONTRIBUTORS.md](./CONTRIBUTORS.md) for a full list of contributors.
+```
+
+---
+
+## Formatting and Styling Standards
+
+### Heading Hierarchy
+
+**Correct Structure**:
+```
+# Title (H1) — One per document
+## Major Section (H2)
+### Subsection (H3)
+#### Details (H4)
+```
+
+**Do Not**:
+- Use multiple H1 headings in one document
+- Skip heading levels (e.g., H2 → H4)
+- Use headings for styling purposes only
+
+### Lists
+
+**Unordered Lists** (bullet points):
+- Use for items without inherent order
+- Use one of: `-`, `*`, or `+` consistently
+- Do not exceed 10 items per list
+- Use for features, prerequisites, steps with alternatives
+
+**Ordered Lists** (numbered):
+- Use for step-by-step procedures
+- Use for prioritized items
+- Use for ranked lists
+- Restart numbering for each list
+- Avoid nesting more than 2 levels
+
+**Example**:
+```markdown
+### Installation Steps
+
+1. Clone the repository
+ - Using HTTPS: `git clone https://...`
+ - Using SSH: `git clone git@...`
+
+2. Install dependencies
+ ```bash
+ npm install
+ ```
+
+3. Configure environment
+ - Copy `.env.example` to `.env`
+ - Update with your settings
+```
+
+### Code Blocks
+
+**Requirements**:
+- Always specify language for syntax highlighting
+- Keep examples under 20 lines
+- Include sufficient context (imports, setup)
+- Add inline comments only for non-obvious code
+- Show both input and output when relevant
+
+**Example**:
+```markdown
+```python
+from hyperkit import SmartContractAuditor
+
+# Initialize with model and chains
+auditor = SmartContractAuditor(model="gpt-4")
+
+# Audit contract
+results = auditor.audit("contract.sol")
+```
+```
+
+**Language Identifiers**:
+- `python` - Python code
+- `javascript` or `js` - JavaScript
+- `typescript` or `ts` - TypeScript
+- `bash` or `shell` - Shell commands
+- `json` - JSON data
+- `yaml` or `yml` - YAML configuration
+- `sql` - SQL queries
+- `markdown` - Markdown content
+
+### Tables
+
+**Usage**:
+- Use for comparing features, options, or structured data
+- Include clear headers
+- Align columns consistently
+- Provide explanatory text above complex tables
+
+**Example**:
+```markdown
+### Supported Networks
+
+| Network | Mainnet | Testnet | Support Level |
+|---------|---------|---------|---------------|
+| Ethereum | ✓ | ✓ | Full |
+| Polygon | ✓ | ✓ | Full |
+| Avalanche | ✓ | ✓ | Experimental |
+```
+
+### Emphasis
+
+**Guidelines**:
+- Limit emphasis to ~10% of total text
+- Use **bold** for: UI elements, command names, key terms
+- Use *italics* for: file names, variable names, conceptual terms
+- Use `code formatting` for: code, commands, technical terminology
+- Avoid ALL CAPS for emphasis; use bold instead
+
+**Example**:
+```markdown
+Run the `npm install` command to install **dependencies**.
+Configure your *.env* file with API keys.
+```
+
+### Relative Links
+
+**Best Practice**: Use relative links for internal documentation to support cloned repositories.
+
+**Example**:
+```markdown
+
+[Contribution Guidelines](./CONTRIBUTING.md)
+[Development Setup](./docs/development/setup.md)
+
+
+[Contribution Guidelines](https://github.com/username/repo/blob/main/CONTRIBUTING.md)
+```
+
+### Images and Media
+
+**File Organization**:
+```
+repository-root/
+├── README.md
+├── docs/
+├── src/
+└── assets/
+ ├── images/
+ │ ├── demo-screenshot.png
+ │ ├── architecture.png
+ │ └── workflow.gif
+ └── videos/ (optional)
+```
+
+**Image Implementation**:
+```markdown
+
+
+
+
+
+```
+
+**Image Specifications**:
+- Use descriptive alt text for accessibility
+- Crop to relevant content only
+- Compress images to reasonable file size
+- Use PNG for screenshots (lossless)
+- Use GIF or WebP for animations
+- Use JPG for photographs
+- Specify width; height adjusts automatically to maintain aspect ratio
+
+### Emoji Usage
+
+**Strategic Emoji Placement**:
+- Use emojis in section headers for visual break (maximum 1 per section)
+- Use emojis in feature lists for quick visual scanning
+- Avoid excessive emoji use (unprofessional appearance)
+- Ensure emoji choices are semantic and helpful
+- Support screen readers by including descriptive text
+
+**Recommended Emojis by Context**:
+```
+🚀 Launch, quick start, getting started
+📖 Documentation, guides, learning
+🔧 Configuration, setup, installation
+⚙️ Settings, configuration, advanced options
+🐛 Bugs, issues, troubleshooting
+✨ Features, highlights, new features
+📊 Analytics, metrics, data
+🔍 Search, find, discover
+⚡ Performance, speed, optimization
+🔐 Security, authentication, encryption
+🌐 Global, web, internet, multi-chain
+💡 Tips, ideas, insights
+❓ FAQ, questions, help
+📝 Notes, documentation, changelog
+```
+
+**Not Recommended**:
+- Random emoji not connected to content meaning
+- Multiple emoji per line (visual noise)
+- Emoji instead of actual descriptive text
+- Complex emoji that don't render consistently across platforms
+
+---
+
+## Professional Standards and Practices
+
+### Length and Scope
+
+**Optimal README Length**:
+- 500-2000 words (typically)
+- Longer READMEs may indicate content belongs in separate documentation
+- Shorter READMEs may not provide sufficient information
+
+**Content Boundaries**:
+- README: Project overview, quick start, basic usage, links to detailed docs
+- Separate Documentation: Detailed API docs, architecture, advanced topics
+- GitHub Wiki or Docs Site: Extensive tutorials, how-to guides, FAQs
+
+**Rule of Thumb**: If a section exceeds 200 words, consider moving it to separate documentation and linking from README.
+
+### Tone and Language
+
+**Voice**:
+- Professional yet approachable
+- Friendly but not flippant
+- Direct and clear
+- Use "you" to address readers
+- Avoid marketing hype or exaggeration
+- Be honest about limitations
+
+**Language**:
+- Use active voice when possible
+- Write in present tense for current features
+- Define technical terms before using
+- Avoid culture-specific idioms or references
+- Use "they/them" pronouns for inclusive language
+- Avoid gendered language
+
+**Example**:
+```
+✓ "You can audit smart contracts to identify vulnerabilities"
+✗ "Smart contracts get audited for things that might be wrong"
+
+✓ "Supports 5+ blockchains including Ethereum, Polygon, and Avalanche"
+✗ "We're super excited to offer blockchain support!"
+```
+
+### Accessibility
+
+**GitHub Markdown Rendering**:
+- Test README rendering on GitHub.com (not just local)
+- Ensure adequate color contrast if using color
+- Use alt text for all images
+- Use semantic headings for screen readers
+- Avoid image-only content; include text alternative
+- Test on mobile devices for responsive display
+
+**Automated Accessibility Checks**:
+- Use GitHub's built-in accessibility checker
+- Test with accessibility browser extensions
+- Run markdown linters for structure validation
+
+### Mobile Rendering
+
+- GitHub automatically renders markdown responsively
+- Avoid wide tables (>4 columns may not display well)
+- Test badges on small screens
+- Use relative widths for embedded content
+- Ensure code blocks are horizontally scrollable
+- Preview README on mobile device before publishing
+
+### Maintenance and Updates
+
+**Keep Current**:
+- Update README when project changes significantly
+- Fix broken links immediately
+- Update installation instructions after major updates
+- Refresh screenshots annually or after UI changes
+- Update badges to reflect current project state
+
+**Process**:
+- Link README updates to code changes in Git commits
+- Include README changes in Pull Requests
+- Review README during release planning
+- Use GitHub Issues to track documentation needs
+
+**Automation**:
+- Use GitHub Actions to check for broken links
+- Automate badge updates from CI/CD
+- Generate documentation from code comments where applicable
+- Periodically (quarterly) audit links and content accuracy
+
+---
+
+## README Checklist
+
+Before publishing or updating your README, verify:
+
+### Essential Content
+- [ ] Project title is clear and descriptive
+- [ ] Brief description explains what the project does
+- [ ] Installation/Quick Start instructions work and are current
+- [ ] At least 2-3 working usage examples provided
+- [ ] Links to detailed documentation included
+- [ ] Contributing guidelines linked (CONTRIBUTING.md exists)
+- [ ] License clearly specified
+
+### Formatting and Style
+- [ ] Uses clear heading hierarchy (one H1, proper heading levels)
+- [ ] Proper markdown syntax with no rendering errors
+- [ ] Consistent formatting throughout (bold, italics, code blocks)
+- [ ] All code blocks have language identifiers
+- [ ] Relative links used for internal documentation
+- [ ] All links tested and working
+- [ ] Images have descriptive alt text
+- [ ] Images compressed and stored in appropriate directory
+
+### Professional Quality
+- [ ] Uses active voice and clear language
+- [ ] No typos or grammar errors
+- [ ] Tone is professional yet approachable
+- [ ] Jargon defined or explained
+- [ ] Content scannable with good use of whitespace
+- [ ] Mobile-friendly; tested on small screens
+- [ ] Accessibility tested; alt text provided
+- [ ] Information current and accurate
+
+### Badges and Visuals
+- [ ] Badges (if used) are working and current
+- [ ] Screenshots/GIFs are high quality and relevant
+- [ ] Visual hierarchy draws attention to important info
+- [ ] No excessive emoji or visual clutter
+
+### GitHub Integration
+- [ ] README located in repository root
+- [ ] File named exactly `README.md` (case-sensitive)
+- [ ] Renders correctly on GitHub.com
+- [ ] Table of Contents (if present) links work correctly
+- [ ] All GitHub-specific features tested
+
+---
+
+## Example README Template
+
+```markdown
+# Project Title: Clear, Descriptive, Memorable
+
+
+
+
+
+
+
+## Overview
+
+Brief, compelling description of what your project does (2-3 sentences).
+Explain the problem it solves and its primary use cases.
+
+## Table of Contents
+
+- [Features](#features)
+- [Quick Start](#quick-start)
+- [Usage](#usage)
+- [Documentation](#documentation)
+- [Contributing](#contributing)
+- [License](#license)
+
+## Features
+
+- ✨ **Key Feature 1** - Brief description of benefit
+- 🚀 **Key Feature 2** - Brief description of benefit
+- 📊 **Key Feature 3** - Brief description of benefit
+
+## Quick Start
+
+### Prerequisites
+
+- List any required software or knowledge
+
+### Installation
+
+```bash
+# Step-by-step commands
+git clone https://github.com/username/project.git
+cd project
+npm install
+```
+
+## Usage
+
+```python
+# Working code example with context
+```
+
+## Documentation
+
+- [Full Documentation](./docs/)
+- [API Reference](./docs/api.md)
+- [Contributing Guide](./CONTRIBUTING.md)
+
+## Contributing
+
+We welcome contributions! See [CONTRIBUTING.md](./CONTRIBUTING.md) for guidelines.
+
+## License
+
+Licensed under [MIT License](./LICENSE).
+
+## Acknowledgments
+
+Thanks to [inspiration/tools/people] for [reason].
+```
+
+---
+
+## Tools and Resources
+
+### Markdown Tools
+- **markdown-toc** - Automatically generate table of contents
+- **markdownlint** - Validate markdown syntax and style
+- **prettier** - Format markdown consistently
+
+### Badge Resources
+- **[shields.io](https://shields.io)** - Professional badge creation
+- **[Badgen](https://badgen.net)** - Alternative badge generator
+- **GitHub badges** - Build status, coverage, etc.
+
+### Testing and Validation
+- **[Markdown Preview](https://github.com/markdown-preview/markdown-preview-plus)** - Preview in editor
+- **GitHub Pages** - Preview README in rendered form
+- **Mobile browsers** - Test responsive rendering
+
+### Inspiration
+- Review READMEs of successful projects in your domain
+- Use templates: [Best-README-Template](https://github.com/othneildrew/Best-README-Template)
+- Study award-winning open-source projects
\ No newline at end of file
diff --git a/.cursor/rules/rules.mdc b/.cursor/rules/rules.mdc
new file mode 100644
index 0000000..411dffd
--- /dev/null
+++ b/.cursor/rules/rules.mdc
@@ -0,0 +1,43 @@
+---
+description: Clean Code Implementation and Project Management Best Practices
+globs:
+ - "**/*.ts"
+ - "**/*.js"
+ - "**/*.tsx"
+ - "**/*.jsx"
+alwaysApply: true
+---
+
+# Clean Code Implementation Techniques
+
+- Use descriptive, intention-revealing names for variables, functions, classes, etc.
+- Avoid vague or misleading names to improve readability and maintainability.
+- Each function or module should have one clear purpose, following Single Responsibility Principle (SRP).
+- Write code that clearly expresses intent to minimize comments; comment "why", not "what".
+- Replace magic numbers or strings with named constants for clarity.
+- Organize code into layers or modules (routes, controllers, services, models).
+- Implement centralized and consistent error handling.
+- Use modern language features like async/await for better async operations management.
+- Use code linting and formatting tools (ESLint, Prettier) automatically.
+- Write unit tests to ensure correctness and ease future refactoring.
+- Avoid duplications by abstracting repeated logic into reusable functions/classes.
+- Enforce coding standards using linters and pre-commit hooks.
+- Regularly refactor code for simplicity and reduced technical debt.
+- Avoid Emoji on UI and Codebase
+- Always Professional UI Layout Positioning, Font, Spacing, and more releants
+
+# Project Management and Collaboration
+
+- Define clear project scope, objectives, deliverables, deadlines, and constraints.
+- Assign clear roles and responsibilities for team members.
+- Use project management tools for task, version, and documentation tracking.
+- Practice regular communication, standups, reviews, and retrospectives.
+- Design APIs/modules to be idempotent and implement caching/memoization.
+- Use code reviews with multiple reviewers and integrate automated checks.
+- Employ branching strategies like GitFlow and commit with descriptive messages.
+- Maintain detailed project documentation, including API docs and architecture decisions.
+- Automate repetitive tasks such as builds, deployments, and code quality checks.
+- Use effective communication tools (Slack, Teams) for streamlined interactions.
+- Share reusable code snippets consistently.
+- Keep audit trails with reasons and author for changes and enforce access controls.
+- Adapt conflict resolution styles and encourage collaborative problem-solving.
\ No newline at end of file
diff --git a/.cursor/skills.md b/.cursor/skills.md
new file mode 100644
index 0000000..7b8a28a
--- /dev/null
+++ b/.cursor/skills.md
@@ -0,0 +1,63 @@
+# HyperAgent AI Skills Index
+
+This file provides an index of available AI skills for the HyperAgent project.
+
+## Available Skills
+
+### Backend & API
+- `fastapi/` - FastAPI backend patterns and templates
+- `fastapi-templates/` - FastAPI project templates
+
+### Agent Orchestration
+- `langgraph/` - LangGraph agent orchestration
+- `langgraph-docs/` - LangGraph documentation
+- `langchain-architecture/` - LangChain architecture patterns
+
+### Database & Storage
+- `supabase-postgres-best-practices/` - Supabase and PostgreSQL best practices
+- `database-schema-designer/` - Database schema design tools
+- `database-schema-documentation/` - Database documentation generation
+
+### Smart Contracts
+- `solidity-development/` - Solidity development patterns
+- `smart-contract-security/` - Smart contract security practices
+
+### DevOps & Infrastructure
+- `gitops-principles-skill/` - GitOps principles and patterns
+- `gitops-workflow/` - GitOps workflow automation
+- `github-workflow-automation/` - GitHub Actions automation
+- `github-actions-templates/` - GitHub Actions templates
+
+### Project Management
+- `github-projects/` - GitHub Projects management
+- `github-issues/` - GitHub Issues management
+- `planning-with-files/` - File-based planning tools
+
+### Documentation & Design
+- `api-documentation-generator/` - API documentation generation
+- `beautiful-mermaid/` - Mermaid diagram generation
+- `file-organizer/` - File organization tools
+
+### Monitoring & Observability
+- `prometheus-configuration/` - Prometheus configuration
+
+### Debugging
+- `debugging-strategies/` - Debugging strategies and tools
+
+## Usage
+
+When an AI agent needs to perform a task:
+1. Check this index for relevant skills
+2. Load the specific skill from `.cursor/skills/{skill-name}/SKILL.md`
+3. Follow the skill's instructions and use its templates/references
+4. Apply the skill's patterns to the current task
+
+## Skill Structure
+
+Each skill follows this structure:
+- `SKILL.md` - Main skill documentation
+- `references/` - Reference materials and guides
+- `templates/` - Code templates and examples
+- `scripts/` - Utility scripts (if applicable)
+- `assets/` - Additional assets (if applicable)
+
diff --git a/.cursor/skills/api-documentation-generator/SKILL.md b/.cursor/skills/api-documentation-generator/SKILL.md
new file mode 100644
index 0000000..631aa33
--- /dev/null
+++ b/.cursor/skills/api-documentation-generator/SKILL.md
@@ -0,0 +1,484 @@
+---
+name: api-documentation-generator
+description: "Generate comprehensive, developer-friendly API documentation from code, including endpoints, parameters, examples, and best practices"
+---
+
+# API Documentation Generator
+
+## Overview
+
+Automatically generate clear, comprehensive API documentation from your codebase. This skill helps you create professional documentation that includes endpoint descriptions, request/response examples, authentication details, error handling, and usage guidelines.
+
+Perfect for REST APIs, GraphQL APIs, and WebSocket APIs.
+
+## When to Use This Skill
+
+- Use when you need to document a new API
+- Use when updating existing API documentation
+- Use when your API lacks clear documentation
+- Use when onboarding new developers to your API
+- Use when preparing API documentation for external users
+- Use when creating OpenAPI/Swagger specifications
+
+## How It Works
+
+### Step 1: Analyze the API Structure
+
+First, I'll examine your API codebase to understand:
+- Available endpoints and routes
+- HTTP methods (GET, POST, PUT, DELETE, etc.)
+- Request parameters and body structure
+- Response formats and status codes
+- Authentication and authorization requirements
+- Error handling patterns
+
+### Step 2: Generate Endpoint Documentation
+
+For each endpoint, I'll create documentation including:
+
+**Endpoint Details:**
+- HTTP method and URL path
+- Brief description of what it does
+- Authentication requirements
+- Rate limiting information (if applicable)
+
+**Request Specification:**
+- Path parameters
+- Query parameters
+- Request headers
+- Request body schema (with types and validation rules)
+
+**Response Specification:**
+- Success response (status code + body structure)
+- Error responses (all possible error codes)
+- Response headers
+
+**Code Examples:**
+- cURL command
+- JavaScript/TypeScript (fetch/axios)
+- Python (requests)
+- Other languages as needed
+
+### Step 3: Add Usage Guidelines
+
+I'll include:
+- Getting started guide
+- Authentication setup
+- Common use cases
+- Best practices
+- Rate limiting details
+- Pagination patterns
+- Filtering and sorting options
+
+### Step 4: Document Error Handling
+
+Clear error documentation including:
+- All possible error codes
+- Error message formats
+- Troubleshooting guide
+- Common error scenarios and solutions
+
+### Step 5: Create Interactive Examples
+
+Where possible, I'll provide:
+- Postman collection
+- OpenAPI/Swagger specification
+- Interactive code examples
+- Sample responses
+
+## Examples
+
+### Example 1: REST API Endpoint Documentation
+
+```markdown
+## Create User
+
+Creates a new user account.
+
+**Endpoint:** `POST /api/v1/users`
+
+**Authentication:** Required (Bearer token)
+
+**Request Body:**
+\`\`\`json
+{
+ "email": "user@example.com", // Required: Valid email address
+ "password": "SecurePass123!", // Required: Min 8 chars, 1 uppercase, 1 number
+ "name": "John Doe", // Required: 2-50 characters
+ "role": "user" // Optional: "user" or "admin" (default: "user")
+}
+\`\`\`
+
+**Success Response (201 Created):**
+\`\`\`json
+{
+ "id": "usr_1234567890",
+ "email": "user@example.com",
+ "name": "John Doe",
+ "role": "user",
+ "createdAt": "2026-01-20T10:30:00Z",
+ "emailVerified": false
+}
+\`\`\`
+
+**Error Responses:**
+
+- `400 Bad Request` - Invalid input data
+ \`\`\`json
+ {
+ "error": "VALIDATION_ERROR",
+ "message": "Invalid email format",
+ "field": "email"
+ }
+ \`\`\`
+
+- `409 Conflict` - Email already exists
+ \`\`\`json
+ {
+ "error": "EMAIL_EXISTS",
+ "message": "An account with this email already exists"
+ }
+ \`\`\`
+
+- `401 Unauthorized` - Missing or invalid authentication token
+
+**Example Request (cURL):**
+\`\`\`bash
+curl -X POST https://api.example.com/api/v1/users \
+ -H "Authorization: Bearer YOUR_TOKEN" \
+ -H "Content-Type: application/json" \
+ -d '{
+ "email": "user@example.com",
+ "password": "SecurePass123!",
+ "name": "John Doe"
+ }'
+\`\`\`
+
+**Example Request (JavaScript):**
+\`\`\`javascript
+const response = await fetch('https://api.example.com/api/v1/users', {
+ method: 'POST',
+ headers: {
+ 'Authorization': `Bearer ${token}`,
+ 'Content-Type': 'application/json'
+ },
+ body: JSON.stringify({
+ email: 'user@example.com',
+ password: 'SecurePass123!',
+ name: 'John Doe'
+ })
+});
+
+const user = await response.json();
+console.log(user);
+\`\`\`
+
+**Example Request (Python):**
+\`\`\`python
+import requests
+
+response = requests.post(
+ 'https://api.example.com/api/v1/users',
+ headers={
+ 'Authorization': f'Bearer {token}',
+ 'Content-Type': 'application/json'
+ },
+ json={
+ 'email': 'user@example.com',
+ 'password': 'SecurePass123!',
+ 'name': 'John Doe'
+ }
+)
+
+user = response.json()
+print(user)
+\`\`\`
+```
+
+### Example 2: GraphQL API Documentation
+
+```markdown
+## User Query
+
+Fetch user information by ID.
+
+**Query:**
+\`\`\`graphql
+query GetUser($id: ID!) {
+ user(id: $id) {
+ id
+ email
+ name
+ role
+ createdAt
+ posts {
+ id
+ title
+ publishedAt
+ }
+ }
+}
+\`\`\`
+
+**Variables:**
+\`\`\`json
+{
+ "id": "usr_1234567890"
+}
+\`\`\`
+
+**Response:**
+\`\`\`json
+{
+ "data": {
+ "user": {
+ "id": "usr_1234567890",
+ "email": "user@example.com",
+ "name": "John Doe",
+ "role": "user",
+ "createdAt": "2026-01-20T10:30:00Z",
+ "posts": [
+ {
+ "id": "post_123",
+ "title": "My First Post",
+ "publishedAt": "2026-01-21T14:00:00Z"
+ }
+ ]
+ }
+ }
+}
+\`\`\`
+
+**Errors:**
+\`\`\`json
+{
+ "errors": [
+ {
+ "message": "User not found",
+ "extensions": {
+ "code": "USER_NOT_FOUND",
+ "userId": "usr_1234567890"
+ }
+ }
+ ]
+}
+\`\`\`
+```
+
+### Example 3: Authentication Documentation
+
+```markdown
+## Authentication
+
+All API requests require authentication using Bearer tokens.
+
+### Getting a Token
+
+**Endpoint:** `POST /api/v1/auth/login`
+
+**Request:**
+\`\`\`json
+{
+ "email": "user@example.com",
+ "password": "your-password"
+}
+\`\`\`
+
+**Response:**
+\`\`\`json
+{
+ "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
+ "expiresIn": 3600,
+ "refreshToken": "refresh_token_here"
+}
+\`\`\`
+
+### Using the Token
+
+Include the token in the Authorization header:
+
+\`\`\`
+Authorization: Bearer YOUR_TOKEN
+\`\`\`
+
+### Token Expiration
+
+Tokens expire after 1 hour. Use the refresh token to get a new access token:
+
+**Endpoint:** `POST /api/v1/auth/refresh`
+
+**Request:**
+\`\`\`json
+{
+ "refreshToken": "refresh_token_here"
+}
+\`\`\`
+```
+
+## Best Practices
+
+### ✅ Do This
+
+- **Be Consistent** - Use the same format for all endpoints
+- **Include Examples** - Provide working code examples in multiple languages
+- **Document Errors** - List all possible error codes and their meanings
+- **Show Real Data** - Use realistic example data, not "foo" and "bar"
+- **Explain Parameters** - Describe what each parameter does and its constraints
+- **Version Your API** - Include version numbers in URLs (/api/v1/)
+- **Add Timestamps** - Show when documentation was last updated
+- **Link Related Endpoints** - Help users discover related functionality
+- **Include Rate Limits** - Document any rate limiting policies
+- **Provide Postman Collection** - Make it easy to test your API
+
+### ❌ Don't Do This
+
+- **Don't Skip Error Cases** - Users need to know what can go wrong
+- **Don't Use Vague Descriptions** - "Gets data" is not helpful
+- **Don't Forget Authentication** - Always document auth requirements
+- **Don't Ignore Edge Cases** - Document pagination, filtering, sorting
+- **Don't Leave Examples Broken** - Test all code examples
+- **Don't Use Outdated Info** - Keep documentation in sync with code
+- **Don't Overcomplicate** - Keep it simple and scannable
+- **Don't Forget Response Headers** - Document important headers
+
+## Documentation Structure
+
+### Recommended Sections
+
+1. **Introduction**
+ - What the API does
+ - Base URL
+ - API version
+ - Support contact
+
+2. **Authentication**
+ - How to authenticate
+ - Token management
+ - Security best practices
+
+3. **Quick Start**
+ - Simple example to get started
+ - Common use case walkthrough
+
+4. **Endpoints**
+ - Organized by resource
+ - Full details for each endpoint
+
+5. **Data Models**
+ - Schema definitions
+ - Field descriptions
+ - Validation rules
+
+6. **Error Handling**
+ - Error code reference
+ - Error response format
+ - Troubleshooting guide
+
+7. **Rate Limiting**
+ - Limits and quotas
+ - Headers to check
+ - Handling rate limit errors
+
+8. **Changelog**
+ - API version history
+ - Breaking changes
+ - Deprecation notices
+
+9. **SDKs and Tools**
+ - Official client libraries
+ - Postman collection
+ - OpenAPI specification
+
+## Common Pitfalls
+
+### Problem: Documentation Gets Out of Sync
+**Symptoms:** Examples don't work, parameters are wrong, endpoints return different data
+**Solution:**
+- Generate docs from code comments/annotations
+- Use tools like Swagger/OpenAPI
+- Add API tests that validate documentation
+- Review docs with every API change
+
+### Problem: Missing Error Documentation
+**Symptoms:** Users don't know how to handle errors, support tickets increase
+**Solution:**
+- Document every possible error code
+- Provide clear error messages
+- Include troubleshooting steps
+- Show example error responses
+
+### Problem: Examples Don't Work
+**Symptoms:** Users can't get started, frustration increases
+**Solution:**
+- Test every code example
+- Use real, working endpoints
+- Include complete examples (not fragments)
+- Provide a sandbox environment
+
+### Problem: Unclear Parameter Requirements
+**Symptoms:** Users send invalid requests, validation errors
+**Solution:**
+- Mark required vs optional clearly
+- Document data types and formats
+- Show validation rules
+- Provide example values
+
+## Tools and Formats
+
+### OpenAPI/Swagger
+Generate interactive documentation:
+```yaml
+openapi: 3.0.0
+info:
+ title: My API
+ version: 1.0.0
+paths:
+ /users:
+ post:
+ summary: Create a new user
+ requestBody:
+ required: true
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/CreateUserRequest'
+```
+
+### Postman Collection
+Export collection for easy testing:
+```json
+{
+ "info": {
+ "name": "My API",
+ "schema": "https://schema.getpostman.com/json/collection/v2.1.0/collection.json"
+ },
+ "item": [
+ {
+ "name": "Create User",
+ "request": {
+ "method": "POST",
+ "url": "{{baseUrl}}/api/v1/users"
+ }
+ }
+ ]
+}
+```
+
+## Related Skills
+
+- `@doc-coauthoring` - For collaborative documentation writing
+- `@copywriting` - For clear, user-friendly descriptions
+- `@test-driven-development` - For ensuring API behavior matches docs
+- `@systematic-debugging` - For troubleshooting API issues
+
+## Additional Resources
+
+- [OpenAPI Specification](https://swagger.io/specification/)
+- [REST API Best Practices](https://restfulapi.net/)
+- [GraphQL Documentation](https://graphql.org/learn/)
+- [API Design Patterns](https://www.apiguide.com/)
+- [Postman Documentation](https://learning.postman.com/docs/)
+
+---
+
+**Pro Tip:** Keep your API documentation as close to your code as possible. Use tools that generate docs from code comments to ensure they stay in sync!
diff --git a/.cursor/skills/beautiful-mermaid/SKILL.md b/.cursor/skills/beautiful-mermaid/SKILL.md
new file mode 100644
index 0000000..cde7900
--- /dev/null
+++ b/.cursor/skills/beautiful-mermaid/SKILL.md
@@ -0,0 +1,171 @@
+---
+name: beautiful-mermaid
+description: Render Mermaid diagrams as SVG and PNG using the Beautiful Mermaid library. Use when the user asks to render a Mermaid diagram.
+---
+
+# Beautiful Mermaid Diagram Rendering
+
+Render Mermaid diagrams as SVG and PNG images using the Beautiful Mermaid library.
+
+## Dependencies
+
+This skill requires the `agent-browser` skill for PNG rendering. Load it before proceeding with PNG capture.
+
+## Supported Diagram Types
+
+- **Flowchart** - Process flows, decision trees, CI/CD pipelines
+- **Sequence** - API calls, OAuth flows, database transactions
+- **State** - State machines, connection lifecycles
+- **Class** - UML class diagrams, design patterns
+- **Entity-Relationship** - Database schemas, data models
+
+## Available Themes
+
+Default, Dracula, Solarized, Zinc Dark, Tokyo Night, Tokyo Night Storm, Tokyo Night Light, Catppuccin Latte, Nord, Nord Light, GitHub Dark, GitHub Light, One Dark.
+
+If no theme is specified, use `default`.
+
+## Common Syntax Patterns
+
+### Flowchart Edge Labels
+
+Use pipe syntax for edge labels:
+
+```mermaid
+A -->|label| B
+A ---|label| B
+```
+
+Avoid space-dash syntax which can cause incomplete renders:
+
+```mermaid
+A -- label --> B # May cause issues
+```
+
+### Node Labels with Special Characters
+
+Wrap labels containing special characters in quotes:
+
+```mermaid
+A["Label with (parens)"]
+B["Label with / slash"]
+```
+
+## Workflow
+
+### Step 1: Generate or Validate Mermaid Code
+
+If the user provides a description rather than code, generate valid Mermaid syntax. Consult `references/mermaid-syntax.md` for full syntax details.
+
+### Step 2: Render SVG
+
+Run the rendering script to produce an SVG file:
+
+```bash
+bun run scripts/render.ts --code "graph TD; A-->B" --output diagram --theme default
+```
+
+Or from a file:
+
+```bash
+bun run scripts/render.ts --input diagram.mmd --output diagram --theme tokyo-night
+```
+
+Alternative runtimes:
+```bash
+npx tsx scripts/render.ts --code "..." --output diagram
+deno run --allow-read --allow-write --allow-net scripts/render.ts --code "..." --output diagram
+```
+
+This produces `