docs: study Android clients and public API feasibility

[hotzenplotz5]

Summary

This documentation and documentation-validation change establishes the current repository truth, a phased feasibility/target-architecture study for Android Mobile, Android TV, browser/PWA, desktop and third-party clients, and the proposed durable client-platform decision in ADR-0051.

The branch starts from current origin/main at cb77ff66e11dca7db2eafa36525762dcde35102d (merged PR #115), after the repository-truth refresh from PR #114.

What changed

• add a comprehensive Android, Android TV and client API feasibility study;
• add proposed ADR-0051: Client Platform and Native Android Architecture;
• trace the current browser frontend, JavaScript Client API, RemoteAction, LiveOverlay, SSE, search, Genres, Recordings, EPG, Timers and SearchTimer boundaries;
• verify that the current browser has structured LiveOverlay state but no Suite video player, MediaSession or Streaming Gateway;
• compare WebView, PWA, hybrid and native Kotlin/Compose/Media3 approaches with a weighted decision matrix;
• recommend a shared non-UI Android core with separate touch and D-pad/focus UIs;
• add a client capability matrix and a detailed API-candidate matrix;
• classify Public v1, compatibility, internal Web, Admin, Media Plane, Agent, provider and UI-only boundaries;
• define a strictly read-only compatibility-adapter PoC;
• map every production gate onto Phases 62 through 67 without inserting a new runtime phase;
• advance the canonical ADR index and its validation guard from ADR-0050/0051 to ADR-0051/0052;
• refresh CURRENT.md, the strict roadmap and documentation indices for merged PR feat(frontend): add configurable photorealistic VDR remote #115.

Main architecture conclusions

• Native Kotlin, Jetpack Compose and Android Media3 are the recommended production direction.
• Android Mobile and Android TV share a non-UI core but keep separate touch and D-pad/focus presentation surfaces.
• A PWA is a useful parallel browser enhancement.
• WebView/TWA is acceptable only as a clearly temporary, preferably read-only transition shell.
• Current unversioned /api/... routes and VdrSuiteClientApi wrappers are transition contracts, not automatically /api/v1.
• Public HTTP API, Web wrapper, Android client library, Agent protocol, Media Plane and plugin schema remain separate contracts.
• Product authentication and mutations depend on Phase 62.
• Product playback depends on Phase 65 Media Sessions and Streaming Gateway.
• A stable independent-client API and publishable SDK depend on Phase 67.
• Phase 62 remains the next strict runtime phase.

Validation

• reviewed current main code, tests, accepted ADRs, roadmap/status documents and merged/open PR state;
• traced current routes and runtime owners to concrete files;
• checked current Android recommendations against official Android/Google upstream documentation;
• ran the repository documentation CI and used its uploaded log to identify the required ADR-index guard update;
• compared the branch to its exact main baseline: ten files, no Runtime/API/frontend implementation changes.

The VDR-local checkout /home/yavdr/vdr-suite is not mounted in the execution environment, so no local Git commands, builds or real-system VDR acceptance tests were run. Repository reads and writes were performed through the connected GitHub repository.