# V2 Config Documentation And Operational Runbook

This runbook covers `TODOS.phase-72.72.12.1.15`: config documentation and an
operational runbook for live configuration, feature flags, maintenance mode,
config dashboard review, and message-of-the-day announcements.

## Authority

This document is the operator-facing index for the V2 live-service config
system. The detailed source runbooks remain:

- `V2/docs/live-service/remote-config-service.md`
- `V2/docs/live-service/feature-flag-service.md`
- `V2/docs/live-service/config-dashboard.md`
- `V2/docs/live-service/message-of-the-day.md`

The validated contract is
`V2/ue/Content/V2/LiveOps/ConfigDocumentationRunbook_V2_Contract.json`, and the
release gate is `V2/ue/Tools/check-v2-config-documentation-runbook.py`.

## Operator Scope

Operators use this runbook when they need to:

- change game parameters without a client patch through
  `@v2/remote-config-service`
- enable, disable, gradually roll out, or kill-switch feature flags through
  `@v2/feature-flag-service`
- inspect active remote configs, current values, segment targeting, and flag
  states through the `apps/v2/web/live-service/config-dashboard` surface
- open or close maintenance-mode redirects during server updates
- push message-of-the-day announcements for events, downtime, and patch notes

No client patch is required for the supported live config workflows when the
client already supports the documented refresh surfaces.

Every production change must leave an audit trail that answers who changed what,
when it changed, why it changed, and how it was validated.

## Change Lifecycle

### change-intake

Create a change record before editing any production-bound config. The record
must include owner, requested environment, affected keys or flag IDs, expected
player impact, rollback owner, rollout window, and whether the change is tied to
an incident ID.

### risk-classification

Classify each change before staging:

- Standard: low-risk tuning, copy, or scheduling changes.
- Guarded: economy, progression, matchmaking, combat balance, targeting, or
  rollout-percentage changes.
- Emergency: kill switch, maintenance-mode, critical downtime, rollback, or any
  player-impacting mitigation tied to an incident ID.

Guarded and emergency changes require four-eyes approval before production.
Emergency changes must include the incident ID in the published audit metadata.

### validation-rules

Run validation before staging and before production promotion. Remote config
changes must pass the validation-rules surface, including known parameter keys,
numeric bounds, positive enemy health, drop-rate caps, and non-decreasing XP
curves. Feature flags must keep rollout percentages in range and preserve
`clientPatchRequired: false`.

### preview-staging

Preview production-bound changes in staging before promotion. The staging review
must compare current value, default value, proposed value, segment targeting,
feature flag state, ETag, generated timestamp, and audit reason in the config
dashboard.

### production-rollout

Roll production changes in the smallest useful scope:

1. Publish to staging and verify the staging client payload.
2. Confirm the config dashboard shows the expected active values and flag state.
3. Promote to production with owner, reason, change summary, and incident ID
   when applicable.
4. Watch the active ETag, client refresh TTL, dashboard propagation state, and
   any affected gameplay telemetry.
5. Leave the old version available for rollback until post-change monitoring is
   complete.

## Incident Controls

### rollback

Use remote config version history for instant rollback when a published config
is bad. Rollback publishes a new version that restores a previous parameter map,
marks the bad version rolled back, preserves `requiresClientPatch: false`, and
records the rollback reason in audit-log-traceability.

### kill-switch

Use the feature flag kill-switch path when a shipped feature must be disabled
across refresh-capable clients without a patch. The kill switch sets the target
flag to `force-disabled`, sets rollout percentage to 0, invalidates the previous
ETag, emits a cache-bust token, and caps max client staleness.

### maintenance-mode

Use maintenance-mode when server updates require all clients to leave gameplay
or matchmaking. The maintenance command must publish title, message, reason,
estimated resume time, status page URL, support URL when available, and a
bounded `maxClientStalenessSeconds`. Closing maintenance must publish a clearing
version so clients leave `/maintenance`.

### message-of-the-day

Use the message-of-the-day service for player-facing communications around
events, downtime, and patch notes. Downtime messages should be non-dismissible
when acknowledgement is required. Dismissible announcements must preserve
per-account dismissal.

### post-incident-review

After an emergency change, attach the production version ID, incident ID, active
ETag, rollback or kill-switch result, operator, reviewer, and screenshots or
logs from the config dashboard to the incident review.

## Audit Evidence

Required evidence for every production change:

- change request link or incident ID
- operator and reviewer
- source runbook used
- validation report
- staging preview result
- production version ID and ETag
- affected config keys, feature flags, maintenance state, or MOTD message IDs
- rollback plan and rollback owner
- post-change monitoring result

Audit-log-traceability must be enough for another operator to reconstruct the
who, what, when, and why without relying on chat history.

## Verification

Run the relevant service gates for the affected surface, then run the
cross-runbook gate:

```bash
pnpm --filter @v2/remote-config-service test
pnpm --filter @v2/remote-config-service typecheck
pnpm --filter @v2/feature-flag-service test
pnpm --filter @v2/feature-flag-service typecheck
pnpm --filter @v2/message-of-the-day-service test
pnpm --filter @v2/message-of-the-day-service typecheck
python3 V2/ue/Tools/check-v2-remote-config-service.py
python3 V2/ue/Tools/check-v2-remote-config-validation-rules.py
python3 V2/ue/Tools/check-v2-remote-config-preview-staging.py
python3 V2/ue/Tools/check-v2-remote-config-delivery-optimization.py
python3 V2/ue/Tools/check-v2-remote-config-maintenance-mode.py
python3 V2/ue/Tools/check-v2-feature-flag-service.py
python3 V2/ue/Tools/check-v2-feature-flag-kill-switch.py
python3 V2/ue/Tools/check-v2-config-dashboard.py
python3 V2/ue/Tools/check-v2-message-of-the-day.py
python3 V2/ue/Tools/check-v2-config-documentation-runbook.py
python3 V2/ue/Tools/check-v2-ci-workflow.py
python3 V2/tools/validate-v2-docs.py
```

Required gates:

- `config-documentation-runbook-doc`
- `config-documentation-runbook-change-lifecycle`
- `config-documentation-runbook-validation-staging`
- `config-documentation-runbook-rollout-rollback`
- `config-documentation-runbook-incident-controls`
- `config-documentation-runbook-audit-evidence`
- `config-documentation-runbook-ci-wired`