AGENTS.md Tanstack Start with Cloudflare

## Stack: 
## Tanstack Start
## Infra: Alchemy / Cloudflare
## UI: Shadcn 
## Store: Zustand
## DB Drizzle

## Commands

- Dev Server:  pnpm dev  (runs Alchemy dev with hot-reload; uses .env.dev)  
- Build:  pnpm build  (Vite + Nitro SSR; outputs to dist/)  
- Deploy:  pnpm deploy  (Alchemy deploy to prod2; uses .env.prod2)  
- Lint:  pnpm lint  (ESLint + Prettier via .oxlintrc.json and .prettierrc)  
- Typecheck:  pnpm typecheck  (TypeScript via tsconfig.json)  
- Test All:  pnpm test  (Vitest; unit/integration; mocks Cloudflare workers)  
- Test Single:  pnpm test path/to/file.test.ts  or  pnpm test -- --run=describeName  
  (e.g.,  pnpm test tests/unit/assistant-adapter.test.ts )  
- Test Integration:  pnpm test:integration  (uses Vitest config; enable  
  ALCHEMY_TEST=1 for worker-mode)  
- DB Migrations:  pnpm drizzle-kit generate  (local SQL gen); Alchemy handles apply  
  on deploy  
- DB Studio:  pnpm db:studio:dev  (Drizzle Studio for local inspection)  

## Code Style Guidelines

- Language/Stack: TypeScript React (.tsx); TanStack Start 1.131.28, React 19, Zustand  
  5, TanStack Query 6; pnpm only; no shadcn-ui (use shadcn@latest)  
- Imports: Use ~ alias for src/ (e.g.,  import { foo } from '~/utils' ); named  
  exports only; no defaults in routes; env via import.meta.env (browser-safe) or  
  process.env (server-only)  
- Formatting: Prettier (.prettierrc); ESLint (.oxlintrc.json); 2-space indent; single  
  quotes; trailing commas  
- Types: Always type props/hooks/loaders; async arrow loaders return typed objects;  
  use readonly/const for immutability  
- Naming: PascalCase components; camelCase functions/vars; snake_case DB cols;  
  descriptive (e.g., useSuspenseQuery over useQuery)  
- Structure: Routes in src/routes (folder-based, colocated loader/action); components  
  stateless/fetch-free in src/components; hooks in src/hooks; stores in src/lib/stores  
  (Zustand per context)  
- Data Fetching: Route loaders for required data; TanStack Query for cacheable  
  (prefetch in loader, useSuspenseQuery); defer() for streaming; no useEffect for fetch  
- API Routes: createServerFileRoute from @tanstack/react-start/server  
- Alchemy/Cloudflare: Workers use entrypoint (not script); bindings via alchemy.run.  
  ts; no Wrangler; mock env in tests  
- Error Handling: Try-catch in async; use TanStack Query error boundaries  
- Testing: Mock Cloudflare workers; use helpers in tests/helpers; no real network;  
  Vitest with vi.doMock  
- Security: Never commit secrets (.env.example only)  
- Proactivity: Minimal changes; follow patterns; verify with lint/typecheck/test  
  after edits; ask to add commands/styles here if learned