DoGaMa project state

Read this compact operational baseline before starting a milestone. Open detailed domain documents only when the current work affects them.

Baseline

Current reference: main after milestone 7 and feat(instances): add Docker labels, user IDs, image tags and deferred recreation (c820c9c).
Released SQLite migrations: 0001 through 0007; never rewrite them.
Roadmap milestones 1-7 are implemented. The instance-container configuration feature landed after milestone 7.

Go main application: HTTP API, embedded server-rendered UI, authentication/authorization, SQLite, workflows, backups and WASM runtime.
Private restricted Go agent: sole Docker-socket owner; authenticated typed API; registered-instance and plan-digest binding; no generic Docker proxy.
Integrations: capability-scoped WebAssembly adapters only. Palworld REST is the reference module.
Data: SQLite plus canonical allowed server, import and backup roots. Persistent game data lives outside containers.
Contracts: declarative YAML templates and module manifests validated against JSON Schemas; released snapshots are immutable.

Bootstrap administrator, local authentication, secure sessions and CSRF protection.
Validated embedded catalog, deterministic deployment previews and instance registry.
Restricted instance create/inspect/start/stop/restart/delete and reconciliation.
Per-instance memberships, overrides and installation requests with backend authorization.
Backup scheduling/retention, safe imports, export and restore with safety backups.
Sandboxed WASM runtime and normalized module API with Palworld reference adapter.
Game-container configuration: global and per-instance labels, safe label variables, derived instance slug, immutable Docker-user selection, tracked/pinned image tags, immediate or deferred container recreation, and public game-icon route.

Editable Docker labels apply only to game-server instance containers.
Labels on the DoGaMa application container remain Compose configuration and are never read, copied or edited by DoGaMa.
Merge order is global labels, then instance labels; instance values win. Internal technical labels are applied last and cannot be overridden.
dogama.* and io.dogama.* are reserved label namespaces.
Label values support only the explicit allowlist in internal/instance/container_config.go; unknown variables are errors, not arbitrary templates.
{{game.icon_url}} is the public icon for the game. {{instance.slug}} remains supported.
Instance slugs are derived from the display name, not canonical IDs. Accents are normalized to ASCII; whitespace, /, punctuation and special characters become safe hyphen separators; repeated and edge hyphens are removed.
Docker user mode is fixed at creation to DoGaMa UID/GID, custom numeric UID/GID, or image-defined user. Never perform automatic recursive ownership changes.
A pinned image tag is an explicit mutable tag, not an immutable digest. Tracked mode follows the template's declared default tag.
Replacement-requiring changes use the generic container_config_pending desired-versus-applied state. Replacements preserve bind-mounted data and prior running/stopped intent.
The main app never gains Docker-socket access; the agent remains deny-by-default and independently validates privileged plan fields.

Roadmap milestone 8 remains broader than the delivered instance-container configuration: controlled update history, mods and rollback paths are not complete.
Notification channels, audit delivery/retention UI and release hardening remain roadmap work.
The web interface is intentionally modest; several advanced workflows are API-first.
Linux is the deployment target. Native Windows execution of the full Go suite is blocked by Unix Statfs code; use Linux/WSL/CI for complete execution.
staticcheck, golangci-lint and Python specification dependencies may not be installed on every development host; report missing tooling rather than silently skipping or installing it.

No repository-hosted Gitea/GitHub workflow files are currently present.
Normal completion gate for Go changes is the validation set in AGENTS.md on Linux.
Specification validation is python tools/validate_spec.py with tools/requirements-validation.txt available.
Start with package/file-specific tests, then run global tests, build, race detection, vet, static analysis and schema validation as applicable.

Roadmap milestone 8: controlled game updates, configuration history and rollback; complete mod configuration only within declarative safe contracts.
Then milestone 9: notifications and light audit trail.
Update this file at the end of every merged milestone or durable architectural change; keep it compact and remove stale statements.