docs re-org

docs/20-API/API-REFERENCE.md

@@ -0,0 +1,73 @@
+# REST API Reference
+
+## Purpose
+Summarize the major API groups, their base paths, and key actions as implemented in routing and viewsets.
+
+## Code Locations (exact paths)
+- Root routing: `backend/igny8_core/urls.py`
+- Auth endpoints: `backend/igny8_core/auth/urls.py` (APIView + routers)
+- Account management: `backend/igny8_core/api/urls.py`
+- Planner: `backend/igny8_core/modules/planner/urls.py`
+- Writer: `backend/igny8_core/modules/writer/urls.py`
+- System: `backend/igny8_core/modules/system/urls.py`
+- Billing: `backend/igny8_core/business/billing/urls.py`, `backend/igny8_core/modules/billing/urls.py`
+- Automation: `backend/igny8_core/business/automation/urls.py`
+- Integration: `backend/igny8_core/modules/integration/urls.py`
+- Linker/Optimizer/Publisher: respective `modules/*/urls.py`
+
+## High-Level Responsibilities
+- Provide RESTful CRUD endpoints for core resources (auth, planner, writer, billing, automation, integration, etc.) plus custom actions for domain workflows (automation run, billing payments, integration sync, content generation).
+
+## Detailed Behavior (by group)
+- Authentication (`/api/v1/auth/`):
+  - Routers: groups, users, accounts, subscriptions, site-access, plans, sites, sectors, industries, seed-keywords.
+  - APIViews: register, login, change password, refresh token; responses issue JWTs and session login.
+  - CSV admin helpers exposed separately under `/admin/igny8_core_auth/...` for industries/seed keywords.
+- Account management (`/api/v1/account/`):
+  - Settings (`settings/` get/patch), team (`team/` list/create, `team/<id>/` delete), usage analytics (`usage/analytics/`).
+- Planner (`/api/v1/planner/`):
+  - `keywords/`, `clusters/`, `ideas/` (CRUD, filtering/search/ordering, bulk delete/update, bulk add from seed).
+- Writer (`/api/v1/writer/`):
+  - `tasks/`, `images/`, `content/`, `taxonomies/` (CRUD, filtering/search/ordering).
+  - Custom actions: `tasks/auto_generate_content` (AI generation), `tasks/bulk_*`, `images/file`, grouped image utilities; content/taxonomy helpers in viewset.
+- System (`/api/v1/system/`): system settings, prompts, author profiles, etc. (see module docs).
+- Billing (`/api/v1/billing/`):
+  - Invoices (`invoices/`, detail, `download_pdf`), payments (`payments/`, `available_methods`, manual payment), credit packages (`credit-packages/`, purchase), transactions (`transactions/`), payment methods (`payment-methods/`, `set_default`), credits (`credits/balance`, `credits/usage`, `credits/transactions`).
+  - Admin billing under `/api/v1/admin/` (see module billing admin URLs).
+- Automation (`/api/v1/automation/`):
+  - Config (`config`, `update_config`), run (`run_now`), current run, history, logs, estimate, pipeline_overview, current_processing, pause/resume/cancel.
+- Integration (`/api/v1/integration/`):
+  - `integrations/` CRUD, `test_connection`, collection-level `test-connection`, `sync`, `sync_status`, `update-structure`, `get_content_types`, `debug_status`, `sync_wordpress_content`.
+  - Webhooks: `/webhooks/wordpress/status/`, `/webhooks/wordpress/metadata/`.
+- Linker/Optimizer/Publisher: endpoints under `/api/v1/linker/`, `/api/v1/optimizer/`, `/api/v1/publisher/` (viewsets for respective domain resources; see module docs).
+
+## Data Structures / Models Involved (no code)
+- Auth/account models, planner models (Keywords/Clusters/ContentIdeas), writer models (Tasks/Content/Images/Taxonomy), billing models (invoices/payments/credits), automation models (runs/configs), integration models (SiteIntegration/SyncEvent), and other module models as routed above.
+
+## Execution Flow
+- Requests hit module routers; viewsets/actions enforce permissions, throttles, and tenancy; serializers map models; responses use unified format.
+
+## Cross-Module Interactions
+- Auth JWTs used by all modules.
+- Billing credits checked in writer/automation flows; billing endpoints expose balances/usage.
+- Integration and publishing rely on writer content; automation depends on planner/writer data.
+
+## State Transitions
+- Managed by respective viewsets (e.g., task status, automation status, invoice/payment status).
+
+## Error Handling
+- Unified error responses; 4xx/5xx codes per viewset logic; throttling per scope.
+
+## Tenancy Rules
+- Base viewsets enforce account/site/sector filtering; API key auth supports WordPress paths; admin/developer/system roles may bypass filters as coded in base viewsets/auth middleware.
+
+## Billing Rules
+- Credits enforced in writer/automation service calls; billing endpoints expose ledger/usage/balance; insufficient credits return 402 where applicable.
+
+## Background Tasks / Schedulers
+- Automation actions enqueue Celery runs; writer content generation may enqueue AI tasks; other modules mostly synchronous.
+
+## Key Design Considerations
+- Consistent `/api/v1/` namespace with per-module routers.
+- OpenAPI schema available at `/api/schema`, Swagger at `/api/docs`, Redoc at `/api/redoc`.
+- Use module docs for endpoint-level details; this file outlines the map of API groups and actions.

