# Plan: Arma 3 Adapter UX Enhancement

**Status:** APPROVED — Ready to implement
**Branch:** main
**Estimated effort:** ~20h total (5 active phases)

---

## Progress Tracker

> **IMPLEMENTING AGENT:** Update this section at the start and end of each session. Mark each phase `[x]` when ALL its checklist items pass. This is the only reliable way for the next session to know where to pick up.

| Phase | Status | Last session note |
|-------|--------|------------------|
| 1 — Config UI Schema | `[x] done` | TagListEditor, useServerConfigSchema, ConfigEditor widget routing, backend get_ui_schema + endpoint |
| 2 — Mission Rotation | `[x] done` | terrain in list_missions, rotation GET/PUT endpoints, MissionRotationEntry type, useServerMissionRotation/useUpdateMissionRotation hooks, multi-file upload, MissionList redesigned with Available + Rotation sections |
| 3 — Mod Display Names + Split Pane | `[x] done` | _parse_mod_cpp/_parse_meta_cpp in mod_manager, ModList split-pane redesign |
| 4 — Player Kick/Ban | `[x] done` | get_by_slot in PlayerRepository, get_rcon_client in ThreadRegistry, kick/ban endpoints, PlayerTable modals |
| 5 — Log File Browser | `[x] done` | list_log_files/get_log_file_path in RPTParser, logfiles_router (GET/download/DELETE), LogViewer file browser section |

**How to resume:** Read this table first. Find the first phase that is not `[x] done`. Read only that phase section — do not re-read earlier phases. Run `cd frontend && npx tsc --noEmit` to confirm the build is clean before making any changes.

---

## Background & Context

### What was analyzed

`arma-server-web-admin` (Node.js/Express + Backbone.js) was deep-analyzed as a UX benchmark. Reference documentation is in `docs/` (this repo):
- `docs/ANALYSIS.md` — feature inventory, tech stack, directory structure
- `docs/HOW_IT_WORKS.md` — internal flows (server start/stop, mission upload, mod discovery, Socket.IO bridge)
- `docs/CHERRY_PICK.md` — adapter candidates with file paths and adapter strategies

**You do NOT need to read the original arma-server-web-admin source.** All relevant patterns are documented in `docs/` and self-contained below.

### Problem statement

languard-servers-manager has a **complete backend** (42+ endpoints, Arma3ConfigGenerator, Arma3MissionManager, Arma3ModManager, Arma3BanManager, Arma3RemoteAdmin) but the **frontend has gaps** that make daily Arma 3 server administration painful:

| Problem | Root cause |
|---------|-----------|
| All config fields render as text boxes | ConfigEditor is generic; no per-field widget hints |
| Can't build a mission rotation | Backend config supports `missions[]` array; no UI |
| Mods show `@CBA_A3` not "Community Base Addons" | `mod.cpp` not parsed; no `display_name` field |
| Can't kick a player from the UI | `Arma3RemoteAdmin.kick_player()` exists; endpoint missing |
| Can't browse/download historical log files | Only real-time WebSocket stream; no file browser |
| Must navigate to detail page to start/stop | No quick-action buttons on ServerCard |

---

## Cross-Reference: Cherry-Pick Classification

### MUST HAVE

| Feature | Gap in languard |
|---------|----------------|
| Config field UI widgets (textarea/dropdown/toggle/tag-list) | Generic `<input>` for everything |
| Kick player from Players tab | `Arma3RemoteAdmin.kick_player(slot_id, reason)` exists but no HTTP endpoint |
| Mission rotation table + per-mission difficulty | Backend: `Arma3MissionManager.get_rotation_config()` exists. Frontend: nothing |
| Multi-file mission upload | `useUploadMission` accepts single `File` only |

### GOOD TO HAVE

| Feature | Gap |
|---------|-----|
| Mod display names (mod.cpp parsing) | `list_available_mods()` returns path only, no `display_name` |
| Split-pane mod assignment UI | Flat checkbox list |
| Server card start/stop quick actions | Must navigate to ServerDetailPage |
| Log file browser + download | WebSocket stream only |
| Admin UIDs tag list in config | Hidden in raw JSON config editor |
| Ban from player list quick action | User must go to Bans tab manually |

### OPTIONAL

| Feature | Note |
|---------|------|
| Steam Workshop mission download | Requires external `steamcmd` binary |
| Mod Steam Workshop ID (meta.cpp) | Informational only |
| Log viewer level filter | Pure client-side |
| Headless client count in UI | Niche advanced feature |

---

## Current Codebase — Critical File Inventory

### Backend (FastAPI + Python)

