docs: state ladder + fallback semantics in README; mediasession2mqtt retirement + universal-player glue appendix in RESEARCH_SHIELD; TiviMate as the documented no-session case (P3-3d)

README.md

@@ -52,6 +52,43 @@ Changes inherited from upstream still apply in 0.1.x code: polling is timer-base
 the ADB connection lives inside the media player entity, and fallback app state
 arrives in Phase 3.
 
+## State ladder and fallback semantics (Phase 3)
+
+The media player state is decided top-down; each tier serves only when the
+ones above it are silent. Both transports live in the entry's
+`ShieldConnectionManager` (`connection.py`) — ADB is the state source, the
+remote protocol is the fast push/command path:
+
+1. **Plug off** — the power switch says `off` → `off`.
+2. **Protocol power push** (`is_on`) — `False` → `off`; `None` falls through.
+3. **ADB wake** (exact `mWakefulness` parse) — asleep → `idle` (standby).
+4. **Intent** — a just-sent command's target state, self-healing against
+   reality within 30 s (retry goes over the transport that served it).
+5. **Jellyfin** — `playing` / `paused` while a Jellyfin session is active.
+6. **ADB media session** — `playing` / `paused` for apps that publish a
+   session (foreground app preferred).
+7. **Foreground fallback** — an app is open (`current_app` protocol push,
+   then the ADB `mResumedActivity` parse) but publishes no media session →
+   `on`. Its identity comes from the TTL-capped last-known-state cache, the
+   last channel entered, or the zero-cost "audio playback" hint
+   (`media recently active`) — never resurrecting `playing` past the 60 s
+   state TTL.
+8. **On** — powered, awake, nothing more specific.
+
+TiviMate (`ar.tvplayer.tv`) is the documented no-session case: it publishes
+no MediaSession on Shield Android 11 (RESEARCH_SHIELD R2), so tiers 6–7 plus
+the audio hint are what keep it visible.
+
+### Migration from mediasession2mqtt + universal-player glue
+
+The `mediasession2mqtt` bridge sensors and the universal media player YAML
+templates the fork replaces are retired by the ladder above: the media player
+entity already carries the DAG attributes (`media_dag_running_apps` with
+foreground/last-known enrichment, `media_dag_now_playing` with its source
+tag) that media-zone orchestration consumed from those sensors. See the
+appendix in [`docs/RESEARCH_SHIELD.md`](docs/RESEARCH_SHIELD.md) for the
+retirement mapping and the universal-player glue it replaces.
+
 ## Releases
 
 - **Date-based versioning**: `vYYYY.MM.DD` (e.g. `v2026.10.08`).