# Guide for AI and Codex contributors

This repository is deliberately structured so an AI can add a game integration without reverse-engineering the manager. Treat normative prose, JSON Schemas and reference examples as a single contract set.

## Before making a change

1. Read `README.md` product invariants and root `AGENTS.md`.
2. Identify the authoritative domain document.
3. Validate current schemas and examples before editing.
4. Inspect Palworld as the reference, but do not generalize a Palworld quirk into the core model.
5. State uncertain game behavior and cite primary game/container API documentation in contributor-facing notes.

## Adding a game without an API

Create a template only. Declare container image, ports, storage, fields, health, backups, mods and update behavior. Do not invent a module merely to start/stop Docker; generic orchestration already handles that.

## Adding a game with an API

Create:

```text
catalog/<game>/template.yaml
modules/<module-id>/manifest.yaml
modules/<module-id>/README.md
modules/<module-id>/src/...     implementation phase
modules/<module-id>/tests/...
```

Choose only required capabilities. Translate game errors into normalized errors. Use the logical `instance_api` host functions; never accept arbitrary destination URLs. Keep game API credentials as declared secret configuration.

## Required verification for a contribution

- Template validates against `specs/template.schema.json`.
- Manifest validates against `specs/module-manifest.schema.json`.
- Declared capabilities correspond to normalized functions and module exports.
- Template module version range accepts the manifest version.
- All integration ports exist in the template and remain private unless explicitly required for players.
- Backup source mount exists and strategy matches module capability.
- Secret fields are write-only and excluded from examples/fixtures.
- Minimum/recommended requirements and upstream image/API facts have primary-source evidence.
- Failure behavior works when the game API is offline, slow, malformed or unauthorized.

## Safe response to “add this new game”

An AI should produce a short evidence table first: upstream image, required ports, persistent player-data path, health method, configuration interface, save consistency, update mechanism, mod mechanism and API availability. Unknowns remain explicit `TODO` blockers or conservative template omissions; do not fabricate them.

Then implement the smallest valid surface:

- Template-only when generic Docker lifecycle is enough.
- Status-only module when only status is reliable.
- Add player moderation or online save only with verified API behavior.

## Contract-edit rule

If a new game cannot fit the current schema, first determine whether it exposes a genuinely generic need. Extend the schema narrowly with documentation, migration/compatibility analysis, validation, negative tests and updated examples. Never add an escape hatch such as arbitrary commands, raw Compose fragments, host paths or unrestricted network permissions.