```
backend/
├── adapters/arma3/
│   ├── adapter.py            # Arma3Adapter — registers capabilities, returns sub-managers
│   ├── config_generator.py   # Arma3ConfigGenerator
│   │                           SECTIONS: ServerSection, BasicSection, ProfileSection,
│   │                           LaunchSection, RconSection
│   │                           KEY FIELDS IN ServerSection:
│   │                             hostname (str), max_players (int), password (str),
│   │                             admin_password (str), motd_lines (list[str]),
│   │                             forced_difficulty (str), battle_eye (bool), von (bool),
│   │                             admin_uids (list[str])
│   │                           KEY FIELDS IN LaunchSection:
│   │                             additional_args (list[str])
│   │                           METHODS: get_sections(), write_configs(), build_launch_args(),
│   │                           get_sensitive_fields(), get_defaults()
│   │                           ADD: get_ui_schema() -> dict
│   ├── mission_manager.py    # Arma3MissionManager
│   │                           list_missions() -> [{name, filename, size_bytes}]
│   │                           parse_mission_filename(fn) -> {mission_name, terrain, filename}
│   │                           get_rotation_config(entries) -> Arma3 missions config block string
│   │                           UPDATE: list_missions() add terrain field
│   ├── mod_manager.py        # Arma3ModManager
│   │                           list_available_mods() -> [{name, path, size_bytes, enabled}]
│   │                           get_enabled_mods(), set_enabled_mods(), build_mod_args()
│   │                           UPDATE: add display_name, workshop_id to list_available_mods()
│   ├── log_parser.py         # RPTParser
│   │                           parse_line(), get_log_file_resolver()
│   │                           ADD: list_log_files(server_dir), get_log_file_path(server_dir, filename)
│   ├── remote_admin.py       # Arma3RemoteAdmin (DO NOT MODIFY — stable)
│   │                           kick_player(slot_id, reason) -> bool  ← USE THIS
│   │                           ban_player(uid, duration_minutes, reason) -> bool
│   │                           get_players() -> list[dict]
│   └── ban_manager.py        # Arma3BanManager — bans.txt sync (stable)
│
├── core/servers/
│   ├── router.py             # Main server endpoints
│   │                           ADD: GET /api/servers/{id}/config/schema
│   ├── service.py            # ServerService
│   │                           ADD: get_config_schema(), kick_player(), ban_from_player()
│   ├── missions_router.py    # GET/POST/DELETE /api/servers/{id}/missions/*
│   │                           ADD: GET /api/servers/{id}/missions/rotation
│   │                           ADD: PUT /api/servers/{id}/missions/rotation
│   ├── players_router.py     # GET /api/servers/{id}/players
│   │                           ADD: POST /api/servers/{id}/players/{slot_id}/kick
│   │                           ADD: POST /api/servers/{id}/players/{slot_id}/ban
│   └── [NEW] logfiles_router.py
│         GET  /api/servers/{id}/logfiles
│         GET  /api/servers/{id}/logfiles/{filename}/download
│         DELETE /api/servers/{id}/logfiles/{filename}
│
└── main.py                   # ADD: include_router(logfiles_router)
```

### Frontend (React 19 + TypeScript + TanStack Query)

```
frontend/src/
├── hooks/
│   └── useServerDetail.ts    # All query/mutation hooks for server detail
│                               ADD: useServerConfigSchema()
│                               ADD: useServerMissionRotation(), useUpdateMissionRotation()
│                               ADD: useKickPlayer(), useBanPlayer()
│                               ADD: useServerLogFiles(), useDeleteLogFile()
│                               UPDATE: useUploadMission(File[]) — was single File
│                               UPDATE: Mod type — add display_name, workshop_id
│                               UPDATE: Mission type — add terrain field
│
├── components/servers/
│   ├── ConfigEditor.tsx      # UPDATE: consume schema, render per-widget type
│   ├── MissionList.tsx       # REDESIGN: Available section + Rotation section
│   ├── ModList.tsx           # REDESIGN: split pane (Available vs Selected)
│   ├── PlayerTable.tsx       # UPDATE: add Actions column (Kick/Ban buttons, admin only)
│   ├── LogViewer.tsx         # UPDATE: level filter + Log Files browser section
│   └── ServerCard.tsx        # UPDATE: Start/Stop quick-action buttons
│
└── components/ui/
    └── [NEW] TagListEditor.tsx   # Dynamic string-list editor (reused in ConfigEditor)
```

---

## Execution Order

| Phase | Description | Priority | Est. |
|-------|-------------|----------|------|
| 1 | Config UI Schema (widget hints per field) | MUST | ~4h |
| 4 | Player Kick/Ban | MUST | ~3h |
| 2 | Mission Rotation + Multi-file upload | MUST | ~5h |
| 3 | Mod Display Names + Split Pane | GOOD | ~4h |
| 5 | Log File Browser + Level Filter | GOOD | ~3h |
| 6 | Server Card Quick Actions | ~~GOOD~~ | **DONE** |

---

## Phase 1 — Config UI Schema System (MUST HAVE, ~4h)

**Goal:** Each Arma 3 config field renders with the right UI widget instead of a generic text box.

### 1.1 `backend/adapters/arma3/config_generator.py` — add `get_ui_schema()`

Add this method to `Arma3ConfigGenerator`:

