diff --git a/roles/plasma-bigscreen/default.nix b/roles/plasma-bigscreen/default.nix
index 108bd04..99d6bb8 100644
--- a/roles/plasma-bigscreen/default.nix
+++ b/roles/plasma-bigscreen/default.nix
@@ -5,7 +5,8 @@ with lib;
 let
   cfg = config.roles.plasma-bigscreen;
 
-  # Plasma Bigscreen package — not yet in nixpkgs, built from upstream master
+  # Plasma Bigscreen package — not yet in nixpkgs, built from upstream master.
+  # TODO: Replace with pkgs.kdePackages.plasma-bigscreen once available.
   plasma-bigscreen = pkgs.kdePackages.callPackage ./package.nix {};
 
   jellyfinMediaPlayerPkg =
diff --git a/roles/plasma-bigscreen/package.nix b/roles/plasma-bigscreen/package.nix
index ebf5500..07219b0 100644
--- a/roles/plasma-bigscreen/package.nix
+++ b/roles/plasma-bigscreen/package.nix
@@ -1,8 +1,12 @@
 # Plasma Bigscreen — TV interface for Plasma 6
 # Not yet released or packaged in nixpkgs; built from upstream master.
+#
+# TODO: Remove this file once plasma-bigscreen lands in nixpkgs.
+#   Tracking issue: https://github.com/NixOS/nixpkgs/issues/428077
+#   Draft nixpkgs PR: https://github.com/NixOS/nixpkgs/pull/428353
+#   When available, switch to pkgs.kdePackages.plasma-bigscreen.
+#
 # Upstream: https://invent.kde.org/plasma/plasma-bigscreen
-# Tracking: https://github.com/NixOS/nixpkgs/issues/428077
-# Based on: https://github.com/NixOS/nixpkgs/pull/428353
 {
   mkKdeDerivation,
   lib,
@@ -30,7 +34,7 @@
   libkscreen,
   kdeconnect-kde,
   # Qt 6
-  qtdeclarative,
+  qtdeclarative, # needed for Qt6::QmlPrivate — see QCoro workaround in postPatch
   qtmultimedia,
   qtwebengine,
   # Other
@@ -50,7 +54,6 @@ mkKdeDerivation {
     owner = "plasma";
     repo = "plasma-bigscreen";
     rev = "bd143fea7e386bac1652b8150a3ed3d5ef7cf93c";
-    # Build will fail with hash mismatch — copy the correct hash from the error
     hash = "sha256-y439IX7e0+XqxqFj/4+P5le0hA7DiwA+smDsD0UH/fI=";
   };
 
@@ -80,7 +83,7 @@ mkKdeDerivation {
     milou
     libkscreen
     kdeconnect-kde
-    # Qt
+    # Qt — qtdeclarative is needed for Qt6::QmlPrivate (see postPatch)
     qtdeclarative
     qtmultimedia
     qtwebengine
@@ -96,13 +99,16 @@ mkKdeDerivation {
     substituteInPlace bin/plasma-bigscreen-wayland.in \
       --replace @KDE_INSTALL_FULL_LIBEXECDIR@ "${plasma-workspace}/libexec"
 
-    # Plasma version numbers must match; we're building an unreleased package
-    # against a stable Plasma release.
+    # WORKAROUND: Plasma version numbers must match; we're building an
+    # unreleased package against a stable Plasma release. Remove once
+    # bigscreen is part of the Plasma release cycle.
     substituteInPlace CMakeLists.txt \
       --replace-fail 'set(PROJECT_VERSION "6.5.80")' 'set(PROJECT_VERSION "${plasma-workspace.version}")'
 
-    # QCoro6Qml links against Qt6::QmlPrivate but doesn't import it.
-    # Add find_package for Qt6QmlPrivate before QCoro is loaded.
+    # WORKAROUND: QCoro6Qml's cmake config links against Qt6::QmlPrivate but
+    # doesn't call find_package to import the target. This is arguably a QCoro
+    # packaging bug in nixpkgs (it should propagate qtdeclarative). Remove
+    # once QCoro or the nixpkgs plasma-bigscreen package is fixed upstream.
     substituteInPlace CMakeLists.txt \
       --replace-fail 'find_package(QCoro6' 'find_package(Qt6 ''${QT_MIN_VERSION} CONFIG REQUIRED COMPONENTS QmlPrivate)
 find_package(QCoro6'