From 9d4d20d425533ba524673798426fba37a0137308 Mon Sep 17 00:00:00 2001
From: Christian Vidal Wolf <christianvidalwolf@gmail.com>
Date: Sun, 29 Mar 2026 19:05:02 +0200
Subject: [PATCH] Add AGENTS.md with developer guidelines

---
 AGENTS.md | 194 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 194 insertions(+)
 create mode 100644 AGENTS.md

diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 0000000..def1ac1
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,194 @@
+# AGENTS.md - Developer Guidelines for Craze-Data-check
+
+## Build, Lint, and Test Commands
+
+### Development
+```bash
+npm run dev              # Start dev server on port 3000
+npm run build            # Production build
+npm run preview          # Preview production build
+npm run clean            # Remove dist folder
+```
+
+### Linting & Type Checking
+```bash
+npm run lint             # TypeScript type check only (tsc --noEmit)
+```
+
+Note: This project does not have a separate test framework configured. To add tests, consider installing Vitest or Jest.
+
+---
+
+## Code Style Guidelines
+
+### General Principles
+- Use TypeScript for all new code
+- Prefer functional components with hooks over class components
+- Keep components focused and modular
+- Use meaningful variable and function names
+
+### Imports
+
+**Order (top to bottom):**
+1. React imports (`react`)
+2. External libraries (`lucide-react`, `xlsx`, etc.)
+3. Internal components (`./components/...`)
+4. Internal lib/utils (`./lib/...`)
+5. Types (`./types`)
+
+```typescript
+import React, { useState, useMemo } from 'react';
+import { Search, Filter, Edit2 } from 'lucide-react';
+import { ExcelRow, COLUMNS } from '../types';
+import { cn } from '../lib/utils';
+```
+
+### TypeScript Conventions
+
+- Use explicit types for props and function parameters
+- Use `any` sparingly; prefer union types or interfaces
+- Define column indices in a centralized `COLUMNS` object (see `src/types.ts`)
+
+```typescript
+// Good
+interface ProductDescriptionsProps {
+  data: ExcelRow[];
+  onEdit: (index: number) => void;
+}
+
+// Good - centralized constants
+export const COLUMNS = {
+  ARTICLE_NO: 0,
+  ARTICLE_NAME: 2,
+  LINE: 7,
+};
+```
+
+### Naming Conventions
+
+| Element | Convention | Example |
+|---------|------------|---------|
+| Components | PascalCase | `ProductDescriptions`, `MatrixView` |
+| Functions | camelCase | `handleFileUpload`, `formatCellValue` |
+| Variables | camelCase | `activeModule`, `paginatedData` |
+| Constants | UPPER_SNAKE_CASE | `ARTICLE_NO`, `MAX_UPLOAD_SIZE` |
+| Interfaces | PascalCase | `AppState`, `ExcelRow` |
+| Types | PascalCase | `TabType`, `SortDirection` |
+
+### React Patterns
+
+- Destructure props in function signature
+- Use `useMemo` for expensive computations
+- Use `useCallback` for event handlers passed to child components
+- Keep `useState` calls at the top of component
+
+```typescript
+export function ProductDescriptions({ data, onEdit }: ProductDescriptionsProps) {
+  const [activeTab, setActiveTab] = useState<TabType>('all');
+  const [search, setSearch] = useState('');
+
+  const filteredData = useMemo(() => {
+    // expensive computation
+  }, [data, activeTab, search]);
+}
+```
+
+### Error Handling
+
+- Use TypeScript's type system for runtime safety
+- Use optional chaining (`?.`) and nullish coalescing (`??`)
+- Validate file uploads with proper type checks
+
+```typescript
+const file = e.target.files?.[0];
+if (!file) return;
+
+// Validate Excel data
+if (data.length > 0) {
+  const rawHeaders = data[0];
+  const rawRows = data.slice(1);
+}
+```
+
+### UI/Styling
+
+- Use Tailwind CSS for all styling
+- Use `cn()` utility from `lib/utils` for conditional classes
+- Follow existing color scheme (slate, blue, green, red for status)
+- Use `lucide-react` for icons
+- Keep responsive design in mind
+
+```typescript
+import { cn } from '../lib/utils';
+
+<button
+  className={cn(
+    "px-4 py-2 rounded-md text-sm font-medium",
+    isActive 
+      ? "bg-blue-600 text-white" 
+      : "bg-slate-800 text-slate-400"
+  )}
+>
+```
+
+### File Organization
+
+```
+src/
+├── components/       # React components
+│   ├── Sidebar.tsx
+│   ├── MatrixView.tsx
+│   └── ...
+├── lib/             # Utilities and helpers
+│   ├── utils.ts     # cn(), helpers
+│   ├── auth.ts      # Authentication
+│   └── supabase.ts  # Database operations
+├── services/        # External API integrations
+│   ├── gemini.ts
+│   └── anthropic.ts
+├── types.ts         # TypeScript types and constants
+├── App.tsx          # Main application
+└── main.tsx         # Entry point
+```
+
+### Data Processing
+
+- When processing Excel data, handle both string and number types
+- Use centralized column index constants
+- Format numbers consistently (2 decimal places for prices/weights)
+- Handle Excel date serial numbers properly (convert to readable dates)
+
+```typescript
+// Handle date columns from Excel
+if (header.includes('date') || header.includes('launch')) {
+  if (typeof val === 'number' && val >= 25569 && val <= 60000) {
+    const excelEpoch = new Date(1899, 11, 30);
+    const date = new Date(excelEpoch.getTime() + val * 86400000);
+    return date.toLocaleDateString('en-GB');
+  }
+}
+```
+
+### Git Workflow
+
+- Make small, focused commits
+- Write clear commit messages describing what changed
+- Push to main to trigger Vercel deployment automatically
+
+### Running Single Components
+
+When testing or developing specific features:
+```bash
+npm run dev    # Start dev server - access at http://localhost:3000
+```
+
+### Environment Variables
+
+- Use `.env` file for local development
+- Never commit secrets - use Vercel dashboard for production env vars
+
+Required environment variables (production):
+- `VITE_SUPABASE_URL`
+- `VITE_SUPABASE_ANON_KEY`
+- `VITE_GEMINI_API_KEY`
+- `VITE_ANTHROPIC_API_KEY`