```python
def get_ui_schema(self) -> dict:
    return {
        "server": {
            # Field names MUST match Arma3ConfigGenerator.ServerConfig exactly
            "hostname":             {"widget": "text",     "label": "Server Hostname"},
            "max_players":          {"widget": "number",   "label": "Max Players", "min": 1, "max": 1000},
            "password":             {"widget": "password", "label": "Player Password"},
            "password_admin":       {"widget": "password", "label": "Admin Password"},  # NOT admin_password
            "motd_lines":           {"widget": "textarea", "label": "Message of the Day (one line per row)"},
            "forced_difficulty":    {"widget": "select",   "label": "Difficulty Preset",
                                     "options": ["Recruit", "Regular", "Veteran", "Custom"]},
            "battleye":             {"widget": "toggle",   "label": "BattleEye Anti-Cheat"},  # NOT battle_eye
            "disable_von":          {"widget": "toggle",   "label": "Disable Voice over Net (VoN)"},  # NOT von — and it's inverted
            "verify_signatures":    {"widget": "number",   "label": "Verify Signatures (0=off, 1=on, 2=strict)", "min": 0, "max": 2},
            "persistent":           {"widget": "toggle",   "label": "Persistent (keep running when empty)"},
            "admin_uids":           {"widget": "tag-list", "label": "Admin Steam UIDs",
                                     "placeholder": "76561198000000000"},
        },
        "basic": {
            "max_packet_size":      {"widget": "number", "label": "Max Packet Size"},
            "max_custom_file_size": {"widget": "number", "label": "Max Custom File Size (bytes)"},
        },
        "launch": {
            "additional_args":      {"widget": "tag-list", "label": "Additional Startup Parameters",
                                     "placeholder": "-limitFPS=100"},
        },
        "rcon": {
            "password":             {"widget": "password", "label": "RCon Password"},
            "port":                 {"widget": "number",   "label": "RCon Port"},
        },
    }
```

### 1.2 `backend/core/servers/service.py` — add `get_config_schema()`

Follow the existing pattern: `ServerService.__init__` already stores `self._server_repo` and `self._config_repo`. No `db` param needed:
```python
def get_config_schema(self, server_id: int) -> dict:
    server = self.get_server(server_id)  # raises 404 if not found, uses self._server_repo
    adapter = GameAdapterRegistry.get(server["game_type"])
    config_gen = adapter.get_config_generator()
    if hasattr(config_gen, "get_ui_schema"):
        return config_gen.get_ui_schema()
    return {}
```

### 1.3 `backend/core/servers/router.py` — new endpoint

Add after existing config routes, following the `ServerService(db)` inline pattern:
```python
@router.get("/{server_id}/config/schema")
def get_config_schema(
    server_id: int,
    db: Annotated[Connection, Depends(get_db)],
    _user: Annotated[dict, Depends(get_current_user)],
) -> dict:
    schema = ServerService(db).get_config_schema(server_id)
    return {"success": True, "data": schema, "error": None}
```

### 1.4 `frontend/src/hooks/useServerDetail.ts` — add schema types + hook

```typescript
export interface FieldSchema {
  widget: "text" | "number" | "password" | "textarea" | "select" | "toggle" | "tag-list";
  label?: string;
  placeholder?: string;
  min?: number;
  max?: number;
  options?: string[];
}

export interface ConfigSchema {
  [section: string]: { [field: string]: FieldSchema };
}

export function useServerConfigSchema(serverId: number) {
  return useQuery({
    queryKey: ["servers", serverId, "config", "schema"],
    queryFn: async () => {
      const res = await apiClient.get<{ success: boolean; data: ConfigSchema }>(
        `/api/servers/${serverId}/config/schema`,
      );
      return res.data.data;
    },
    enabled: serverId > 0,
  });
}
```

### 1.5 `frontend/src/components/ui/TagListEditor.tsx` — NEW component

```typescript
interface TagListEditorProps {
  value: string[];
  onChange: (v: string[]) => void;
  placeholder?: string;
  disabled?: boolean;
}

export function TagListEditor({ value, onChange, placeholder, disabled }: TagListEditorProps) {
  const update = (idx: number, val: string) =>
    onChange(value.map((v, i) => (i === idx ? val : v)));
  const remove = (idx: number) => onChange(value.filter((_, i) => i !== idx));
  const add = () => onChange([...value, ""]);

  return (
    <div className="space-y-1">
      {value.map((item, idx) => (
        <div key={idx} className="flex gap-2">
          <input
            className="flex-1 neu-input"
            value={item}
            placeholder={placeholder}
            disabled={disabled}
            onChange={(e) => update(idx, e.target.value)}
          />
          <button
            type="button"
            onClick={() => remove(idx)}
            disabled={disabled}
            className="btn-ghost text-status-crashed px-2"
          >
            ✕
          </button>
        </div>
      ))}
      <button type="button" onClick={add} disabled={disabled} className="btn-ghost text-sm">
        + Add
      </button>
    </div>
  );
}
```

### 1.6 `frontend/src/components/servers/ConfigEditor.tsx` — consume schema

- Import `useServerConfigSchema` and `TagListEditor`
- Call `useServerConfigSchema(serverId)` alongside existing config queries
- For each field in a config section, look up `schema?.[sectionName]?.[fieldName]`
- Render based on `widget`:
  - `"text"` → `<input type="text" />`
  - `"number"` → `<input type="number" min={} max={} />`
  - `"password"` → `<input type="password" />`
  - `"textarea"` → `<textarea rows={4} />`
  - `"select"` → `<select>` with `schema.options.map(o => <option>)`
  - `"toggle"` → `<input type="checkbox" />` (styled toggle)
  - `"tag-list"` → `<TagListEditor value={} onChange={} placeholder={} />`
  - fallback → `<input type="text" />`
