docs: complete Arch prerequisites and scope device setup notes

Document matching kernel headers, pacman dependencies, repository checkout, mode-switch destination creation and MCU1 branch selection. Distinguish missing DKMS builds from stale module indexes and firmware-loader IDs from working interfaces. Correct the installer support claim and explain the NetworkManager connectivity penalty with its upstream reference.

Keeps the contributor-reported Lukton DQ-211 results scoped to that unit. Validation: all Bash examples parse, local links resolve, and commands were checked against the repository installer, Makefile, AUR packaging and upstream documentation. Follow-up corrections for #109; no Arch hardware test is claimed.

INSTALL_ARCH.md

@@ -1,9 +1,14 @@
 # Arch Linux / CachyOS install notes
 
-Notes for installing the AIC8800D80 driver on Arch-based distributions, where
+Notes for installing the AIC8800D80 driver on Arch-based distributions.
-the `install.sh` helper (written for Ubuntu/Debian/Fedora and derivatives) is
+The repository's [quick installer](INSTALL_SCRIPT.md) already supports
-not the most convenient path or cannot manage DKMS rebuilds for rolling
+pacman and DKMS, including automatic rebuilds for kernel updates. This page
-kernels.
+also covers the AUR package, manual installation, and device setup.
+
+Choose the hardware branch described in the [README](README.md) first.
+Adapters reporting `chip_mcu_id=1` need the matched `legacy-mcu1` driver and
+firmware. The AUR package inspected for these notes tracks `main`; use the
+repository installer or manual method from `legacy-mcu1` for MCU1 hardware.
 
 ## Tested device
 
@@ -15,43 +20,98 @@ kernels.
 - After the Pandora `F3`+`F2` mode switch it re-enumerates as
   `a69c:8d80 aicsemi AIC Wlan`.
 
-## Tested on
+## Contributor-reported testing
 
 - CachyOS, kernel `7.2.0-1-cachyos` and `6.18.42-1-cachyos-lts`.
 - Wi-Fi 6 (HE) association and traffic confirmed; Bluetooth bound to `btusb`.
 
