# IGNY8 AI Agent Rules

**Version:** 1.1.3 | **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)

---

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

---

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

---

## 📊 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. **Check existing patterns** - Search codebase for similar implementations before creating new ones
3. **Use existing components** - Never duplicate; reuse components from `frontend/src/components/`
4. **Check data scope** - Know if your model is Global, Account, or Site/Sector scoped (see table above)

### During Coding
5. **Use correct base class** - Global: `models.Model`, Account: `AccountBaseModel`, Site: `SiteSectorBaseModel`
6. **Use AI framework** - Use `backend/igny8_core/ai/` for AI operations, NOT legacy `utils/ai_processor.py`
7. **Follow service pattern** - Business logic in `backend/igny8_core/business/*/services/`
8. **Check permissions** - Use `IsAuthenticatedAndActive`, `HasTenantAccess` in views
9. **Use TypeScript types** - All frontend code must be typed
10. **Use TailwindCSS** - No inline styles; follow `frontend/DESIGN_SYSTEM.md`

### After Coding
11. **Update CHANGELOG.md** - Every commit needs a changelog entry with git reference
12. **Increment version** - PATCH for fixes, MINOR for features, MAJOR for breaking changes
13. **Update docs** - If you changed APIs or architecture, update relevant docs in `docs/`
14. **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`
- ❌ Add account filtering to Global models (they're platform-wide!)
- ❌ Forget site/sector filtering on content models
- ❌ Forget to update CHANGELOG
- ❌ Use inline styles (use TailwindCSS)
- ❌ Hardcode values (use settings/constants)
- ❌ Work on Linker/Optimizer (inactive modules - Phase 2)
- ❌ Use any SiteBuilder code (deprecated - mark for removal)

---

## 📊 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:**
- `CHANGELOG.md` - Version history
- `README.md` - Project quickstart  
- `IGNY8-APP.md` - Executive summary
- `TODOS.md` - Cleanup tracking

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

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

- [ ] Read relevant module docs
- [ ] Used existing components/patterns
- [ ] Correct data scope (Global/Account/Site)
- [ ] Updated CHANGELOG.md with git reference
- [ ] Updated version number
- [ ] Ran migrations if model changed
- [ ] Tested locally