# Project instructions

## Purpose

This repository checks one NVIDIA CMP 170HX at a time on a fresh Ubuntu 26.04 x86-64 host. The normal sequence is: prepare driver and tools, check PCIe lane width, install cmpunlocker for stock memory, cold boot, confirm unlocked memory, then check the final PCIe link. The capacitor width check passes at **x16**, even if the link is Gen1. A completed post-unlock card check passes only at **Gen2 x16**.

## Source and outputs

- `check_cards.py` owns the CLI, per-card flow, report scoring, and terminal result.
- `cxlib.py` owns host setup, the cmpunlocker harness clone/update and opt-in installer, card identity, subprocess logging, PCIe inspection, and optional VBIOS backup.
- `README.md` is the operator guide. Keep its flags, output paths, reboot steps, and exit codes aligned with the code.
- `harness/`, `cards/`, and `unidentified/` contain generated source, logs, reports, or firmware backups. Do not commit their contents.
- The bundled `nvflash_5.867_linux/` contains the optional backup tool. Backups belong under `extras/`, not at repository root.

## Invariants

- A card folder is named from an automatically read **physical serial number**. Never request manual serial entry or substitute a GPU UUID or PCI address for a serial. When serial lookup fails, continue the run under `unidentified/` and report the missing serial.
- Match every card-sensitive operation to the detected PCI address. A host may have another NVIDIA GPU even though only one CMP 170HX is being checked.
- Measure capacitor-related lane width before unlocking. The width result is independent of cmpunlocker: Gen1 x16 passes the width check, while x4 fails it. Do not claim the capacitor is physically verified; the width is an observed link result on the current host.
- Keep the final PCIe acceptance check after unlock. Preserve a red `[ERROR]` message and failing exit for any final link other than Gen2 x16. Gen1 x16 passes the earlier width check but fails the final card check.
- Preserve cold-boot state by card identity. GPU UUID may be used internally for this purpose, but not as a folder name.
- The cmpunlocker harness is cloned from upstream **main** into `harness/cmpunlocker/`, and `git pull --ff-only` runs before every install (a failed pull warns and continues with the existing checkout). Invoke `install.sh` only with flags the checked-out version actually accepts — currently **no flags**; never pass `--no-passthrough` to older checkouts without verifying them first.
- VBIOS backup is optional and read-only. Select the detected PCI address for nvflash and sysfs ROM operations. Never add a flashing step to the normal workflow.

## Working in this repository

- Git is **local only**. Do not run `git push`, `git remote` commands, or add a remote. Local status, diff, and commits are allowed.
- Do not run host setup, unlock, VBIOS, or PCIe mutation commands on a development machine. Those actions belong on the intended Ubuntu host when the user requests them.
- Keep reports and long-running installation logs visible and useful to an operator. Save full output on disk; show installation progress in the terminal.
- If asked to verify without a card, `python3 check_cards.py --demo` is the synthetic path. It does not establish hardware correctness.