[codex] Document Linux graphical QA machine plan

[Jesssullivan]

Summary

• record the decision that public graphical Linux QA should use physical installs or ordinary user-managed VMs
• add a first-pass distro/DE machine pool for Ubuntu, Fedora, Debian, Rocky, Arch-family, Mint, and NixOS targets
• thread the decision into the QA intake, distro readiness, and shard punchlist docs

Validation

• git diff --check

Linear

• TIN-732

[greptile-apps]

Greptile Summary

This PR adds docs/linux-graphical-qa-machine-plan.md, a new reference document recording the decision that public graphical Linux QA should use physical installs or ordinary user-managed VMs rather than the existing honey KVM/QEMU or NixOS desktop surfaces. It threads that decision and a first-pass distro/DE machine pool (Ubuntu, Fedora, Debian, Rocky, Arch-family, Mint, NixOS) into three existing docs.

The only issue is that the newly added markdown links in docs/linear-qa-shard-punchlist.md use absolute local filesystem paths (/Users/jess/git/cmux/…) that follow a pre-existing pattern in that file but will appear broken on GitHub for all other contributors.

Confidence Score: 4/5

Safe to merge — documentation-only changes with no code impact; two P2 style issues with absolute local paths in the punchlist.

All findings are P2 style issues (absolute local filesystem paths in markdown links). Content across all four docs is internally consistent and well-structured. No logic or code concerns.

docs/linear-qa-shard-punchlist.md — three markdown links (one in 'Use it with', two in QA-MACH-001 References) use absolute /Users/jess/git/cmux/… paths that won't resolve on GitHub.

Important Files Changed

Filename	Overview
docs/linux-graphical-qa-machine-plan.md	New document defining the graphical QA machine pool decision, priority matrix (P0/P1 distros/DEs), evidence requirements, and promotion rules — well-structured and internally consistent.
docs/linear-qa-shard-punchlist.md	Adds QA-MACH-001 shard and a 'Use it with' link, but both the new top-level link and the two References inside QA-MACH-001 use absolute local filesystem paths (/Users/jess/git/cmux/…) that break on GitHub and for other contributors.
docs/distro-testing-readiness-plan.md	Adds a 'Graphical human QA' section and cross-reference to the new plan doc — content is accurate and consistent with the rest of the PR.
docs/linux-qa-intake.md	Adds a graphical QA policy blurb and 'First Machine Targets' section; machine list is consistent with the new plan document.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    A[Graphical Linux QA Request] --> B{Machine type?}
    B -->|Physical install or user-managed VM| C[Public QA — source of truth]
    B -->|honey KVM/QEMU| D[Private lab: package proof only]
    B -->|NixOS desktop VM| E[Internal demos & early Nix reports]

    C --> F{Distro priority}
    F -->|P0| G[Ubuntu 24.04 GNOME\nFedora 42 GNOME\nFedora 42 KDE\nDebian 12 GNOME\nRocky 10.1 GNOME]
    F -->|P1| H[CachyOS KDE\nOmarchy Hyprland\nLinux Mint Cinnamon\nNixOS GNOME/Sway/Hyprland]

    G --> I[Collect evidence per linux-qa-intake.md]
    H --> I
    I --> J{Meets promotion rules?}
    J -->|One clean pass| K[Unblock early QA language]
    J -->|Repeated clean passes| L[Support stronger docs claims]
    J -->|Incomplete evidence| M[Hold — do not promote]

Loading

_{Reviews (1): Last reviewed commit: "Document Linux graphical QA machine plan" | Re-trigger Greptile}

[greptile-apps]

Absolute local filesystem path in markdown link

The newly added link uses /Users/jess/git/cmux/… — an absolute path that is valid only on the author's machine. It won't resolve on GitHub, in CI, or for any other contributor. The existing links in this file share the same pattern, but each new addition extends the problem. Consider using a repo-relative path instead.

Suggested change

	- [linux-graphical-qa-machine-plan.md](/Users/jess/git/cmux/docs/linux-graphical-qa-machine-plan.md:1)
	- [linux-graphical-qa-machine-plan.md](docs/linux-graphical-qa-machine-plan.md)

[greptile-apps]

Absolute local filesystem paths in QA-MACH-001 references

Same issue as the "Use it with" link above — both References entries in the new shard use absolute /Users/jess/git/cmux/… paths. These will appear as broken links on GitHub. Relative paths would work universally.

Suggested change

	- Fedora 42 KDE Plasma Desktop
	- Debian 12 GNOME; Xfce optional later
	- [linux-graphical-qa-machine-plan.md](docs/linux-graphical-qa-machine-plan.md)
	- [linux-qa-intake.md](docs/linux-qa-intake.md)