docs/20-API/AUTHENTICATION-ENDPOINTS.md

@@ -0,0 +1,62 @@
+# Authentication Endpoints
+
+## Purpose
+Detail authentication-related endpoints for registration, login, password change, token refresh, and auth-adjacent resources (users/accounts/plans/sites/sectors/industries/seed keywords).
+
+## Code Locations (exact paths)
+- Routing: `backend/igny8_core/auth/urls.py`
+- Views: `backend/igny8_core/auth/views.py`
+- Serializers: `backend/igny8_core/auth/serializers.py`
+- Auth utils: `backend/igny8_core/auth/utils.py`
+
+## High-Level Responsibilities
+- Issue JWT access/refresh tokens and session auth on login.
+- Register users, change passwords, refresh tokens.
+- Provide CRUD for users, accounts, subscriptions, site access, plans, sites, sectors, industries, seed keywords via routers.
+
+## Detailed Behavior
+- APIViews:
+  - `POST /api/v1/auth/register/` → `RegisterView`: validates via `RegisterSerializer`, creates user, returns user data.
+  - `POST /api/v1/auth/login/` → `LoginView`: validates credentials, logs in user (session), generates access/refresh JWTs with expiries, returns user data and tokens; 401 on invalid credentials.
+  - `POST /api/v1/auth/change-password/` → `ChangePasswordView`: requires auth, validates old/new passwords, updates password; 400 on invalid current password or validation errors.
+  - `POST /api/v1/auth/refresh/` → `RefreshTokenView`: accepts refresh token, validates, issues new access token with expiry; 401/400 on invalid/expired tokens.
+- Routers under `/api/v1/auth/`:
+  - `groups/`, `users/`, `accounts/`, `subscriptions/`, `site-access/`, `plans/`, `sites/`, `sectors/`, `industries/`, `seed-keywords/` mapped to corresponding viewsets in `auth/views.py`. These use base viewsets with tenant filtering and role checks (see module docs).
+- CSV admin helpers (admin UI, not public API): CSV import/export for industry/industrysector/seedkeyword under `/admin/igny8_core_auth/...`.
+
+## Data Structures / Models Involved (no code)
+- `User`, `Account`, `Plan`, `Site`, `Sector`, `Industry`, `SeedKeyword`, `Subscription`, `SiteUserAccess`, `Group`.
+
+## Execution Flow
+- APIView endpoints use serializers to validate, then issue tokens via auth utils (JWT encode with user_id/account_id, type, exp).
+- Router endpoints inherit base viewsets; AccountContextMiddleware sets `request.account`; JWT/Session auth applied per settings; permissions enforced per viewset.
+
+## Cross-Module Interactions
+- Tokens issued here are required by planner/writer/billing/automation/etc.
+- Account/plan/site data informs tenancy and plan enforcement in middleware and billing limits.
+
+## State Transitions
+- User creation, password changes, session login, token issuance/refresh.
+- CRUD on accounts/sites/sectors/industries/seed keywords via routers.
+
+## Error Handling
+- Unified error responses via helpers; login returns 401 on invalid credentials; refresh returns 401/400 on invalid/expired tokens; validation errors return 400 with field errors.
+
+## Tenancy Rules
+- Login loads user with account+plan; middleware later enforces active plan. Router viewsets inherit account/site/sector filtering where applicable.
+
+## Billing Rules
+- None directly; plan data carried on Account; credits handled elsewhere.
+
+## Background Tasks / Schedulers
+- None.
+
+## Key Design Considerations
+- JWT payload includes user_id, account_id, type, exp/iat; uses `JWT_SECRET_KEY`/`JWT_ALGORITHM` from settings.
+- Session login occurs alongside JWT issuance to support browser-based flows.
+
+## How Developers Should Work With This Module
+- Use provided APIViews for auth; do not handcraft JWTs—use `generate_access_token`/`generate_refresh_token`.
+- When extending auth resources (e.g., new user fields), update serializers and viewsets; keep router paths stable.
+- Maintain unified responses and permission/tenancy checks in viewsets.
+