- Use `schema.label` as the field label; fall back to field name (capitalized) if absent

---

## Phase 2 — Mission Rotation Management (MUST HAVE, ~5h)

**Goal:** Users build/reorder a mission rotation with per-mission difficulty. Multi-file upload.

### 2.1 `backend/adapters/arma3/mission_manager.py` — add `terrain` to `list_missions()`

`parse_mission_filename()` already extracts `terrain`. Ensure `list_missions()` includes it:
```python
# Current return per mission:
{"name": mission_name, "filename": filename, "size_bytes": size}
# Updated return:
{"name": mission_name, "filename": filename, "size_bytes": size, "terrain": terrain}
```

### 2.2 `backend/core/servers/missions_router.py` — add rotation endpoints

Add Pydantic schemas at top of file:
```python
class MissionRotationEntry(BaseModel):
    name: str
    difficulty: str = ""

class MissionRotationUpdate(BaseModel):
    missions: list[MissionRotationEntry]
    config_version: int
```

Add endpoints — follow the `ServerService(db)` inline pattern used by all existing routers:
```python
from typing import Annotated
from sqlalchemy.engine import Connection
from core.servers.service import ServerService

@router.get("/rotation")  # prefix already includes /{server_id}/missions
def get_mission_rotation(
    server_id: int,
    db: Annotated[Connection, Depends(get_db)],
    _user: Annotated[dict, Depends(get_current_user)],
) -> dict:
    # "server" section is always seeded on create — never None for existing server
    config = ServerService(db).get_config_section(server_id, "server")
    missions = config.get("missions", [])
    return {"success": True, "data": {"missions": missions}, "error": None}

@router.put("/rotation")
def update_mission_rotation(
    server_id: int,
    body: MissionRotationUpdate,
    db: Annotated[Connection, Depends(get_db)],
    _admin: Annotated[dict, Depends(require_admin)],
) -> dict:
    # ServerService.update_config_section() handles load-merge-upsert + 409 on conflict
    updated = ServerService(db).update_config_section(
        server_id=server_id,
        section="server",
        data={"missions": [e.model_dump() for e in body.missions]},
        expected_version=body.config_version,
    )
    return {"success": True, "data": {"missions": updated.get("missions", [])}, "error": None}
```

### 2.3 `frontend/src/hooks/useServerDetail.ts` — rotation hooks + updated types

Update `Mission` type:
```typescript
export interface Mission {
  name: string;
  filename: string;
  size_bytes: number;
  terrain: string;   // new
}
```

Add rotation types and hooks:
```typescript
export interface MissionRotationEntry {
  name: string;
  difficulty: string;
}

export function useServerMissionRotation(serverId: number) {
  return useQuery({
    queryKey: ["missions", serverId, "rotation"],
    queryFn: async () => {
      const res = await apiClient.get<{
        success: boolean; data: { missions: MissionRotationEntry[] }
      }>(`/api/servers/${serverId}/missions/rotation`);
      return res.data.data.missions;
    },
    enabled: serverId > 0,
  });
}

export function useUpdateMissionRotation(serverId: number) {
  const queryClient = useQueryClient();
  return useMutation({
    mutationFn: (data: { missions: MissionRotationEntry[]; config_version: number }) =>
      apiClient.put(`/api/servers/${serverId}/missions/rotation`, data),
    onSuccess: () => {
      queryClient.invalidateQueries({ queryKey: ["missions", serverId, "rotation"] });
      // Invalidate server config section too — missions are stored inside it
      queryClient.invalidateQueries({ queryKey: ["servers", serverId, "config", "server"] });
    },
  });
}
```

Update `useUploadMission` to accept `File[]`:
```typescript
export function useUploadMission(serverId: number) {
  const queryClient = useQueryClient();
  return useMutation({
    mutationFn: async (files: File[]) => {
      for (const file of files) {
        const formData = new FormData();
        formData.append("file", file);
        await apiClient.post(`/api/servers/${serverId}/missions`, formData, {
          headers: { "Content-Type": "multipart/form-data" },
        });
      }
    },
    onSuccess: () =>
      queryClient.invalidateQueries({ queryKey: ["missions", serverId] }),
  });
}
```

### 2.4 `frontend/src/components/servers/MissionList.tsx` — redesign

Difficulty constant (define once, reuse here and in Phase 1 schema):
```typescript
const DIFFICULTY_OPTIONS = ["", "Recruit", "Regular", "Veteran", "Custom"];
```

Component layout — two sections:

**Section A: Available Missions**
- Table: Mission Name | Terrain badge | Size | Actions
- Actions per row: "Add to Rotation" button + Delete button
- Upload zone: `<input type="file" multiple accept=".pbo" />` → calls `useUploadMission(files)`
- Show per-file upload progress (filename + spinner/✓)

**Section B: Mission Rotation**
- Table: # | Mission Name | Terrain | Difficulty | Remove
- Row: index, name, terrain badge, `<select>` with `DIFFICULTY_OPTIONS`, remove button
- "Save Rotation" → `useUpdateMissionRotation({ missions: rotation, config_version })`
- "Clear Rotation" button → sets rotation to `[]`

State:
- `rotation: MissionRotationEntry[]` — local state, synced from query on load
- `uploadProgress: { filename: string; done: boolean }[]` — per-file status (sequential uploads)

