nixos-config/AGENTS.md at trunk

1. Record the current package and kernel baselines.

Evaluate the locked versions of Mutter, GNOME Shell, libdrm, and the selected CachyOS kernel.
Confirm that the Intel Arc B580 (8086:e20b) is using the xe driver.
Save the current working kernel and NixOS generation as the rollback baseline.

2. Pin all experimental upstream sources.

Pin Mutter merge request !3797 to a specific commit instead of following its branch.
Record the MR base commit and verify whether it is compatible with the Mutter version in the locked nixpkgs input.
Identify the exact revisions of the Intel async-flip and IN_FORMATS_ASYNC kernel patches referenced by the i915 and Xe work items.
Use fixed-output hashes for every fetched patch or source archive.

3. Determine which Intel DRM patches are still required.

Inspect the selected CachyOS kernel source for patches that have already been merged or backported.
Select only the missing patches needed to expose async-capable formats and prevent unchanged or disabled planes from incorrectly rejecting an async atomic commit.
Confirm that the selected changes affect the Intel display code shared by xe and i915, and therefore apply to the B580 even when the original report is filed under i915.
Document the required patch order and each patch's upstream URL and revision.

4. Add a dedicated, reversible Wayland-tearing overlay or module.

Keep the experimental Mutter and kernel overrides together in a new, clearly named repository file.
Scope the override to drivebystation-nix where practical.
Provide a single enable switch or isolated import so the experiment can be disabled without editing generated hardware configuration.
Preserve all unrelated existing worktree changes.

5. Override Mutter with merge request !3797.

Prefer applying the pinned MR commits to the nixpkgs Mutter derivation so nixpkgs build flags and dependency wiring are retained.
If the patch series is incompatible, use the pinned MR source only after confirming its Mutter ABI matches the installed GNOME Shell.
Verify that libdrm is at least version 2.4.120.
Ensure GNOME Shell and the display-manager session reference the overridden Mutter rather than merely installing it alongside the stock package.
Enable the experimental feature with MUTTER_DEBUG_EXPERIMENTAL_FEATURES=tearing in the session environment.

6. Override the CachyOS kernel with the selected Intel DRM patches.

Extend the existing pkgs.cachyosKernels.linuxPackages-cachyos-latest kernel derivation rather than replacing it with an unrelated kernel package set.
Apply the pinned patches in their upstream dependency order.
Verify that every patch applies cleanly to the exact CachyOS kernel source.
Keep boot.extraModulePackages tied to the patched kernel package set so r8125 and v4l2loopback are rebuilt against the correct kernel.
Do not modify the generated hardware-configuration.nix beyond any unavoidable existing kernel selection; place the override in a maintained host module.

7. Validate the Nix expressions without activating the system.

Run formatting and syntax checks on every changed Nix file.
Evaluate the complete drivebystation-nix configuration.
Run nix flake check and resolve evaluation failures attributable to these changes.
Confirm that all sources are pinned and reproducible and that no mutable branch names remain.

8. Build each risky component independently.

Build the overridden Mutter derivation.
Build the patched kernel derivation.
Build the matching r8125 and v4l2loopback modules.
Inspect the build logs for rejected patches, warnings related to async flips, and ABI mismatches.

9. Build the complete NixOS system before switching.

Build the drivebystation-nix toplevel without activating it.
Verify that the closure contains the pinned patched Mutter and patched CachyOS kernel.
Confirm that a previous known-good boot generation remains available.

10. Activate the result safely.

Use nixos-rebuild boot first so the new system is selected only after reboot.
Reboot into the patched generation and verify the running kernel version and xe driver binding.
If the display fails or the system is unstable, boot the previous generation and disable the experimental module.

11. Verify the kernel DRM capabilities.

Run drm_info and confirm atomic async-page-flip capability is reported.
Confirm IN_FORMATS_ASYNC is populated for supported primary planes.
Confirm its absence on the cursor plane is handled as expected rather than causing the entire commit to fail.
Capture a DRM debug log while submitting tearing-enabled fullscreen frames.

12. Test KDE Plasma tearing.

Enable Plasma's "Allow in fullscreen windows" tearing setting.
Run a fullscreen tearing-aware game or test client with frame rate above the monitor refresh rate.
Confirm that KWin's async atomic commits no longer fail with -EINVAL.
Confirm that the previous cursor A: async flip not supported and plane 2A: async flip not supported errors no longer occur for disabled or unchanged planes.
Check cursor movement, fullscreen entry and exit, direct scanout, VRR enabled and disabled, and all connected monitors.

13. Test GNOME Mutter tearing.

Start a GNOME Wayland session and confirm the tearing-control protocol is advertised.
Run weston-simple-egl -v -f -t or an equivalent tearing-aware client.
Confirm that requested asynchronous flips are accepted and visibly tear when the frame rate exceeds the refresh rate.
Confirm unsupported async commits fall back to synchronized presentation without breaking the session.
Test cursor movement, fullscreen transitions, VRR, multiple monitors, and suspend/resume.

14. Document results and removal criteria.

Record the tested hardware, kernel, Mutter, GNOME Shell, Plasma, and libdrm versions.
Record the exact patches used and the outcome of both compositor tests.
Document how to disable the overrides and roll back to the previous generation.
Note which upstream merge or kernel release will allow each local override to be removed.

CODE GENERATION INSTRUCTIONS