diff --git a/flake.nix b/flake.nix
index 7411d21..e04ba59 100644
--- a/flake.nix
+++ b/flake.nix
@@ -56,7 +56,68 @@
         inherit pkgs system agenix;
       };
 
-      # Cross-compile overlay fixes for Hyprland and deps on aarch64
+       ##############################################################################
+      # CROSS-COMPILE WORKAROUNDS — packages that fail aarch64 cross-compile
+      #
+      # These packages need NATIVE COMPILATION on the uConsole itself (aarch64).
+      # They cannot cross-compile from x86_64 for various reasons listed below.
+      # We work around them in the overlay until we set up distributed builds
+      # with the uConsole as a native aarch64 builder.
+      #
+      # ==== Cross-compile failures ====
+      #
+      # libcamera / libcamera-rpi / libpisp:
+      #   meta.platforms excludes aarch64. pipewire hard-depends on them in nixos-25.11.
+      #   Fix: empty meta.platforms + strip from pipewire buildInputs.
+      #
+      # gjs:
+      #   Need native display (GTK3/4 tests) for cross-compile configure.
+      #   Fix: meson -Dskip_gtk_tests=true.
+      #
+      # hyprland:
+      #   Qt6Quick missing from aarch64 qtdeclarative, breaks hyprland-qt-support.
+      #   Fix: wrapRuntimeDeps=false (Qt UI components disabled, WM still works).
+      #
+      # boost.mpi:
+      #   Boost.Build has no b2 architecture alternatives for ARM.
+      #   Fix: useMpi=false.
+      #
+      # perl-ldap (perlPackages.perlldap):
+      #   Module::Install requires Perl dynamic loading (Fcntl) which is
+      #   unavailable in cross-compiled Perl.
+      #   Fix: stripped from john.s propagatedBuildInputs.
+      #
+      # john (John the Ripper):
+      #   Indirectly affected — depends on perl-ldap for perl utility scripts.
+      #   Fix: perl-ldap stripped from propagatedBuildInputs (john still works,
+      #   just loses sha-dump.pl etc. LDAP support).
+      #
+      # gss (GNU Generic Security Service):
+      #   autogen.sh fails cross-compile. Pulled by mailutils → emacs-pgtk.
+      #   Fix: emacs withMailutils=false.
+      #
+      # emacs-pgtk:
+      #   Indirectly affected — depends on mailutils which depends on gss.
+      #   Fix: withMailutils=false (no mail/IMAP within emacs).
+      #
+      # qtquick3d (Qt6):
+      #   Qt::Quick not available in aarch64 cross-compile qtdeclarative.
+      #   cmake skips build, ninja has no install target.
+      #   Fix: removed js8call, switched wireshark → wireshark-cli.
+      #
+      # js8call:
+      #   REMOVED from system packages. Depends on Qt6 multimedia → qtquick3d.
+      #
+      # wireshark-qt:
+      #   SWITCHED to wireshark-cli. Same Qt6 multimedia → qtquick3d chain.
+      #
+      # ==== How to build natively on uConsole ====
+      # To native-compile these on the uConsole:
+      # 1. Add uConsole as a remote builder (nix.buildMachines)
+      # 2. Set nix.extra-platforms = [ "aarch64-linux" ] on server
+      # 3. Remove the overlay workarounds below
+      # 4. Packages will auto-dispatch to uConsole for native builds
+      ##############################################################################
       uconsoleCrossOverlay = final: prev: {
         libcamera = prev.libcamera.overrideAttrs (_: { meta.platforms = []; });
         libcamera-rpi = prev.libcamera-rpi.overrideAttrs (_: { meta.platforms = []; });