Craze-Data-check/AGENTS.md

# AGENTS.md - Developer Guidelines for Craze-Data-check

## Ruflo Standard Operating Procedure (SOP)
**MANDATORY: Follow these steps for every user instruction.**

1. **Retrieve (Semantic Memory)**: Before starting, run `ruflo memory search -q "<task description>"` to find relevant historical patterns or previous solutions.
2. **Verify (Security)**: Use `ruflo security defend -i "<user instruction>"` to ensure the instruction is safe and follows security protocols.
3. **Execute (Agent Swarm)**: For complex tasks (refactors, multi-file changes), consider spawning specialized agents with `ruflo agent spawn -t <type>`.
4. **Version Control**: Use `agentic-jujutsu` for managing concurrent changes or if a lock-free approach is needed.
5. **Record (Learning)**: After completion, record the outcome with `ruflo memory store --key "<task_id>" --value "<outcome_details>"` to improve future performance.

---

## 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: No test framework configured. To add tests, install 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 (`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
interface ProductDescriptionsProps {
  data: ExcelRow[];
  onEdit: (index: number) => void;
}

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

### Error Handling
- Use TypeScript's type system for runtime safety
- Use optional chaining (`?.`) and nullish coalescing (`??`)
- Validate file uploads with proper type checks

### 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

```typescript
<button className={cn("px-4 py-2 rounded-md", isActive ? "bg-blue-600" : "bg-slate-800")}>
```

### File Organization
```
src/
├── components/       # React components
├── lib/              # Utilities (utils.ts, auth.ts, supabase.ts)
├── services/         # External API integrations (gemini.ts, anthropic.ts)
├── types.ts          # TypeScript types and constants
├── App.tsx           # Main application
└── main.tsx          # Entry point
```

### Data Processing
- Handle both string and number types when processing Excel data
- Use centralized column index constants
- Format numbers consistently (2 decimal places for prices/weights)
- Handle Excel date serial numbers properly

```typescript
// Handle date columns from Excel
if (typeof val === 'number' && val >= 25569 && val <= 60000) {
  const excelEpoch = new Date(1899, 11, 30);
  return new Date(excelEpoch.getTime() + val * 86400000).toLocaleDateString('en-GB');
}
```

### Git Workflow
- Make small, focused commits
- Write clear commit messages describing what changed
- Push to main to trigger Vercel deployment automatically

### Environment Variables
- Use `.env` file for local development
- Never commit secrets - use Vercel dashboard for production env vars

Required: `VITE_SUPABASE_URL`, `VITE_SUPABASE_ANON_KEY`, `VITE_GEMINI_API_KEY`, `VITE_ANTHROPIC_API_KEY`