Add comprehensive Copilot instruction documentation and navigation

.github/COPILOT_QUICKSTART.md

@@ -0,0 +1,228 @@
+# GitHub Copilot Quick Start Guide
+
+**For developers and AI agents working on StormCom**
+
+## 🎯 First Time Setup
+
+### 1. Read Core Instructions
+Start here: **`.github/copilot-instructions.md`**
+- Repository overview and architecture
+- Build and validation workflows
+- MCP usage patterns
+
+### 2. Install Dependencies
+```bash
+npm install                    # Install all dependencies (20-30s)
+npm run prisma:generate       # Generate Prisma Client (5s)
+```
+
+### 3. Environment Configuration
+Create `.env.local`:
+```bash
+DATABASE_URL="postgresql://user:password@localhost:5432/stormcom_dev"
+NEXTAUTH_SECRET="development-secret-at-least-32-chars"
+NEXTAUTH_URL="http://localhost:3000"
+EMAIL_FROM="noreply@example.com"
+RESEND_API_KEY="re_dummy_key_for_build"  # Optional: Enables email sending
+```
+
+**Note:** Build succeeds without `RESEND_API_KEY`. When the key is missing, magic links are logged to the console instead of being emailed.
+
+### 4. Validate Setup
+```bash
+npm run type-check           # TypeScript validation (8-12s)
+npm run lint                 # ESLint check (8-15s)
+npm run build                # Production build (15-25s)
+npm run dev                  # Start dev server (1-2s)
+```
+
+## 🔍 Understanding the Codebase
+
+### Tech Stack
+- **Framework:** Next.js 16.0.3 (App Router, Turbopack)
+- **Language:** TypeScript 5
+- **Database:** PostgreSQL with Prisma 6.19.0
+- **Auth:** NextAuth 4.24 (email magic link)
+- **UI:** shadcn/ui with Tailwind CSS
+- **Multi-Tenancy:** Organization-based with Store scoping
+
+### Key Directories
+```
+src/
+├── app/                    # Next.js App Router
+│   ├── (auth)/            # Public auth routes
+│   ├── api/               # API routes
+│   ├── dashboard/         # Protected admin UI
+│   └── store/[slug]/      # Public storefront
+├── components/
+│   ├── ui/                # shadcn/ui primitives
+│   └── dashboard/         # Admin components
+└── lib/
+    ├── auth.ts            # NextAuth config
+    ├── prisma.ts          # Prisma singleton
+    └── multi-tenancy.ts   # Multi-tenant utilities
+```
+
+### Architecture Principles
+1. **Multi-Tenancy:** ALWAYS filter by `organizationId` AND `userId`
+2. **Server Components:** Default to Server Components, add `"use client"` only when needed
+3. **Prisma Singleton:** Never create `new PrismaClient()` outside `src/lib/prisma.ts`
+4. **Route Protection:** Add new protected routes to `middleware.ts` matcher
+
+## 🛠️ Common Development Tasks
+
+### Adding a New API Route
+1. Create route file: `src/app/api/your-route/route.ts`
+2. Export HTTP method handlers: `GET`, `POST`, etc.
+3. Validate input with Zod schemas
+4. Filter by `storeId` or `organizationId` for multi-tenancy
+5. Use `getServerSession(authOptions)` for auth checks
+
+### Adding a shadcn/ui Component
+```bash
+# ❌ Don't manually copy files
+# ✅ Use MCP tool
+#mcp_shadcn_get_add_command_for_items ["@shadcn/dialog", "@shadcn/form"]
+# Then run: npx shadcn@latest add dialog form
+```
+
+### Adding a Protected Route
+1. Create route folder: `src/app/your-route/page.tsx`
+2. Add to `middleware.ts` matcher: `"/your-route/:path*"`
+3. Use `getServerSession(authOptions)` in Server Component
+
+### Database Schema Changes
+```bash
+# 1. Edit prisma/schema.prisma
+# 2. Create migration (source env vars first!)
+export $(cat .env.local | xargs) && npm run prisma:migrate:dev
+# 3. Commit both schema and migration files
+```
+
+## 🤖 Using MCP Servers
+
+### Next.js Documentation (Always First!)
+```bash
+# ❌ Never answer Next.js questions from memory
+# ✅ Always query via MCP
+# Use: next-devtools MCP server → nextjs_docs tool
+```
+
+### Runtime Diagnostics
+```bash
+# When dev server is running:
+# Use: next-devtools → nextjs_runtime tools
+#   - discover_servers
+#   - list_tools
+#   - call_tool (get_errors, get_logs)
+```
+
+### Browser Testing
+```bash
+# Use: playwright MCP server
+#   - navigate to URL
+#   - click, type, fill forms
+#   - screenshot for verification
+#   - console_messages for errors
+```
+
+## 📚 Path-Specific Instructions
+
+When working on specific file types, Copilot automatically uses specialized instructions:
+
+| File Pattern | Instruction File | Focus Area |
+|--------------|------------------|------------|
+| `**/*.tsx, **/*.ts, **/*.jsx, **/*.js, **/*.css` | `nextjs.instructions.md` | Next.js 16 patterns |
+| `**/*.tsx, **/*.ts, **/*.jsx, **/*.js, **/*.css` | `nextjs-tailwind.instructions.md` | Next.js + Tailwind |
+| `**/*.jsx, **/*.tsx, **/*.js, **/*.ts` | `reactjs.instructions.md` | React 19 best practices |
+| `**/*.ts, **/*.js` | `typescript-mcp-server.instructions.md` | MCP server development |
+| `**/*.ts, **/*.tsx, **/*.js, **/*.jsx` | `playwright-typescript.instructions.md` | Browser testing |
+| `**/*.sql` | `sql-sp-generation.instructions.md` | SQL development |
+| `**` | `a11y.instructions.md` | Accessibility (WCAG 2.2) |
+| `**` | `security-and-owasp.instructions.md` | Security (OWASP Top 10) |
+| `**` | `performance-optimization.instructions.md` | Performance optimization |
+
+See `.github/instructions/` for all available instruction files.
+
+## 🎓 Custom Agents for Specialized Tasks
+
+### Planning & Architecture
+- **`Planer`** - Multi-step planning
+- **`task-planner`** - Implementation plans
+- **`implementation-plan`** - Feature breakdown
+- **`prd`** - Product requirements
+
+### Development Experts
+- **`expert-nextjs-developer`** - Next.js 16 specialist
+- **`expert-react-frontend-engineer`** - React 19 specialist
+- **`ui-ux-saas-specialist-agent`** - SaaS UI/UX specialist
+- **`typescript-mcp-expert`** - MCP server development
+
+### Testing & Quality
+- **`playwright-tester`** - Browser test generation
+- **`tdd-red`** → **`tdd-green`** → **`tdd-refactor`** - TDD workflow
+- **`web-design-guidelines-agent`** - UI/UX audits
+
+### DevOps & Security
+- **`se-gitops-ci-specialist`** - CI/CD debugging
+- **`se-security-reviewer`** - Security reviews
+- **`github-actions-expert`** - Workflow optimization
+
+Use: `@agent-name` or invoke via task tool
+
+## ⚡ Quick Reference
+
+### Build Commands
+```bash
+npm run dev              # Dev server (Turbopack)
+npm run build           # Production build
+npm run start           # Production server
+npm run type-check      # TypeScript validation
+npm run lint            # ESLint check
+npm run prisma:generate # Generate Prisma Client
+npm run prisma:migrate:dev # Run migrations
+```
+
+### Known Warnings (Safe to Ignore)
+- `@typescript-eslint/no-unused-vars` in `next-auth.d.ts`
+- `react-hooks/incompatible-library` in `src/components/data-table.tsx`
+
+### Build Times (Reference)
+- npm install: 18-30s
+- npm run build: 15-25s
+- npm run type-check: 8-12s
+- npm run lint: 8-15s
+
+## 🚨 Common Pitfalls
+
+### 1. Missing RESEND_API_KEY
+**Behavior:** Auth email sending is disabled and magic links are logged to the console because `RESEND_API_KEY` is not set
+**Fix:** Add `RESEND_API_KEY="re_your_actual_key"` to `.env.local` (a dummy value works for local development if you don't need actual emails sent)
+
+### 2. Prisma Client Not Generated
+**Error:** "Cannot find module '@prisma/client'"
+**Fix:** Run `npm run prisma:generate`
+
+### 3. Environment Variables Not Loaded
+**Error:** Prisma migrations fail
+**Fix:** Source env vars: `export $(cat .env.local | xargs) && npm run prisma:migrate:dev`
+
+### 4. Multi-Tenancy Data Leakage
+**Error:** Wrong store's data shown
+**Fix:** ALWAYS filter by `organizationId` AND `userId` or `storeId`
+
+### 5. next/dynamic with SSR: false in Server Component
+**Error:** Build/runtime error
+**Fix:** Move client logic to Client Component (`"use client"`), import directly
+
+## 📖 Additional Resources
+
+- **Full Instructions:** `.github/copilot-instructions.md`
+- **Instruction System:** `.github/README.md`
+- **Agent Guide:** `AGENT.md`
+- **GitHub Best Practices:** https://gh.io/copilot-coding-agent-tips
+- **Copilot Docs:** https://docs.github.com/en/copilot
+
+---
+
+**Ready to code?** Start with `npm install` and `.env.local` setup, then dive in! 🚀