# AGENTS.md for platform

This file applies to `platform/`.

## Backend Structure

Keep definitions out of business logic:

- Request/response structs go in `dto/` or a dedicated contract package.
- Database tables go in `model/` with field comments and tags before migrations or repositories reference them.
- API route declarations and handlers go in `api/`.
- Business aggregates and value objects go in `domain/`.
- Protocol payloads go in `protocol/`.
- Shared helper functions go in `shared/` only when at least two packages need them.

## API Rules

Every HTTP/API handler must have OpenAPI-style comments when implemented. Request bodies, response bodies, and errors must reference named DTO structs.

## Database Rules

Prefer model-first table definitions. Do not define table schemas only inside migration SQL. Migrations may use raw DDL only when the model remains the source of truth.

## Platform Boundaries

Plugins and platform_web must never receive run credentials, raw host paths, or AI provider keys. All access must pass through platform authorization and bounded DTOs.

Platform may read plugin manifests, validate lifecycle/action declarations, package plugin-owned action assets into generated run distributions, and dispatch lifecycle jobs with typed inputs. Platform must not implement game-specific install/update/start behavior itself.

Platform may persist desired lifecycle state, last-known run reports, audit history, and UI projections. It must not treat those persisted fields as the authoritative source for the current machine/process state; current runtime status must come from the registered run endpoint's reports, heartbeats, supervised process facts, and job/log channels.

Do not add platform service code that hardcodes a game's executable path, Steam app ID, SteamCMD command line, process name, default launch flags, or update policy. For SCUM specifically, `SCUMServer.exe`, app `3792580`, `+app_update 3792580 validate`, `-port`, `-MaxPlayers`, and `-log` must come from the SCUM plugin action assets or plugin-declared startup fields.

If a lifecycle job requires checking whether game files exist, installing missing files, updating existing files, stopping before update, or building the final launch command, dispatch the plugin-owned action and keep platform limited to authorization, input validation, job creation, and result handling.