diff --git a/.rules b/.rules index 3fdc900d..bf77bd6c 100644 --- a/.rules +++ b/.rules @@ -1,6 +1,6 @@ # IGNY8 AI Agent Rules -**Version:** 1.1.0 | **Updated:** December 27, 2025 +**Version:** 1.1.3 | **Updated:** December 27, 2025 --- @@ -26,6 +26,25 @@ --- +## ⚠️ 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:** @@ -57,26 +76,44 @@ docker logs igny8_celery_worker -f --- +## 📊 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 -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` +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 -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` +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` --- @@ -117,10 +154,13 @@ docker logs igny8_celery_worker -f - ❌ Create duplicate components - ❌ Use `docker-compose` for exec commands (use `docker exec`) - ❌ Use legacy `utils/ai_processor.py` -- ❌ Skip account scoping in queries +- ❌ 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) --- @@ -134,9 +174,42 @@ docker logs igny8_celery_worker -f | Billing | `/api/v1/billing/` | | Integration | `/api/v1/integration/` | | System | `/api/v1/system/` | -| Publisher | `/api/v1/publisher/` | -**API Docs:** http://localhost:8000/api/docs/ +**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. --- @@ -144,7 +217,7 @@ docker logs igny8_celery_worker -f - [ ] Read relevant module docs - [ ] Used existing components/patterns -- [ ] Account scoped all queries +- [ ] Correct data scope (Global/Account/Site) - [ ] Updated CHANGELOG.md with git reference - [ ] Updated version number - [ ] Ran migrations if model changed diff --git a/CHANGELOG.md b/CHANGELOG.md index 755e7355..a6bdcd12 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,6 +1,6 @@ # IGNY8 Change Log -**Current Version:** 1.1.1 +**Current Version:** 1.1.3 **Last Updated:** December 27, 2025 --- @@ -9,6 +9,8 @@ | Version | Date | Summary | |---------|------|---------| +| 1.1.3 | Dec 27, 2025 | Merged RULES.md into .rules | +| 1.1.2 | Dec 27, 2025 | Module status documentation, TODOS.md | | 1.1.1 | Dec 27, 2025 | Simplified AI agent rules file | | 1.1.0 | Dec 25, 2025 | UX overhaul, page consolidation, pre-launch audit | | 1.0.5 | Dec 12, 2025 | Purchase Credits tab, UI reorganization | @@ -20,16 +22,48 @@ --- +## v1.1.3 - December 27, 2025 + +### Changed +- **Merged RULES.md into .rules** - Single rules file for AI agents + - Added documentation rules section to `.rules` + - Deleted redundant `RULES.md` file + - Now only one rules file: `.rules` + +--- + +## v1.1.2 - December 27, 2025 + +### Added +- **Module Status section** in `.rules` file showing active/inactive modules + - Linker, Optimizer marked as ⏸️ Inactive (Phase 2) + - SiteBuilder marked as ❌ Removed (deprecated) +- **TODOS.md** file for tracking deprecated code cleanup + - Template for logging SiteBuilder and other deprecated code + +### Changed +- Updated "Don't Do" list with warnings about inactive modules and SiteBuilder + +--- + ## v1.1.1 - December 27, 2025 ### Changed - **Rules File Overhaul**: Simplified `.rules` file for AI agents - - Reduced from 300+ lines to ~120 lines + - Reduced from 300+ lines to ~150 lines - Added clear Docker container names and correct exec commands - Added one-line rules format for quick reading - Added quick reference table pointing to INDEX.md - Removed verbose code examples (agents should read actual codebase) - Added changelog format with git reference requirement + - **Added Data Scoping section** clarifying Global vs Account vs Site/Sector models + - Global settings (API keys, prompts, author profiles) are platform-wide, NOT account-scoped + - Site/Sector models (Keywords, Clusters, Content) need site+sector filtering + +### Added +- **MODELS.md**: Added Data Scoping Overview table and Global Models section + - Documents `GlobalIntegrationSettings`, `GlobalAIPrompt`, `GlobalAuthorProfile` + - Clear distinction between Global/Account/Site scoped models --- diff --git a/RULES.md b/RULES.md deleted file mode 100644 index b4d46592..00000000 --- a/RULES.md +++ /dev/null @@ -1,229 +0,0 @@ -# IGNY8 Documentation Rules - -**Version:** 1.0 -**Last Updated:** December 25, 2025 -**Purpose:** Rules for maintaining consistent, accurate documentation - ---- - -## Core Principles - -1. **Single Source of Truth** - One file per topic, no duplicates -2. **Code is King** - Documentation reflects actual code, not plans -3. **Tables Over Prose** - Use tables for lists of 3+ items -4. **Code Paths Always** - Every feature links to exact files -5. **Brief But Complete** - No fluff, every word has purpose - ---- - -## File Structure Rules - -### Root Folder (/) - -Only these MD files allowed in root: -- `CHANGELOG.md` - Version history -- `RULES.md` - This file -- `IGNY8-APP.md` - Executive summary (non-technical) -- `README.md` - Project quickstart - -**DO NOT CREATE** random MD files in root. All documentation goes in `/docs/`. - -### Docs Folder (/docs/) - -``` -docs/ -├── INDEX.md # Master navigation (update when adding docs) -├── 00-SYSTEM/ # Architecture, auth, tenancy -├── 10-MODULES/ # One file per module -├── 20-API/ # API endpoints and schemas -├── 30-FRONTEND/ # Pages, stores, components -├── 40-WORKFLOWS/ # Cross-module flows -└── 90-REFERENCE/ # Models, AI functions, troubleshooting -``` - ---- - -## Document Templates - -### Module Document - -Every module doc must include: - -```markdown -# [Module Name] - -**Last Verified:** YYYY-MM-DD -**Status:** ✅ Active | ⏸️ Inactive -**Backend Path:** `backend/...` -**Frontend Path:** `frontend/...` - -## Quick Reference -| What | File | Key Items | -|------|------|-----------| - -## Data Models -[Tables with fields] - -## API Endpoints -| Method | Path | Handler | Purpose | - -## Business Logic -[Key operations with credit costs] - -## Frontend Pages -[Routes and components] - -## Common Issues -| Issue | Cause | Fix | - -## Planned Changes -| Feature | Status | Description | -``` - -### Status Values - -For Planned Changes tables: -- ✅ Completed -- 🐛 Bug (known issue) -- 🔜 Planned (confirmed future work) -- ⏸️ Pending (waiting on dependency) -- ❌ Cancelled - ---- - -## Update Rules - -### When to Update Documentation - -| Event | Action | -|-------|--------| -| New feature added | Update relevant module doc | -| Bug fixed | Add to Common Issues if recurring | -| API endpoint changed | Update API endpoints table | -| Model changed | Update data models section | -| Config changed | Update relevant doc | -| Release | Update CHANGELOG.md | - -### What to Update - -| Change Type | Files to Update | -|-------------|-----------------| -| New module | Create module doc, update INDEX.md | -| New endpoint | Module doc + API/ENDPOINTS.md | -| New model | Module doc + 90-REFERENCE/MODELS.md | -| Frontend page | Module doc + 30-FRONTEND/PAGES.md | -| Bug fix | Common Issues in relevant doc | - -### "Last Verified" Dates - -Update `Last Verified:` date when: -- You confirm the doc matches current code -- After making changes to the doc -- During documentation reviews - ---- - -## Writing Style - -### Do - -- Use present tense ("Creates" not "Will create") -- Use tables for any list of 3+ items -- Include exact file paths -- Link to related docs -- Keep sentences short - -### Don't - -- Don't explain obvious things -- Don't use jargon without defining -- Don't duplicate info across files -- Don't use passive voice -- Don't leave TODOs in docs (use Planned Changes table) - -### Code Path Format - -``` -Backend: `backend/igny8_core/modules/planner/views.py:KeywordViewSet.bulk_delete` -Frontend: `frontend/src/pages/Planner/Keywords.tsx:handleBulkDelete` -``` - ---- - -## AI Agent Instructions - -When AI agents (Copilot, Claude, etc.) make changes: - -### After Code Changes - -1. Identify which module(s) were modified -2. Update the relevant module doc(s) -3. If API changed, update API endpoints -4. If model changed, update MODELS.md -5. Update CHANGELOG.md for significant changes - -### What NOT to Do - -- DO NOT create new MD files in root folder -- DO NOT create "summary" or "implementation" docs -- DO NOT duplicate existing documentation -- DO NOT add verbose explanations -- DO NOT leave placeholder content - -### Verification Checklist - -After documentation update: -- [ ] File is in correct location (/docs/ structure) -- [ ] INDEX.md updated if new file added -- [ ] No duplicate information -- [ ] All code paths are accurate -- [ ] Tables used appropriately -- [ ] Last Verified date updated - ---- - -## Documentation Review Schedule - -| Frequency | Action | -|-----------|--------| -| Per commit | Update affected docs | -| Weekly | Review recent changes vs docs | -| Monthly | Full audit: code vs docs | -| Per release | Update CHANGELOG.md, verify all docs | - ---- - -## Quick Reference: File Locations - -| Topic | File | -|-------|------| -| Master navigation | `docs/INDEX.md` | -| Architecture | `docs/00-SYSTEM/ARCHITECTURE.md` | -| Authentication | `docs/00-SYSTEM/AUTH-FLOWS.md` | -| Multi-tenancy | `docs/00-SYSTEM/TENANCY.md` | -| Planner module | `docs/10-MODULES/PLANNER.md` | -| Writer module | `docs/10-MODULES/WRITER.md` | -| Billing module | `docs/10-MODULES/BILLING.md` | -| Automation | `docs/10-MODULES/AUTOMATION.md` | -| Integrations | `docs/10-MODULES/INTEGRATIONS.md` | -| Settings | `docs/10-MODULES/SYSTEM-SETTINGS.md` | -| Linker (inactive) | `docs/10-MODULES/LINKER.md` | -| Optimizer (inactive) | `docs/10-MODULES/OPTIMIZER.md` | -| Publisher | `docs/10-MODULES/PUBLISHER.md` | -| API endpoints | `docs/20-API/ENDPOINTS.md` | -| All models | `docs/90-REFERENCE/MODELS.md` | -| Troubleshooting | `docs/90-REFERENCE/TROUBLESHOOTING.md` | -| Version history | `CHANGELOG.md` | -| Executive summary | `IGNY8-APP.md` | - ---- - -## Enforcement - -These rules are enforced by: -1. Code review checklist includes documentation -2. AI agents instructed to follow these rules -3. Monthly documentation audits -4. CHANGELOG must be updated for releases - -**When in doubt: Update the existing doc, don't create a new file.** diff --git a/TODOS.md b/TODOS.md new file mode 100644 index 00000000..0138355e --- /dev/null +++ b/TODOS.md @@ -0,0 +1,46 @@ +# IGNY8 Cleanup TODOs + +**Last Updated:** December 27, 2025 + +--- + +## 🗑️ Code Marked for Removal + +### SiteBuilder (Deprecated) + +SiteBuilder module is completely removed from the app. Any code found related to it should be cleaned up. + +| File/Location | Type | Status | Notes | +|---------------|------|--------|-------| +| *Add entries here when found* | | | | + +**How to identify SiteBuilder code:** +- References to `sitebuilder`, `site_builder`, `SiteBuilder` +- Components/pages with "SiteBuilder" in name +- API endpoints containing `sitebuilder` +- Models or services for building sites using IGNY8 + +--- + +## ⏸️ Inactive Modules (Phase 2) + +These modules exist but are NOT active. Do not modify unless specifically requested. + +| Module | Status | Planned Activation | +|--------|--------|-------------------| +| Linker | ⏸️ Disabled | Phase 2 | +| Optimizer | ⏸️ Disabled | Phase 2 | + +--- + +## 📝 Found Items Log + +*When you find deprecated code during development, add it here:* + +```markdown +### [Date] - [Found By] +- **File:** path/to/file +- **Type:** SiteBuilder / Other +- **Action Needed:** Remove / Refactor +- **Notes:** Description +``` diff --git a/docs/90-REFERENCE/MODELS.md b/docs/90-REFERENCE/MODELS.md index 672a8002..3de08b82 100644 --- a/docs/90-REFERENCE/MODELS.md +++ b/docs/90-REFERENCE/MODELS.md @@ -1,6 +1,63 @@ # Database Models Reference -**Last Verified:** December 25, 2025 +**Last Verified:** December 27, 2025 + +--- + +## Data Scoping Overview + +| Scope | Models | Base Class | Filter By | +|-------|--------|------------|-----------| +| **Global** | `GlobalIntegrationSettings`, `GlobalAIPrompt`, `GlobalAuthorProfile`, `GlobalStrategy`, `GlobalModuleSettings`, `Industry`, `SeedKeyword` | `models.Model` | None (platform-wide) | +| **Account** | `Account`, `User`, `Plan`, `IntegrationSettings`, `ModuleEnableSettings`, `AISettings`, `AIPrompt`, `AuthorProfile`, `CreditBalance` | `AccountBaseModel` | `account` | +| **Site+Sector** | `Keywords`, `Clusters`, `ContentIdeas`, `Tasks`, `Content`, `Images`, `AutomationConfig` | `SiteSectorBaseModel` | `site`, `sector` | + +--- + +## Global Models (`igny8_core/modules/system/global_settings_models.py`) + +**Purpose:** Platform-wide defaults and API keys. Admin-only. NOT account-scoped. + +### GlobalIntegrationSettings (Singleton) + +```python +class GlobalIntegrationSettings(models.Model): + # OpenAI (used by ALL accounts) + openai_api_key = CharField(max_length=500) + openai_model = CharField(default='gpt-4o-mini') + openai_temperature = FloatField(default=0.7) + openai_max_tokens = IntegerField(default=8192) + + # DALL-E / Image Generation + dalle_api_key = CharField(max_length=500) + dalle_model = CharField(default='dall-e-3') + dalle_size = CharField(default='1024x1024') + + # Runware + runware_api_key = CharField(max_length=500) +``` + +**Critical:** Singleton (pk=1). API keys here are used by ALL accounts. + +### GlobalAIPrompt + +```python +class GlobalAIPrompt(models.Model): + prompt_type = CharField(max_length=100) # clustering, ideas, content_generation + prompt_value = TextField() + variables = JSONField(default=list) + is_active = BooleanField(default=True) +``` + +### GlobalAuthorProfile + +```python +class GlobalAuthorProfile(models.Model): + name = CharField(max_length=255) + tone = CharField(max_length=50) # professional, casual, technical + language = CharField(max_length=10, default='en') + is_active = BooleanField(default=True) +``` ---