**config_version source:** Call `useServerConfigSection(serverId, "server")` inside `MissionList`. Read `sectionData._meta.config_version` and pass it as `config_version` when calling `useUpdateMissionRotation`. This hook already exists in `useServerDetail.ts`.

---

## Phase 3 — Mod Display Names + Split Pane (GOOD TO HAVE, ~4h)

**Goal:** Parse `mod.cpp` for human-readable names. Redesign mod UI as split pane.

### 3.1 `backend/adapters/arma3/mod_manager.py` — add display_name + workshop_id

Add as **module-level functions** (not class methods — pure `Path → str | None`, no state needed, easier to test):
```python
import re

def _parse_mod_cpp(mod_dir: Path) -> str | None:
    mod_cpp = mod_dir / "mod.cpp"
    if not mod_cpp.exists():
        return None
    text = mod_cpp.read_text(errors="ignore")
    m = re.search(r'name\s*=\s*"([^"]+)"', text, re.IGNORECASE)
    return m.group(1) if m else None

def _parse_meta_cpp(mod_dir: Path) -> str | None:
    meta_cpp = mod_dir / "meta.cpp"
    if not meta_cpp.exists():
        return None
    text = meta_cpp.read_text(errors="ignore")
    m = re.search(r'publishedid\s*=\s*(\d+)', text, re.IGNORECASE)
    return m.group(1) if m else None
```

Update each mod dict in `list_available_mods()`:
```python
{
    "name": str(rel_path),
    "path": str(mod_dir),
    "size_bytes": size,
    "enabled": name in enabled_set,
    "display_name": _parse_mod_cpp(mod_dir),   # new — None if no mod.cpp
    "workshop_id":  _parse_meta_cpp(mod_dir),  # new — None if no meta.cpp
}
```

### 3.2 `frontend/src/hooks/useServerDetail.ts` — update Mod type

```typescript
export interface Mod {
  name: string;
  path: string;
  size_bytes: number;
  enabled: boolean;
  display_name: string | null;   // new
  workshop_id: string | null;    // new
}
```

### 3.3 `frontend/src/components/servers/ModList.tsx` — split pane redesign

CSS grid 2-column (50% each). Each pane:
- Header: "Available (N)" / "Selected (N)"
- Search `<input>` for client-side filter
- Scrollable list of mod rows

Each mod row:
- Primary text: `display_name ?? name`
- Secondary text (small, muted): `name` (folder path)
- Optional badge: "Workshop" if `workshop_id !== null`
- File size (e.g., "1.2 GB")
- Click → moves to other pane (immutable state update)

State:
- `available: Mod[]` — mods with `enabled === false`
- `selected: Mod[]` — mods with `enabled === true`
- Initialized from query; mutations update local state only until "Apply"

Bottom of component:
- "Apply Selection" button → `useSetEnabledMods(selected.map(m => m.name))`
- Shows confirmation: "N mods selected. Server restart required for changes to take effect."

---

## Phase 4 — Player Kick + Ban (MUST HAVE, ~3h)

**Goal:** Admin can kick or ban from the Players tab via RCon without using raw RCon console.

### 4.1 `backend/core/servers/players_router.py` — new action endpoints

Add imports at top of file:
```python
from pydantic import BaseModel
from dependencies import require_admin
```

Add Pydantic schemas:
```python
class KickRequest(BaseModel):
    reason: str = "Kicked by admin"

class BanFromPlayerRequest(BaseModel):
    reason: str = "Banned by admin"
    duration_minutes: int | None = None  # None = permanent
```

Add endpoints — follow existing `ServerService(db)` inline pattern:
```python
@router.post("/{slot_id}/kick")  # prefix already is /servers/{server_id}/players
def kick_player(
    server_id: int, slot_id: int,
    body: KickRequest,
    db: Annotated[Connection, Depends(get_db)],
    _admin: Annotated[dict, Depends(require_admin)],
) -> dict:
    ServerService(db).kick_player(server_id, slot_id, body.reason)
    return {"success": True, "data": {"message": f"Player {slot_id} kicked"}, "error": None}

@router.post("/{slot_id}/ban")
def ban_player_from_list(
    server_id: int, slot_id: int,
    body: BanFromPlayerRequest,
    db: Annotated[Connection, Depends(get_db)],
    admin: Annotated[dict, Depends(require_admin)],
) -> dict:
    ban = ServerService(db).ban_from_player(
        server_id, slot_id, body.reason, body.duration_minutes,
        banned_by=admin["username"],
    )
    return {"success": True, "data": ban, "error": None}
```

### 4.2 `backend/core/dal/player_repository.py` — add `get_by_slot()`

`get_by_slot()` does not exist yet. Add it. Note: slot_id is stored as a string in the DB (see `upsert()` which calls `str(player.get("slot_id", ""))`):
```python
def get_by_slot(self, server_id: int, slot_id: int) -> dict | None:
    return self._fetchone(
        "SELECT * FROM players WHERE server_id = :sid AND slot_id = :slot",
        {"sid": server_id, "slot": str(slot_id)},  # cast to str — stored as string in DB
    )
```

### 4.2 `backend/core/threads/thread_registry.py` — add `get_rcon_client()`

