opensite-ai/opensite-skills / linux-install-planner
linux-install-planner
FlaggedGenerate a safe, step-by-step runbook for installing Linux on a physical machine (replacing Windows, dual-booting, or a clean install) for a human sitting at the computer. Use when someone needs instructions to wipe Windows and install Linux, create bootable USB media, enter UEFI/BIOS, disable Secure Boot or Fast Startup, handle BitLocker or Intel RST, partition and encrypt a disk with LUKS, walk through a distro installer, or finish first-boot setup (drivers, firmware, power management). It emits instructions for a person to follow; it does not perform the install itself.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 10.6 KB |
| agents/openai.yaml | config | 454 B |
| examples/dell-xps-full-wipe-ubuntu.md | markdown | 5.6 KB |
| references/activation.md | markdown | 2.7 KB |
| references/bootable-media.md | markdown | 5.2 KB |
| references/first-boot-checklist.md | markdown | 4.1 KB |
| references/laptop-fixes.md | markdown | 4.2 KB |
| references/partitioning-encryption.md | markdown | 5.4 KB |
| references/uefi-secureboot.md | markdown | 5.0 KB |
| templates/install-runbook.md | markdown | 4.2 KB |
references/laptop-fixes.md
View on GitHub# Reference — Phase 7: Common Laptop Pain Points & Fixes
> Personalize the runbook with only the fixes that match the user's hardware
> (from the Phase 1 recon). Commands are run at the machine; versions are "as of
> 2026-07 — verify."
---
## 7.1 NVIDIA hybrid graphics (Optimus)
- **Best path:** pick a distro that handles it — **Pop!_OS NVIDIA ISO**
(preconfigured, ships a GPU switcher) or Ubuntu with `nvidia-driver` + built-in
**PRIME**.
- **Default to hybrid / render-offload:** the iGPU drives the display for battery;
run a specific app on the dGPU:
- `prime-run <app>` (Arch), or the official NVIDIA method:
`__NV_PRIME_RENDER_OFFLOAD=1 __GLX_VENDOR_LIBRARY_NAME=nvidia <app>`
- **Ubuntu:** `prime-select on-demand|nvidia|intel`
- **Pop!_OS:** GPU switcher in the top bar
- Alternatives: `optimus-manager` (Arch) or `switcheroo-control`
(desktop-integrated; also handles AMD/Intel)
- **Symptoms to expect:**
- Black screen on first boot after driver install — usually a pending **MOK
enrollment**; reboot and complete the blue MOK screen (Secure Boot on).
- External HDMI ports wired to the dGPU only — needs the dGPU active to output.
- **Wayland vs Xorg:** NVIDIA + Wayland (default on Fedora/GNOME) is solid on
recent drivers (555+); older setups may prefer Xorg.
---
## 7.2 Wi-Fi firmware
Have a **USB-Ethernet adapter or phone USB-tethering** ready during install so the
user can pull drivers if Wi-Fi is missing on the live USB.
- **Broadcom** (PCI IDs `14e4:`): often no Wi-Fi on the live USB. Install
post-boot over Ethernet/tether:
- **Ubuntu:** `bcmwl-kernel-source` (or `firmware-b43-installer`)
- **Arch:** `broadcom-wl` / `broadcom-wl-dkms` for newer chips, `b43-firmware`
for old. If both could apply, **prefer `broadcom-wl`** (b43 has known freezes
on BCM4331). Newest chips use in-kernel `brcmfmac` with firmware from
`linux-firmware`.
- **Realtek USB/PCIe** (e.g. RTL8821CE, early RTL8852): install `linux-firmware`;
for unsupported chips use a community DKMS repo (e.g. `rtl8821ce-dkms`). Modern
kernels (6.11+) cover most.
- **Intel / MediaTek:** generally excellent; work on the live USB.
---
## 7.3 Battery life
- Confirm only **one** power manager is active (see the first-boot reference).
- Inspect and auto-tune: `sudo powertop --auto-tune`.
- Enable **TLP** for more savings (then mask power-profiles-daemon). Set battery
**charge thresholds** on ThinkPads and other supported machines.
- For Intel, confirm **S0ix** works (see 7.4).
---
## 7.4 Suspend: S3 vs Modern Standby (s2idle)
Check what the machine offers:
```bash
cat /sys/power/mem_sleep # [s2idle] deep => s2idle is the active mode
```
Many 2020+ laptops are **s2idle / Modern Standby only** (no S3 in firmware).
s2idle should match S3 savings but on some machines drains the battery in a bag
(the "hot bag" problem). Fixes, in order:
1. **BIOS update** (`fwupd`) — the most common real fix.
2. If firmware exposes a "Sleep mode: Windows / Linux (S3)" toggle, choose
**Linux/S3**.
3. If `deep` (S3) is listed but not the default, add the kernel parameter
`mem_sleep_default=deep` (via `/etc/default/grub`
`GRUB_CMDLINE_LINUX_DEFAULT`, or a systemd-boot entry), then update the
bootloader config.
4. **AMD:** use `amd_s2idle` / `amd-debug-tools`. **Intel:** use
`S0ixSelftestTool` to find the device blocking deep idle.
---
## 7.5 HiDPI / fractional scaling
- **Wayland (GNOME/KDE)** handles HiDPI best — prefer it on HiDPI laptops and for
mixed-DPI multi-monitor setups (per-monitor scaling).
- **GNOME** fractional scaling (125 / 150 / 175 %) is on by default in recent
releases; if not:
```bash
gsettings set org.gnome.mutter experimental-features "['scale-monitor-framebuffer']"
```
then pick the percentage in `Settings → Displays`. **KDE Plasma** has a native
scaling slider.
- **Xorg** cleanly does integer scaling only; fractional via `xrandr --scale` is
blurry and heavier. Prefer Wayland for HiDPI.
---
## Sources (authoritative)
- Arch Wiki — NVIDIA Optimus / PRIME; Broadcom wireless; Power management; TLP;
Suspend and hibernate (`mem_sleep`); HiDPI
- NVIDIA — PRIME render offload docs
- Kernel/vendor tools — `amd-debug-tools`, Intel `S0ixSelftestTool`, `powertop`
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack." | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |