Document Vulkan Video design and simplify player layout

.github/workflows/release-ci.yml

@@ -367,6 +367,10 @@ jobs:
           Enter-VsDevShell -VsInstallPath $InstallPath -SkipAutomaticLocation -DevCmdArguments '-arch=x64 -host_arch=x64'
           ./scripts/build_windows.ps1 -Compiler stable
           $env:Path = "$(Resolve-Path dist\vkvideo-windows-x64);$env:Path"
+          $HelpText = (& .\dist\vkvideo-windows-x64\v_vulkan_video.exe --help | Out-String)
+          if ($LASTEXITCODE -ne 0 -or $HelpText -notmatch 'Usage:') {
+            throw 'The Windows player did not print its command-line help.'
+          }
           v -cc msvc test .
           ./scripts/verify_windows_package.ps1
       - name: Upload Windows package

BUILDING.md

@@ -59,13 +59,15 @@ a platform-independent archive.
 ## Player command line
 
 ```sh
-./v_vulkan_video [--list-gpus] [--gpu INDEX] [video.mp4]
+./v_vulkan_video [--list-gpus] [--gpu INDEX] [--decode-output-mode MODE] [video.mp4]
 ```
 
 GPU compatibility is evaluated against the input stream's actual H.264
 profile. Without `--gpu`, the first fully compatible presentation/decode device
 is selected. Invalid media and unsupported or out-of-range devices return a
 clean non-zero exit status with a diagnostic instead of a panic.
+`--decode-output-mode auto|coincident|distinct` selects an advertised DPB and
+output-image mode; `auto` is the default.
 
 ## Ubuntu 24.04 binary package
 

PLATFORM_SUPPORT.md

@@ -34,6 +34,8 @@ Video-capable GPU is available. The remaining Windows work is:
 The completed MSVC build and GTX 765M unsupported-device test do not satisfy
 these playback checks.
 
+## Supported media and failure behavior
+
 The application currently decodes H.264/AVC video carried in MP4. It supports
 8-bit 4:2:0 progressive Baseline, Main, and High profiles when the driver
 reports a compatible Vulkan Video profile. Other codecs, chroma formats,
@@ -74,6 +76,8 @@ This deliberately does not advertise Vulkan Video extensions or emulate video
 commands. Decoded-picture-buffer operation, image transitions, queue
 synchronization, and presentation still require a real Vulkan Video device.
 
+## Hardware validation checklist
+
 Before calling a platform supported for release, run at least:
 
 - playback through multiple loops;

README.md

@@ -26,8 +26,11 @@ To compile and run directly from a source checkout, target the repository root:
 v run . [--list-gpus] [--gpu INDEX] [--decode-output-mode MODE] [video.mp4]
 ```
 
-`examples/video_decode_app` is the application's importable module rather than
-a standalone `main` package, so it is not a direct `v run` target.
+The player is one V application. `main.v` handles command-line options;
+`app.v` owns the window and rendering loop; `device_context.v` selects the GPU.
+`mp4_parser.v`, `decoder_session.v`, `player_decode.v`, and
+`player_presentation.v` implement the media path. Shared player state and
+resource ownership are in `video_player.v`.
 
 Without a video path, the bundled self-recorded and metadata-sanitized sample
 is used. `--list-gpus` reports compatibility against the selected video's
@@ -69,6 +72,14 @@ workflow.
 See [PLATFORM_SUPPORT.md](PLATFORM_SUPPORT.md) for tested hardware, known
 limitations, and the release-validation matrix.
 
+## Learn from the implementation
+
+The [design guide](docs/learning-path.md) traces an encoded picture through
+MP4 parsing, GPU capability selection, Vulkan Video decoding, synchronization,
+and presentation. It explains the underlying decisions, their tradeoffs, and
+how to apply the same concepts in another project. Start with its system map
+and follow the chapters that match the problem you are solving.
+
 ## Tests
 
 ```sh