`ThreadRegistry.get_remote_admin()` does not exist. Add this class method. The RCon client lives on `bundle["rcon_poller"]._client` (verified from `RemoteAdminPollerThread.__init__`):
```python
@classmethod
def get_rcon_client(cls, server_id: int):
    """Return the live Arma3RemoteAdmin client for a running server, or None."""
    registry = cls._get_instance()
    if registry is None:
        return None
    bundle = registry._bundles.get(server_id)
    if bundle is None:
        return None
    poller = bundle.get("rcon_poller")
    if poller is None or not poller.is_alive():
        return None
    return getattr(poller, "_client", None)
```

### 4.2 `backend/core/servers/service.py` — new service methods

```python
def kick_player(self, server_id: int, slot_id: int, reason: str) -> None:
    from core.threads.thread_registry import ThreadRegistry
    ra = ThreadRegistry.get_rcon_client(server_id)  # use get_rcon_client, NOT get_remote_admin
    if not ra or not ra.is_connected():
        raise HTTPException(status.HTTP_400_BAD_REQUEST,
            detail={"code": "RCON_NOT_CONNECTED", "message": "RCon not connected — server must be running"})
    success = ra.kick_player(int(slot_id), reason)  # kick_player takes int, slot stored as str
    if not success:
        raise HTTPException(status.HTTP_500_INTERNAL_SERVER_ERROR,
            detail={"code": "KICK_FAILED", "message": "Kick command failed"})

def ban_from_player(
    self, server_id: int, slot_id: int,
    reason: str, duration_minutes: int | None,
    banned_by: str,   # pass admin["username"] from router — service never accepts User objects
) -> dict:
    from datetime import datetime, timezone, timedelta
    from core.dal.player_repository import PlayerRepository
    from core.dal.ban_repository import BanRepository
    player = PlayerRepository(self._db).get_by_slot(server_id, int(slot_id))
    if not player:
        raise HTTPException(status.HTTP_404_NOT_FOUND,
            detail={"code": "NOT_FOUND", "message": "Player not found"})
    # Convert duration_minutes → expires_at ISO string (None = permanent)
    expires_at = None
    if duration_minutes is not None and duration_minutes > 0:
        expires_at = (datetime.now(timezone.utc) + timedelta(minutes=duration_minutes)).isoformat()
    from core.threads.thread_registry import ThreadRegistry
    ra = ThreadRegistry.get_rcon_client(server_id)
    if ra and ra.is_connected():
        ra.ban_player(player["guid"], duration_minutes or 0, reason)
    ban_repo = BanRepository(self._db)
    ban_id = ban_repo.create(
        server_id=server_id, guid=player["guid"], name=player["name"],
        reason=reason, banned_by=banned_by,
        expires_at=expires_at,   # BanRepository.create() takes expires_at, NOT duration_minutes
    )
    return dict(ban_repo.get_by_id(ban_id))  # create() returns int id, get_by_id() returns dict
```

### 4.3 `frontend/src/hooks/useServerDetail.ts` — kick/ban mutations

```typescript
export function useKickPlayer(serverId: number) {
  const queryClient = useQueryClient();
  return useMutation({
    mutationFn: ({ slotId, reason }: { slotId: number; reason: string }) =>
      apiClient.post(`/api/servers/${serverId}/players/${slotId}/kick`, { reason }),
    onSuccess: () => queryClient.invalidateQueries({ queryKey: ["players", serverId] }),
  });
}

export function useBanPlayer(serverId: number) {
  const queryClient = useQueryClient();
  return useMutation({
    mutationFn: ({
      slotId, reason, durationMinutes,
    }: { slotId: number; reason: string; durationMinutes?: number }) =>
      apiClient.post(`/api/servers/${serverId}/players/${slotId}/ban`, {
        reason,
        duration_minutes: durationMinutes ?? null,
      }),
    onSuccess: () => {
      queryClient.invalidateQueries({ queryKey: ["players", serverId] });
      queryClient.invalidateQueries({ queryKey: ["bans", serverId] });
    },
  });
}
```

### 4.4 `frontend/src/components/servers/PlayerTable.tsx` — add Actions column

- Import `useKickPlayer`, `useBanPlayer`, `useAuthStore`
- Check `isAdmin = useAuthStore(s => s.user?.role === "admin")`
- Add "Actions" column at far right, visible only when `isAdmin`
- **Kick flow:** "Kick" button → inline reason input on that row → "Confirm" → `kickPlayer({ slotId: player.slot_id, reason })`
- **Ban flow:** "Ban" button → small modal/dialog with reason textarea + optional duration (minutes) → "Confirm Ban" → `banPlayer({ slotId, reason, durationMinutes })`
- Disable both buttons when `server.status !== "running"` with tooltip "Server must be running"

---

## Phase 5 — Log File Browser (GOOD TO HAVE, ~3h)

**Goal:** Browse, download, and delete historical `.rpt` log files. Filter live log by level.

### 5.1 `backend/adapters/arma3/log_parser.py` — add file listing

> **Log path:** Arma 3 writes `.rpt` files to `C:\Users\<username>\AppData\Local\Arma 3` by default on Windows. The log directory should be configurable. Use a `log_dir` setting from server config (fall back to `server_dir / "logs"` if not set). The implementation below uses `server_dir / "logs"` as the convention for this app; the `ARMA3_LOG_DIR` env var or a config field can override it per-server.

