feat(server): initial implementation

This commit captures the full server code accumulated across
several development sessions. It includes the following layers,
applied in roughly this order during development:

1. Base infrastructure
   - cmd/poc-server HTTP+WebSocket server, /health, /stats
   - internal/transport wire types (Envelope + all message types)
   - internal/catalog, internal/realtime, internal/stats
   - internal/storage/postgres with migrations 001-004
   - .env, .env.example, docker-compose, Dockerfile, scripts/

2. Swagger documentation
   - go get github.com/swaggo/http-swagger
   - swag init produces docs/docs.go
   - /swagger/index.html UI, /swagger/doc.json spec
   - annotations on health/stats/ws and catalog handlers

3. Races API
   - internal/races/{store,service,keyset,types}.go
   - migration 005_races.sql: finished_races, race_plans, race_queue
   - GET /api/races with keyset pagination, status filter
   - GET /api/races/upcoming
   - POST /api/races/queue/join, GET, DELETE
   - POST/GET /api/races/plans, DELETE /{id}
   - lobby.RaceMeta simplification (no host_id/host_name)

4. Races seeder
   - internal/races/seed with deterministic generator
   - --seed-races / --reset CLI flags in main.go
   - 30 finished + 5 live + 5 plans + 4 queue entries

5. Drivers and clans
   - internal/drivers, internal/clans (CRUD, validation)
   - migration 008_drivers_clans.sql
   - /api/clans and /api/drivers endpoints
   - 3-letter uppercase nickname/tag validation
   - lobby.DriverMeta: Nickname, AvatarURL, ClanID, ClanTag

6. Podium
   - internal/transport.RacePodiumEntry
   - lobby.SetDriverProfile for in-memory metadata sync
   - migration 007_podium.sql (podium JSONB column)
   - seeder populates top-3 per finished race

7. Live races persistence
   - migration 009_live_persistence.sql: live_races,
     live_race_drivers, lobby_drivers
   - internal/races/live_store.go: LiveStore with write-side
     mirror for lobby.Service mutations
   - Service.collectLive and Upcoming read from Postgres
   - main.go RestoreFromDB rehydrates lobby on startup

8. Unify live + finished into one races table
   - migration 010_unify_races.sql: rename finished_races to
     races, expand status CHECK, merge live rows
   - PgStore now hosts both write paths; LiveStore is a
     thin facade implementing lobby.Persistence
   - seeder resetAll drops only finished/cancelled rows and
     race_plans / race_queue / lobby_drivers

Each layer is consistent on its own; cross-layer changes are
visible in the file history. A future refactor may split this
commit into the per-stage boundaries listed above.

server/proto/server_agent.proto

@@ -0,0 +1,96 @@
+syntax = "proto3";
+
+package x0gp.v1;
+
+option go_package = "github.com/x0gp/server/proto/gen/serveragentpb";
+
+// ============================================================
+// Wire protocol between server (Edge / agent-linker) and the
+// on-board agent (ESP32-S3 in PoC).
+// ============================================================
+//
+// The agent runs MicroPython (PoC) or ESP-IDF C (prod). It connects via
+// Wi-Fi to the gateway-агент (in MVP) or directly to this server (in PoC)
+// over WebSocket using the same envelope pattern as client_server.proto.
+
+// --- Server -> Agent ---
+
+message AgentHelloAck {
+  string agent_id = 1;
+  int32  fw_version_major = 2;
+  int32  fw_version_minor = 3;
+  ServerConfig config = 4;
+}
+
+message ServerConfig {
+  int32 tick_rate_hz     = 1;
+  int32 telemetry_rate_hz = 2;
+}
+
+message AgentCommand {
+  string car_id   = 1;
+  float  steering = 2;   // -1.0 .. 1.0
+  float  throttle = 3;   //  0.0 .. 1.0
+  float  brake    = 4;   //  0.0 .. 1.0
+  int32  gear     = 5;
+  uint32 flags    = 6;   // bit0: E-stop, bit1: lights, ...
+  int64  expires_at_ms = 7;  // safety: drop if older than this
+}
+
+message AgentConfig {
+  string car_id = 1;
+  float max_steering_rate = 2;   // per second
+  float max_throttle_rate = 3;
+  RampLimits ramp = 4;
+}
+
+message RampLimits {
+  float throttle_up_per_s   = 1;
+  float throttle_down_per_s = 2;
+  float brake_per_s         = 3;
+}
+
+// --- Agent -> Server ---
+
+message AgentHello {
+  string car_id    = 1;
+  string fw_version = 2;
+  string hw_id      = 3;
+  int32  rssi       = 4;  // dBm
+}
+
+message AgentTelemetry {
+  string car_id         = 1;
+  int64  ts_ms          = 2;
+  float  steering_actual = 3;
+  float  throttle_actual = 4;
+  int32  rpm             = 5;
+  float  voltage_v       = 6;
+  float  current_a       = 7;
+  float  temp_esc_c      = 8;
+  float  temp_motor_c    = 9;
+  Imu    imu             = 10;
+  IrLine ir              = 11;
+  float  battery_pct     = 12;  // 0..100
+}
+
+message Imu {
+  float ax = 1; float ay = 2; float az = 3;
+  float gx = 4; float gy = 5; float gz = 6;
+}
+
+message IrLine {
+  bool front = 1;
+  bool rear  = 2;
+}
+
+message AgentHeartbeat {
+  int64 ts_ms     = 1;
+  int64 uptime_s  = 2;
+  repeated string errors = 3;
+}
+
+message AgentLog {
+  string level = 1;  // "debug" | "info" | "warn" | "error"
+  string msg   = 2;
+}