# IGNY8 AI Agent Rules

**Version:** 1.2.0 | **Updated:** January 2, 2026

---

## 🚀 Quick Start for AI Agents

**BEFORE any change, read these docs in order:**
1. [docs/INDEX.md](docs/INDEX.md) - Quick navigation to any module/feature
2. [docs/30-FRONTEND/COMPONENT-SYSTEM.md](docs/30-FRONTEND/COMPONENT-SYSTEM.md) - **REQUIRED** for any frontend work
3. [docs/30-FRONTEND/DESIGN-TOKENS.md](docs/30-FRONTEND/DESIGN-TOKENS.md) - Color tokens and styling rules
4. Module doc for the feature you're modifying (see INDEX.md for paths)
5. [CHANGELOG.md](CHANGELOG.md) - Recent changes and version history

---

## 📁 Project Structure

| Layer | Path | Purpose |
|-------|------|---------|
| Backend | `backend/igny8_core/` | Django REST API |
| Frontend | `frontend/src/` | React + TypeScript SPA |
| Docs | `docs/` | Technical documentation |
| AI Engine | `backend/igny8_core/ai/` | AI functions (use this, NOT `utils/ai_processor.py`) |
| Design Tokens | `frontend/src/styles/design-system.css` | **Single source** for colors, shadows, typography |
| UI Components | `frontend/src/components/ui/` | Button, Badge, Card, Modal, etc. |
| Form Components | `frontend/src/components/form/` | InputField, Select, Checkbox, Switch |
| Icons | `frontend/src/icons/` | All SVG icons (import from `../../icons`) |