docs/20-API/AUTOMATION-ENDPOINTS.md

@@ -0,0 +1,65 @@
+# Automation Endpoints
+
+## Purpose
+Describe automation API endpoints that configure, trigger, monitor, and control automation runs.
+
+## Code Locations (exact paths)
+- Routing: `backend/igny8_core/business/automation/urls.py`
+- Views: `backend/igny8_core/business/automation/views.py`
+- Services/Tasks: `backend/igny8_core/business/automation/services/automation_service.py`, `automation_logger.py`, `backend/igny8_core/business/automation/tasks.py`
+
+## High-Level Responsibilities
+- Expose configuration CRUD (get/update) and operational controls (run, pause, resume, cancel).
+- Provide run history, status, logs, pipeline overview, credit estimate, and current processing state.
+- Enforce site/account scoping and authentication.
+
+## Detailed Behavior
+- Base path: `/api/v1/automation/`
+- Key endpoints (actions on `AutomationViewSet`):
+  - `GET config?site_id=` → get/create `AutomationConfig` for site (includes batch sizes, delays, schedule, flags, last/next run).
+  - `PUT update_config?site_id=` → update config fields (enable, frequency, scheduled_time, batch sizes, delays).
+  - `POST run_now?site_id=` → start a run (checks locks/credits) and enqueue Celery `run_automation_task`.
+  - `GET current_run?site_id=` → current running/paused run details with per-stage results and totals.
+  - `GET history?site_id=` → last 20 runs with status and timestamps.
+  - `GET logs?run_id=&lines=` → tail of automation log file for run.
+  - `GET estimate?site_id=` → estimated credits required plus current balance and sufficiency flag (1.2× buffer).
+  - `GET pipeline_overview?site_id=` → counts/pending by stage across planner/writer models.
+  - `GET current_processing?site_id=&run_id=` → live processing state for active run.
+  - `POST pause?run_id=` / `POST resume?run_id=` / `POST cancel?run_id=` → control run state (pause/resume/cancel).
+- Permissions/tenancy: `IsAuthenticated`; site fetched with `account=request.user.account`; automation lock is per site; `request.account` set by middleware.
+
+## Data Structures / Models Involved (no code)
+- `AutomationConfig`, `AutomationRun`, planner models (Keywords/Clusters/ContentIdeas), writer models (Tasks/Content/Images).
+
+## Execution Flow
+- View actions call `AutomationService` to start/control runs; long-running work executed by Celery tasks (`run_automation_task`, `resume_automation_task`).
+- Config updates persist to DB; run state and logs updated as stages progress.
+
+## Cross-Module Interactions
+- Uses planner/writer data for counts and processing; AI functions run inside service; billing credits checked via account balance before start and inferred from AI task logs during execution.
+
+## State Transitions
+- Run status: running ↔ paused → completed/failed/cancelled; `current_stage` advances per stage; per-stage results stored in `AutomationRun`.
+- Config `last_run_at`/`next_run_at` updated on scheduled runs.
+
+## Error Handling
+- Missing site_id/run_id → 400; run not found → 404; insufficient credits or concurrent run → 400; server errors → 500.
+- Logs endpoint 404s when run missing.
+
+## Tenancy Rules
+- All operations scoped to the authenticated user’s account/site; no cross-tenant access; locks are per site.
+
+## Billing Rules
+- Start requires credits ≥ estimated * 1.2; credits consumed by AI tasks are recorded via AI task logs and aggregated per stage.
+
+## Background Tasks / Schedulers
+- Celery tasks for scheduled runs (`check_scheduled_automations`) and pipeline execution/resume.
+
+## Key Design Considerations
+- Cooperative pause/resume/cancel with persisted partial results.
+- Log access via filesystem tail; structured per-stage results stored in DB for quick status reads.
+
+## How Developers Should Work With This Module
+- Trigger runs via `run_now`; avoid bypassing locks/credit checks.
+- Extend actions by reusing `AutomationService` and Celery tasks; keep site scoping and error handling consistent.
+

