docs: record milestone 8 delivery

docs/PROJECT-STATE.md

@@ -4,9 +4,9 @@ Read this compact operational baseline before starting a milestone. Open detaile
 
 ## 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.
+- Current reference: milestone 8 implementation `7f5fa30` after baseline `c820c9c`.
+- Released SQLite migrations: `0001` through `0008`; never rewrite them.
+- Roadmap milestones 1-8 are implemented.
 
 ## Architecture
 
@@ -25,6 +25,9 @@ Read this compact operational baseline before starting a milestone. Open detaile
 - 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.
+- Controlled digest-aware game updates with confirmation, policy-driven pre-update backups, readiness verification, mod warnings and automatic container-plan rollback.
+- Redacted configuration history retained to the latest 10 revisions, with pinned-template revalidation and immediate or deferred rollback.
+- Declarative Steam Workshop item configuration with numeric-ID validation, stable ordering and backend `mods.manage` enforcement.
 
 ## Durable decisions
 
@@ -39,10 +42,11 @@ Read this compact operational baseline before starting a milestone. Open detaile
 - 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.
+- Update candidates are explicit `tag@sha256:digest` references. Mutable tags alone are rejected; automatic updates remain disabled.
+- Mod configuration is data-only. Provider commands, scripts and arbitrary download URLs are forbidden.
 
 ## Known limitations and debt
 
-- 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.
@@ -57,6 +61,5 @@ Read this compact operational baseline before starting a milestone. Open detaile
 
 ## Next known work
 
-- 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.
+- Roadmap 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.

docs/operations/instance-operations.md

@@ -31,18 +31,24 @@ The template states destination mount, ordering, restart requirement, dependency
 
 DoGaMa clearly labels unofficial mod support and never assumes a server update is compatible with installed mods.
 
+The V1 implementation accepts only Steam Workshop numeric item IDs when the pinned template explicitly declares that provider. It persists a normalized declarative list and rejects provider commands, scripts, arbitrary URLs and changes for templates without mod support.
+
 ## Configuration application
 
 Each template field declares `apply: immediate` or `restart_required`. Secret fields are write-only. Validate types, ranges, patterns and conflicts on both client and server. A preview lists pending changes and whether container replacement or game restart is needed.
 
 Keep the last 10 redacted configuration revisions by default. Rollback revalidates the old revision against the pinned template/module versions before applying it.
 
+Every desired container or mod change creates a revision, listed newest first. Rollback never restores secrets, never changes the immutable Docker user and may be immediate or deferred until the next explicit start.
+
 ## Updates
 
 Image updates are digest-aware. A mutable tag alone is never treated as proof that nothing changed. The UI shows current and candidate references, template release notes if available, mod warnings and whether a backup will run.
 
 The full update sequence and rollback behavior are normative in `docs/domain/instance-lifecycle.md`. Managers may trigger only updates allowed by global/instance policy; administrators choose channels and may pin a digest. Automatic updates remain disabled by default.
 
+The V1 API requires an explicit candidate tag and SHA-256 image digest plus confirmation. A required `pre_update` backup must finish before replacement. Readiness is bounded by the template timeout; failed replacement, start or readiness restores the prior image/configuration plan when rollback is enabled, without restoring player data.
+
 ## Game-container labels, users and tags
 
 Administrators can define global labels for game-server containers and instance-specific overrides, one `key=value` per line. Empty lines are ignored and only the first `=` separates the key. Instance labels override global labels; DoGaMa's technical labels always win. Both `dogama.*` and `io.dogama.*` are reserved.
@@ -70,4 +76,3 @@ Label and tag changes can apply immediately or at the next start. Immediate appl
 - Local copied templates are independent and are never overwritten by their origin.
 - Module packages update independently and require compatibility plus connection tests before activation.
 - Rollback keeps the prior template snapshot, module binary and container plan available until the new combination is verified.
-