# Coding Rules

> Project-specific coding conventions discovered in the code. General engineering behavior lives in the Engineering Platform's `instructions/`.

_Verified against the codebase on 2026-07-23._

---

## Validated rules
- **Never bypass the canonical action services.** All pipeline transitions go through `Startup/InvestorLabelActionService`. Do not mutate `group_id`/status/action fields directly to "transition" an entity.
- **Reuse the REST controllers.** MCP tools and agent executors build sub-requests and delegate to the same controllers — do not duplicate business logic in a new surface.
- **Tag the activity source.** Writes carry an `ActivityContext` source (`SOURCE_AGENT`, dashboard, API, …) for the audit trail.
- **Respect the AI feature flag.** Anything under `/api/v1/ai/*` must honor `config('ai.enabled')` (404 when off) and the `ai.cb` circuit breaker.
- **Audit AI activity.** Use the existing `AiActivityLogger` (append-only `ai_activity_logs`, PII redaction) rather than ad-hoc logging.
- **Handle bilingual data.** Populate `*_ar`/`*_en` pairs and use locale-aware accessors; route name transliteration through `NameTransliterator` (cached).
- **Keep integration credentials isolated.** Bookings vs Webinars Azure apps must never cross-wire (see [`../04-integrations/microsoft-graph.md`](../04-integrations/microsoft-graph.md)).
- **Style:** `laravel/pint` is the formatter.

## Notes
- Detailed per-file style conventions beyond Pint defaults: **Unknown - requires confirmation** (no project style guide found in-repo).
- See [`database-rules.md`](database-rules.md) and [`api-rules.md`](api-rules.md) for persistence/API specifics.