# Project-Wide Agent Rules — OpticParse Monorepo

These rules apply to ALL agents working in this repository, regardless of
which service they are modifying.

## Repository Structure
This is a **polyglot monorepo** containing two independent microservices:

| Service | Language | Directory | Render URL |
|---------|----------|-----------|------------|
| OpticParse | Python / FastAPI | Repository root | `opticparse-python-sg.onrender.com` |
| PhishVision | TypeScript / Express | `opticparse-js/` | `opticparse-1opticparse-node-sg.onrender.com` |

## Strict Isolation Rules
1. **Never cross service boundaries.** If you are fixing OpticParse, do NOT
   touch files inside `opticparse-js/`. If you are fixing PhishVision, do NOT
   touch `server.py` or other root-level Python files.
2. **`render.yaml` ownership**: Lines 1–19 belong to OpticParse. Lines 21–39
   belong to PhishVision. Never edit the other service's block.

## Git Workflow
1. **Never push directly to `main`.** Always create a `fix/<service>-<description>` branch.
2. Use **conventional commit** format:
   - `fix(opticparse): <description>` for bug fixes
   - `feat(opticparse): <description>` for new features
   - `chore(opticparse): <description>` for maintenance
   - Replace `opticparse` with `phishvision` for the Node service.
3. After pushing, create a **Draft Pull Request** and halt for user review.

## Security Rules
1. **Never commit `.env` files.** They contain API keys and database credentials.
2. **Never log API keys** — not even partially. Use `***` masking if needed.
3. **Never hardcode secrets** in source code. Always use `os.getenv()` (Python)
   or `process.env` (TypeScript).

## Testing Requirements
1. **Python (OpticParse)**: Run `python -m pytest test_server.py -v` before committing.
2. **TypeScript (PhishVision)**: Run `npx tsc --noEmit` before committing.
3. If any test or compilation fails, fix it before committing. No exceptions.

## AI Provider Rotation
Both services share the same set of free AI provider API keys. When adding
or modifying providers:
1. Follow the existing data structure (`AI_PROVIDERS` dict in Python, `AIProvider` interface in TypeScript).
2. Add new providers to the END of the rotation list.
3. Update BOTH services if a provider key changes or a model is deprecated.

## Documentation
1. Preserve all existing comments and docstrings unless directly related to
   your code change.
2. New public endpoints must include OpenAPI documentation.
3. Update `README.md` if adding new endpoints or changing the API contract.