DoGaMa-serv/AGENTS.md

Instructions for Codex and automated contributors

Read README.md and the relevant documents under docs/ before changing implementation or contracts.

Non-negotiable rules

1. Preserve the product invariants in README.md.
2. Do not give the main application direct Docker-socket access.
3. Do not implement integrations as native plugins, host executables, scripts, or sidecar containers. Integrations are WebAssembly adapters only.
4. Do not add arbitrary command execution, arbitrary Docker API proxying, arbitrary host paths, or unrestricted network access.
5. Treat templates and module manifests as untrusted input. Validate them against specs/*.schema.json before persistence or execution.
6. Keep secrets out of API responses, logs, audit payloads, exports, error messages, and test fixtures.
7. Preserve player data and backups by default in every deletion, update, restore, and migration workflow.
8. Keep compose.yaml minimal. Product settings belong in the database and web interface unless they are bootstrap secrets, bind roots, or network/listen settings required before startup.
9. SQLite is the V1 database. Do not introduce an external database, message broker, Kubernetes, or distributed-node design without an accepted architecture decision.
10. Palworld is the reference integration. Any contract change affecting templates, modules, backups, permissions, or instance lifecycles must be checked against both Palworld examples.

Change workflow

• Locate the normative document first.
• State assumptions when requirements are ambiguous; do not silently invent security-sensitive behavior.
• Update documentation, schema, example, implementation, and tests together when a contract changes.
• Prefer small Go packages with explicit interfaces and dependency direction.
• Add migrations for persisted data changes. Never edit an already released migration.
• Use deterministic serialization and stable identifiers.
• Validate JSON Schemas and YAML examples in automated checks.
• Add negative tests for authorization, path validation, module capabilities, archive extraction, and agent operation scope.
• Report what was validated and what still needs physical or integration testing.

Definition of done for a change

• Relevant requirements and acceptance criteria are satisfied.
• Authorization is enforced in the backend, not only hidden in the UI.
• Audit and notification behavior is deliberate.
• Failure and rollback behavior is covered.
• Documentation and machine-readable examples agree.
• Tests cover success, denial, and interruption paths.