.cursorrules

# AgentOS Base Project Rules

You are an expert AI software engineer working on AgentOS Base v7.0.
Adhere strictly to the following architectural and operational rules.

## 🛡️ Port Management (CRITICAL)
**Goal**: Prevent port conflicts in our complex microservices environment.
1.  **Registry First**: Before adding ANY new service or port binding, you MUST consult `docs/PORT_REGISTRY.md` to find an available port.
2.  **Registration**: If you use a new port, you MUST record it in `docs/PORT_REGISTRY.md`.
3.  **No Hardcoding**: NEVER hardcode port numbers in code.
    *   **Bad**: `app.run(port=3005)`
    *   **Good**: `port = int(os.getenv("NEW_SERVICE_PORT", 3005))` (and ensure default matches Registry)

## 🔌 API Standardization
**Goal**: Ensure unbreakable contracts between Frontend (React) and Backend (FastAPI).
1.  **Spec First**: All API responses must follow the format defined in `docs/API_RESPONSE_SPEC.md`.
2.  **Frontend**:
    *   **MUST** use the typed `apiFetch` client from `utils/apiClient.ts`.
    *   **MUST NOT** use raw `fetch` or `axios` for internal API calls.
    *   **MUST** use shared types from `types/api.ts`.
3.  **Backend**:
    *   **MUST** use `create_structured_error()` from `app.core.responses` for all error returns.
    *   **MUST** return Pydantic schemas that align with `types/api.ts`.

## 🏗️ Architecture
*   **Tech Stack**: React 18, Vite, Python 3.10+ (FastAPI), Temporal (Workflows), PostgreSQL, Docker.
*   **Microservices**: Services should be loosely coupled. Use Temporal for long-running processes.
*   **Frontend**: No direct logic in components. Use Hooks and Contexts.

## 📝 Commit & Code Style
*   Use Conventional Commits (feat, fix, chore, refactor).
*   Run `make lint` (Backend) or `npm run lint` (Frontend) before finishing tasks.