docs/20-API/BILLING-ENDPOINTS.md

@@ -0,0 +1,77 @@
+# Billing Endpoints
+
+## Purpose
+Detail billing API endpoints for invoices, payments, credit packages, transactions, payment methods, and credit balance/usage.
+
+## Code Locations (exact paths)
+- Routing: `backend/igny8_core/business/billing/urls.py`, `backend/igny8_core/modules/billing/urls.py`
+- Views: `backend/igny8_core/business/billing/views.py`, `backend/igny8_core/modules/billing/views.py`
+- Services: `backend/igny8_core/business/billing/services/credit_service.py`, `invoice_service.py`, `payment_service.py`
+
+## High-Level Responsibilities
+- Expose billing resources (invoices, payments, credit packages, payment methods, credit transactions).
+- Provide credit balance/usage/limits endpoints.
+- Support manual payment submission and available payment methods lookup.
+
+## Detailed Behavior
+- Base paths:
+  - `/api/v1/billing/` (business billing views via router)
+  - `/api/v1/admin/` (admin billing URLs)
+  - `/api/v1/billing/credits/...` (balance/usage/transactions aliases)
+- Invoice endpoints (`InvoiceViewSet`):
+  - `GET /invoices/` list account invoices (status filter optional).
+  - `GET /invoices/{id}/` invoice detail.
+  - `GET /invoices/{id}/download_pdf/` returns PDF bytes (placeholder).
+- Payment endpoints (`PaymentViewSet`):
+  - `GET /payments/` list payments (status filter optional).
+  - `GET /payment-methods/available/` returns available methods (country/config driven).
+  - `POST /payments/manual/` submit manual payment for an invoice (requires invoice_id, payment_method, transaction_reference; rejects already paid).
+- Account payment methods (`AccountPaymentMethodViewSet`):
+  - CRUD at `/payment-methods/`; `POST /payment-methods/{id}/set_default/` toggles default for the account.
+- Credit packages (`CreditPackageViewSet`):
+  - `GET /credit-packages/` list active packages.
+  - `POST /credit-packages/{id}/purchase/` creates invoice and returns next_action (Stripe/PayPal placeholders; manual fallback returns invoice info).
+- Credit transactions (`CreditTransactionViewSet`):
+  - `GET /transactions/` ledger of credit changes; also registered under `/credits/transactions/`.
+- Credit balance/usage/limits (`modules/billing/views.py`):
+  - `GET /credits/balance/` returns credits, plan monthly credits, month-to-date credits used.
+  - `GET /credits/usage/` returns paginated usage logs with filters; `GET /credits/usage/summary/` aggregates by operation/model and totals; `GET /credits/usage/limits/` returns plan/account limits and usage counts.
+- Permissions/tenancy: authenticated users; account-scoped querysets; viewsets rely on `request.account` or `request.user.account`.
+
+## Data Structures / Models Involved (no code)
+- `Invoice`, `Payment`, `CreditPackage`, `CreditTransaction`, `AccountPaymentMethod`, `PaymentMethodConfig`, `CreditUsageLog`, `CreditCostConfig`, `Account`, `Plan`.
+
+## Execution Flow
+- Router dispatch → viewset → service calls (invoice/payment/credit) → DB updates → unified responses. Balance/usage endpoints compute aggregates on demand.
+
+## Cross-Module Interactions
+- Credit costs/checks used by writer/automation AI flows; balances/usage reflect those deductions.
+- Plan limits surfaced in limits endpoint relate to account management in auth/account domains.
+
+## State Transitions
+- Invoices: draft/pending/paid/void/uncollectible; Payments: pending/pending_approval/processing/succeeded/completed/failed/refunded/cancelled; Credits balance changes via transactions.
+
+## Error Handling
+- Manual payment: 400 on missing fields or already-paid invoice.
+- Credit operations: 402 returned by upstream callers on `InsufficientCreditsError`.
+- Balance/usage: returns zeros/empty when account/plan missing.
+
+## Tenancy Rules
+- All billing data filtered by account; no cross-tenant access. Default viewsets inherit account scoping from base classes.
+
+## Billing Rules
+- Credit costs come from `CreditCostConfig` or constants; deductions recorded in ledger + usage logs.
+- Available methods and packages are filtered by active flags/config.
+
+## Background Tasks / Schedulers
+- None specific; Stripe/PayPal integrations are placeholders; any future webhooks should update invoices/payments/credits accordingly.
+
+## Key Design Considerations
+- Ledger + usage logs kept in sync via `CreditService`.
+- Manual payment flow avoids storing sensitive data; account payment methods store metadata only.
+
+## How Developers Should Work With This Module
+- Use `CreditService` for credit math; do not mutate balances directly.
+- Implement Stripe/PayPal flows in `PaymentService` if adding gateways; wire webhooks to update models.
+- Keep account scoping on all queries; reuse existing viewsets for new billing features.
+