+These results describe one Lukton DQ-211 unit, not all adapters sold as 88M80.
+
+## Prerequisites
+
+Update the system before installing build dependencies. Reboot first if the
+update replaces the running kernel, so its matching headers are available:
+
+```bash
+sudo pacman -Syu
+```
+
+```bash
+sudo pacman -S --needed base-devel dkms git usb_modeswitch usbutils iw
+```
+
+Install headers for **each kernel that should receive a DKMS build**. Examples:
+
+| Kernel package | Header package |
+| --- | --- |
+| `linux` | `linux-headers` |
+| `linux-lts` | `linux-lts-headers` |
+| `linux-cachyos` | `linux-cachyos-headers` |
+
+For example, on the standard Arch `linux` kernel:
+
+```bash
+sudo pacman -S --needed linux-headers
+```
+
+Choose the corresponding package for other CachyOS or custom kernels; installing
+`linux-headers` alone does not provide headers for those kernels. See the
+[Arch DKMS instructions](https://wiki.archlinux.org/title/Dynamic_Kernel_Module_Support).
+Confirm the running kernel has a build tree before continuing:
+
+```bash
+uname -r
+test -r "/usr/lib/modules/$(uname -r)/build/Makefile"
+```
+
+If the check fails, install the matching headers or reboot into the kernel
+whose headers are installed. Use one installation method below to keep
+package ownership and DKMS registration consistent.
+
 ## Option A: AUR package (recommended on Arch)
 
 The `aic8800d80-dkms` package in the AUR packages this driver and its firmware
-with DKMS, rebuilding automatically for each installed kernel:
+with DKMS, rebuilding automatically for installed kernels with matching headers.
+With an already installed AUR helper such as `yay`, run as your normal user:
 
 ```bash
-sudo pacman -S --needed dkms base-devel
 yay -S --needed aic8800d80-dkms
 ```
 
 The package installs the firmware under `/lib/firmware/aic8800D80/` and installs
 `aic.rules` to `/usr/lib/udev/rules.d/`.
 
-### The mode-switch config file is not shipped by the AUR package
+### Check the mode-switch config file
 
 `aic.rules` runs `usb_modeswitch -c /etc/usb_modeswitch.d/1111:1111`, but that
-config file must exist or the switch is a no-op. Copy it from the repository
+config file must exist or the switch fails. The inspected AUR package
-(note the colon in the filename on Linux):
+(`pkgrel=6`, 2026-10-19) does not install it. If the file is missing, obtain
+it from the repository (note the colon in the destination filename):
 
 ```bash
-sudo cp usb_modeswitch/1111_1111 "/etc/usb_modeswitch.d/1111:1111"
+git clone https://github.com/shenmintao/aic8800d80.git
-sudo udevadm control --reload
+cd aic8800d80
+sudo install -Dm644 usb_modeswitch/1111_1111 "/etc/usb_modeswitch.d/1111:1111"
+sudo udevadm control --reload-rules
 ```
 
-Without this file the adapter stays in CD mode (`1111:1111`) and no interface
+Unplug and reconnect the adapter after installing the file. Without it, this
-appears.
+rule cannot switch the reported unit out of CD mode (`1111:1111`).
 
 ### Refresh the module index
 
-The DKMS modules land in `updates/dkms/`, which the kernel only finds after
+DKMS normally refreshes the module index during installation. If
-`depmod`. If `modprobe aic8800_fdrv` reports `Module not found` right after
+`modprobe aic8800_fdrv` reports `Module not found`, first check that DKMS
-installation:
+reports the module as **installed for the running kernel**:
+
+```bash
+dkms status
+uname -r
+```
+
+If that kernel has no installed module, resolve its headers/build failure;
+`depmod` does not build missing modules. If the module is already installed,
+refresh the index and retry:
 
 ```bash
 sudo depmod -a "$(uname -r)"
@@ -60,28 +120,40 @@ sudo modprobe aic8800_fdrv
 
 ## Option B: manual install from this repository
 
-```bash
+After the prerequisites above, build first. For MCU1 hardware, replace
-git clone https://github.com/shenmintao/aic8800d80.git
+`--branch main` with `--branch legacy-mcu1` in the clone command:
-cd aic8800d80
 
+```bash
+git clone --branch main https://github.com/shenmintao/aic8800d80.git
+cd aic8800d80
+make -C drivers/aic8800
+```
+
+Only after the build succeeds, install from the same repository directory:
+
+```bash
 # remove any previous AIC firmware first — a mismatched version can freeze the system
 sudo rm -rf /lib/firmware/aic8800*
 
-sudo cp aic.rules /usr/lib/udev/rules.d/
 sudo cp -r ./fw/aic8800* /lib/firmware/
-sudo cp usb_modeswitch/1111_1111 "/etc/usb_modeswitch.d/1111:1111"
+sudo install -Dm644 aic.rules /usr/lib/udev/rules.d/aic.rules
-sudo udevadm control --reload
+sudo install -Dm644 usb_modeswitch/1111_1111 "/etc/usb_modeswitch.d/1111:1111"
-
+sudo make -C drivers/aic8800 install
-cd drivers/aic8800
+sudo udevadm control --reload-rules
-make
-sudo make install
-sudo depmod -a "$(uname -r)"
 sudo modprobe aic8800_fdrv
 ```
 
-The manual path has no DKMS: after every kernel update you must rerun
+Unplug and reconnect the adapter. The manual path has no DKMS: after kernel
-`make clean && make && sudo make install`. Prefer Option A on rolling-release
+updates, install matching headers and rerun these commands from the repository:
-distributions.
+
+```bash
+make -C drivers/aic8800 clean
+make -C drivers/aic8800
+sudo make -C drivers/aic8800 install
+```
+
+The install target runs `depmod` itself. Prefer a DKMS method for automatic
+rebuilds on rolling-release distributions.
 
 ## Why the driver loads automatically after the switch
 
@@ -90,12 +162,16 @@ re-enumerates as `a69c:8d80` the kernel loads the driver on its own — no
 `modules-load.d` entry is needed. The full plug sequence is:
 
 `1111:1111` → `aic.rules` → `usb_modeswitch -c /etc/usb_modeswitch.d/1111:1111`
-→ `a69c:8d80` → kernel autoloads `aic_load_fw` → firmware upload → `wlanX`.
+→ `a69c:8d80` → kernel autoloads `aic_load_fw` → firmware upload
+→ operational USB identity → `aic8800_fdrv` → wireless interface.
+
+`a69c:8d80` is the firmware-loader identity; reaching it alone does not mean
+Wi-Fi initialization succeeded.
 
 ## Connecting and route priority (NetworkManager)
 
-The adapter shows up as a second wireless interface (for example `wlan1`, next
+The following commands assume NetworkManager is installed and managing Wi-Fi.
-to an onboard `wlan0`):
+Find the adapter's interface name first (`wlan1` is only an example):
 
 ```bash
 nmcli device status
@@ -109,10 +185,17 @@ sudo nmcli con mod "<SSID> 1" ipv4.route-metric 300 ipv6.route-metric 300
 sudo nmcli con up "<SSID> 1"
 ```
 
-Note: on some NetworkManager versions the effective DHCP route metric ends up
+NetworkManager can add a `20000` route-metric penalty when an interface fails
-offset (observed `300` → `20300`), which still leaves the onboard radio
+its global connectivity check, which can explain an observed `300` → `20300`.
-preferred. If that happens, disable autoconnect on the onboard profile so the
+Check connectivity before treating this as a driver or metric-setting failure;
-adapter owns the default route:
+see the [NetworkManager connectivity documentation](https://networkmanager.pages.freedesktop.org/NetworkManager/NetworkManager/NetworkManager.conf.html).
+
+```bash
+nmcli networking connectivity check
+```
+
+If you intentionally want only the adapter's connection active, disable
+autoconnect on the onboard profile and disconnect it:
 
 ```bash
 sudo nmcli con mod "<onboard-profile>" connection.autoconnect no
@@ -122,7 +205,7 @@ sudo nmcli con down "<onboard-profile>"
 ## Verification
 
 ```bash
-lsusb | grep -E "1111:1111|a69c"
+lsusb | grep -iE "1111:1111|a69c|368b"
 lsmod | grep -E "aic8800_fdrv|aic_load_fw"
 iw dev
 nmcli device status
@@ -130,11 +213,12 @@ ip route show default
 sudo dmesg | grep -i aic
 ```
 
-A successful bring-up shows `HE supp 1` in the driver log (802.11ax / Wi-Fi 6)
+The log line `HE supp 1` indicates HE capability. Use `iw dev <interface> link`
-and a new `wlanX` interface.
+and actual network traffic to check the active connection.
 
 ## Notes
 
 - The onboard-vs-adapter interface names are not fixed; confirm with `iw dev`.
-- As with other Pandora clones, `usb_modeswitch -K/-J` and `eject` do not
+- The reported unit used the vendor `F3`+`F2` sequence. Other adapters sold
-  perform the switch — only the vendor `F3`+`F2` CDBs do.
+  under similar names can require different switching or firmware profiles;
+  see [issue #79](https://github.com/shenmintao/aic8800d80/issues/79).

INSTALL_SCRIPT.md

@@ -17,7 +17,7 @@ module without replacing the distribution's `btusb.ko`.
 - Wi-Fi-only and Wi-Fi/Bluetooth combo adapter support from the same branch
 - Comprehensive error handling
 - Colored output and logging
-- Compatible with Ubuntu, Debian, Fedora, and derivatives (DKMS supported `dkms.conf`)
+- Compatible with Ubuntu, Debian, Fedora, Arch Linux, and derivatives (DKMS supported `dkms.conf`)
 
 ## Usage
 

README.md

@@ -87,8 +87,8 @@ must pass the wireless stack version separately.
 
 For Arch-based distributions (Arch, CachyOS, …), see
 [Arch Linux / CachyOS install notes](INSTALL_ARCH.md) — including the AUR/DKMS
-path, the `/etc/usb_modeswitch.d/1111:1111` file the AUR package does not ship,
+path, matching kernel headers, mode-switch configuration, and module-index
-and the `depmod` step needed after DKMS installation.
+troubleshooting.
 
 #### Method 1: [Quick Installation](INSTALL_SCRIPT.md) (Recommended)