```python
def list_log_files(self, server_dir: Path) -> list[dict]:
    import os
    log_dir = Path(os.environ.get("ARMA3_LOG_DIR", str(server_dir / "logs")))
    if not log_dir.exists():
        return []
    files = sorted(log_dir.glob("*.rpt"), key=lambda f: f.stat().st_mtime, reverse=True)
    return [
        {
            "filename": f.name,
            "size_bytes": f.stat().st_size,
            "modified_at": f.stat().st_mtime,  # Unix timestamp float
        }
        for f in files
    ]

def get_log_file_path(self, server_dir: Path, filename: str) -> Path:
    """Returns absolute path with path-traversal protection."""
    log_dir = (server_dir / "server").resolve()
    path = (log_dir / filename).resolve()
    if not str(path).startswith(str(log_dir)):
        raise ValueError("Path traversal detected")
    if not path.exists():
        raise FileNotFoundError(filename)
    return path
```

### 5.2 `backend/core/servers/logfiles_router.py` — NEW file

> **Note:** `adapter.get_log_parser()` already exists on `Arma3Adapter` (returns `RPTParser()`). No adapter changes needed — just call `adapter.get_log_parser()` directly.

```python
from fastapi import APIRouter, Depends, HTTPException
from fastapi.responses import FileResponse
from pathlib import Path

router = APIRouter(prefix="/api/servers", tags=["logfiles"])

@router.get("/{server_id}/logfiles")
async def list_log_files(
    server_id: int, db=Depends(get_db), user=Depends(get_current_user)
):
    server = server_repo.get_by_id(server_id, db)
    adapter = adapter_registry.get(server.game_type)
    log_parser = adapter.get_log_parser()
    server_dir = Path(settings.SERVERS_DIR) / str(server_id)
    return {"success": True, "data": log_parser.list_log_files(server_dir)}

@router.get("/{server_id}/logfiles/{filename}/download")
async def download_log_file(
    server_id: int, filename: str, db=Depends(get_db), user=Depends(get_current_user)
):
    server = server_repo.get_by_id(server_id, db)
    adapter = adapter_registry.get(server.game_type)
    log_parser = adapter.get_log_parser()
    server_dir = Path(settings.SERVERS_DIR) / str(server_id)
    try:
        path = log_parser.get_log_file_path(server_dir, filename)
    except (ValueError, FileNotFoundError) as e:
        raise HTTPException(404, str(e))
    return FileResponse(path, filename=filename, media_type="text/plain")

@router.delete("/{server_id}/logfiles/{filename}")
async def delete_log_file(
    server_id: int, filename: str, db=Depends(get_db), user=Depends(require_admin)
):
    server = server_repo.get_by_id(server_id, db)
    adapter = adapter_registry.get(server.game_type)
    log_parser = adapter.get_log_parser()
    server_dir = Path(settings.SERVERS_DIR) / str(server_id)
    try:
        path = log_parser.get_log_file_path(server_dir, filename)
        path.unlink()
    except (ValueError, FileNotFoundError) as e:
        raise HTTPException(404, str(e))
    return {"success": True, "data": {"message": f"{filename} deleted"}}
```

### 5.3 `backend/main.py` — register router

```python
from backend.core.servers.logfiles_router import router as logfiles_router
app.include_router(logfiles_router)
```

### 5.4 `frontend/src/hooks/useServerDetail.ts` — log file hooks

```typescript
export interface LogFile {
  filename: string;
  size_bytes: number;
  modified_at: number;  // Unix timestamp float
}

export function useServerLogFiles(serverId: number) {
  return useQuery({
    queryKey: ["servers", serverId, "logfiles"],
    queryFn: async () => {
      const res = await apiClient.get<{ success: boolean; data: LogFile[] }>(
        `/api/servers/${serverId}/logfiles`,
      );
      return res.data.data;
    },
    enabled: serverId > 0,
    refetchInterval: 30_000,
  });
}

export function useDeleteLogFile(serverId: number) {
  const queryClient = useQueryClient();
  return useMutation({
    mutationFn: (filename: string) =>
      apiClient.delete(`/api/servers/${serverId}/logfiles/${encodeURIComponent(filename)}`),
    onSuccess: () =>
      queryClient.invalidateQueries({ queryKey: ["servers", serverId, "logfiles"] }),
  });
}
```

### 5.5 `frontend/src/components/servers/LogViewer.tsx` — extend

**Add level filter** at top of component:
```typescript
const [levelFilter, setLevelFilter] = useState<"all" | "info" | "warning" | "error">("all");
const filtered = levelFilter === "all" ? logs : logs.filter(l => l.level === levelFilter);
// Render filtered instead of logs
```
Filter buttons: `[All] [Info] [Warning] [Error]` — active button uses `bg-accent` class.

**Add Log Files section** below live stream (collapsible):
- Uses `useServerLogFiles(serverId)` and `useDeleteLogFile(serverId)`
- Table: Filename | Size | Modified | Actions (Download, Delete)
- Download: open `/api/servers/{id}/logfiles/{name}/download` in new tab (with auth token in header via apiClient blob request → object URL → anchor click)
- Delete: confirm prompt before calling mutation