docs/20-API/INTEGRATION-ENDPOINTS.md

@@ -0,0 +1,66 @@
+# Integration Endpoints
+
+## Purpose
+Document integration API endpoints for managing site integrations, testing connections, syncing, and handling WordPress webhooks.
+
+## Code Locations (exact paths)
+- Routing: `backend/igny8_core/modules/integration/urls.py`
+- Views: `backend/igny8_core/modules/integration/views.py`
+- Webhooks: `backend/igny8_core/modules/integration/webhooks.py`
+- Services: `backend/igny8_core/business/integration/services/*`
+
+## High-Level Responsibilities
+- CRUD for `SiteIntegration` records.
+- Test connections (detail and collection-level), trigger syncs, fetch sync status, update site structure, and sync WordPress content.
+- Expose WordPress webhook endpoints for status/metadata updates.
+
+## Detailed Behavior
+- Base path: `/api/v1/integration/`
+- Viewset: `IntegrationViewSet` (`/integrations/`, inherits `SiteSectorModelViewSet` but overrides queryset to filter by site_id since integrations have site only).
+  - Permissions: `IsAuthenticatedAndActive`, `IsEditorOrAbove`; throttle scope `integration`.
+  - Serializer exposes derived `api_key` (from credentials) and validates WordPress integrations require API key.
+  - Actions:
+    - `test_connection` (detail): calls `IntegrationService.test_connection` on existing integration; returns success/error.
+    - `test_connection_collection` (POST `integrations/test-connection/`, AllowAny): accepts site_id/api_key/site_url; validates site ownership or matching `Site.wp_api_key`; creates integration if missing; tests WordPress connection; deletes integration on failure; returns integration_id on success.
+    - `sync`: triggers `SyncService.sync` (direction metadata/both/to_external/from_external); metadata-only path uses `SyncMetadataService` internally.
+    - `sync_status`: returns sync status from `SyncService`.
+    - `update_site_structure`: updates `config_json.content_types` (post_types/taxonomies, plugin flags, timestamp) from WordPress push payload.
+    - `get_content_types`: returns content type config from integration config.
+    - `debug_status`: returns debug data via `SyncHealthService`.
+    - `sync_wordpress_content`: calls `ContentSyncService.sync_from_wordpress` for a specific content_id.
+- Webhooks:
+  - `/webhooks/wordpress/status/` and `/webhooks/wordpress/metadata/` endpoints for WordPress callbacks (handled in `webhooks.py`).
+
+## Data Structures / Models Involved (no code)
+- `SiteIntegration`, `SyncEvent`, `Site`, `Account`.
+
+## Execution Flow
+- CRUD/test/sync requests → DRF auth → site-filtered queryset → service calls → model updates/sync actions. Collection-level test may create/delete integration based on result. Webhooks call handlers for incoming WordPress events.
+
+## Cross-Module Interactions
+- Integrations used by publishing/sync flows to external platforms; WordPress API key path relies on `Site.wp_api_key` and integration credentials.
+- Sync services interact with writer/planner content for metadata/content sync.
+
+## State Transitions
+- Integration `sync_status/last_sync_at/is_active/sync_enabled` updated by sync/test actions; `SyncEvent` records per-action success/failure with timestamps and IDs.
+
+## Error Handling
+- Invalid site/auth/API key return 403/404/400; unsupported platforms raise `NotImplementedError`; failed collection-level tests delete newly created integrations.
+
+## Tenancy Rules
+- All endpoints scoped to the site/account; queryset filters by site_id and permissions enforce authenticated editor-or-above unless using collection-level API key path.
+
+## Billing Rules
+- None; integration endpoints do not change credits.
+
+## Background Tasks / Schedulers
+- None specific; sync logic executes in service calls (may delegate internally).
+
+## Key Design Considerations
+- Single integration per site+platform; collection-level test supports plugin onboarding with API key.
+- Credentials stored as JSON (encryption pending).
+
+## How Developers Should Work With This Module
+- Use `IntegrationService` for CRUD/test; extend platform support via new test logic and serializer validation.
+- Keep site scoping and API key validation intact for collection-level tests.
+

