Flight Simulator — Workflow Rules

Change process (mandatory)

Small, incremental changes — work is done one change at a time, in smaller parts; each part must be tested thoroughly with unit and e2e tests covering it before moving on. Connected issues/tasks that reference the same part of code MAY be done together on one branch/PR with a single version bump (e.g. two UI tweaks to the same panel).
Feature branch + PR — every change lands on a feature branch off master (no direct pushes to master). The branch carries the commits below; open a pull request to master.
Changelog entry — every such change is listed in CHANGELOG.md with date, time and version (format: ## v<version> — YYYY-MM-DD HH:MM, then bullet points of what changed).
Version bump — the version is updated in package.json.
CI must pass — enforced by branch protection on master (required status check CI / build + unit + e2e (pull request)): the PR cannot be merged until CI is green. Merge via auto-merge (POST /repos/{owner}/{repo}/pulls/{n}/merge with body {"do":"merge","merge_style":"merge","merge_when_checks_succeed":true}) so it merges automatically once CI passes. CI never deploys to production; its e2e runs against an isolated stack inside dind.
Tag + manual deploy after merge — once merged, tag the version on master (e.g. v0.13.0). Production (https://flight.dev.kkhost.pl) is updated manually afterwards: docker compose up -d --build on the host.

CI-only — e2e runs ONLY in CI, against an isolated docker stack inside dind built from docker-compose.ci.yml (project name flight-ci, app container on a static IP; see .gitea/workflows/ci.yml). There are NO local e2e runs at all: locally you verify with tsc --noEmit + npx vitest run + npx playwright test --list (typecheck, unit suite, specs compile and list), and the full e2e suite is verified by CI on every PR. CI never deploys to or modifies production.
CI env vars (playwright.config.ts, all optional) — E2E_BASE_URL (app under test; CI sets it to the in-network app host, so the config's default of the live Traefik instance at https://flight.dev.kkhost.pl is never used), E2E_DEPLOY_CMD (runs as Playwright webServer: deploys the stack and waits for readiness before tests start; CI uses build + up -d + logs -f), PW_REMOTE_BROWSER=0 (CI runs local chromium because the shared remote browser server at 192.168.1.4 cannot reach a stack inside dind — when unset, the config defaults to that remote server and to the live instance as baseURL), and E2E_COMPOSE_ARGS, read by e2e/state.spec.ts for its mid-run docker compose restart flight (CI points it at -f docker-compose.ci.yml -p flight-ci).

Live base URL — https://flight.dev.kkhost.pl (the docker-compose build behind Traefik).
Machine-readable spec — OpenAPI 3.x at https://flight.dev.kkhost.pl/api/openapi; current app version at /api/version.
Spec lives in code — generated from lib/openapi.ts, served by app/api/openapi/route.ts; must be updated whenever an endpoint changes.