# IGNY8 AI Agent Rules

**Version:** 1.1.0 | **Updated:** December 27, 2025

---

## 🚀 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. Module doc for the feature you're modifying (see INDEX.md for paths)
3. [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`) |

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

---

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

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

---

## ✅ Rules (One Line Each)

### Before Coding
1. **Read docs first** - Always read the relevant module doc from `docs/10-MODULES/` before changing code
2. **Check existing patterns** - Search codebase for similar implementations before creating new ones
3. **Use existing components** - Never duplicate; reuse components from `frontend/src/components/`

### During Coding
4. **Scope by account** - Every query must filter by `account` (use `AccountBaseModel` or `SiteSectorBaseModel`)
5. **Use AI framework** - Use `backend/igny8_core/ai/` for AI operations, NOT legacy `utils/ai_processor.py`
6. **Follow service pattern** - Business logic in `backend/igny8_core/business/*/services/`
7. **Check permissions** - Use `IsAuthenticatedAndActive`, `HasTenantAccess` in views
8. **Use TypeScript types** - All frontend code must be typed
9. **Use TailwindCSS** - No inline styles; follow `frontend/DESIGN_SYSTEM.md`

### After Coding
10. **Update CHANGELOG.md** - Every commit needs a changelog entry with git reference
11. **Increment version** - PATCH for fixes, MINOR for features, MAJOR for breaking changes
12. **Update docs** - If you changed APIs or architecture, update relevant docs in `docs/`
13. **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) |
| 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) |

---

## 🚫 Don't Do

- ❌ Skip reading docs before coding
- ❌ Create duplicate components
- ❌ Use `docker-compose` for exec commands (use `docker exec`)
- ❌ Use legacy `utils/ai_processor.py`
- ❌ Skip account scoping in queries
- ❌ Forget to update CHANGELOG
- ❌ Use inline styles (use TailwindCSS)
- ❌ Hardcode values (use settings/constants)

---

## 📊 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/` |
| Publisher | `/api/v1/publisher/` |

**API Docs:** http://localhost:8000/api/docs/

---

## 🎯 Quick Checklist Before Commit

- [ ] Read relevant module docs
- [ ] Used existing components/patterns
- [ ] Account scoped all queries
- [ ] Updated CHANGELOG.md with git reference
- [ ] Updated version number
- [ ] Ran migrations if model changed
- [ ] Tested locally