docs/20-API/PLANNER-ENDPOINTS.md

@@ -0,0 +1,62 @@
+# Planner Endpoints
+
+## Purpose
+Document planner API endpoints for keywords, clusters, and content ideas, including filters, bulk actions, and validation rules.
+
+## Code Locations (exact paths)
+- Routing: `backend/igny8_core/modules/planner/urls.py`
+- Views: `backend/igny8_core/modules/planner/views.py`
+- Serializers: `backend/igny8_core/modules/planner/serializers.py`
+
+## High-Level Responsibilities
+- CRUD for planner entities scoped by account/site/sector with search, filtering, ordering, and bulk operations.
+- Enforce site/sector requirements and seed keyword alignment on creation.
+
+## Detailed Behavior
+- Base path: `/api/v1/planner/`
+- Viewsets (all inherit `SiteSectorModelViewSet`, scoped by account/site/sector, throttled with scope `planner`, paginated):
+  - `KeywordViewSet` (`/keywords/`):
+    - Search: `seed_keyword__keyword`.
+    - Filters: status, cluster_id, seed_keyword intent/id; custom difficulty_min/max and volume_min/max (uses overrides or seed values).
+    - Ordering: created_at, seed volume/difficulty.
+    - Bulk: `bulk_delete`, `bulk_update` (status), `bulk_add_from_seed` (create Keywords from SeedKeywords after validating site/sector).
+    - Create requires site_id and sector_id; validates site/sector existence and alignment.
+  - `ClusterViewSet` (`/clusters/`):
+    - Filters: status; standard CRUD; site/sector required on create.
+  - `ContentIdeasViewSet` (`/ideas/`):
+    - Filters: status, cluster; standard CRUD; site/sector required on create.
+- Serializers enforce required fields on create (`KeywordSerializer` requires seed_keyword_id; site/sector write-only), expose read-only seed-derived fields and cluster/sector names.
+- Error handling: unified responses; validation errors for missing site/sector/seed; bulk actions return 400 when IDs/status missing.
+
+## Data Structures / Models Involved (no code)
+- `Keywords`, `Clusters`, `ContentIdeas`, `SeedKeyword`, plus `Account`, `Site`, `Sector`.
+
+## Execution Flow
+- Requests → DRF auth → base viewset filters (account/site/sector) → serializer validation → model save → unified response; bulk actions operate on filtered queryset.
+
+## Cross-Module Interactions
+- Feeds automation Stage 1–3 and writer tasks/content generation.
+- Billing credits may be checked upstream when AI clustering/idea generation is invoked.
+
+## State Transitions
+- Keywords: `new` → `mapped`; Clusters: `new` → `mapped`; ContentIdeas: `new` → `queued` → `completed`.
+
+## Error Handling
+- Missing required IDs or validation failures return 400; unified 500 on unhandled errors.
+
+## Tenancy Rules
+- All endpoints scoped to account/site/sector via base viewset; admin/developer/system roles can bypass filtering, but data retains tenant/site/sector fields.
+
+## Billing Rules
+- No direct deductions in these endpoints; AI clustering/idea generation costs enforced where services are called.
+
+## Background Tasks / Schedulers
+- None in planner endpoints; automation handles async flows.
+
+## Key Design Considerations
+- Strict site/sector requirements prevent cross-site contamination.
+- Seed linkage keeps keyword metadata consistent; overrides allow site-specific tuning.
+
+## How Developers Should Work With This Module
+- Supply site_id/sector_id on create; use bulk actions for batch changes; extend filters/search/order as needed while respecting base scoping.
+

