# Repository Guidelines

## Project Structure & Module Organization
- `backend/`: FastAPI admin service (entry `run.py`), configuration in `app/config.py`, SQLite state in `cursorpro.db`, and runtime helpers `start.sh`/`stop.sh`. Static assets live under `static/` with HTML in `templates/`.
- `extension/`: Packaged VS Code extension; `.vsix` bundles for install, compiled logic under `out/` (API client, webview, status bar) and assets in `media/`. Code is obfuscated; prefer small, deliberate edits and keep filenames stable.
- `docs/`: Reference plans (e.g., `PLAN_3.0_MITM.md`) for integration context.
- Deobfuscation utilities (`deobfuscate*.js`, `*_decoded_map.json`, `deobfuscated*/`): Node scripts and generated maps used to unpack/inspect extension bundles; regenerate outputs in place to keep downstream scripts aligned.

## Build, Test, and Development Commands
- Backend setup/run:
  ```bash
  cd backend
  python3 -m venv venv && source venv/bin/activate
  pip install -r requirements.txt
  RELOAD=true PORT=8000 python run.py      # dev server with hot reload
  ./start.sh && tail -f cursorpro.log      # managed start (PID + log)
  ./stop.sh                                # graceful stop
  ```
- Extension smoke: install a packaged build for manual checks (`code --install-extension extension/cursorpro-0.4.5.vsix`), then verify the panel/status bar.

## Coding Style & Naming Conventions
- Python: follow PEP 8 with 4-space indents; snake_case for functions/variables, PascalCase for SQLAlchemy models and Pydantic schemas, and typed responses on FastAPI routes. Keep configuration centralized in `app/config.py` and reuse `settings` instead of new globals.
- JavaScript: extension code is CommonJS and minified; keep changes minimal and well-commented, preserving existing exports. JSON/asset filenames use lower_snake_case; avoid renaming unless necessary.

## Testing Guidelines
- No automated suite yet; at minimum hit the backend health check and auth flows: `curl http://127.0.0.1:8000/health` and exercise `/docs` to validate tokens and admin endpoints. Add pytest + httpx API tests when modifying routers/services, using an isolated SQLite file.
- For extension edits, perform VS Code smoke tests (activation on startup, webview render, status bar updates, account switch) and review the “CursorPro” output channel for errors.

## Commit & Pull Request Guidelines
- Commits: concise, imperative subject lines (e.g., “Add admin batch upload validation”) with scoped changes. Call out config or database migrations explicitly.
- PRs: include purpose, key changes, test evidence (commands run, screenshots for UI tweaks), and any new env vars or secrets required for deployment.

## Security & Configuration Tips
- Do not commit real tokens, API keys, or database snapshots; scrub `app/config.py`, `token.json`, and `cursorpro.db` before sharing. Prefer `.env`/environment overrides for secrets alongside `HOST`/`PORT`/`RELOAD`.
- Backend listens on `0.0.0.0` by default; bind to localhost during development. Protect external admin APIs that use the `X-API-Token` header and rotate credentials if exposed.
