Imported from joaofernandesuk/fanbackstage (docs/AGENTS.md). Install upstream with npx skills add joaofernandesuk/fanbackstage --skill docs. Copyright stays with the author.

Codex Engineering Instructions

This file is the mandatory operating contract for Codex and human contributors. When another document conflicts with this file, stop and resolve the conflict rather than guessing.

Mandatory reading order

Before making architectural or implementation changes, read:

1. PROJECT.md
2. PRODUCT.md
3. ARCHITECTURE.md
4. The domain document(s) relevant to the task.
5. DATA_MODEL.md and PERMISSIONS.md for any schema/authorisation work.
6. FINANCIAL_LEDGER.md for any feature that creates, moves, reserves, discounts, refunds or allocates value.
7. TRUST_AND_SAFETY.md for any content, messaging, live, marketplace or moderation work.
8. ROADMAP.md before introducing a domain that belongs to a later phase.

Non-negotiable engineering rules

• Build a modular monolith first. Do not introduce microservices without a documented need.
• PostgreSQL + SQLAlchemy 2 + Alembic are the source of truth for persistent relational state.
• Business rules live in backend/domain services, not only in React/Next.js components.
• Never treat front-end visibility as authorisation.
• Every paid action must be idempotent and traceable to immutable ledger entries.
• Never recalculate historical earnings using current commission, group split, pricing or promotion settings.
• Never overwrite an accepted group financial split. Create a new proposed/accepted contract version.
• Never expose protected media originals to unauthorised clients. Generate authorised derivatives/previews.
• Every access decision must resolve through explicit entitlement/access policy.
• Every critical admin/manager action must emit an audit event.
• Do not invent schema fields or duplicate concepts that already have a domain owner.
• Prefer explicit state machines and enums over ambiguous booleans.
• Use UTC for persisted timestamps; convert at presentation boundaries.
• Monetary values use integer minor units or an exact decimal strategy; never binary floating point.
• Currency must always be explicit.
• Use database transactions around multi-step financial/state changes.
• External payment/streaming/media callbacks must be idempotent and replay-safe.
• Add tests for every business invariant changed by the task.
• Migrations must be reviewed; autogenerated Alembic output is not accepted blindly.
• Preserve backward compatibility of public APIs unless the task explicitly includes a versioned break.
• Do not implement adult-content policy assumptions ad hoc; use central policy/configuration and Trust & Safety rules.

Definition of done

A change is not complete until:

• Schema and migrations are intentional and reversible where practical.
• API/domain validation is implemented server-side.
• Permission checks are covered by tests.
• Relevant ledger/entitlement/audit effects are covered by tests.
• State transition edge cases and retries are tested.
• No protected original media URL leaks through API payloads.
• Documentation is updated when a business rule or domain boundary changes.