**Module → File Quick Reference:** See [docs/INDEX.md](docs/INDEX.md#module--file-quick-reference)

---

## ⚠️ Module Status

| Module | Status | Notes |
|--------|--------|-------|
| Planner | ✅ Active | Keywords, Clusters, Ideas |
| Writer | ✅ Active | Tasks, Content, Images |
| Automation | ✅ Active | 7-stage pipeline |
| Billing | ✅ Active | Credits, Plans |
| Publisher | ✅ Active | WordPress publishing |
| **Linker** | ⏸️ Inactive | Exists but disabled - Phase 2 |
| **Optimizer** | ⏸️ Inactive | Exists but disabled - Phase 2 |
| **SiteBuilder** | ❌ Removed | Code exists but NOT part of app - mark for removal in TODOS.md |

**Important:**
- Do NOT work on Linker/Optimizer unless specifically requested
- SiteBuilder code is deprecated - if found, add to `TODOS.md` for cleanup

---

## 🎨 DESIGN SYSTEM RULES (CRITICAL!)

> **🔒 STYLE LOCKED** - All UI must use the design system. ESLint enforces these rules.

### Color System (Only 6 Base Colors!)

All colors in the system derive from 6 primary hex values in `design-system.css`:
- `--color-primary` (#0077B6) - Brand Blue
- `--color-success` (#2CA18E) - Success Green  
- `--color-warning` (#D9A12C) - Warning Amber
- `--color-danger` (#A12C40) - Danger Red
- `--color-info` (#18b2c4) - Info/accent color
- `--color-gray-base` (#667085) - Neutral gray

### Tailwind Color Classes

**✅ USE ONLY THESE** (Tailwind defaults are DISABLED):
```
brand-*    (50-950) - Primary blue scale
gray-*     (25-950) - Neutral scale
success-*  (25-950) - Green scale  
error-*    (25-950) - Red scale
warning-*  (25-950) - Amber scale
info-*     (25-950) - Info/accent scale
```

**❌ BANNED** (These will NOT work):
```
blue-*, red-*, green-*, emerald-*, amber-*, indigo-*, 
pink-*, rose-*, sky-*, teal-*, cyan-*, etc.
```

### Styling Rules

| ✅ DO | ❌ DON'T |
|-------|---------|
| `className="bg-brand-500"` | `className="bg-blue-500"` |
| `className="text-gray-700"` | `className="text-[#333]"` |
| `<Button variant="primary">` | `<button className="...">` |
| Import from `../../icons` | Import from `@heroicons/*` |
| Use CSS variables `var(--color-primary)` | Hardcode hex values |

---

## 🧩 COMPONENT RULES (ESLint Enforced!)

> **Never use raw HTML elements** - Use design system components.

### Required Component Mappings

| HTML Element | Required Component | Import Path |
|--------------|-------------------|-------------|
| `<button>` | `Button` or `IconButton` | `components/ui/button/Button` |
| `<input type="text/email/password">` | `InputField` | `components/form/input/InputField` |
| `<input type="checkbox">` | `Checkbox` | `components/form/input/Checkbox` |
| `<input type="radio">` | `Radio` | `components/form/input/Radio` |
| `<select>` | `Select` or `SelectDropdown` | `components/form/Select` |
| `<textarea>` | `TextArea` | `components/form/input/TextArea` |

### Component Quick Reference

```tsx
// Buttons
<Button variant="primary" tone="brand">Save</Button>
<Button variant="outline" tone="danger">Delete</Button>
<IconButton icon={<CloseIcon />} variant="ghost" title="Close" />

// Form Inputs
<InputField type="text" label="Name" value={val} onChange={setVal} />
<Select options={opts} onChange={setVal} />
<Checkbox label="Accept" checked={val} onChange={setVal} />
<Switch label="Enable" checked={val} onChange={setVal} />

// Display
<Badge tone="success" variant="soft">Active</Badge>
<Alert variant="error" title="Error" message="Failed" />
<Spinner size="md" />
```

### Icon Rules

**Always import from central location:**
```tsx
// ✅ CORRECT
import { PlusIcon, CloseIcon, CheckCircleIcon } from '../../icons';

// ❌ BANNED - External icon libraries
import { XIcon } from '@heroicons/react/24/outline';
import { Trash } from 'lucide-react';
```

**Icon sizing:**
- `className="w-4 h-4"` - In buttons, badges
- `className="w-5 h-5"` - Standalone
- `className="w-6 h-6"` - Headers, features

---

## 🐳 Docker Commands (IMPORTANT!)

**Container Names:**
| Container | Name | Purpose |
|-----------|------|---------|
| Backend | `igny8_backend` | Django API server |
| Frontend | `igny8_frontend` | React dev server |
| Celery Worker | `igny8_celery_worker` | Background tasks |
| Celery Beat | `igny8_celery_beat` | Scheduled tasks |

**Run commands INSIDE containers:**
```bash
# ✅ CORRECT - Run Django management commands
docker exec -it igny8_backend python manage.py migrate
docker exec -it igny8_backend python manage.py makemigrations
docker exec -it igny8_backend python manage.py shell

# ✅ CORRECT - Run npm commands
docker exec -it igny8_frontend npm install
docker exec -it igny8_frontend npm run build
docker exec -it igny8_frontend npm run lint  # Check design system violations

# ✅ CORRECT - View logs
docker logs igny8_backend -f
docker logs igny8_celery_worker -f

# ❌ WRONG - Don't use docker-compose for commands
# docker-compose exec backend python manage.py migrate
```

---

## 📊 Data Scoping (CRITICAL!)

**Understand which data is scoped where:**

| Scope | Models | Notes |
|-------|--------|-------|
| **Global (Platform-wide)** | `GlobalIntegrationSettings`, `GlobalAIPrompt`, `GlobalAuthorProfile`, `GlobalStrategy`, `GlobalModuleSettings`, `Industry`, `SeedKeyword` | Admin-only, shared by ALL accounts |
| **Account-scoped** | `Account`, `User`, `Plan`, `IntegrationSettings`, `ModuleEnableSettings`, `AISettings`, `AIPrompt`, `AuthorProfile` | Filter by `account` |
| **Site+Sector-scoped** | `Keywords`, `Clusters`, `ContentIdeas`, `Tasks`, `Content`, `Images` | Filter by `site` AND optionally `sector` |

**Key Rules:**
- Global settings: NO account filtering (platform-wide, admin managed)
- Account models: Use `AccountBaseModel`, filter by `request.user.account`
- Site/Sector models: Use `SiteSectorBaseModel`, filter by `site` and `sector`

---

## ✅ Rules (One Line Each)

### Before Coding
1. **Read docs first** - Always read the relevant module doc from `docs/10-MODULES/` before changing code
2. **Read COMPONENT-SYSTEM.md** - **REQUIRED** before any frontend changes
3. **Check existing patterns** - Search codebase for similar implementations before creating new ones
4. **Use existing components** - Never duplicate; reuse components from `frontend/src/components/`
5. **Check data scope** - Know if your model is Global, Account, or Site/Sector scoped (see table above)

### During Coding - Backend
6. **Use correct base class** - Global: `models.Model`, Account: `AccountBaseModel`, Site: `SiteSectorBaseModel`
7. **Use AI framework** - Use `backend/igny8_core/ai/` for AI operations, NOT legacy `utils/ai_processor.py`
8. **Follow service pattern** - Business logic in `backend/igny8_core/business/*/services/`
9. **Check permissions** - Use `IsAuthenticatedAndActive`, `HasTenantAccess` in views

### During Coding - Frontend (DESIGN SYSTEM)
10. **Use design system components** - Button, InputField, Select, Badge, Card - never raw HTML
11. **Use only design system colors** - `brand-*`, `gray-*`, `success-*`, `error-*`, `warning-*`, `purple-*`
12. **Import icons from central location** - `import { Icon } from '../../icons'` - never external libraries
13. **No inline styles** - Use Tailwind utilities or CSS variables only
14. **No hardcoded colors** - No hex values, no `blue-500`, `red-500` (Tailwind defaults disabled)
15. **Use TypeScript types** - All frontend code must be typed

### After Coding
16. **Run ESLint** - `docker exec -it igny8_frontend npm run lint` to check design system violations
17. **Update CHANGELOG.md** - Every commit needs a changelog entry with git reference
18. **Increment version** - PATCH for fixes, MINOR for features, MAJOR for breaking changes
19. **Update docs** - If you changed APIs or architecture, update relevant docs in `docs/`
20. **Run migrations** - After model changes: `docker exec -it igny8_backend python manage.py makemigrations`

---

## 📝 Changelog Format

```markdown
## v1.1.1 - December 27, 2025

### Fixed
- Description here (git: abc1234)

### Added
- Description here (git: def5678)

### Changed
- Description here (git: ghi9012)
```

---

## 🔗 Key Documentation

| I want to... | Go to |
|--------------|-------|
| Find any module | [docs/INDEX.md](docs/INDEX.md) |
| **Use UI components** | [docs/30-FRONTEND/COMPONENT-SYSTEM.md](docs/30-FRONTEND/COMPONENT-SYSTEM.md) |
| **Check design tokens** | [docs/30-FRONTEND/DESIGN-TOKENS.md](docs/30-FRONTEND/DESIGN-TOKENS.md) |
| **Design guide** | [docs/30-FRONTEND/DESIGN-GUIDE.md](docs/30-FRONTEND/DESIGN-GUIDE.md) |
| Understand architecture | [docs/00-SYSTEM/ARCHITECTURE.md](docs/00-SYSTEM/ARCHITECTURE.md) |
| Find an API endpoint | [docs/20-API/ENDPOINTS.md](docs/20-API/ENDPOINTS.md) |
| See all models | [docs/90-REFERENCE/MODELS.md](docs/90-REFERENCE/MODELS.md) |
| Understand AI functions | [docs/90-REFERENCE/AI-FUNCTIONS.md](docs/90-REFERENCE/AI-FUNCTIONS.md) |
| See frontend pages | [docs/30-FRONTEND/PAGES.md](docs/30-FRONTEND/PAGES.md) |
| See recent changes | [CHANGELOG.md](CHANGELOG.md) |
| View component demos | App route: `/ui-elements` |

---

## 🚫 Don't Do

### General
- ❌ Skip reading docs before coding
- ❌ Create duplicate components
- ❌ Use `docker-compose` for exec commands (use `docker exec`)
- ❌ Use legacy `utils/ai_processor.py`
- ❌ Add account filtering to Global models (they're platform-wide!)
- ❌ Forget site/sector filtering on content models
- ❌ Forget to update CHANGELOG
- ❌ Hardcode values (use settings/constants)
- ❌ Work on Linker/Optimizer (inactive modules - Phase 2)
- ❌ Use any SiteBuilder code (deprecated - mark for removal)

### Frontend - DESIGN SYSTEM VIOLATIONS
- ❌ Use raw `<button>` - use `Button` or `IconButton`
- ❌ Use raw `<input>` - use `InputField`, `Checkbox`, `Radio`
- ❌ Use raw `<select>` - use `Select` or `SelectDropdown`
- ❌ Use raw `<textarea>` - use `TextArea`
- ❌ Use inline `style={}` attributes
- ❌ Hardcode hex colors (`#0693e3`, `#ff0000`)
- ❌ Use Tailwind default colors (`blue-500`, `red-500`, `green-500`)
- ❌ Import from `@heroicons/*`, `lucide-react`, `@mui/icons-material`
- ❌ Create new CSS files (use `design-system.css` only)

---

## 📊 API Base URLs

| Module | Base URL |
|--------|----------|
| Auth | `/api/v1/auth/` |
| Planner | `/api/v1/planner/` |
| Writer | `/api/v1/writer/` |
| Billing | `/api/v1/billing/` |
| Integration | `/api/v1/integration/` |
| System | `/api/v1/system/` |

**API Docs:** https://api.igny8.com/api/docs/
**Admin:** https://api.igny8.com/admin/
**App:** https://app.igny8.com/

---

## 📄 Documentation Rules

**Root folder MD files allowed (ONLY these):**
- `.rules` - AI agent rules (this file)
- `CHANGELOG.md` - Version history
- `README.md` - Project quickstart

**All other docs go in `/docs/` folder:**
```
docs/
├── INDEX.md              # Master navigation
├── 00-SYSTEM/            # Architecture, auth, tenancy, IGNY8-APP.md
├── 10-MODULES/           # One file per module
├── 20-API/               # API endpoints
├── 30-FRONTEND/          # Pages, stores, DESIGN-GUIDE, DESIGN-TOKENS, COMPONENT-SYSTEM
├── 40-WORKFLOWS/         # Cross-module flows
├── 90-REFERENCE/         # Models, AI functions, FIXES-KB
└── plans/                # FINAL-PRELAUNCH, implementation plans
```

**When updating docs:**
| Change Type | Update These Files |
|-------------|-------------------|
| New endpoint | Module doc + `docs/20-API/ENDPOINTS.md` |
| New model | Module doc + `docs/90-REFERENCE/MODELS.md` |
| New page | Module doc + `docs/30-FRONTEND/PAGES.md` |
| New module | Create module doc + update `docs/INDEX.md` |

**DO NOT** create random MD files - update existing docs instead.

---

## 🎯 Quick Checklist Before Commit

### Backend Changes
- [ ] Read relevant module docs
- [ ] Correct data scope (Global/Account/Site)
- [ ] Ran migrations if model changed

### Frontend Changes
- [ ] Read COMPONENT-SYSTEM.md
- [ ] Used design system components (not raw HTML)
- [ ] Used design system colors (brand-*, gray-*, success-*, error-*, warning-*, purple-*)
- [ ] Icons imported from `../../icons`
- [ ] No inline styles or hardcoded hex colors
- [ ] Ran `npm run lint` - no design system violations

### All Changes
- [ ] Updated CHANGELOG.md with git reference
- [ ] Incremented version number
- [ ] Tested locally