browser/AGENTS.md

# AGENTS.md

This file applies to the entire repository.

## Scope

This repository is a game server management platform. Do not add billing, cloud host sales, agent-provider/cloud-provider workflows, or unrelated SaaS marketplace features unless a future OpenSpec change explicitly requires them.

The platform's required first-party areas are 首页、服务器管理、插件市场、用户管理、AI 提供商管理.

The platform_web visual direction is a unified magical-girl crystal-moonlight game operations console. Preserve the style rules in `platform_web/AGENTS.md` and `platform_web/theme/README.md`; do not replace it with generic opaque SaaS cards or unrelated visual systems without a future OpenSpec change. Global magical ultimate effects belong in `platform_web/components/MagicalParticleLayer.tsx`, not in page-local fixed decoration spans or one-off backdrop CSS.

## Server Creation Rules

Creating a server instance must require only the game plugin type and the server name. Do not require the owner to pick a deployment target, run endpoint, or runtime profile at creation time: the run executor does not exist yet at that point, so any such field can only be filled incorrectly.

This is a prerequisite rule, not a ban on the create wizard. The create wizard may collect plugin-declared deployment mode, game configuration, and startup fields before submit as long as deployment target, run endpoint, and runtime profile selection are not creation prerequisites.

The binding between a server instance and its run endpoint is established when the generated run registers itself, not by pre-selecting an existing endpoint in the creation form. Deployment target and runtime profile selection may exist only as optional actions on an already-created instance, never as creation prerequisites.

## Project Roots

- `platform/` contains backend platform code.
- `platform_web/` contains the management frontend.
- `plugins/` contains game management plugins and plugin SDK/examples.

The machine-side run executor lives in the independent repository `git@git.npc0.com:admin343/run.git`; do not re-add a `run/` source tree to this repository.

Do not place implementation code outside the matching root. Shared contracts must be generated or copied through explicit contract packages, not imported by reaching across ownership boundaries casually.

## CSS Authoring Rules

Any task that touches CSS must keep CSS declarations compressed and compact. Do not expand a single selector's style block across many lines when it can be written as a concise one-line rule.

## OpenSpec Rules

- Use judgment before creating an OpenSpec change. Create one when the work changes behavior, architecture, public/API contracts, validation rules, persistence, security boundaries, cross-root workflows, or the required product/visual direction.
- OpenSpec is not required for small scoped bug fixes, copy/documentation updates, tests, local refactors without behavior change, or styling/label fixes that preserve the existing visual system. For those, reason through the steps, make the edit directly, and report the verification performed.
- If an OpenSpec change is created, update proposal/design/specs/tasks before implementation when behavior, architecture, or validation rules change.
- If an OpenSpec change is created, do not mark its tasks complete until verification evidence exists, and run `openspec validate <change> --strict` before completion.

## Task Creation Rules

When creating a task, include the following prompt boundaries before implementation starts:

- Positive prompt (正向提示词): clearly state the intended outcome, accepted success criteria, and the first-party product area the work supports.
- Directional prompt (方向提示词): state the expected implementation direction, affected project root, relevant existing patterns to preserve, and verification command or evidence expected.
- Boundary prompt (任务边界): explicitly list out-of-scope areas, forbidden product expansions, and files or roots that must not be touched unless the task explicitly requires them.

## Git Completion Rules

All repository modifications must happen on `main` unless the user explicitly asks for another branch in the current task. Do not create, switch to, or push `codex/*` or other task branches by default. If the working tree is not on `main`, switch back to `main` before editing; if local changes block the switch, stop and report the blocker instead of creating a new branch.

For every substantial session task that modifies repository files, automatically stage only the files changed for that task, create a concise git commit after verification succeeds, and push the current branch to its configured git remote before sending the final response.

Do not include unrelated pre-existing worktree changes in the commit. If commit or push is blocked by missing credentials, a missing remote, conflicts, or a failing required verification step, report the blocker clearly instead of broadening the commit scope.

## Structure Rules

Backend roots must keep these concerns in fixed directories:

- API route declarations and handlers.
- Request/response DTOs.
- Domain types.
- Database models.
- Repository interfaces and implementations.
- Service interfaces and implementations.
- Protocol contracts.
- Validation rules.
- Shared utilities.

