create-win-project 1.3.0

package/playbooks/concerns/t3-env.md

@@ -0,0 +1,48 @@
+# t3-env for Next.js
+
+> Optional: adopt this when a Next.js project needs one typed, startup/build-time environment boundary. Install `@t3-oss/env-nextjs` and `zod` in the same change.
+
+## Setup
+
+Declare only values the selected stack actually consumes:
+
+```ts
+import { createEnv } from '@t3-oss/env-nextjs'
+import { z } from 'zod'
+
+export const env = createEnv({
+  server: {
+    DATABASE_URL: z.string().min(1).optional(),
+  },
+  client: {
+    NEXT_PUBLIC_API_URL: z.string().url().optional(),
+    NEXT_PUBLIC_SUPABASE_URL: z.string().url().optional(),
+    NEXT_PUBLIC_SUPABASE_PUBLISHABLE_KEY: z.string().min(1).optional(),
+  },
+  runtimeEnv: {
+    DATABASE_URL: process.env.DATABASE_URL,
+    NEXT_PUBLIC_API_URL: process.env.NEXT_PUBLIC_API_URL,
+    NEXT_PUBLIC_SUPABASE_URL: process.env.NEXT_PUBLIC_SUPABASE_URL,
+    NEXT_PUBLIC_SUPABASE_PUBLISHABLE_KEY: process.env.NEXT_PUBLIC_SUPABASE_PUBLISHABLE_KEY,
+  },
+})
+```
+
+Make a value required only for a stack that cannot run without it. Client-prefixed values are bundled and are never secrets.
+
+## Rules
+
+- Server-only values belong in `server`; client-visible values require `NEXT_PUBLIC_` and belong in `client`.
+- Add each new value to the schema, runtime mapping, `.env.example`, deployment configuration, and generated environment documentation.
+- Keep secrets out of logs, client schemas, public prefixes, and committed environment files.
+- Do not copy speculative JWT, administrator, or provider secrets into every project.
+
+## Agent Quick Reference
+
+```text
+New value?        → identify its runtime owner and whether the browser needs it
+Server secret?    → server schema, no public prefix
+Browser value?    → client schema with NEXT_PUBLIC_; treat as public
+Required value?   → fail validation before serving traffic
+Unused value?     → remove it from schema, examples, CI, and deployment config
+```

package/playbooks/concerns/tanstack-query.md

@@ -0,0 +1,145 @@
+# TanStack Query — Server State
+
+> **When to use:** Any data fetched from a server or API that needs caching, background refetch,
+> loading/error states, or invalidation after mutations.
+> Required for React Native. Optional for web stacks.
+
+---
+
+# 1. The Mental Model
+
+```text
+TanStack Query owns:  fetch, cache, loading, error, background refetch, invalidation
+Your code owns:       queryFn (calls a service), queryKey (cache identity)
+```
+
+Never manage loading/error state manually when TanStack Query can do it.
+
+---
+
+# 2. Query Key Convention
+
+```text
+Resource list:              ['products']
+Resource by ID:             ['products', id]
+Resource with filters:      ['products', { category, page }]
+Nested resource:            ['products', productId, 'reviews']
+Non-resource (dashboard):   ['dashboard', 'stats']
+Auth session:               ['auth', 'session']
+```
+
+Keys are the cache identity. Same key = same cache entry. Be consistent.
+
+---
+
+# 3. Read Hook
+
+```ts
+// features/products/hooks/useProducts.ts
+import { useQuery } from '@tanstack/react-query'
+import { productService } from '../services/productService'
+
+export const productKeys = {
+  all: ['products'] as const,
+  byId: (id: string) => ['products', id] as const,
+  filtered: (filters: ProductFilters) => ['products', 'filtered', filters] as const,
+}
+
+export function useProducts(filters?: ProductFilters) {
+  return useQuery({
+    queryKey: filters ? productKeys.filtered(filters) : productKeys.all,
+    queryFn: () => productService.getAll(filters),
+    staleTime: 1000 * 60 * 5, // 5 minutes
+  })
+}
+
+export function useProduct(id: string) {
+  return useQuery({
+    queryKey: productKeys.byId(id),
+    queryFn: () => productService.getById(id),
+    enabled: !!id,
+  })
+}
+```
+
+---
+
+# 4. Mutation Hook
+
+```ts
+// features/products/hooks/useCreateProduct.ts
+import { useMutation, useQueryClient } from '@tanstack/react-query'
+
+export function useCreateProduct() {
+  const queryClient = useQueryClient()
+
+  return useMutation({
+    mutationFn: (input: CreateProductInput) => productService.create(input),
+    onSuccess: () => {
+      queryClient.invalidateQueries({ queryKey: productKeys.all })
+    },
+  })
+}
+```
+
+---
+
+# 5. QueryClient Setup
+
+```ts
+// lib/queryClient.ts  (web: src/lib/queryClient.ts)
+// lib/queryClient.ts  (RN: lib/queryClient.ts)
+import { QueryClient } from '@tanstack/react-query'
+
+export const queryClient = new QueryClient({
+  defaultOptions: {
+    queries: {
+      staleTime: 1000 * 60 * 5,   // 5min — most data
+      retry: 1,
+      refetchOnWindowFocus: false, // web only; ignored on RN
+    },
+  },
+})
+```
+
+Stale time guide:
+```text
+Real-time (notifications, live status)  → staleTime: 0
+Normal data (products, users, orders)   → staleTime: 1000 * 60 * 5  (5min)
+Slow-changing (profile, settings)       → staleTime: 1000 * 60 * 30 (30min)
+Static (categories, countries)          → staleTime: Infinity
+```
+
+---
+
+# 6. Rules
+
+- Hooks call services. Services call the API client. Never call `fetch` or `axios` directly in `queryFn`.
+- Always define query keys in a `[resource]Keys` object — never inline magic strings.
+- Always invalidate related query keys after a mutation succeeds.
+- `enabled: !!id` — guard queries that depend on a param that may not exist yet.
+- Never put query results in Zustand — TanStack Query IS your cache.
+
+---
+
+# 7. Platform Notes
+
+> **React Native** — works identically. `refetchOnWindowFocus` is ignored (no window).
+> Wrap the root component in `<QueryClientProvider client={queryClient}>` in your root layout.
+
+> **Next.js** — Server Components do NOT use TanStack Query.
+> TanStack Query is for Client Components that need cached/refetched server data.
+
+---
+
+# 8. Agent Quick Reference
+
+```text
+New data fetch?              → useQuery hook → features/[name]/hooks/
+New mutation?                → useMutation hook → features/[name]/hooks/
+                             → invalidateQueries on success
+QueryKey for a list?         → ['resource']
+QueryKey for a single item?  → ['resource', id]
+Query depends on a param?    → enabled: !!param
+Server data in Zustand?      → move to useQuery instead
+```

