chore: drop agent/plan docs, unify .env for Docker stack

- Remove PLAN/agent instruction files; single root .env.example for DB + API
- Stack compose uses env_file .env; delete stack env example duplicate
- Refresh README, backend docs, API doc; trim gitignore/dockerignore

Made-with: Cursor

README.md

@@ -1,56 +1,47 @@
 # Calendar Run
 
-Calendar Run is a races calendar project: a **backend API** (Express + PostgreSQL) and a **React SPA** for viewing and analyzing your race schedule.
+Монорепозиторий: **backend** (Express + PostgreSQL) и **frontend** (React + Vite) — календарь забегов.
 
-Product scope and data model: [PLAN.md](PLAN.md).
+## Переменные окружения
 
-## Backend — quick start
+Один шаблон для локальной разработки и для Docker-стека: **[`.env.example`](.env.example)** → скопируйте в **`.env`** в корне репозитория.
 
-1. Install dependencies:
-   - `cd backend`
-   - `npm install`
-2. Configure environment variables. Copy the root template and edit:
+Там же перечислены **`DB_HOST`**, **`DB_PORT`**, **`DB_NAME`**, **`DB_USER`**, **`DB_PASSWORD`** (подключение бэкенда к БД), **`PORT`** / **`API_PORT`**, опционально **`CALENDAR_RUN_MOCK_DB`**, **`CORS_ORIGIN`**, а для локального Vite — **`VITE_API_BASE_URL`**.
 
-   ```bash
-   cp .env.example .env
-   ```
+## Backend — локально
 
-   Use the **repository root** `.env` (the backend loads it via `backend/src/config.ts`).
+1. `cd backend && npm install`
+2. Корень: `cp .env.example .env`, задайте `DB_*` (и при необходимости `CORS_ORIGIN`).
+3. Postgres: из корня `docker compose up -d` (см. [`docker-compose.yml`](docker-compose.yml)) — в compose используются те же `DB_NAME`, `DB_USER`, `DB_PASSWORD` из `.env`.
+4. `cd backend && npm run db:migrate && npm run seed`
+5. `npm run build && npm run dev`
 
-   - `DB_HOST`, `DB_PORT`, `DB_NAME`, `DB_USER`, `DB_PASSWORD` — required unless mock mode is on.
-   - API port: `PORT` (takes precedence) or `API_PORT` (default `3001`).
-   - **No PostgreSQL (CI / local smoke):** set `CALENDAR_RUN_MOCK_DB=1` (or `true`). Real `DB_*` values are not required; the API uses in-memory stubs for SQL used by the HTTP routes. **Do not** use mock mode for `npm run db:migrate` or `npm run seed`.
-3. With a real database: from repo root, `docker-compose up -d`, then `cd backend && npm run db:migrate && npm run seed`.
-4. Build and run API:
+Без PostgreSQL (только smoke API): в `.env` задайте `CALENDAR_RUN_MOCK_DB=1`; **`db:migrate` и `seed` с mock не использовать**.
 
-   ```bash
-   npm run build
-   npm run dev
-   ```
+## Frontend — локально
 
-## Frontend — quick start
+```bash
+cd frontend
+cp .env.example .env
+npm install
+npm run dev
+```
 
-1. Configure the API URL for Vite (file is read from `frontend/`):
+Значение `VITE_API_BASE_URL` см. в **корневом** [`.env.example`](.env.example); для dev по умолчанию `http://localhost:3001`. У бэкенда `CORS_ORIGIN` должен совпадать с origin приложения (например `http://localhost:5173`).
 
-   ```bash
-   cd frontend
-   cp .env.example .env
-   ```
+## Docker: backend + frontend рядом с Postgres
 
-   Edit `VITE_API_BASE_URL` if the API is not on `http://localhost:3001`.
+Используйте [`docker-compose.stack.yml`](docker-compose.stack.yml): общая **внешняя** сеть с контейнером Postgres (как в вашей инфраструктуре). В корне должен быть **`.env`** (из `.env.example`): `DB_HOST` — имя сервиса/контейнера Postgres в этой сети, `DB_PORT=5432`, плюс остальные `DB_*` и **`CORS_ORIGIN=http://localhost:3033`**, если заходите на фронт с хоста на порту 3033.
 
-2. Install and run:
+```bash
+docker compose -f docker-compose.stack.yml up -d --build
+docker compose -f docker-compose.stack.yml exec backend node dist/migrate.js
+docker compose -f docker-compose.stack.yml exec backend node dist/seed.js
+```
 
-   ```bash
-   npm install
-   npm run dev
-   ```
+Фронт в браузере обращается к API по префиксу **`/api`** (nginx в образе фронта проксирует на backend).
 
-   Default app URL: `http://localhost:5173`. The backend `CORS_ORIGIN` must match this origin (see root `.env.example`).
+## Документация API и бэкенда
 
-## Docs
-
-- [Backend API for Frontend](docs/backend-api-for-frontend.md)
-- [Backend operations](docs/backend.md)
-- [Backend agent instruction](docs/agent-backend-instruction.md)
-- [Backend sync fix instruction](docs/agent-fix-backend-sync-instruction.md)
+- [Шпаргалка API для фронта](docs/backend-api-for-frontend.md)
+- [Эксплуатация backend](docs/backend.md)