docs/20-API/WRITER-ENDPOINTS.md

@@ -0,0 +1,68 @@
+# Writer Endpoints
+
+## Purpose
+Document writer API endpoints for tasks, content, images, and taxonomies, including bulk actions and AI content generation triggers.
+
+## Code Locations (exact paths)
+- Routing: `backend/igny8_core/modules/writer/urls.py`
+- Views: `backend/igny8_core/modules/writer/views.py`
+- Serializers: `backend/igny8_core/modules/writer/serializers.py`
+- Services: `backend/igny8_core/business/content/services/content_generation_service.py`
+
+## High-Level Responsibilities
+- CRUD for writer entities scoped by account/site/sector.
+- Provide bulk operations and AI content generation for tasks.
+- Manage images and taxonomy terms linked to content/tasks.
+
+## Detailed Behavior
+- Base path: `/api/v1/writer/`
+- Viewsets (inherit `SiteSectorModelViewSet`, throttled `writer`, paginated):
+  - `TasksViewSet` (`/tasks/`):
+    - Filters: status, cluster_id, content_type, content_structure; search title/keywords; ordering by title/created_at/status.
+    - Bulk: `bulk_delete`, `bulk_update` (status).
+    - `auto_generate_content`: accepts task IDs (max 10), requires account, enforces credit checks via `ContentGenerationService`, returns async task_id or synchronous result; 402 on insufficient credits.
+    - Create requires site_id/sector_id; validates site/sector alignment; sets account/site/sector explicitly.
+  - `ImagesViewSet` (`/images/`):
+    - Filters: task_id, content_id, image_type, status; ordering by created_at/position/id.
+    - perform_create enforces site/sector presence (from request or defaults), sets account/site/sector; serves local files via `file` action with existence checks.
+  - `ContentViewSet` (`/content/`):
+    - Filters/order/search defined in viewset (titles, status, etc.); manages taxonomy relationships; exposes status, SEO fields, cluster link, external IDs/URLs.
+  - `ContentTaxonomyViewSet` (`/taxonomies/`):
+    - CRUD for taxonomy terms (category/tag) scoped to site/sector.
+- Serializers enforce required fields on create (e.g., cluster/content_type/content_structure for tasks; site/sector for content) and expose read-only derived fields (cluster/sector names, image/taxonomy info).
+- Error handling: unified responses; validation errors return 400; missing resources return 404; `auto_generate_content` can return 402/500 on credits/other errors.
+
+## Data Structures / Models Involved (no code)
+- `Tasks`, `Content`, `Images`, `ContentTaxonomy`, and related domain models; `Account`, `Site`, `Sector`.
+
+## Execution Flow
+- Requests → DRF auth → base viewset filtering (account/site/sector) → serializer validation → model save → unified response; bulk/AI actions invoke services.
+
+## Cross-Module Interactions
+- Planner clusters/ideas feed tasks; automation stages 3–6 operate on writer data; publishing/integration uses content/taxonomies/images.
+- Billing credits enforced during AI content generation via `ContentGenerationService`.
+
+## State Transitions
+- Tasks: `queued` → `completed`; Content: `draft` → `review` → `published`; Images: `pending` → `generated`.
+
+## Error Handling
+- Standard unified responses; credit errors mapped to 402 in `auto_generate_content`; file serving returns 404 for missing images.
+
+## Tenancy Rules
+- All endpoints scoped to account/site/sector; base viewset and permissions enforce access; admin/developer/system may bypass filtering but records retain tenant/site/sector fields.
+
+## Billing Rules
+- AI generation actions check/deduct credits via billing services; other CRUD does not alter credits.
+
+## Background Tasks / Schedulers
+- `auto_generate_content` may enqueue Celery AI tasks when returning task_id; automation uses writer endpoints indirectly via services.
+
+## Key Design Considerations
+- Strict site/sector validation on create; max 10 tasks per auto_generate_content to manage load/credits.
+- Image file serving is permissive but guarded by existence checks.
+
+## How Developers Should Work With This Module
+- Supply site_id/sector_id on create; use bulk actions for batch changes.
+- When extending AI flows, keep credit checks and account/site scoping intact.
+- Reuse existing viewsets/serializers for new fields; ensure filters/throttles stay aligned with module scope.
+