Initial commit

2025-11-30 08:25:53 +08:00
commit 36a2b87167
20 changed files with 3513 additions and 0 deletions
--- a/.claude-plugin/plugin.json
+++ b/.claude-plugin/plugin.json
@@ -0,0 +1,12 @@
+{
+  "name": "zustand-state-management",
+  "description": "Build type-safe global state in React applications with Zustand. Supports TypeScript, persist middleware, devtools, slices pattern, and Next.js SSR. Use when setting up React state, migrating from Redux/Context API, implementing localStorage persistence, or troubleshooting Next.js hydration errors, TypeScript inference issues, or infinite render loops.",
+  "version": "1.0.0",
+  "author": {
+    "name": "Jeremy Dawes",
+    "email": "jeremy@jezweb.net"
+  },
+  "skills": [
+    "./"
+  ]
+}
--- a/README.md
+++ b/README.md
@@ -0,0 +1,3 @@
+# zustand-state-management
+
+Build type-safe global state in React applications with Zustand. Supports TypeScript, persist middleware, devtools, slices pattern, and Next.js SSR. Use when setting up React state, migrating from Redux/Context API, implementing localStorage persistence, or troubleshooting Next.js hydration errors, TypeScript inference issues, or infinite render loops.
--- a/SKILL.md
+++ b/SKILL.md
@@ -0,0 +1,799 @@
+---
+name: zustand-state-management
+description: |
+  Build type-safe global state in React applications with Zustand. Supports TypeScript, persist middleware, devtools, slices pattern, and Next.js SSR.
+
+  Use when setting up React state, migrating from Redux/Context API, implementing localStorage persistence, or troubleshooting Next.js hydration errors, TypeScript inference issues, or infinite render loops.
+license: MIT
+---
+
+# Zustand State Management
+
+**Status**: Production Ready ✅
+**Last Updated**: 2025-10-24
+**Latest Version**: zustand@5.0.8
+**Dependencies**: React 18+, TypeScript 5+
+
+---
+
+## Quick Start (3 Minutes)
+
+### 1. Install Zustand
+
+```bash
+npm install zustand
+# or
+pnpm add zustand
+# or
+yarn add zustand
+```
+
+**Why Zustand?**
+- Minimal API: Only 1 function to learn (`create`)
+- No boilerplate: No providers, reducers, or actions
+- TypeScript-first: Excellent type inference
+- Fast: Fine-grained subscriptions prevent unnecessary re-renders
+- Flexible: Middleware for persistence, devtools, and more
+
+### 2. Create Your First Store (TypeScript)
+
+```typescript
+import { create } from 'zustand'
+
+interface BearStore {
+  bears: number
+  increase: (by: number) => void
+  reset: () => void
+}
+
+const useBearStore = create<BearStore>()((set) => ({
+  bears: 0,
+  increase: (by) => set((state) => ({ bears: state.bears + by })),
+  reset: () => set({ bears: 0 }),
+}))
+```
+
+**CRITICAL**: Notice the **double parentheses** `create<T>()()` - this is required for TypeScript with middleware.
+
+### 3. Use Store in Components
+
+```tsx
+import { useBearStore } from './store'
+
+function BearCounter() {
+  const bears = useBearStore((state) => state.bears)
+  return <h1>{bears} around here...</h1>
+}
+
+function Controls() {
+  const increase = useBearStore((state) => state.increase)
+  return <button onClick={() => increase(1)}>Add bear</button>
+}
+```
+
+**Why this works:**
+- Components only re-render when their selected state changes
+- No Context providers needed
+- Selector function extracts specific state slice
+
+---
+
+## The 3-Pattern Setup Process
+
+### Pattern 1: Basic Store (JavaScript)
+
+For simple use cases without TypeScript:
+
+```javascript
+import { create } from 'zustand'
+
+const useStore = create((set) => ({
+  count: 0,
+  increment: () => set((state) => ({ count: state.count + 1 })),
+  decrement: () => set((state) => ({ count: state.count - 1 })),
+}))
+```
+
+**When to use:**
+- Prototyping
+- Small apps
+- No TypeScript in project
+
+### Pattern 2: TypeScript Store (Recommended)
+
+For production apps with type safety:
+
+```typescript
+import { create } from 'zustand'
+
+// Define store interface
+interface CounterStore {
+  count: number
+  increment: () => void
+  decrement: () => void
+}
+
+// Create typed store
+const useCounterStore = create<CounterStore>()((set) => ({
+  count: 0,
+  increment: () => set((state) => ({ count: state.count + 1 })),
+  decrement: () => set((state) => ({ count: state.count - 1 })),
+}))
+```
+
+**Key Points:**
+- Separate interface for state + actions
+- Use `create<T>()()` syntax (currying for middleware)
+- Full IDE autocomplete and type checking
+
+### Pattern 3: Persistent Store
+
+For state that survives page reloads:
+
+```typescript
+import { create } from 'zustand'
+import { persist, createJSONStorage } from 'zustand/middleware'
+
+interface UserPreferences {
+  theme: 'light' | 'dark' | 'system'
+  language: string
+  setTheme: (theme: UserPreferences['theme']) => void
+  setLanguage: (language: string) => void
+}
+
+const usePreferencesStore = create<UserPreferences>()(
+  persist(
+    (set) => ({
+      theme: 'system',
+      language: 'en',
+      setTheme: (theme) => set({ theme }),
+      setLanguage: (language) => set({ language }),
+    }),
+    {
+      name: 'user-preferences', // unique name in localStorage
+      storage: createJSONStorage(() => localStorage), // optional: defaults to localStorage
+    },
+  ),
+)
+```
+
+**Why this matters:**
+- State automatically saved to localStorage
+- Restored on page reload
+- Works with sessionStorage too
+- Handles serialization automatically
+
+---
+
+## Critical Rules
+
+### Always Do
+
+✅ Use `create<T>()()` (double parentheses) in TypeScript for middleware compatibility
+✅ Define separate interfaces for state and actions
+✅ Use selector functions to extract specific state slices
+✅ Use `set` with updater functions for derived state: `set((state) => ({ count: state.count + 1 }))`
+✅ Use unique names for persist middleware storage keys
+✅ Handle Next.js hydration with `hasHydrated` flag pattern
+✅ Use `shallow` for selecting multiple values
+✅ Keep actions pure (no side effects except state updates)
+
+### Never Do
+
+❌ Use `create<T>(...)` (single parentheses) in TypeScript - breaks middleware types
+❌ Mutate state directly: `set((state) => { state.count++; return state })` - use immutable updates
+❌ Create new objects in selectors: `useStore((state) => ({ a: state.a }))` - causes infinite renders
+❌ Use same storage name for multiple stores - causes data collisions
+❌ Access localStorage during SSR without hydration check
+❌ Use Zustand for server state - use TanStack Query instead
+❌ Export store instance directly - always export the hook
+
+---
+
+## Known Issues Prevention
+
+This skill prevents **5** documented issues:
+
+### Issue #1: Next.js Hydration Mismatch
+
+**Error**: `"Text content does not match server-rendered HTML"` or `"Hydration failed"`
+
+**Source**:
+- [DEV Community: Persist middleware in Next.js](https://dev.to/abdulsamad/how-to-use-zustands-persist-middleware-in-nextjs-4lb5)
+- GitHub Discussions #2839
+
+**Why It Happens**:
+Persist middleware reads from localStorage on client but not on server, causing state mismatch.
+
+**Prevention**:
+```typescript
+import { create } from 'zustand'
+import { persist } from 'zustand/middleware'
+
+interface StoreWithHydration {
+  count: number
+  _hasHydrated: boolean
+  setHasHydrated: (hydrated: boolean) => void
+  increase: () => void
+}
+
+const useStore = create<StoreWithHydration>()(
+  persist(
+    (set) => ({
+      count: 0,
+      _hasHydrated: false,
+      setHasHydrated: (hydrated) => set({ _hasHydrated: hydrated }),
+      increase: () => set((state) => ({ count: state.count + 1 })),
+    }),
+    {
+      name: 'my-store',
+      onRehydrateStorage: () => (state) => {
+        state?.setHasHydrated(true)
+      },
+    },
+  ),
+)
+
+// In component
+function MyComponent() {
+  const hasHydrated = useStore((state) => state._hasHydrated)
+
+  if (!hasHydrated) {
+    return <div>Loading...</div>
+  }
+
+  // Now safe to render with persisted state
+  return <ActualContent />
+}
+```
+
+### Issue #2: TypeScript Double Parentheses Missing
+
+**Error**: Type inference fails, `StateCreator` types break with middleware
+
+**Source**: [Official Zustand TypeScript Guide](https://zustand.docs.pmnd.rs/guides/typescript)
+
+**Why It Happens**:
+The currying syntax `create<T>()()` is required for middleware to work with TypeScript inference.
+
+**Prevention**:
+```typescript
+// ❌ WRONG - Single parentheses
+const useStore = create<MyStore>((set) => ({
+  // ...
+}))
+
+// ✅ CORRECT - Double parentheses
+const useStore = create<MyStore>()((set) => ({
+  // ...
+}))
+```
+
+**Rule**: Always use `create<T>()()` in TypeScript, even without middleware (future-proof).
+
+### Issue #3: Persist Middleware Import Error
+
+**Error**: `"Attempted import error: 'createJSONStorage' is not exported from 'zustand/middleware'"`
+
+**Source**: GitHub Discussion #2839
+
+**Why It Happens**:
+Wrong import path or version mismatch between zustand and build tools.
+
+**Prevention**:
+```typescript
+// ✅ CORRECT imports for v5
+import { create } from 'zustand'
+import { persist, createJSONStorage } from 'zustand/middleware'
+
+// Verify versions
+// zustand@5.0.8 includes createJSONStorage
+// zustand@4.x uses different API
+
+// Check your package.json
+// "zustand": "^5.0.8"
+```
+
+### Issue #4: Infinite Render Loop
+
+**Error**: Component re-renders infinitely, browser freezes
+
+**Source**: GitHub Discussions #2642
+
+**Why It Happens**:
+Creating new object references in selectors causes Zustand to think state changed.
+
+**Prevention**:
+```typescript
+import { shallow } from 'zustand/shallow'
+
+// ❌ WRONG - Creates new object every time
+const { bears, fishes } = useStore((state) => ({
+  bears: state.bears,
+  fishes: state.fishes,
+}))
+
+// ✅ CORRECT Option 1 - Select primitives separately
+const bears = useStore((state) => state.bears)
+const fishes = useStore((state) => state.fishes)
+
+// ✅ CORRECT Option 2 - Use shallow for multiple values
+const { bears, fishes } = useStore(
+  (state) => ({ bears: state.bears, fishes: state.fishes }),
+  shallow,
+)
+```
+
+### Issue #5: Slices Pattern TypeScript Complexity
+
+**Error**: `StateCreator` types fail to infer, complex middleware types break
+
+**Source**: [Official Slices Pattern Guide](https://github.com/pmndrs/zustand/blob/main/docs/guides/slices-pattern.md)
+
+**Why It Happens**:
+Combining multiple slices requires explicit type annotations for middleware compatibility.
+
+**Prevention**:
+```typescript
+import { create, StateCreator } from 'zustand'
+
+// Define slice types
+interface BearSlice {
+  bears: number
+  addBear: () => void
+}
+
+interface FishSlice {
+  fishes: number
+  addFish: () => void
+}
+
+// Create slices with proper types
+const createBearSlice: StateCreator<
+  BearSlice & FishSlice,  // Combined store type
+  [],                      // Middleware mutators (empty if none)
+  [],                      // Chained middleware (empty if none)
+  BearSlice               // This slice's type
+> = (set) => ({
+  bears: 0,
+  addBear: () => set((state) => ({ bears: state.bears + 1 })),
+})
+
+const createFishSlice: StateCreator<
+  BearSlice & FishSlice,
+  [],
+  [],
+  FishSlice
+> = (set) => ({
+  fishes: 0,
+  addFish: () => set((state) => ({ fishes: state.fishes + 1 })),
+})
+
+// Combine slices
+const useStore = create<BearSlice & FishSlice>()((...a) => ({
+  ...createBearSlice(...a),
+  ...createFishSlice(...a),
+}))
+```
+
+---
+
+## Middleware Configuration
+
+### Persist Middleware (localStorage)
+
+```typescript
+import { create } from 'zustand'
+import { persist, createJSONStorage } from 'zustand/middleware'
+
+interface MyStore {
+  data: string[]
+  addItem: (item: string) => void
+}
+
+const useStore = create<MyStore>()(
+  persist(
+    (set) => ({
+      data: [],
+      addItem: (item) => set((state) => ({ data: [...state.data, item] })),
+    }),
+    {
+      name: 'my-storage',
+      storage: createJSONStorage(() => localStorage),
+      partialize: (state) => ({ data: state.data }), // Only persist 'data'
+    },
+  ),
+)
+```
+
+### Devtools Middleware (Redux DevTools)
+
+```typescript
+import { create } from 'zustand'
+import { devtools } from 'zustand/middleware'
+
+interface CounterStore {
+  count: number
+  increment: () => void
+}
+
+const useStore = create<CounterStore>()(
+  devtools(
+    (set) => ({
+      count: 0,
+      increment: () =>
+        set(
+          (state) => ({ count: state.count + 1 }),
+          undefined,
+          'counter/increment', // Action name in DevTools
+        ),
+    }),
+    { name: 'CounterStore' }, // Store name in DevTools
+  ),
+)
+```
+
+### Combining Multiple Middlewares
+
+```typescript
+import { create } from 'zustand'
+import { devtools, persist } from 'zustand/middleware'
+
+const useStore = create<MyStore>()(
+  devtools(
+    persist(
+      (set) => ({
+        // store definition
+      }),
+      { name: 'my-storage' },
+    ),
+    { name: 'MyStore' },
+  ),
+)
+```
+
+**Order matters**: `devtools(persist(...))` shows persist actions in DevTools.
+
+---
+
+## Common Patterns
+
+### Pattern: Computed/Derived Values
+
+```typescript
+interface StoreWithComputed {
+  items: string[]
+  addItem: (item: string) => void
+  // Computed in selector, not stored
+}
+
+const useStore = create<StoreWithComputed>()((set) => ({
+  items: [],
+  addItem: (item) => set((state) => ({ items: [...state.items, item] })),
+}))
+
+// Use in component
+function ItemCount() {
+  const count = useStore((state) => state.items.length)
+  return <div>{count} items</div>
+}
+```
+
+### Pattern: Async Actions
+
+```typescript
+interface AsyncStore {
+  data: string | null
+  isLoading: boolean
+  error: string | null
+  fetchData: () => Promise<void>
+}
+
+const useAsyncStore = create<AsyncStore>()((set) => ({
+  data: null,
+  isLoading: false,
+  error: null,
+  fetchData: async () => {
+    set({ isLoading: true, error: null })
+    try {
+      const response = await fetch('/api/data')
+      const data = await response.text()
+      set({ data, isLoading: false })
+    } catch (error) {
+      set({ error: (error as Error).message, isLoading: false })
+    }
+  },
+}))
+```
+
+### Pattern: Resetting Store
+
+```typescript
+interface ResettableStore {
+  count: number
+  name: string
+  increment: () => void
+  reset: () => void
+}
+
+const initialState = {
+  count: 0,
+  name: '',
+}
+
+const useStore = create<ResettableStore>()((set) => ({
+  ...initialState,
+  increment: () => set((state) => ({ count: state.count + 1 })),
+  reset: () => set(initialState),
+}))
+```
+
+### Pattern: Selector with Params
+
+```typescript
+interface TodoStore {
+  todos: Array<{ id: string; text: string; done: boolean }>
+  addTodo: (text: string) => void
+  toggleTodo: (id: string) => void
+}
+
+const useStore = create<TodoStore>()((set) => ({
+  todos: [],
+  addTodo: (text) =>
+    set((state) => ({
+      todos: [...state.todos, { id: Date.now().toString(), text, done: false }],
+    })),
+  toggleTodo: (id) =>
+    set((state) => ({
+      todos: state.todos.map((todo) =>
+        todo.id === id ? { ...todo, done: !todo.done } : todo
+      ),
+    })),
+}))
+
+// Use with parameter
+function Todo({ id }: { id: string }) {
+  const todo = useStore((state) => state.todos.find((t) => t.id === id))
+  const toggleTodo = useStore((state) => state.toggleTodo)
+
+  if (!todo) return null
+
+  return (
+    <div>
+      <input
+        type="checkbox"
+        checked={todo.done}
+        onChange={() => toggleTodo(id)}
+      />
+      {todo.text}
+    </div>
+  )
+}
+```
+
+---
+
+## Using Bundled Resources
+
+### Templates (templates/)
+
+This skill includes 8 ready-to-use template files:
+
+- `basic-store.ts` - Minimal JavaScript store example
+- `typescript-store.ts` - Properly typed TypeScript store
+- `persist-store.ts` - localStorage persistence with migration
+- `slices-pattern.ts` - Modular store organization
+- `devtools-store.ts` - Redux DevTools integration
+- `nextjs-store.ts` - SSR-safe Next.js store with hydration
+- `computed-store.ts` - Derived state patterns
+- `async-actions-store.ts` - Async operations with loading states
+
+**Example Usage:**
+```bash
+# Copy template to your project
+cp ~/.claude/skills/zustand-state-management/templates/typescript-store.ts src/store/
+```
+
+**When to use each:**
+- Use `basic-store.ts` for quick prototypes
+- Use `typescript-store.ts` for most production apps
+- Use `persist-store.ts` when state needs to survive page reloads
+- Use `slices-pattern.ts` for large, complex stores (100+ lines)
+- Use `nextjs-store.ts` for Next.js projects with SSR
+
+### References (references/)
+
+Deep-dive documentation for complex scenarios:
+
+- `middleware-guide.md` - Complete middleware documentation (persist, devtools, immer, custom)
+- `typescript-patterns.md` - Advanced TypeScript patterns and troubleshooting
+- `nextjs-hydration.md` - SSR, hydration, and Next.js best practices
+- `migration-guide.md` - Migrating from Redux, Context API, or Zustand v4
+
+**When Claude should load these:**
+- Load `middleware-guide.md` when user asks about persistence, devtools, or custom middleware
+- Load `typescript-patterns.md` when encountering complex type inference issues
+- Load `nextjs-hydration.md` for Next.js-specific problems
+- Load `migration-guide.md` when migrating from other state management solutions
+
+### Scripts (scripts/)
+
+- `check-versions.sh` - Verify Zustand version and compatibility
+
+**Usage:**
+```bash
+cd your-project/
+~/.claude/skills/zustand-state-management/scripts/check-versions.sh
+```
+
+---
+
+## Advanced Topics
+
+### Vanilla Store (Without React)
+
+```typescript
+import { createStore } from 'zustand/vanilla'
+
+const store = createStore<CounterStore>()((set) => ({
+  count: 0,
+  increment: () => set((state) => ({ count: state.count + 1 })),
+}))
+
+// Subscribe to changes
+const unsubscribe = store.subscribe((state) => {
+  console.log('Count changed:', state.count)
+})
+
+// Get current state
+console.log(store.getState().count)
+
+// Update state
+store.getState().increment()
+
+// Cleanup
+unsubscribe()
+```
+
+### Custom Middleware
+
+```typescript
+import { StateCreator, StoreMutatorIdentifier } from 'zustand'
+
+type Logger = <T>(
+  f: StateCreator<T, [], []>,
+  name?: string,
+) => StateCreator<T, [], []>
+
+const logger: Logger = (f, name) => (set, get, store) => {
+  const loggedSet: typeof set = (...a) => {
+    set(...(a as Parameters<typeof set>))
+    console.log(`[${name}]:`, get())
+  }
+  return f(loggedSet, get, store)
+}
+
+// Use custom middleware
+const useStore = create<MyStore>()(
+  logger((set) => ({
+    // store definition
+  }), 'MyStore'),
+)
+```
+
+### Immer Middleware (Mutable Updates)
+
+```typescript
+import { create } from 'zustand'
+import { immer } from 'zustand/middleware/immer'
+
+interface TodoStore {
+  todos: Array<{ id: string; text: string }>
+  addTodo: (text: string) => void
+}
+
+const useStore = create<TodoStore>()(
+  immer((set) => ({
+    todos: [],
+    addTodo: (text) =>
+      set((state) => {
+        // Mutate directly with Immer
+        state.todos.push({ id: Date.now().toString(), text })
+      }),
+  })),
+)
+```
+
+---
+
+## Dependencies
+
+**Required**:
+- `zustand@5.0.8` - State management library
+- `react@18.0.0+` - React framework
+
+**Optional**:
+- `@types/node` - For TypeScript path resolution
+- `immer` - For mutable update syntax
+- Redux DevTools Extension - For devtools middleware
+
+---
+
+## Official Documentation
+
+- **Zustand**: https://zustand.docs.pmnd.rs/
+- **GitHub**: https://github.com/pmndrs/zustand
+- **TypeScript Guide**: https://zustand.docs.pmnd.rs/guides/typescript
+- **Slices Pattern**: https://github.com/pmndrs/zustand/blob/main/docs/guides/slices-pattern.md
+- **Context7 Library ID**: `/pmndrs/zustand`
+
+---
+
+## Package Versions (Verified 2025-10-24)
+
+```json
+{
+  "dependencies": {
+    "zustand": "^5.0.8",
+    "react": "^19.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "typescript": "^5.0.0"
+  }
+}
+```
+
+**Compatibility**:
+- React 18+, React 19 ✅
+- TypeScript 5+ ✅
+- Next.js 14+, Next.js 15+ ✅
+- Vite 5+ ✅
+
+---
+
+## Troubleshooting
+
+### Problem: Store updates don't trigger re-renders
+**Solution**: Ensure you're using selector functions, not destructuring: `const bears = useStore(state => state.bears)` not `const { bears } = useStore()`
+
+### Problem: TypeScript errors with middleware
+**Solution**: Use double parentheses: `create<T>()()` not `create<T>()`
+
+### Problem: Persist middleware causes hydration error
+**Solution**: Implement `_hasHydrated` flag pattern (see Issue #1)
+
+### Problem: Actions not showing in Redux DevTools
+**Solution**: Pass action name as third parameter to `set`: `set(newState, undefined, 'actionName')`
+
+### Problem: Store state resets unexpectedly
+**Solution**: Check if using HMR (hot module replacement) - Zustand resets on module reload in development
+
+---
+
+## Complete Setup Checklist
+
+Use this checklist to verify your Zustand setup:
+
+- [ ] Installed `zustand@5.0.8` or later
+- [ ] Created store with proper TypeScript types
+- [ ] Used `create<T>()()` double parentheses syntax
+- [ ] Tested selector functions in components
+- [ ] Verified components only re-render when selected state changes
+- [ ] If using persist: Configured unique storage name
+- [ ] If using persist: Implemented hydration check for Next.js
+- [ ] If using devtools: Named actions for debugging
+- [ ] If using slices: Properly typed `StateCreator` for each slice
+- [ ] All actions are pure functions
+- [ ] No direct state mutations
+- [ ] Store works in production build
+
+---
+
+**Questions? Issues?**
+
+1. Check [references/typescript-patterns.md](references/typescript-patterns.md) for TypeScript help
+2. Check [references/nextjs-hydration.md](references/nextjs-hydration.md) for Next.js issues
+3. Check [references/middleware-guide.md](references/middleware-guide.md) for persist/devtools help
+4. Official docs: https://zustand.docs.pmnd.rs/
+5. GitHub issues: https://github.com/pmndrs/zustand/issues
--- a/assets/example-template.txt
+++ b/assets/example-template.txt
@@ -0,0 +1,14 @@
+[TODO: Example Template File]
+
+[TODO: This directory contains files that will be used in the OUTPUT that Claude produces.]
+
+[TODO: Examples:]
+- Templates (.html, .tsx, .md)
+- Images (.png, .svg)
+- Fonts (.ttf, .woff)
+- Boilerplate code
+- Configuration file templates
+
+[TODO: Delete this file and add your actual assets]
+
+These files are NOT loaded into context. They are copied or used directly in the final output.
--- a/plugin.lock.json
+++ b/plugin.lock.json
@@ -0,0 +1,109 @@
+{
+  "$schema": "internal://schemas/plugin.lock.v1.json",
+  "pluginId": "gh:jezweb/claude-skills:skills/zustand-state-management",
+  "normalized": {
+    "repo": null,
+    "ref": "refs/tags/v20251128.0",
+    "commit": "66e9a5da10c3fc3bbbc79fa955a12af56dc0d1f8",
+    "treeHash": "a4aa587f60dc89e7fda9871c379f9f86cf4a57fe716d14f9de73f6a1e2b63947",
+    "generatedAt": "2025-11-28T10:18:59.659661Z",
+    "toolVersion": "publish_plugins.py@0.2.0"
+  },
+  "origin": {
+    "remote": "git@github.com:zhongweili/42plugin-data.git",
+    "branch": "master",
+    "commit": "aa1497ed0949fd50e99e70d6324a29c5b34f9390",
+    "repoRoot": "/Users/zhongweili/projects/openmind/42plugin-data"
+  },
+  "manifest": {
+    "name": "zustand-state-management",
+    "description": "Build type-safe global state in React applications with Zustand. Supports TypeScript, persist middleware, devtools, slices pattern, and Next.js SSR. Use when setting up React state, migrating from Redux/Context API, implementing localStorage persistence, or troubleshooting Next.js hydration errors, TypeScript inference issues, or infinite render loops.",
+    "version": "1.0.0"
+  },
+  "content": {
+    "files": [
+      {
+        "path": "README.md",
+        "sha256": "45143f23a412d833a692ea801ba8dd376ca4baaea62074c4818884e3790442b6"
+      },
+      {
+        "path": "SKILL.md",
+        "sha256": "bf7cae6a656ce5a6969503f8cada38364ea3aeeb9f9d166d91b4288efcfc381d"
+      },
+      {
+        "path": "references/example-reference.md",
+        "sha256": "77c788d727d05d6479a61d6652b132e43882ffc67c145bb46ba880567d83f7f8"
+      },
+      {
+        "path": "references/nextjs-hydration.md",
+        "sha256": "ff2def96df47ace91d0902ae01ee34cfb3c68e5fb299db7fdbe48b0d74f34162"
+      },
+      {
+        "path": "references/migration-guide.md",
+        "sha256": "a59c0d560924d2d0c22b0f0cdb3d40eaef035d8f6cdbd408cd4fddb53e6f64cf"
+      },
+      {
+        "path": "references/middleware-guide.md",
+        "sha256": "421fc14143c5bc2651fcbb10083e6d531d0ae49d8de4161217e1360db55d31b5"
+      },
+      {
+        "path": "references/typescript-patterns.md",
+        "sha256": "c671dbe8c06c22c6a3aabcbdb2f98013bf0321fb53cc36160cfc87771bb34390"
+      },
+      {
+        "path": "scripts/check-versions.sh",
+        "sha256": "aec3932e266b7affd59830a5ead12a9d10d21d27cfa92a589a6d450113e564fa"
+      },
+      {
+        "path": "scripts/example-script.sh",
+        "sha256": "83d2b09d044811608e17cbd8e66d993b1e9998c7bd3379a42ab81fbdba973e0e"
+      },
+      {
+        "path": ".claude-plugin/plugin.json",
+        "sha256": "3e03b08c2dc1530bad96d64a1cf703a288fb1f3adbfca8dec00f3388d616afce"
+      },
+      {
+        "path": "templates/async-actions-store.ts",
+        "sha256": "a632d997c7f89ee56eae0cbd2684c88a4cba10bc876cf0f9a55332498af42788"
+      },
+      {
+        "path": "templates/computed-store.ts",
+        "sha256": "9f192a17951fab6fd260acdcae2abd9449f69e2af3e5bb1d479f0d4f4b8cb60b"
+      },
+      {
+        "path": "templates/typescript-store.ts",
+        "sha256": "33f5ad98c9bcfe27ab9442b5ecc69688f37f81055a1df07ba7ccb17ddc6188fc"
+      },
+      {
+        "path": "templates/nextjs-store.ts",
+        "sha256": "8e4d2ac1f0b08a080510b8f11917ecc78813fa0391f8203a91453df65a9926e5"
+      },
+      {
+        "path": "templates/slices-pattern.ts",
+        "sha256": "05c3548a5901bcc34d1ae6f12146aa0638c243c769310b5cf8c7a0d41ed2643f"
+      },
+      {
+        "path": "templates/persist-store.ts",
+        "sha256": "9413e38459af97597d2c0fd558267b8a78f99bc35125964e8bfd100f08b9ff90"
+      },
+      {
+        "path": "templates/basic-store.ts",
+        "sha256": "55b975521c02fa360bbea92a676c5b6d7acbc1eba0d6f7b1a7a05745772a496f"
+      },
+      {
+        "path": "templates/devtools-store.ts",
+        "sha256": "b0cbea6c84bdadac58cefd6fb186cc8531d145ea41fe9f2bd7c6c27679acca98"
+      },
+      {
+        "path": "assets/example-template.txt",
+        "sha256": "3f725c80d70847fd8272bf1400515ba753f12f98f3b294d09e50b54b4c1b024a"
+      }
+    ],
+    "dirSha256": "a4aa587f60dc89e7fda9871c379f9f86cf4a57fe716d14f9de73f6a1e2b63947"
+  },
+  "security": {
+    "scannedAt": null,
+    "scannerVersion": null,
+    "flags": []
+  }
+}
--- a/references/example-reference.md
+++ b/references/example-reference.md
@@ -0,0 +1,26 @@
+# [TODO: Reference Document Name]
+
+[TODO: This file contains reference documentation that Claude can load when needed.]
+
+[TODO: Delete this file if you don't have reference documentation to provide.]
+
+## Purpose
+
+[TODO: Explain what information this document contains]
+
+## When Claude Should Use This
+
+[TODO: Describe specific scenarios where Claude should load this reference]
+
+## Content
+
+[TODO: Add your reference content here - schemas, guides, specifications, etc.]
+
+---
+
+**Note**: This file is NOT loaded into context by default. Claude will only load it when:
+- It determines the information is needed
+- You explicitly ask Claude to reference it
+- The SKILL.md instructions direct Claude to read it
+
+Keep this file under 10k words for best performance.
--- a/references/middleware-guide.md
+++ b/references/middleware-guide.md
@@ -0,0 +1,303 @@
+# Zustand Middleware Complete Guide
+
+Complete reference for all Zustand middleware. Load when user asks about persistence, devtools, immer, or custom middleware.
+
+---
+
+## Persist Middleware
+
+### Basic Usage
+
+```typescript
+import { create } from 'zustand'
+import { persist, createJSONStorage } from 'zustand/middleware'
+
+const useStore = create<Store>()(
+  persist(
+    (set) => ({ /* store */ }),
+    { name: 'storage-name' }
+  )
+)
+```
+
+### Storage Options
+
+```typescript
+// localStorage (default)
+storage: createJSONStorage(() => localStorage)
+
+// sessionStorage
+storage: createJSONStorage(() => sessionStorage)
+
+// Custom storage
+storage: createJSONStorage(() => customStorage)
+```
+
+### Partial Persistence
+
+```typescript
+persist(
+  (set) => ({ /* store */ }),
+  {
+    name: 'storage',
+    partialize: (state) => ({
+      theme: state.theme,
+      // Don't persist sensitive data
+    }),
+  }
+)
+```
+
+### Schema Migration
+
+```typescript
+persist(
+  (set) => ({ /* store */ }),
+  {
+    name: 'storage',
+    version: 2,
+    migrate: (persistedState: any, version) => {
+      if (version === 0) {
+        // v0 → v1
+        persistedState.newField = 'default'
+      }
+      if (version === 1) {
+        // v1 → v2
+        delete persistedState.oldField
+      }
+      return persistedState
+    },
+  }
+)
+```
+
+---
+
+## Devtools Middleware
+
+### Basic Usage
+
+```typescript
+import { devtools } from 'zustand/middleware'
+
+const useStore = create<Store>()(
+  devtools(
+    (set) => ({ /* store */ }),
+    { name: 'StoreName' }
+  )
+)
+```
+
+### Named Actions
+
+```typescript
+increment: () => set(
+  (state) => ({ count: state.count + 1 }),
+  undefined,
+  'counter/increment' // Shows in DevTools
+)
+```
+
+### Production Toggle
+
+```typescript
+devtools(
+  (set) => ({ /* store */ }),
+  {
+    name: 'Store',
+    enabled: process.env.NODE_ENV === 'development'
+  }
+)
+```
+
+---
+
+## Immer Middleware
+
+Allows mutable state updates (Immer handles immutability):
+
+```typescript
+import { immer } from 'zustand/middleware/immer'
+
+const useStore = create<Store>()(
+  immer((set) => ({
+    todos: [],
+    addTodo: (text) => set((state) => {
+      // Mutate directly!
+      state.todos.push({ id: Date.now(), text })
+    }),
+  }))
+)
+```
+
+**When to use**: Complex nested state updates
+
+---
+
+## Combining Middlewares
+
+### Order Matters
+
+```typescript
+// ✅ CORRECT: devtools wraps persist
+const useStore = create<Store>()(
+  devtools(
+    persist(
+      (set) => ({ /* store */ }),
+      { name: 'storage' }
+    ),
+    { name: 'Store' }
+  )
+)
+
+// Shows persist actions in DevTools
+```
+
+### Common Combinations
+
+```typescript
+// Persist + Devtools
+devtools(persist(...), { name: 'Store' })
+
+// Persist + Immer
+persist(immer(...), { name: 'storage' })
+
+// All three
+devtools(
+  persist(
+    immer(...),
+    { name: 'storage' }
+  ),
+  { name: 'Store' }
+)
+```
+
+---
+
+## Custom Middleware
+
+### Logger Example
+
+```typescript
+const logger = (config) => (set, get, api) => {
+  return config(
+    (...args) => {
+      console.log('Before:', get())
+      set(...args)
+      console.log('After:', get())
+    },
+    get,
+    api
+  )
+}
+
+const useStore = create(logger((set) => ({ /* store */ })))
+```
+
+### TypeScript Logger
+
+```typescript
+import { StateCreator } from 'zustand'
+
+type Logger = <T>(
+  f: StateCreator<T, [], []>,
+  name?: string
+) => StateCreator<T, [], []>
+
+const logger: Logger = (f, name) => (set, get, store) => {
+  const loggedSet: typeof set = (...a) => {
+    set(...(a as Parameters<typeof set>))
+    console.log(`[${name}]:`, get())
+  }
+  return f(loggedSet, get, store)
+}
+```
+
+---
+
+## Middleware API Reference
+
+### persist()
+
+```typescript
+persist<T>(
+  stateCreator: StateCreator<T>,
+  options: {
+    name: string                    // Storage key (required)
+    storage?: PersistStorage<T>     // Storage engine
+    partialize?: (state: T) => Partial<T>  // Select what to persist
+    version?: number                // Schema version
+    migrate?: (state: any, version: number) => T  // Migration function
+    merge?: (persisted: any, current: T) => T     // Custom merge
+    onRehydrateStorage?: (state: T) => void       // Hydration callback
+  }
+)
+```
+
+### devtools()
+
+```typescript
+devtools<T>(
+  stateCreator: StateCreator<T>,
+  options?: {
+    name?: string      // Store name in DevTools
+    enabled?: boolean  // Enable/disable
+  }
+)
+```
+
+### immer()
+
+```typescript
+immer<T>(
+  stateCreator: StateCreator<T>
+)
+```
+
+---
+
+## Common Patterns
+
+### Reset Store
+
+```typescript
+const initialState = { count: 0 }
+
+const useStore = create<Store>()(
+  persist(
+    (set) => ({
+      ...initialState,
+      reset: () => set(initialState),
+    }),
+    { name: 'storage' }
+  )
+)
+```
+
+### Clear Persisted Data
+
+```typescript
+// Clear localStorage
+localStorage.removeItem('storage-name')
+
+// Or programmatically
+const useStore = create<Store>()(
+  persist(
+    (set) => ({
+      clearStorage: () => {
+        localStorage.removeItem('storage-name')
+        set(initialState)
+      },
+    }),
+    { name: 'storage-name' }
+  )
+)
+```
+
+---
+
+## Official Documentation
+
+- **Persist**: https://github.com/pmndrs/zustand/blob/main/docs/integrations/persisting-store-data.md
+- **Devtools**: https://github.com/pmndrs/zustand/blob/main/docs/middlewares/devtools.md
+- **Immer**: https://github.com/pmndrs/zustand/blob/main/docs/middlewares/immer.md
--- a/references/migration-guide.md
+++ b/references/migration-guide.md
@@ -0,0 +1,302 @@
+# Migrating to Zustand
+
+Guide for migrating from Redux, Context API, or Zustand v4. Load when user is migrating state management.
+
+---
+
+## From Redux to Zustand
+
+### Before (Redux)
+
+```typescript
+// Action types
+const INCREMENT = 'INCREMENT'
+const DECREMENT = 'DECREMENT'
+
+// Actions
+const increment = () => ({ type: INCREMENT })
+const decrement = () => ({ type: DECREMENT })
+
+// Reducer
+const reducer = (state = { count: 0 }, action) => {
+  switch (action.type) {
+    case INCREMENT:
+      return { count: state.count + 1 }
+    case DECREMENT:
+      return { count: state.count - 1 }
+    default:
+      return state
+  }
+}
+
+// Store
+const store = createStore(reducer)
+
+// Provider
+<Provider store={store}>
+  <App />
+</Provider>
+
+// Component
+const count = useSelector((state) => state.count)
+const dispatch = useDispatch()
+<button onClick={() => dispatch(increment())}>Increment</button>
+```
+
+### After (Zustand)
+
+```typescript
+// Store (all in one!)
+import { create } from 'zustand'
+
+interface Store {
+  count: number
+  increment: () => void
+  decrement: () => void
+}
+
+const useStore = create<Store>()((set) => ({
+  count: 0,
+  increment: () => set((state) => ({ count: state.count + 1 })),
+  decrement: () => set((state) => ({ count: state.count - 1 })),
+}))
+
+// No provider needed!
+
+// Component
+const count = useStore((state) => state.count)
+const increment = useStore((state) => state.increment)
+<button onClick={increment}>Increment</button>
+```
+
+**Benefits**:
+- ~90% less boilerplate
+- No provider wrapper
+- No action types/creators
+- No reducer switch
+- Built-in TypeScript support
+
+---
+
+## From Context API to Zustand
+
+### Before (Context)
+
+```typescript
+// Context
+const CountContext = createContext(null)
+
+// Provider
+function CountProvider({ children }) {
+  const [count, setCount] = useState(0)
+
+  const increment = () => setCount((c) => c + 1)
+  const decrement = () => setCount((c) => c - 1)
+
+  return (
+    <CountContext.Provider value={{ count, increment, decrement }}>
+      {children}
+    </CountContext.Provider>
+  )
+}
+
+// Hook
+function useCount() {
+  const context = useContext(CountContext)
+  if (!context) throw new Error('useCount must be within CountProvider')
+  return context
+}
+
+// App
+<CountProvider>
+  <App />
+</CountProvider>
+
+// Component
+const { count, increment } = useCount()
+```
+
+### After (Zustand)
+
+```typescript
+// Store
+const useStore = create<Store>()((set) => ({
+  count: 0,
+  increment: () => set((state) => ({ count: state.count + 1 })),
+  decrement: () => set((state) => ({ count: state.count - 1 })),
+}))
+
+// Component (no provider needed!)
+const count = useStore((state) => state.count)
+const increment = useStore((state) => state.increment)
+```
+
+**Benefits**:
+- No provider needed
+- No context null checks
+- No wrapper components
+- Better performance (no context re-renders)
+- Persistent by default (with middleware)
+
+---
+
+## From Zustand v4 to v5
+
+### Breaking Changes
+
+#### 1. TypeScript Syntax
+
+```typescript
+// ❌ v4
+const useStore = create<Store>((set) => ({ /* ... */ }))
+
+// ✅ v5
+const useStore = create<Store>()((set) => ({ /* ... */ }))
+//                            ^^ Double parentheses required
+```
+
+#### 2. Persist Middleware Imports
+
+```typescript
+// ❌ v4
+import { persist } from 'zustand/middleware'
+
+const useStore = create(
+  persist((set) => ({ /* ... */ }), { name: 'storage' })
+)
+
+// ✅ v5
+import { persist, createJSONStorage } from 'zustand/middleware'
+
+const useStore = create<Store>()(
+  persist(
+    (set) => ({ /* ... */ }),
+    {
+      name: 'storage',
+      storage: createJSONStorage(() => localStorage),
+    }
+  )
+)
+```
+
+#### 3. Shallow Import
+
+```typescript
+// ❌ v4
+import shallow from 'zustand/shallow'
+
+// ✅ v5
+import { shallow } from 'zustand/shallow'
+```
+
+---
+
+## Migration Strategies
+
+### Gradual Migration
+
+1. **Install Zustand** alongside existing solution
+2. **Migrate one feature** at a time
+3. **Test thoroughly** before moving to next
+4. **Remove old code** once stable
+
+### Big Bang Migration
+
+1. **Create Zustand stores** for all state
+2. **Update all components** at once
+3. **Remove old state management** entirely
+4. **Test everything**
+
+**Recommendation**: Gradual migration for large apps.
+
+---
+
+## Code Mapping
+
+### Redux → Zustand
+
+| Redux | Zustand |
+|-------|---------|
+| Actions | Direct functions in store |
+| Action types | Not needed |
+| Reducers | Inline in `set()` calls |
+| `useSelector` | Direct store selectors |
+| `useDispatch` | Direct function calls |
+| Provider | Not needed |
+| Middleware | Built-in (`persist`, `devtools`) |
+| DevTools | `devtools` middleware |
+
+### Context → Zustand
+
+| Context | Zustand |
+|---------|---------|
+| `createContext` | `create()` |
+| Provider | Not needed |
+| `useContext` | Direct store access |
+| State | Store state |
+| Updaters | Store actions |
+
+---
+
+## Common Pitfalls
+
+### 1. Forgetting Double Parentheses (v5)
+
+```typescript
+// ❌ WRONG
+create<Store>((set) => ({ /* ... */ }))
+
+// ✅ CORRECT
+create<Store>()((set) => ({ /* ... */ }))
+```
+
+### 2. Creating Objects in Selectors
+
+```typescript
+// ❌ WRONG - Causes infinite renders
+const { a, b } = useStore((state) => ({ a: state.a, b: state.b }))
+
+// ✅ CORRECT
+const a = useStore((state) => state.a)
+const b = useStore((state) => state.b)
+```
+
+### 3. Not Using Persist Correctly
+
+```typescript
+// ❌ WRONG - Missing createJSONStorage
+persist((set) => ({ /* ... */ }), { name: 'storage' })
+
+// ✅ CORRECT
+persist(
+  (set) => ({ /* ... */ }),
+  {
+    name: 'storage',
+    storage: createJSONStorage(() => localStorage),
+  }
+)
+```
+
+---
+
+## Checklist
+
+- [ ] Installed Zustand v5+
+- [ ] Created store with `create<T>()()`
+- [ ] Removed Context providers (if migrating from Context)
+- [ ] Removed Redux boilerplate (if migrating from Redux)
+- [ ] Updated all `useSelector` to Zustand selectors
+- [ ] Updated all `useDispatch` to direct function calls
+- [ ] Added `persist` if state needs persistence
+- [ ] Added `devtools` if using Redux DevTools
+- [ ] Tested all components
+- [ ] Verified no hydration errors (Next.js)
+- [ ] Removed old state management code
+
+---
+
+## Official Resources
+
+- **Zustand Docs**: https://zustand.docs.pmnd.rs/
+- **Migration Guide**: https://github.com/pmndrs/zustand/wiki/Migrating-to-v4
+- **TypeScript Guide**: https://zustand.docs.pmnd.rs/guides/typescript
--- a/references/nextjs-hydration.md
+++ b/references/nextjs-hydration.md
@@ -0,0 +1,274 @@
+# Zustand + Next.js Hydration Guide
+
+Complete guide for using Zustand with Next.js SSR. Load for Next.js-specific problems.
+
+---
+
+## The Hydration Problem
+
+**Error**: `"Text content does not match server-rendered HTML"`
+
+**Why it happens**:
+- Server renders with default state
+- Client loads persisted state from localStorage
+- Content doesn't match → hydration error
+
+---
+
+## Solution: Hydration Flag Pattern
+
+### Store Setup
+
+```typescript
+'use client'
+
+import { create } from 'zustand'
+import { persist } from 'zustand/middleware'
+
+interface Store {
+  _hasHydrated: boolean  // Track hydration
+  count: number
+  setHasHydrated: (hydrated: boolean) => void
+  increment: () => void
+}
+
+export const useStore = create<Store>()(
+  persist(
+    (set) => ({
+      _hasHydrated: false,
+      count: 0,
+      setHasHydrated: (hydrated) => set({ _hasHydrated: hydrated }),
+      increment: () => set((state) => ({ count: state.count + 1 })),
+    }),
+    {
+      name: 'storage',
+      onRehydrateStorage: () => (state) => {
+        state?.setHasHydrated(true)  // Set true when done
+      },
+    },
+  ),
+)
+```
+
+### Component Usage
+
+```typescript
+'use client'
+
+function Component() {
+  const hasHydrated = useStore((state) => state._hasHydrated)
+  const count = useStore((state) => state.count)
+
+  if (!hasHydrated) {
+    return <div>Loading...</div>
+  }
+
+  return <div>Count: {count}</div>
+}
+```
+
+---
+
+## Alternative: Accept Flash
+
+If loading state is unacceptable, accept brief flash:
+
+```typescript
+'use client'
+
+function Component() {
+  const count = useStore((state) => state.count)
+
+  // Will show default (0) briefly, then correct value
+  return <div>Count: {count}</div>
+}
+```
+
+**Trade-off**: Simpler code, but user sees flash.
+
+---
+
+## App Router vs Pages Router
+
+### App Router (Recommended)
+
+```typescript
+// app/layout.tsx
+export default function RootLayout({ children }) {
+  return (
+    <html>
+      <body>{children}</body>
+    </html>
+  )
+}
+
+// app/page.tsx
+'use client'
+
+import { useStore } from './store'
+
+export default function Page() {
+  return <Component />
+}
+```
+
+**Note**: Add `'use client'` to components using Zustand.
+
+### Pages Router
+
+```typescript
+// pages/_app.tsx
+export default function App({ Component, pageProps }) {
+  return <Component {...pageProps} />
+}
+
+// pages/index.tsx
+import { useStore } from '../store'
+
+export default function Page() {
+  return <Component />
+}
+```
+
+**Note**: No `'use client'` needed in Pages Router.
+
+---
+
+## Server Components
+
+**NEVER** use Zustand in Server Components:
+
+```typescript
+// ❌ WRONG - Server Component
+export default async function ServerComponent() {
+  const count = useStore((state) => state.count)  // Error!
+  return <div>{count}</div>
+}
+
+// ✅ CORRECT - Client Component
+'use client'
+
+export default function ClientComponent() {
+  const count = useStore((state) => state.count)
+  return <div>{count}</div>
+}
+```
+
+---
+
+## SSR with getServerSideProps
+
+```typescript
+// pages/index.tsx
+import { GetServerSideProps } from 'next'
+
+export const getServerSideProps: GetServerSideProps = async () => {
+  // Fetch data on server
+  const data = await fetchData()
+
+  return {
+    props: { data },
+  }
+}
+
+export default function Page({ data }) {
+  const setData = useStore((state) => state.setData)
+
+  // Sync server data to store
+  useEffect(() => {
+    setData(data)
+  }, [data, setData])
+
+  return <Component />
+}
+```
+
+---
+
+## Common Patterns
+
+### Initialize Store from Props
+
+```typescript
+'use client'
+
+function Page({ serverData }) {
+  const setData = useStore((state) => state.setData)
+
+  useEffect(() => {
+    setData(serverData)
+  }, [serverData, setData])
+
+  return <Component />
+}
+```
+
+### Conditional Rendering
+
+```typescript
+'use client'
+
+function Component() {
+  const hasHydrated = useStore((state) => state._hasHydrated)
+  const theme = useStore((state) => state.theme)
+
+  return (
+    <div className={hasHydrated ? theme : 'default'}>
+      {hasHydrated ? <Content /> : <Skeleton />}
+    </div>
+  )
+}
+```
+
+### Progressive Enhancement
+
+```typescript
+'use client'
+
+function Component() {
+  const hasHydrated = useStore((state) => state._hasHydrated)
+  const preferences = useStore((state) => state.preferences)
+
+  // Always render, but enhance after hydration
+  return (
+    <div>
+      <DefaultUI />
+      {hasHydrated && <EnhancedUI preferences={preferences} />}
+    </div>
+  )
+}
+```
+
+---
+
+## Debugging Hydration Errors
+
+### Enable Strict Mode
+
+```typescript
+// next.config.js
+module.exports = {
+  reactStrictMode: true,
+}
+```
+
+### Check for Differences
+
+```typescript
+useEffect(() => {
+  console.log('Server state:', defaultState)
+  console.log('Client state:', persistedState)
+}, [])
+```
+
+### Use React DevTools
+
+Look for red warnings about hydration mismatches.
+
+---
+
+## Official Resources
+
+- **Next.js Hydration**: https://nextjs.org/docs/messages/react-hydration-error
+- **Zustand Persist**: https://github.com/pmndrs/zustand/blob/main/docs/integrations/persisting-store-data.md
+- **DEV.to Guide**: https://dev.to/abdulsamad/how-to-use-zustands-persist-middleware-in-nextjs-4lb5
--- a/references/typescript-patterns.md
+++ b/references/typescript-patterns.md
@@ -0,0 +1,281 @@
+# Zustand TypeScript Advanced Patterns
+
+Advanced TypeScript patterns and troubleshooting. Load when encountering complex type inference issues.
+
+---
+
+## Basic TypeScript Setup
+
+### The Golden Rule: Double Parentheses
+
+```typescript
+// ✅ CORRECT
+const useStore = create<Store>()((set) => ({ /* ... */ }))
+
+// ❌ WRONG
+const useStore = create<Store>((set) => ({ /* ... */ }))
+```
+
+**Why**: Currying syntax enables middleware type inference.
+
+---
+
+## Store Interface Pattern
+
+```typescript
+// Define types
+interface BearState {
+  bears: number
+}
+
+interface BearActions {
+  increase: (by: number) => void
+  decrease: (by: number) => void
+}
+
+// Combine
+type BearStore = BearState & BearActions
+
+// Use
+const useBearStore = create<BearStore>()((set) => ({
+  bears: 0,
+  increase: (by) => set((state) => ({ bears: state.bears + by })),
+  decrease: (by) => set((state) => ({ bears: state.bears - by })),
+}))
+```
+
+---
+
+## Slices Pattern Types
+
+```typescript
+import { StateCreator } from 'zustand'
+
+// Define slice type
+interface BearSlice {
+  bears: number
+  addBear: () => void
+}
+
+// Create slice with proper types
+const createBearSlice: StateCreator<
+  BearSlice & FishSlice,  // Combined store type
+  [],                      // Middleware mutators
+  [],                      // Chained middleware
+  BearSlice               // This slice
+> = (set) => ({
+  bears: 0,
+  addBear: () => set((state) => ({ bears: state.bears + 1 })),
+})
+```
+
+---
+
+## Middleware Types
+
+### With Devtools
+
+```typescript
+import { StateCreator } from 'zustand'
+import { devtools } from 'zustand/middleware'
+
+interface Store {
+  count: number
+  increment: () => void
+}
+
+const useStore = create<Store>()(
+  devtools(
+    (set) => ({
+      count: 0,
+      increment: () =>
+        set(
+          (state) => ({ count: state.count + 1 }),
+          undefined,
+          'increment'
+        ),
+    }),
+    { name: 'Store' }
+  )
+)
+```
+
+### With Persist
+
+```typescript
+import { persist } from 'zustand/middleware'
+
+const useStore = create<Store>()(
+  persist(
+    (set) => ({ /* ... */ }),
+    { name: 'storage' }
+  )
+)
+```
+
+### With Multiple Middlewares
+
+```typescript
+const useStore = create<Store>()(
+  devtools(
+    persist(
+      (set) => ({ /* ... */ }),
+      { name: 'storage' }
+    ),
+    { name: 'Store' }
+  )
+)
+```
+
+---
+
+## Slices with Middleware
+
+```typescript
+import { StateCreator } from 'zustand'
+import { devtools } from 'zustand/middleware'
+
+const createBearSlice: StateCreator<
+  BearSlice & FishSlice,
+  [['zustand/devtools', never]],  // Add devtools mutator
+  [],
+  BearSlice
+> = (set) => ({
+  bears: 0,
+  addBear: () =>
+    set(
+      (state) => ({ bears: state.bears + 1 }),
+      undefined,
+      'bear/add'
+    ),
+})
+```
+
+---
+
+## Selector Types
+
+### Basic Selector
+
+```typescript
+const bears = useStore((state) => state.bears)
+// Type: number
+```
+
+### Computed Selector
+
+```typescript
+const selectTotal = (state: Store) => state.items.reduce((sum, item) => sum + item.price, 0)
+
+const total = useStore(selectTotal)
+// Type: number
+```
+
+### Parameterized Selector
+
+```typescript
+const selectById = (id: string) => (state: Store) =>
+  state.items.find((item) => item.id === id)
+
+const item = useStore(selectById('123'))
+// Type: Item | undefined
+```
+
+---
+
+## Vanilla Store Types
+
+```typescript
+import { createStore } from 'zustand/vanilla'
+
+const store = createStore<Store>()((set) => ({
+  count: 0,
+  increment: () => set((state) => ({ count: state.count + 1 })),
+}))
+
+// Get state
+const state = store.getState()
+// Type: Store
+
+// Subscribe
+const unsubscribe = store.subscribe((state) => {
+  // state is typed as Store
+})
+```
+
+---
+
+## Custom Hook with Types
+
+```typescript
+import { useStore } from 'zustand'
+
+const bearStore = createStore<BearStore>()((set) => ({
+  bears: 0,
+  increase: () => set((state) => ({ bears: state.bears + 1 })),
+}))
+
+// Create custom hook
+function useBearStore<T>(selector: (state: BearStore) => T): T {
+  return useStore(bearStore, selector)
+}
+```
+
+---
+
+## Common Type Errors
+
+### Error: Type inference breaks
+
+**Problem**: Using single parentheses
+
+```typescript
+// ❌ WRONG
+const useStore = create<Store>((set) => ({ /* ... */ }))
+```
+
+**Solution**: Use double parentheses
+
+```typescript
+// ✅ CORRECT
+const useStore = create<Store>()((set) => ({ /* ... */ }))
+```
+
+### Error: StateCreator types fail
+
+**Problem**: Missing middleware mutators
+
+```typescript
+// ❌ WRONG
+const createSlice: StateCreator<CombinedStore, [], [], MySlice>
+```
+
+**Solution**: Add middleware mutators
+
+```typescript
+// ✅ CORRECT
+const createSlice: StateCreator<
+  CombinedStore,
+  [['zustand/devtools', never]],  // Add this
+  [],
+  MySlice
+>
+```
+
+### Error: Circular reference
+
+**Problem**: Slices referencing each other
+
+**Solution**: Define combined type first, then reference in slices
+
+```typescript
+type AllSlices = BearSlice & FishSlice & SharedSlice
+
+const createBearSlice: StateCreator<AllSlices, [], [], BearSlice> = ...
+```
+
+---
+
+## Official TypeScript Guide
+
+https://zustand.docs.pmnd.rs/guides/typescript
--- a/scripts/check-versions.sh
+++ b/scripts/check-versions.sh
@@ -0,0 +1,141 @@
+#!/bin/bash
+
+# Zustand Version Checker
+# Verifies installed versions and compatibility
+# Usage: ./scripts/check-versions.sh
+
+set -e
+
+echo "🐻 Zustand Version Checker"
+echo "=========================="
+echo ""
+
+# Check if package.json exists
+if [ ! -f "package.json" ]; then
+  echo "❌ No package.json found in current directory"
+  echo "   Run this script from your project root"
+  exit 1
+fi
+
+# Function to get installed version
+get_version() {
+  local package=$1
+  if [ -f "node_modules/$package/package.json" ]; then
+    node -p "require('./node_modules/$package/package.json').version" 2>/dev/null || echo "not installed"
+  else
+    echo "not installed"
+  fi
+}
+
+# Function to get latest version from npm
+get_latest() {
+  local package=$1
+  npm view "$package" version 2>/dev/null || echo "unknown"
+}
+
+# Check Zustand
+echo "📦 Zustand"
+zustand_installed=$(get_version "zustand")
+zustand_latest=$(get_latest "zustand")
+
+if [ "$zustand_installed" = "not installed" ]; then
+  echo "   Status: ❌ Not installed"
+  echo "   Install: npm install zustand"
+else
+  echo "   Installed: $zustand_installed"
+  echo "   Latest:    $zustand_latest"
+
+  # Check if major version is 5
+  major=$(echo "$zustand_installed" | cut -d'.' -f1)
+  if [ "$major" -ge 5 ]; then
+    echo "   Status: ✅ v5+ (recommended)"
+  elif [ "$major" -eq 4 ]; then
+    echo "   Status: ⚠️  v4 (upgrade recommended)"
+    echo "   Migration: See references/migration-guide.md"
+  else
+    echo "   Status: ❌ v$major (unsupported)"
+    echo "   Action: Upgrade to v5+"
+  fi
+fi
+
+echo ""
+
+# Check React
+echo "📦 React"
+react_installed=$(get_version "react")
+react_latest=$(get_latest "react")
+
+if [ "$react_installed" = "not installed" ]; then
+  echo "   Status: ❌ Not installed"
+else
+  echo "   Installed: $react_installed"
+  echo "   Latest:    $react_latest"
+
+  # Check if version is 18+
+  major=$(echo "$react_installed" | cut -d'.' -f1)
+  if [ "$major" -ge 18 ]; then
+    echo "   Status: ✅ v18+ (compatible)"
+  else
+    echo "   Status: ⚠️  v$major (Zustand works, but upgrade recommended)"
+  fi
+fi
+
+echo ""
+
+# Check TypeScript (optional)
+echo "📦 TypeScript (optional)"
+ts_installed=$(get_version "typescript")
+
+if [ "$ts_installed" = "not installed" ]; then
+  echo "   Status: ℹ️  Not installed (optional)"
+else
+  echo "   Installed: $ts_installed"
+
+  # Check if version is 5+
+  major=$(echo "$ts_installed" | cut -d'.' -f1)
+  if [ "$major" -ge 5 ]; then
+    echo "   Status: ✅ v5+ (recommended)"
+  else
+    echo "   Status: ⚠️  v$major (upgrade recommended for better types)"
+  fi
+fi
+
+echo ""
+
+# Check Next.js (if using persist)
+if grep -q '"next"' package.json 2>/dev/null; then
+  echo "📦 Next.js (detected)"
+  next_installed=$(get_version "next")
+  echo "   Installed: $next_installed"
+
+  # Check if major version is 14+
+  major=$(echo "$next_installed" | cut -d'.' -f1)
+  if [ "$major" -ge 14 ]; then
+    echo "   Status: ✅ v14+ (App Router supported)"
+  elif [ "$major" -eq 13 ]; then
+    echo "   Status: ✅ v13 (supported)"
+  else
+    echo "   Status: ⚠️  v$major (upgrade recommended)"
+  fi
+
+  echo "   Note: See references/nextjs-hydration.md for SSR setup"
+  echo ""
+fi
+
+# Summary
+echo "=========================="
+echo "✅ Version check complete"
+echo ""
+
+if [ "$zustand_installed" = "not installed" ]; then
+  echo "Next steps:"
+  echo "  npm install zustand"
+  echo "  See SKILL.md for setup instructions"
+elif [ "$major" -lt 5 ]; then
+  echo "Recommended upgrade:"
+  echo "  npm install zustand@latest"
+  echo "  See references/migration-guide.md for v4→v5 changes"
+else
+  echo "All versions compatible! 🎉"
+  echo "See SKILL.md for usage patterns"
+fi
--- a/scripts/example-script.sh
+++ b/scripts/example-script.sh
@@ -0,0 +1,15 @@
+#!/bin/bash
+
+# [TODO: Script Name]
+# [TODO: Brief description of what this script does]
+
+# Example script structure - delete if not needed
+
+set -e  # Exit on error
+
+# [TODO: Add your script logic here]
+
+echo "Example script - replace or delete this file"
+
+# Usage:
+# ./scripts/example-script.sh [args]
--- a/templates/async-actions-store.ts
+++ b/templates/async-actions-store.ts
@@ -0,0 +1,309 @@
+/**
+ * Zustand Store with Async Actions
+ *
+ * Use when:
+ * - Fetching data from APIs
+ * - Need loading/error states
+ * - Handling async operations
+ *
+ * Pattern: Actions can be async, just call set() when done
+ *
+ * Features:
+ * - Loading states
+ * - Error handling
+ * - Optimistic updates
+ * - Request cancellation
+ *
+ * NOTE: For server state (data fetching), consider TanStack Query instead!
+ * Zustand is better for client state. But this pattern works for simple cases.
+ *
+ * Learn more: See SKILL.md Common Patterns section
+ */
+
+import { create } from 'zustand'
+
+interface User {
+  id: string
+  name: string
+  email: string
+}
+
+interface Post {
+  id: string
+  title: string
+  body: string
+  userId: string
+}
+
+interface AsyncStore {
+  // Data state
+  user: User | null
+  posts: Post[]
+
+  // Loading states
+  isLoadingUser: boolean
+  isLoadingPosts: boolean
+  isSavingPost: boolean
+
+  // Error states
+  userError: string | null
+  postsError: string | null
+  saveError: string | null
+
+  // Actions
+  fetchUser: (userId: string) => Promise<void>
+  fetchPosts: (userId: string) => Promise<void>
+  createPost: (post: Omit<Post, 'id'>) => Promise<void>
+  deletePost: (postId: string) => Promise<void>
+  reset: () => void
+}
+
+export const useAsyncStore = create<AsyncStore>()((set, get) => ({
+  // Initial state
+  user: null,
+  posts: [],
+  isLoadingUser: false,
+  isLoadingPosts: false,
+  isSavingPost: false,
+  userError: null,
+  postsError: null,
+  saveError: null,
+
+  // Fetch user
+  fetchUser: async (userId) => {
+    set({ isLoadingUser: true, userError: null })
+
+    try {
+      const response = await fetch(`https://api.example.com/users/${userId}`)
+
+      if (!response.ok) {
+        throw new Error(`Failed to fetch user: ${response.statusText}`)
+      }
+
+      const user = await response.json()
+      set({ user, isLoadingUser: false })
+    } catch (error) {
+      set({
+        userError: (error as Error).message,
+        isLoadingUser: false,
+        user: null,
+      })
+    }
+  },
+
+  // Fetch posts
+  fetchPosts: async (userId) => {
+    set({ isLoadingPosts: true, postsError: null })
+
+    try {
+      const response = await fetch(`https://api.example.com/users/${userId}/posts`)
+
+      if (!response.ok) {
+        throw new Error(`Failed to fetch posts: ${response.statusText}`)
+      }
+
+      const posts = await response.json()
+      set({ posts, isLoadingPosts: false })
+    } catch (error) {
+      set({
+        postsError: (error as Error).message,
+        isLoadingPosts: false,
+      })
+    }
+  },
+
+  // Create post with optimistic update
+  createPost: async (post) => {
+    const tempId = `temp-${Date.now()}`
+    const optimisticPost = { ...post, id: tempId }
+
+    // Optimistic update
+    set((state) => ({
+      posts: [...state.posts, optimisticPost],
+      isSavingPost: true,
+      saveError: null,
+    }))
+
+    try {
+      const response = await fetch('https://api.example.com/posts', {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify(post),
+      })
+
+      if (!response.ok) {
+        throw new Error(`Failed to create post: ${response.statusText}`)
+      }
+
+      const savedPost = await response.json()
+
+      // Replace optimistic post with real one
+      set((state) => ({
+        posts: state.posts.map((p) =>
+          p.id === tempId ? savedPost : p
+        ),
+        isSavingPost: false,
+      }))
+    } catch (error) {
+      // Rollback optimistic update
+      set((state) => ({
+        posts: state.posts.filter((p) => p.id !== tempId),
+        saveError: (error as Error).message,
+        isSavingPost: false,
+      }))
+    }
+  },
+
+  // Delete post
+  deletePost: async (postId) => {
+    // Store original posts for rollback
+    const originalPosts = get().posts
+
+    // Optimistic update
+    set((state) => ({
+      posts: state.posts.filter((p) => p.id !== postId),
+    }))
+
+    try {
+      const response = await fetch(`https://api.example.com/posts/${postId}`, {
+        method: 'DELETE',
+      })
+
+      if (!response.ok) {
+        throw new Error(`Failed to delete post: ${response.statusText}`)
+      }
+    } catch (error) {
+      // Rollback on error
+      set({
+        posts: originalPosts,
+        saveError: (error as Error).message,
+      })
+    }
+  },
+
+  // Reset
+  reset: () =>
+    set({
+      user: null,
+      posts: [],
+      isLoadingUser: false,
+      isLoadingPosts: false,
+      isSavingPost: false,
+      userError: null,
+      postsError: null,
+      saveError: null,
+    }),
+}))
+
+/**
+ * Usage in components:
+ *
+ * function UserProfile({ userId }: { userId: string }) {
+ *   const user = useAsyncStore((state) => state.user)
+ *   const isLoading = useAsyncStore((state) => state.isLoadingUser)
+ *   const error = useAsyncStore((state) => state.userError)
+ *   const fetchUser = useAsyncStore((state) => state.fetchUser)
+ *
+ *   useEffect(() => {
+ *     fetchUser(userId)
+ *   }, [userId, fetchUser])
+ *
+ *   if (isLoading) return <div>Loading...</div>
+ *   if (error) return <div>Error: {error}</div>
+ *   if (!user) return <div>No user found</div>
+ *
+ *   return (
+ *     <div>
+ *       <h1>{user.name}</h1>
+ *       <p>{user.email}</p>
+ *     </div>
+ *   )
+ * }
+ *
+ * function PostsList({ userId }: { userId: string }) {
+ *   const posts = useAsyncStore((state) => state.posts)
+ *   const isLoading = useAsyncStore((state) => state.isLoadingPosts)
+ *   const error = useAsyncStore((state) => state.postsError)
+ *   const fetchPosts = useAsyncStore((state) => state.fetchPosts)
+ *   const deletePost = useAsyncStore((state) => state.deletePost)
+ *
+ *   useEffect(() => {
+ *     fetchPosts(userId)
+ *   }, [userId, fetchPosts])
+ *
+ *   if (isLoading) return <div>Loading posts...</div>
+ *   if (error) return <div>Error: {error}</div>
+ *
+ *   return (
+ *     <ul>
+ *       {posts.map((post) => (
+ *         <li key={post.id}>
+ *           <h3>{post.title}</h3>
+ *           <p>{post.body}</p>
+ *           <button onClick={() => deletePost(post.id)}>Delete</button>
+ *         </li>
+ *       ))}
+ *     </ul>
+ *   )
+ * }
+ *
+ * function CreatePostForm({ userId }: { userId: string }) {
+ *   const [title, setTitle] = useState('')
+ *   const [body, setBody] = useState('')
+ *   const createPost = useAsyncStore((state) => state.createPost)
+ *   const isSaving = useAsyncStore((state) => state.isSavingPost)
+ *   const error = useAsyncStore((state) => state.saveError)
+ *
+ *   const handleSubmit = async (e: FormEvent) => {
+ *     e.preventDefault()
+ *     await createPost({ title, body, userId })
+ *     setTitle('')
+ *     setBody('')
+ *   }
+ *
+ *   return (
+ *     <form onSubmit={handleSubmit}>
+ *       <input
+ *         value={title}
+ *         onChange={(e) => setTitle(e.target.value)}
+ *         placeholder="Title"
+ *       />
+ *       <textarea
+ *         value={body}
+ *         onChange={(e) => setBody(e.target.value)}
+ *         placeholder="Body"
+ *       />
+ *       <button type="submit" disabled={isSaving}>
+ *         {isSaving ? 'Creating...' : 'Create Post'}
+ *       </button>
+ *       {error && <div>Error: {error}</div>}
+ *     </form>
+ *   )
+ * }
+ *
+ * ADVANCED: Request Cancellation with AbortController
+ *
+ * let abortController: AbortController | null = null
+ *
+ * fetchUserWithCancellation: async (userId) => {
+ *   // Cancel previous request
+ *   abortController?.abort()
+ *   abortController = new AbortController()
+ *
+ *   set({ isLoadingUser: true, userError: null })
+ *
+ *   try {
+ *     const response = await fetch(
+ *       `https://api.example.com/users/${userId}`,
+ *       { signal: abortController.signal }
+ *     )
+ *     // ... rest of fetch logic
+ *   } catch (error) {
+ *     if (error.name === 'AbortError') {
+ *       // Request was cancelled
+ *       return
+ *     }
+ *     // ... handle other errors
+ *   }
+ * }
+ */
--- a/templates/basic-store.ts
+++ b/templates/basic-store.ts
@@ -0,0 +1,41 @@
+/**
+ * Basic Zustand Store (JavaScript style, no TypeScript)
+ *
+ * Use when:
+ * - Prototyping quickly
+ * - Small applications
+ * - No TypeScript in project
+ *
+ * Learn more: See SKILL.md for TypeScript version
+ */
+
+import { create } from 'zustand'
+
+// Create store with minimal setup
+export const useStore = create((set) => ({
+  // State
+  count: 0,
+  user: null,
+
+  // Actions
+  increment: () => set((state) => ({ count: state.count + 1 })),
+  decrement: () => set((state) => ({ count: state.count - 1 })),
+  setUser: (user) => set({ user }),
+  reset: () => set({ count: 0, user: null }),
+}))
+
+/**
+ * Usage in component:
+ *
+ * function Counter() {
+ *   const count = useStore((state) => state.count)
+ *   const increment = useStore((state) => state.increment)
+ *
+ *   return (
+ *     <div>
+ *       <p>Count: {count}</p>
+ *       <button onClick={increment}>Increment</button>
+ *     </div>
+ *   )
+ * }
+ */
--- a/templates/computed-store.ts
+++ b/templates/computed-store.ts
@@ -0,0 +1,214 @@
+/**
+ * Zustand Store with Computed/Derived Values
+ *
+ * Use when:
+ * - Need values calculated from state
+ * - Want to avoid storing redundant data
+ * - Need efficient memoization
+ *
+ * Pattern: Compute in selectors, not in store
+ *
+ * Benefits:
+ * - Cleaner state (only source data)
+ * - Automatic recomputation when dependencies change
+ * - Components only re-render when result changes
+ *
+ * Learn more: See SKILL.md Common Patterns section
+ */
+
+import { create } from 'zustand'
+
+interface Product {
+  id: string
+  name: string
+  price: number
+  category: string
+  inStock: boolean
+}
+
+interface CartItem {
+  productId: string
+  quantity: number
+}
+
+interface ComputedStore {
+  // Source state (stored)
+  products: Product[]
+  cart: CartItem[]
+  taxRate: number
+  discountPercent: number
+
+  // Actions
+  addProduct: (product: Product) => void
+  addToCart: (productId: string, quantity: number) => void
+  removeFromCart: (productId: string) => void
+  setTaxRate: (rate: number) => void
+  setDiscount: (percent: number) => void
+}
+
+export const useComputedStore = create<ComputedStore>()((set) => ({
+  // Initial state
+  products: [],
+  cart: [],
+  taxRate: 0.1, // 10%
+  discountPercent: 0,
+
+  // Actions
+  addProduct: (product) =>
+    set((state) => ({
+      products: [...state.products, product],
+    })),
+
+  addToCart: (productId, quantity) =>
+    set((state) => {
+      const existing = state.cart.find((item) => item.productId === productId)
+      if (existing) {
+        return {
+          cart: state.cart.map((item) =>
+            item.productId === productId
+              ? { ...item, quantity: item.quantity + quantity }
+              : item
+          ),
+        }
+      }
+      return {
+        cart: [...state.cart, { productId, quantity }],
+      }
+    }),
+
+  removeFromCart: (productId) =>
+    set((state) => ({
+      cart: state.cart.filter((item) => item.productId !== productId),
+    })),
+
+  setTaxRate: (rate) => set({ taxRate: rate }),
+
+  setDiscount: (percent) => set({ discountPercent: percent }),
+}))
+
+// ============================================================================
+// COMPUTED/DERIVED SELECTORS (put these in separate file for reuse)
+// ============================================================================
+
+/**
+ * Selector: Get cart items with product details
+ */
+export const selectCartWithDetails = (state: ComputedStore) =>
+  state.cart.map((item) => {
+    const product = state.products.find((p) => p.id === item.productId)
+    return {
+      ...item,
+      product,
+      subtotal: product ? product.price * item.quantity : 0,
+    }
+  })
+
+/**
+ * Selector: Calculate subtotal (before tax and discount)
+ */
+export const selectSubtotal = (state: ComputedStore) =>
+  state.cart.reduce((sum, item) => {
+    const product = state.products.find((p) => p.id === item.productId)
+    return sum + (product ? product.price * item.quantity : 0)
+  }, 0)
+
+/**
+ * Selector: Calculate discount amount
+ */
+export const selectDiscountAmount = (state: ComputedStore) => {
+  const subtotal = selectSubtotal(state)
+  return subtotal * (state.discountPercent / 100)
+}
+
+/**
+ * Selector: Calculate tax amount
+ */
+export const selectTaxAmount = (state: ComputedStore) => {
+  const subtotal = selectSubtotal(state)
+  const discountAmount = selectDiscountAmount(state)
+  const afterDiscount = subtotal - discountAmount
+  return afterDiscount * state.taxRate
+}
+
+/**
+ * Selector: Calculate final total
+ */
+export const selectTotal = (state: ComputedStore) => {
+  const subtotal = selectSubtotal(state)
+  const discountAmount = selectDiscountAmount(state)
+  const taxAmount = selectTaxAmount(state)
+  return subtotal - discountAmount + taxAmount
+}
+
+/**
+ * Selector: Get products by category
+ */
+export const selectProductsByCategory = (category: string) => (state: ComputedStore) =>
+  state.products.filter((product) => product.category === category)
+
+/**
+ * Selector: Get in-stock products only
+ */
+export const selectInStockProducts = (state: ComputedStore) =>
+  state.products.filter((product) => product.inStock)
+
+/**
+ * Selector: Count items in cart
+ */
+export const selectCartItemCount = (state: ComputedStore) =>
+  state.cart.reduce((sum, item) => sum + item.quantity, 0)
+
+/**
+ * Usage in components:
+ *
+ * function CartSummary() {
+ *   // Each selector only causes re-render when its result changes
+ *   const subtotal = useComputedStore(selectSubtotal)
+ *   const discount = useComputedStore(selectDiscountAmount)
+ *   const tax = useComputedStore(selectTaxAmount)
+ *   const total = useComputedStore(selectTotal)
+ *   const itemCount = useComputedStore(selectCartItemCount)
+ *
+ *   return (
+ *     <div>
+ *       <h3>Cart ({itemCount} items)</h3>
+ *       <p>Subtotal: ${subtotal.toFixed(2)}</p>
+ *       <p>Discount: -${discount.toFixed(2)}</p>
+ *       <p>Tax: ${tax.toFixed(2)}</p>
+ *       <h4>Total: ${total.toFixed(2)}</h4>
+ *     </div>
+ *   )
+ * }
+ *
+ * function ProductList() {
+ *   const inStockProducts = useComputedStore(selectInStockProducts)
+ *
+ *   return (
+ *     <ul>
+ *       {inStockProducts.map((product) => (
+ *         <li key={product.id}>{product.name} - ${product.price}</li>
+ *       ))}
+ *     </ul>
+ *   )
+ * }
+ *
+ * function CategoryFilter() {
+ *   const electronicsProducts = useComputedStore(selectProductsByCategory('electronics'))
+ *
+ *   return <div>{electronicsProducts.length} electronics</div>
+ * }
+ *
+ * PERFORMANCE TIP:
+ * For expensive computations, use useMemo in the component:
+ *
+ * function ExpensiveComputation() {
+ *   const data = useComputedStore((state) => state.products)
+ *
+ *   const result = useMemo(() => {
+ *     // Expensive calculation
+ *     return data.map(...).filter(...).reduce(...)
+ *   }, [data])
+ *
+ *   return <div>{result}</div>
+ * }
+ */
--- a/templates/devtools-store.ts
+++ b/templates/devtools-store.ts
@@ -0,0 +1,141 @@
+/**
+ * Zustand Store with Redux DevTools Integration
+ *
+ * Use when:
+ * - Need debugging capabilities
+ * - Want to track state changes
+ * - Inspecting actions and state history
+ * - Time-travel debugging (with Redux DevTools Extension)
+ *
+ * Setup:
+ * 1. Install Redux DevTools Extension in browser
+ * 2. Use this template
+ * 3. Open DevTools → Redux tab
+ *
+ * Learn more: See SKILL.md for combining with other middleware
+ */
+
+import { create } from 'zustand'
+import { devtools } from 'zustand/middleware'
+
+interface Todo {
+  id: string
+  text: string
+  done: boolean
+}
+
+interface DevtoolsStore {
+  // State
+  todos: Todo[]
+  filter: 'all' | 'active' | 'completed'
+
+  // Actions
+  addTodo: (text: string) => void
+  toggleTodo: (id: string) => void
+  deleteTodo: (id: string) => void
+  setFilter: (filter: DevtoolsStore['filter']) => void
+  clearCompleted: () => void
+}
+
+export const useDevtoolsStore = create<DevtoolsStore>()(
+  devtools(
+    (set) => ({
+      // Initial state
+      todos: [],
+      filter: 'all',
+
+      // Actions with named actions for DevTools
+      addTodo: (text) =>
+        set(
+          (state) => ({
+            todos: [
+              ...state.todos,
+              { id: Date.now().toString(), text, done: false },
+            ],
+          }),
+          undefined,
+          'todos/add', // Action name in DevTools
+        ),
+
+      toggleTodo: (id) =>
+        set(
+          (state) => ({
+            todos: state.todos.map((todo) =>
+              todo.id === id ? { ...todo, done: !todo.done } : todo
+            ),
+          }),
+          undefined,
+          'todos/toggle',
+        ),
+
+      deleteTodo: (id) =>
+        set(
+          (state) => ({
+            todos: state.todos.filter((todo) => todo.id !== id),
+          }),
+          undefined,
+          'todos/delete',
+        ),
+
+      setFilter: (filter) =>
+        set(
+          { filter },
+          undefined,
+          'filter/set',
+        ),
+
+      clearCompleted: () =>
+        set(
+          (state) => ({
+            todos: state.todos.filter((todo) => !todo.done),
+          }),
+          undefined,
+          'todos/clearCompleted',
+        ),
+    }),
+    {
+      name: 'TodoStore', // Store name in DevTools
+      enabled: process.env.NODE_ENV === 'development', // Optional: only in dev
+    },
+  ),
+)
+
+/**
+ * Usage in component:
+ *
+ * function TodoList() {
+ *   const todos = useDevtoolsStore((state) => state.todos)
+ *   const filter = useDevtoolsStore((state) => state.filter)
+ *   const toggleTodo = useDevtoolsStore((state) => state.toggleTodo)
+ *   const deleteTodo = useDevtoolsStore((state) => state.deleteTodo)
+ *
+ *   const filteredTodos = todos.filter((todo) => {
+ *     if (filter === 'active') return !todo.done
+ *     if (filter === 'completed') return todo.done
+ *     return true
+ *   })
+ *
+ *   return (
+ *     <ul>
+ *       {filteredTodos.map((todo) => (
+ *         <li key={todo.id}>
+ *           <input
+ *             type="checkbox"
+ *             checked={todo.done}
+ *             onChange={() => toggleTodo(todo.id)}
+ *           />
+ *           <span>{todo.text}</span>
+ *           <button onClick={() => deleteTodo(todo.id)}>Delete</button>
+ *         </li>
+ *       ))}
+ *     </ul>
+ *   )
+ * }
+ *
+ * DevTools Features:
+ * - See all actions in order
+ * - Inspect state before/after each action
+ * - Time-travel through state changes
+ * - Export/import state for debugging
+ * - Track which components caused updates
+ */
--- a/templates/nextjs-store.ts
+++ b/templates/nextjs-store.ts
@@ -0,0 +1,109 @@
+/**
+ * Next.js SSR-Safe Zustand Store with Hydration Handling
+ *
+ * Use when:
+ * - Using persist middleware in Next.js
+ * - Getting hydration mismatch errors
+ * - Need SSR compatibility
+ *
+ * This template solves:
+ * - "Text content does not match server-rendered HTML"
+ * - "Hydration failed" errors
+ * - Flashing content during hydration
+ *
+ * Learn more: See SKILL.md Issue #1 for detailed explanation
+ */
+
+'use client' // Required for Next.js App Router
+
+import { create } from 'zustand'
+import { persist, createJSONStorage } from 'zustand/middleware'
+
+interface User {
+  id: string
+  name: string
+}
+
+interface NextJsStore {
+  // State
+  _hasHydrated: boolean // CRITICAL: Track hydration status
+  count: number
+  user: User | null
+
+  // Actions
+  setHasHydrated: (hydrated: boolean) => void
+  increment: () => void
+  setUser: (user: User | null) => void
+  reset: () => void
+}
+
+export const useNextJsStore = create<NextJsStore>()(
+  persist(
+    (set) => ({
+      // Initial state
+      _hasHydrated: false, // Start false
+      count: 0,
+      user: null,
+
+      // Hydration action
+      setHasHydrated: (hydrated) => set({ _hasHydrated: hydrated }),
+
+      // Regular actions
+      increment: () => set((state) => ({ count: state.count + 1 })),
+
+      setUser: (user) => set({ user }),
+
+      reset: () => set({ count: 0, user: null }),
+    }),
+    {
+      name: 'nextjs-storage',
+
+      // CRITICAL: Call setHasHydrated when rehydration completes
+      onRehydrateStorage: () => (state) => {
+        state?.setHasHydrated(true)
+      },
+    },
+  ),
+)
+
+/**
+ * Usage in Next.js component:
+ *
+ * 'use client'
+ *
+ * import { useNextJsStore } from './store'
+ *
+ * function Counter() {
+ *   const hasHydrated = useNextJsStore((state) => state._hasHydrated)
+ *   const count = useNextJsStore((state) => state.count)
+ *   const increment = useNextJsStore((state) => state.increment)
+ *
+ *   // Show loading state during hydration
+ *   if (!hasHydrated) {
+ *     return <div>Loading...</div>
+ *   }
+ *
+ *   // Now safe to render with persisted state
+ *   return (
+ *     <div>
+ *       <p>Count: {count}</p>
+ *       <button onClick={increment}>Increment</button>
+ *     </div>
+ *   )
+ * }
+ *
+ * Alternative: Skip hydration check if flashing is acceptable
+ *
+ * function CounterNoLoadingState() {
+ *   const count = useNextJsStore((state) => state.count)
+ *   const increment = useNextJsStore((state) => state.increment)
+ *
+ *   // Will show default value (0) until hydration, then correct value
+ *   return (
+ *     <div>
+ *       <p>Count: {count}</p>
+ *       <button onClick={increment}>Increment</button>
+ *     </div>
+ *   )
+ * }
+ */
--- a/templates/persist-store.ts
+++ b/templates/persist-store.ts
@@ -0,0 +1,119 @@
+/**
+ * Persistent Zustand Store (localStorage/sessionStorage)
+ *
+ * Use when:
+ * - State needs to survive page reloads
+ * - User preferences (theme, language, etc.)
+ * - Shopping carts, draft forms
+ *
+ * Features:
+ * - Automatic save to localStorage
+ * - Automatic restore on load
+ * - Migration support for schema changes
+ * - Partial persistence (only save some fields)
+ *
+ * Learn more: See SKILL.md Issue #1 for Next.js hydration handling
+ */
+
+import { create } from 'zustand'
+import { persist, createJSONStorage } from 'zustand/middleware'
+
+interface User {
+  id: string
+  name: string
+  email: string
+}
+
+interface PersistedStore {
+  // State
+  theme: 'light' | 'dark' | 'system'
+  language: string
+  user: User | null
+  preferences: {
+    notifications: boolean
+    emailUpdates: boolean
+  }
+
+  // Actions
+  setTheme: (theme: PersistedStore['theme']) => void
+  setLanguage: (language: string) => void
+  setUser: (user: User | null) => void
+  updatePreferences: (prefs: Partial<PersistedStore['preferences']>) => void
+  reset: () => void
+}
+
+const initialState = {
+  theme: 'system' as const,
+  language: 'en',
+  user: null,
+  preferences: {
+    notifications: true,
+    emailUpdates: false,
+  },
+}
+
+export const usePersistedStore = create<PersistedStore>()(
+  persist(
+    (set) => ({
+      ...initialState,
+
+      // Actions
+      setTheme: (theme) => set({ theme }),
+
+      setLanguage: (language) => set({ language }),
+
+      setUser: (user) => set({ user }),
+
+      updatePreferences: (prefs) =>
+        set((state) => ({
+          preferences: { ...state.preferences, ...prefs },
+        })),
+
+      reset: () => set(initialState),
+    }),
+    {
+      name: 'app-storage', // unique name in localStorage
+
+      // Optional: use sessionStorage instead
+      // storage: createJSONStorage(() => sessionStorage),
+
+      // Optional: only persist specific fields
+      // partialize: (state) => ({
+      //   theme: state.theme,
+      //   language: state.language,
+      //   preferences: state.preferences,
+      //   // Don't persist user (privacy)
+      // }),
+
+      // Optional: version and migration for schema changes
+      version: 1,
+      migrate: (persistedState: any, version) => {
+        if (version === 0) {
+          // Migration from version 0 to 1
+          // Example: rename field
+          persistedState.language = persistedState.lang || 'en'
+          delete persistedState.lang
+        }
+        return persistedState
+      },
+    },
+  ),
+)
+
+/**
+ * Usage in component:
+ *
+ * function ThemeToggle() {
+ *   const theme = usePersistedStore((state) => state.theme)
+ *   const setTheme = usePersistedStore((state) => state.setTheme)
+ *
+ *   return (
+ *     <button onClick={() => setTheme(theme === 'light' ? 'dark' : 'light')}>
+ *       Toggle theme
+ *     </button>
+ *   )
+ * }
+ *
+ * NEXT.JS WARNING:
+ * For Next.js with SSR, see nextjs-store.ts template for hydration handling!
+ */
--- a/templates/slices-pattern.ts
+++ b/templates/slices-pattern.ts
@@ -0,0 +1,217 @@
+/**
+ * Zustand Slices Pattern (Modular Store Architecture)
+ *
+ * Use when:
+ * - Store is getting large (100+ lines)
+ * - Multiple developers working on store
+ * - Need to organize state by domain/feature
+ *
+ * Benefits:
+ * - Each slice is independent and testable
+ * - Slices can access each other's state/actions
+ * - Easy to add/remove features
+ * - Better code organization
+ *
+ * Learn more: See SKILL.md Issue #5 for TypeScript complexity handling
+ */
+
+import { create, StateCreator } from 'zustand'
+import { devtools } from 'zustand/middleware'
+
+// ============================================================================
+// SLICE 1: User Management
+// ============================================================================
+
+interface User {
+  id: string
+  name: string
+  email: string
+}
+
+interface UserSlice {
+  user: User | null
+  isAuthenticated: boolean
+  setUser: (user: User) => void
+  logout: () => void
+}
+
+const createUserSlice: StateCreator<
+  UserSlice & CartSlice & NotificationSlice,  // Combined type
+  [['zustand/devtools', never]],               // Middleware mutators
+  [],                                          // Chained middleware
+  UserSlice                                     // This slice's type
+> = (set) => ({
+  user: null,
+  isAuthenticated: false,
+
+  setUser: (user) =>
+    set(
+      { user, isAuthenticated: true },
+      undefined,
+      'user/setUser',
+    ),
+
+  logout: () =>
+    set(
+      { user: null, isAuthenticated: false },
+      undefined,
+      'user/logout',
+    ),
+})
+
+// ============================================================================
+// SLICE 2: Shopping Cart
+// ============================================================================
+
+interface CartItem {
+  id: string
+  name: string
+  price: number
+  quantity: number
+}
+
+interface CartSlice {
+  items: CartItem[]
+  addItem: (item: CartItem) => void
+  removeItem: (id: string) => void
+  clearCart: () => void
+  // Access other slices
+  eatFish: () => void // Example: cross-slice action
+}
+
+const createCartSlice: StateCreator<
+  UserSlice & CartSlice & NotificationSlice,
+  [['zustand/devtools', never]],
+  [],
+  CartSlice
+> = (set, get) => ({
+  items: [],
+
+  addItem: (item) =>
+    set(
+      (state) => ({
+        items: [...state.items, item],
+      }),
+      undefined,
+      'cart/addItem',
+    ),
+
+  removeItem: (id) =>
+    set(
+      (state) => ({
+        items: state.items.filter((item) => item.id !== id),
+      }),
+      undefined,
+      'cart/removeItem',
+    ),
+
+  clearCart: () =>
+    set(
+      { items: [] },
+      undefined,
+      'cart/clearCart',
+    ),
+
+  // Example: Action that accesses another slice
+  eatFish: () =>
+    set(
+      (state) => ({
+        // Access notification slice
+        notifications: state.notifications + 1,
+      }),
+      undefined,
+      'cart/eatFish',
+    ),
+})
+
+// ============================================================================
+// SLICE 3: Notifications
+// ============================================================================
+
+interface NotificationSlice {
+  notifications: number
+  messages: string[]
+  addNotification: (message: string) => void
+  clearNotifications: () => void
+}
+
+const createNotificationSlice: StateCreator<
+  UserSlice & CartSlice & NotificationSlice,
+  [['zustand/devtools', never]],
+  [],
+  NotificationSlice
+> = (set) => ({
+  notifications: 0,
+  messages: [],
+
+  addNotification: (message) =>
+    set(
+      (state) => ({
+        notifications: state.notifications + 1,
+        messages: [...state.messages, message],
+      }),
+      undefined,
+      'notifications/add',
+    ),
+
+  clearNotifications: () =>
+    set(
+      { notifications: 0, messages: [] },
+      undefined,
+      'notifications/clear',
+    ),
+})
+
+// ============================================================================
+// COMBINE SLICES
+// ============================================================================
+
+export const useAppStore = create<UserSlice & CartSlice & NotificationSlice>()(
+  devtools(
+    (...a) => ({
+      ...createUserSlice(...a),
+      ...createCartSlice(...a),
+      ...createNotificationSlice(...a),
+    }),
+    { name: 'AppStore' },
+  ),
+)
+
+/**
+ * Usage in components:
+ *
+ * function UserProfile() {
+ *   const user = useAppStore((state) => state.user)
+ *   const logout = useAppStore((state) => state.logout)
+ *
+ *   if (!user) return <div>Not logged in</div>
+ *
+ *   return (
+ *     <div>
+ *       <p>Welcome, {user.name}!</p>
+ *       <button onClick={logout}>Logout</button>
+ *     </div>
+ *   )
+ * }
+ *
+ * function Cart() {
+ *   const items = useAppStore((state) => state.items)
+ *   const clearCart = useAppStore((state) => state.clearCart)
+ *
+ *   return (
+ *     <div>
+ *       <h2>Cart ({items.length} items)</h2>
+ *       <button onClick={clearCart}>Clear</button>
+ *     </div>
+ *   )
+ * }
+ *
+ * ORGANIZATION TIP:
+ * In larger projects, put each slice in its own file:
+ *
+ * src/store/
+ *   ├── index.ts           (combines slices)
+ *   ├── userSlice.ts
+ *   ├── cartSlice.ts
+ *   └── notificationSlice.ts
+ */
--- a/templates/typescript-store.ts
+++ b/templates/typescript-store.ts
@@ -0,0 +1,84 @@
+/**
+ * TypeScript Zustand Store (Recommended for production)
+ *
+ * Use when:
+ * - Production applications
+ * - Need type safety
+ * - Want IDE autocomplete
+ *
+ * CRITICAL: Notice the double parentheses `create<T>()()` - required for TypeScript
+ *
+ * Learn more: See SKILL.md for middleware and advanced patterns
+ */
+
+import { create } from 'zustand'
+
+// Define state interface
+interface User {
+  id: string
+  name: string
+  email: string
+}
+
+// Define store interface (state + actions)
+interface AppStore {
+  // State
+  count: number
+  user: User | null
+  isLoading: boolean
+
+  // Actions
+  increment: () => void
+  decrement: () => void
+  reset: () => void
+  setUser: (user: User) => void
+  clearUser: () => void
+  setLoading: (loading: boolean) => void
+}
+
+// Create typed store with double parentheses
+export const useAppStore = create<AppStore>()((set) => ({
+  // Initial state
+  count: 0,
+  user: null,
+  isLoading: false,
+
+  // Actions
+  increment: () => set((state) => ({ count: state.count + 1 })),
+
+  decrement: () => set((state) => ({ count: state.count - 1 })),
+
+  reset: () => set({ count: 0, user: null }),
+
+  setUser: (user) => set({ user }),
+
+  clearUser: () => set({ user: null }),
+
+  setLoading: (loading) => set({ isLoading: loading }),
+}))
+
+/**
+ * Usage in component:
+ *
+ * function Counter() {
+ *   // Select single value (component only re-renders when count changes)
+ *   const count = useAppStore((state) => state.count)
+ *   const increment = useAppStore((state) => state.increment)
+ *
+ *   return (
+ *     <div>
+ *       <p>Count: {count}</p>
+ *       <button onClick={increment}>Increment</button>
+ *     </div>
+ *   )
+ * }
+ *
+ * function UserProfile() {
+ *   const user = useAppStore((state) => state.user)
+ *   const setUser = useAppStore((state) => state.setUser)
+ *
+ *   if (!user) return <div>No user</div>
+ *
+ *   return <div>Hello, {user.name}!</div>
+ * }
+ */