package/playbooks/concerns/zod.md

@@ -0,0 +1,174 @@
+# Zod + React Hook Form — Validation
+
+> **When to use:** Any project with forms or untrusted input (API responses, URL params, env vars).
+
+---
+
+# 1. Schema First, Always
+
+Write the Zod schema before writing the form component or service. The schema is the source of truth.
+
+```ts
+// features/auth/schemas/login.schema.ts
+import { z } from 'zod'
+
+export const loginSchema = z.object({
+  email: z.string().email('Invalid email address'),
+  password: z.string().min(8, 'Password must be at least 8 characters'),
+})
+
+export type LoginInput = z.infer<typeof loginSchema>
+```
+
+Never write a separate TypeScript type for form data — infer it from the schema.
+
+---
+
+# 2. Schema Placement
+
+```text
+Feature-specific form?           → features/[name]/schemas/[name].schema.ts
+Shared across multiple features? → src/schemas/[name].schema.ts  (web)
+                                   schemas/[name].schema.ts       (RN)
+API response shape?              → features/[name]/types.ts (type only, no runtime parse needed)
+                                   OR parse with z.safeParse() at the API boundary if strict
+```
+
+---
+
+# 3. Web Form (React Hook Form)
+
+```tsx
+// features/auth/components/LoginForm.tsx
+'use client' // Next.js only — omit for React Vite
+import { useForm } from 'react-hook-form'
+import { zodResolver } from '@hookform/resolvers/zod'
+import { loginSchema, type LoginInput } from '../schemas/login.schema'
+
+export function LoginForm({ onSubmit }: { onSubmit: (data: LoginInput) => void }) {
+  const {
+    register,
+    handleSubmit,
+    formState: { errors, isSubmitting },
+  } = useForm<LoginInput>({ resolver: zodResolver(loginSchema) })
+
+  return (
+    <form onSubmit={handleSubmit(onSubmit)}>
+      <input {...register('email')} placeholder="Email" />
+      {errors.email && <span>{errors.email.message}</span>}
+
+      <input type="password" {...register('password')} placeholder="Password" />
+      {errors.password && <span>{errors.password.message}</span>}
+
+      <button type="submit" disabled={isSubmitting}>
+        {isSubmitting ? 'Submitting...' : 'Login'}
+      </button>
+    </form>
+  )
+}
+```
+
+---
+
+# 4. React Native Form (React Hook Form + Controller)
+
+React Native has no native `<input>` — use `Controller` to bridge RHF with RN's `TextInput`.
+
+```tsx
+// features/auth/components/LoginForm.tsx  (React Native)
+import { Controller, useForm } from 'react-hook-form'
+import { zodResolver } from '@hookform/resolvers/zod'
+import { loginSchema, type LoginInput } from '../schemas/login.schema'
+
+export function LoginForm({ onSubmit }: { onSubmit: (data: LoginInput) => void }) {
+  const {
+    control,
+    handleSubmit,
+    formState: { errors, isSubmitting },
+  } = useForm<LoginInput>({ resolver: zodResolver(loginSchema) })
+
+  return (
+    <View className="gap-4">
+      <Controller
+        control={control}
+        name="email"
+        render={({ field }) => (
+          <TextInput
+            value={field.value}
+            onChangeText={field.onChange}
+            placeholder="Email"
+            keyboardType="email-address"
+            autoCapitalize="none"
+          />
+        )}
+      />
+      {errors.email && <Text>{errors.email.message}</Text>}
+
+      <Controller
+        control={control}
+        name="password"
+        render={({ field }) => (
+          <TextInput
+            value={field.value}
+            onChangeText={field.onChange}
+            placeholder="Password"
+            secureTextEntry
+          />
+        )}
+      />
+      {errors.password && <Text>{errors.password.message}</Text>}
+
+      <PrimaryButton
+        title={isSubmitting ? 'Submitting...' : 'Login'}
+        onPress={handleSubmit(onSubmit)}
+        disabled={isSubmitting}
+      />
+    </View>
+  )
+}
+```
+
+---
+
+# 5. Validating API Responses
+
+Parse untrusted data at the boundary, not deep in hooks or components.
+
+```ts
+// features/products/services/productService.ts
+import { z } from 'zod'
+
+const productSchema = z.object({
+  id: z.string(),
+  name: z.string(),
+  price: z.number(),
+})
+
+export async function getProduct(id: string) {
+  const raw = await apiClient.get(`/products/${id}`)
+  return productSchema.parse(raw) // throws if shape is wrong
+}
+```
+
+---
+
+# 6. Rules
+
+- Schema first — always write the schema before the form.
+- Never write a separate TypeScript type for form input — use `z.infer<typeof schema>`.
+- Validate on the server too (or in the service) — never trust client-only validation.
+- Use `z.string().min(1)` not `z.string().nonempty()` — better cross-platform compatibility.
+- Route on `error.code` after submission, never on `error.message`.
+
+---
+
+# 7. Agent Quick Reference
+
+```text
+New form?                    → schema first in features/[name]/schemas/
+                             → useForm + zodResolver
+                             → web: register(); RN: Controller + TextInput
+New type for form data?      → z.infer<typeof schema> instead
+Validate API response?       → z.safeParse() or schema.parse() in service
+Shared schema?               → src/schemas/ or schemas/ (not in features/)
+```