Frontend and plugin page roots must keep these concerns in fixed directories:

- API clients and API types.
- Route definitions.
- Page/view contracts.
- Component contracts.
- Schemas and validators.
- Bridge/SDK types.
- Shared utilities.

Do not define business structs inside functions. Do not define request/response structs inside handlers. Do not define database models inside migrations. Do not hide shared frontend types inside page components.

## Run and Channel Rules

The external run executor must not expose host paths, raw credentials, or direct sockets to plugins or platform_web.

Platform, plugin, and run lifecycle ownership must stay separated:

- Platform owns server instances, plugin manifest validation, distribution builds, run registration binding, authorization, and lifecycle job dispatch.
- Plugins own game-specific lifecycle behavior: install, update, pre-start checks, start arguments, stop logic, status probes, executable paths, Steam app IDs, and game-specific dependency commands.
- Run owns generic machine execution only: scoped file operations, bounded process execution/supervision, declared capability enforcement, logs, artifacts, and channel transport.

Do not hardcode game-specific deployment behavior in run or platform services. Values such as `SCUMServer.exe`, Steam app `3792580`, `steamcmd +app_update`, SCUM install directories, `-port`, `-MaxPlayers`, or `-log` belong in the SCUM plugin's manifests, action specs, templates, or scripts.

When a game needs "install if missing, update if present, then start" behavior, implement it as plugin-owned lifecycle actions. Platform may package and dispatch those actions, and run may execute them through generic capabilities, but neither platform nor run should special-case a game by name to perform those steps.

Realtime log collection must be plugin-declared and plugin-configured. For live terminal output, prefer the plugin-declared supervised process channels (`process.stdout` / `process.stderr`) for the process that run started, and treat game-specific file tails only as plugin-declared sources for history, fallback, or explicit backfill. Do not inspect or prioritize a game log file such as `SCUM.log` merely because it exists on disk; if a plugin needs a file tail, window/console capture, startup flag, hidden window behavior, or another live-log source, declare that behavior in the plugin manifest/action/config and keep run/platform generic.

Run-platform communication must remain channelized:

- Control is lightweight and high priority.
- Jobs carry lifecycle and bounded operations.
- Logs use durable batch ingest with local spool and sequence acknowledgement.
- Artifacts use chunked and resumable transfer with lower priority than logs/control.
- Optional game client bridge is separate from run lifecycle and log ingest.

Large file transfer must not block control heartbeat, job ack/result, or log upload.

## Distribution Build Ownership Rules

Distribution building is a platform-side responsibility. The platform must be able to build a run package for any server instance without depending on a privileged worker run endpoint being registered and online. Do not route `distribution.build` execution through machine-side run endpoints, and do not derive build availability from a run endpoint advertising that capability.

Platform-side builds must execute in a platform-owned Docker builder using a pinned image, with build workspaces isolated per plugin and per job. Builder readiness is a platform-level probe; when it is unavailable, the reported reason must name the platform builder rather than a run endpoint capability.

A generated run carries credentials scoped to one server instance and must never hold distribution-build authority. This restriction is a security boundary, not a fallback path: it must not be relaxed to unblock building. Fix the build path instead.

Component auth keys must stay inside the platform for builder-executed builds. Do not return plaintext auth keys to machine-side run endpoints for distribution builds.

## Local Run Distribution Testing

For local testing, when a generated `run.exe` must be made available to a remote server, start a temporary file server from the build output directory with `python3 -m http.server 8000`. Download the artifact through `https://bt.npc0.com/` followed by its relative file path, then download that file again on the machine where `run` will execute. This is a test-only distribution path; do not treat the temporary HTTP server or tunnel as a production artifact-delivery service.

## AI Provider Rules

AI provider keys and base URLs belong to `platform/`. Plugins may request AI assistance only through platform-mediated capabilities. Plugin page must never receive raw AI keys.

AI-suggested config changes must produce a reviewable diff or recommendation before platform dispatches a run-side write job.

## Verification Rules

Run this before completion:

```bash
scripts/check-structure.sh
```

If you add or change a structural rule, update `scripts/check-structure.sh` in the same change.