<!-- Copilot / AI agent instructions for the IGNY8 monorepo (backend + frontend) -->
# IGNY8 — Copilot Instructions

Purpose: quickly orient AI coding agents so they can make safe, high-value changes across the IGNY8 monorepo.

Key facts (big picture)
- **Monorepo layout:** Backend (Django) lives under `backend/` and the core Python package is `igny8_core/`. Frontend is in `frontend/` (Vite + React/TS). Documentation and architecture notes live in `master-docs/` and repo root `README.md`.
- **Services & runtime:** The project uses Django with Celery (see `igny8_core/celery.py` and `backend/celerybeat-schedule`), and a modern frontend build in `frontend/`. There is a `docker-compose.app.yml` to bring up combined services for development.
- **APIs:** Backend exposes REST endpoints under its `api/` modules and integrates with the WordPress bridge (see `WORDPRESS-PLUGIN-INTEGRATION.md` in `master-docs/`). AI components live under `igny8_core/ai/`.

Where to look first
- `backend/manage.py` — Django project CLI and common quick tests.
- `igny8_core/settings.py` — central configuration; check how secrets and environment variables are read before altering settings.
- `igny8_core/celery.py` and `backend/celerybeat-schedule` — Celery setup, periodic tasks, and beat schedule.
- `backend/requirements.txt` — Python dependencies; use it when creating or updating virtualenvs.
- `docker-compose.app.yml` — local dev composition (DB, cache, web, worker); follow it for local integration testing.
- `frontend/package.json`, `vite.config.ts` — frontend scripts and dev server commands.
- `master-docs/` — architecture and process documents (use these before making cross-cutting changes).

Project-specific conventions and patterns
- Python package: main Django app is `igny8_core` — add new reusable modules under `igny8_core/*` and keep app boundaries clear (`ai/`, `api/`, `auth/`, `modules/`).
- Settings & secrets: inspect `igny8_core/settings.py` for environment-based config; prefer adding new env vars there rather than hard-coding secrets.
- Celery tasks live near the domain logic; follow established naming and task registration patterns in `igny8_core/celery.py`.
- Frontend: components live under `frontend/src/` grouped by feature; tests use `vitest` (see `vitest.config.ts`).
- Docs-first: many architectural decisions are documented — prefer updating `master-docs/*` when you change interfaces, APIs, or long-lived behavior.

Integration points & external dependencies
- Database and cache: check `docker-compose.app.yml` for configured DB and cache services used in local dev (use same service names when writing connection logic).
- Celery & broker: Celery is configured in `igny8_core/celery.py`; ensure worker-related changes are tested with `celery -A igny8_core worker` and `celery -A igny8_core beat` when applicable.
- AI modules: `igny8_core/ai/` contains AI engine integration points — review `ai_core.py` and `engine.py` before changing model orchestration logic.
- Frontend ↔ Backend: frontend calls backend REST APIs; update API shapes in `api/` and coordinate with `frontend/src/api/`.

Developer workflows (copyable commands)
- Create a Python virtualenv and run backend locally:
```powershell
cd backend
python -m venv .venv
.\.venv\Scripts\Activate.ps1
pip install -r requirements.txt
python manage.py migrate
python manage.py runserver
```
- Run Celery worker (in a separate shell):
```powershell
cd backend
.\.venv\Scripts\Activate.ps1
celery -A igny8_core worker -l info
celery -A igny8_core beat -l info
```
- Run the app stack via Docker Compose (local integration):
```powershell
docker-compose -f docker-compose.app.yml up --build
```
- Frontend dev server:
```powershell
cd frontend
npm install
npm run dev
```
- Run backend tests (Django or pytest as configured):
```powershell
cd backend
.\.venv\Scripts\Activate.ps1
python manage.py test
# or `pytest` if pytest is configured
```

Rules for safe automated changes
- Preserve API contracts: when changing backend API responses, update `frontend/` calls and `master-docs/API-COMPLETE-REFERENCE.md`.
- Keep settings/environment changes explicit: add new env vars to `settings.py` and document them in `master-docs/`.
- When adding scheduled work, register tasks via Celery and update any existing beat schedules (and document in `master-docs/`).
- Avoid breaking the frontend build: run `npm run build` or `npm run dev` locally after API changes that affect the client.

Search hacks / quick finds
- Find API surface: search `api/` and `igny8_core/api/` for endpoint implementations.
- Find AI orchestration: search `igny8_core/ai/` for `engine.py` and `ai_core.py` references.
- Find Celery tasks: grep for `@shared_task` or `@app.task` in `igny8_core/`.

Testing and safety
- Use the repo `requirements.txt` and virtualenv for backend testing; run `python manage.py test` or `pytest` depending on existing test setup.
- For frontend, run `npm run test` or `vitest` as configured in `vitest.config.ts`.
- For integration changes, run the `docker-compose.app.yml` stack and exercise both web and worker services.

When you are unsure
- Read `master-docs/02-APPLICATION-ARCHITECTURE.md` and `04-BACKEND-IMPLEMENTATION.md` before large changes.
- Open an issue and link to `master-docs/` when proposing cross-cutting changes (database, schema, API contract).

Examples & quick references
- Start backend: `backend/manage.py runserver`
- Celery entrypoint: `igny8_core/celery.py`
- Local stack: `docker-compose.app.yml`
- Frontend dev: `frontend/package.json` & `vite.config.ts`

Next steps for humans
- Tell me which parts you want expanded: API reference, CI/CD snippets, deployment docs, or example tickets to implement.

— End