package/playbooks/concerns/zustand.md

@@ -0,0 +1,93 @@
+# Zustand — Client State Management
+
+> **When to use:** Shared UI state that persists across components or screens but is NOT server data.
+> If the project has no such need, this concern does not apply.
+
+---
+
+# 1. The One Rule
+
+```text
+Zustand  → sidebar, active tab, auth user, wizard steps, user preferences, modal state
+TanStack Query → anything fetched from a server or API (users, posts, orders, products)
+```
+
+Never put server data in Zustand. Never put UI state in TanStack Query.
+
+---
+
+# 2. Store Setup
+
+```ts
+// src/stores/uiStore.ts  (web)
+// stores/uiStore.ts      (React Native)
+import { create } from 'zustand'
+
+type UIState = {
+  sidebarOpen: boolean
+  toggleSidebar: () => void
+}
+
+export const useUIStore = create<UIState>((set) => ({
+  sidebarOpen: false,
+  toggleSidebar: () => set((state) => ({ sidebarOpen: !state.sidebarOpen })),
+}))
+```
+
+---
+
+# 3. Auth Store Pattern
+
+```ts
+// stores/authStore.ts
+import { create } from 'zustand'
+
+type AuthState = {
+  user: User | null
+  setUser: (user: User | null) => void
+  logout: () => void
+}
+
+export const useAuthStore = create<AuthState>((set) => ({
+  user: null,
+  setUser: (user) => set({ user }),
+  logout: () => set({ user: null }),
+}))
+```
+
+---
+
+# 4. Rules
+
+- One store per domain concern: `authStore`, `cartStore`, `settingsStore` — not one giant global store.
+- Do NOT store server data (fetched from API) in Zustand — use TanStack Query.
+- Do NOT store local component-only state in Zustand — use `useState`.
+- Keep stores narrow. If a store grows beyond 5–6 fields, split it.
+
+---
+
+# 5. What Belongs Where
+
+```text
+useState / useReducer   → one component, resets on unmount
+Zustand                 → multiple components/screens, survives navigation
+TanStack Query          → anything from a server, needs caching or refetch
+```
+
+---
+
+# 6. Platform Notes
+
+> **React Native** — works identically. Import from `zustand` the same way.
+> Zustand has no dependency on the DOM or browser APIs.
+
+---
+
+# 7. Agent Quick Reference
+
+```text
+New shared UI state?           → stores/[name]Store.ts
+State only one component needs → useState instead
+State fetched from server?     → TanStack Query instead
+Store getting large?           → split into focused stores
+```

package/playbooks/devops/makefile.manifest.json

@@ -0,0 +1,10 @@
+{
+  "id": "makefile",
+  "kind": "devops",
+  "label": "Makefile",
+  "required": false,
+  "folders": [],
+  "concerns": [
+    { "id": "makefile", "required": true, "sections": ["Core Rules"] }
+  ]
+}