---

## Phase 6 — Server Card Quick Actions ~~(GOOD TO HAVE, ~1h)~~ **ALREADY IMPLEMENTED — SKIP**

**Verified:** `frontend/src/components/servers/ServerCard.tsx` already has full Start/Stop/Restart quick-action buttons (lines 71–105), including `e.preventDefault()` + `e.stopPropagation()`, pending states, lucide icons (`Play`, `Square`, `RotateCcw`), and error notifications via `useUIStore`. Nothing to do here.

---

## Coding Conventions (for implementing agent)

1. **apiClient** — All API calls use `apiClient` from `@/lib/api` (axios instance with JWT interceptor). Never use `fetch` directly.

2. **Mutations** — Always follow `useMutation` from TanStack Query. On success, call `queryClient.invalidateQueries({ queryKey: [...] })`.

3. **Admin guard** — Check `useAuthStore(s => s.user?.role === "admin")` to show/hide admin-only controls. Never hide entire sections — hide only action buttons/columns.

4. **Optimistic locking** — Config PUT endpoints require `config_version` in the body (from `_meta.config_version` in the fetched config). A 409 response = conflict; display an error message to user.

5. **CSS classes** — Existing utility classes: `neu-card`, `btn-primary`, `btn-ghost`, `btn-danger`, `neu-input`, `text-text-primary`, `text-text-muted`, `text-status-crashed`, `bg-accent`, `bg-surface-recessed`, `shadow-neu-recessed`, `shadow-neu-raised`. `btn-secondary` and `input-base` do NOT exist — use `btn-ghost` and `neu-input` respectively. Do NOT add new CSS files.

6. **Test file location** — `frontend/src/__tests__/`. Mock hooks with `vi.mock("@/hooks/...")`. Follow `CreateServerPage.test.tsx` and existing test patterns.

7. **Do NOT modify** — `backend/adapters/arma3/remote_admin.py` (RCon client is stable), `backend/core/websocket/` (WS manager is stable), `backend/core/auth/` (auth is stable).

8. **Immutability** — Never mutate state directly. Use spread (`[...arr]`, `{...obj}`) for all state updates.

9. **Missing config fields** — If a field exists in `get_ui_schema()` but is absent from the current section data, render it with an empty/default value (not hidden).

10. **Boolean config fields** — Send as string `"true"` / `"false"`. The backend converts to actual Python bool.

11. **Password fields** — Render as editable `<input type="password" />` in edit mode with a show/hide toggle button. Toggle state is component-local (resets to hidden on navigation/reload).

12. **Multi-file upload** — Sequential, one file at a time. Show per-file `{ filename, done }` progress.

13. **Responsive layout** — Split-pane components (mods, potentially others) stack vertically on small screens using `flex-col` below `md:` breakpoint (`md:flex-row`).

14. **Mod folder names** — Show `display_name` when available; fall back to `name` (the raw folder path, e.g. `@CBA_A3`) as-is without stripping `@`.

15. **Kick/Ban buttons when offline** — Both buttons always visible for admins, disabled with `title="Server must be running"` tooltip when `server.status !== "running"`.

16. **Kick UX** — Use a modal dialog (same pattern as Ban) for consistency. Do not use inline row expansion.

17. **Ban duration** — Both presets (1h / 24h / 7d / Permanent) AND a free-text minutes input. Permanent = send `duration_minutes: null`.

18. **Log file download** — Blob fetch via `apiClient` → `URL.createObjectURL()` → programmatic anchor click. Never open in new tab (auth header not sent by browser for new-tab navigations).

19. **Delete confirmations** — Use a small modal dialog component, not `window.confirm()` (blocks browser events).

---

## Testing Checklist

Run after each phase:
```bash
cd frontend && npx vitest run
cd frontend && npx tsc --noEmit
```

### Phase 1 (Config Schema)
- [ ] Config tab: `forced_difficulty` renders as `<select>`, not `<input>`
- [ ] `motd_lines` renders as `<textarea>`
- [ ] `battle_eye` renders as toggle checkbox
- [ ] `admin_uids` renders as TagListEditor; add/remove a UID; save; confirm persisted

### Phase 4 (Kick/Ban)
- [ ] With running server + connected player: click Kick, enter reason, confirm; player disconnects
- [ ] Click Ban, enter reason + duration; entry appears in Bans tab

### Phase 2 (Mission Rotation)
- [ ] Upload 3 `.pbo` files via multi-select; all appear in Available Missions
- [ ] Add all to rotation, set different difficulties; Save; GET config shows `missions` array
- [ ] Remove a mission from rotation; Save; confirms removed

### Phase 3 (Mod Display Names)
- [ ] Mod with `mod.cpp` shows display name instead of folder name
- [ ] Click mod in Available pane → moves to Selected; click Apply → `enabled = true` in response
- [ ] Search filter narrows visible mods in each pane

### Phase 6 (Quick Actions) — ALREADY IMPLEMENTED, no tests needed

### Phase 5 (Log Files)
- [ ] After server runs ≥1 min: Log Files section shows `.rpt` file
- [ ] Download → file downloads; Delete → file removed and list refreshes
- [ ] Click "Error" filter → only error-level lines in live stream