Write A Stick

Write a LexiSuite stick

Status, 11/11/2026: native Windows write path added, not hardware-qualified. Linux image-file fixtures exist; macOS remains untested. The Windows writer now has code to lock/dismount all discovered volumes, write an aligned physical disk and verify the complete readback, but it has not been compiled or exercised on Windows hardware. The shell script install-to-usb.sh remains the established Linux method until the new writer passes release qualification.

lexisuite-flash is the command-line image writer distributed on the LEXISUITE volume. It checks a downloaded image, lists eligible USB disks, asks for a typed confirmation, writes the image, and reads it back to check its SHA-256 digest. The selected USB disk will be erased.

Usage

1. Put LexiSuite-*.img or LexiSuite-*.img.xz and its matching *.sha256 file in the same folder. Verify that the checksum comes from a trusted release channel.
2. Connect a removable USB stick larger than the uncompressed image. On Linux, unmount all partitions before running the tool; on Windows the native writer attempts to lock and dismount every volume associated with the chosen disk (and refuses the operation if any lock or dismount fails). Never select the disk running the system or holding a system folder.
3. Run lexisuite-flash --list, then lexisuite-flash --image LexiSuite.img.xz --target DEVICE --dry-run to validate the image and disk selection without writing.
4. Run lexisuite-flash --image LexiSuite.img.xz --target DEVICE with administrative privileges. Type the exact serial displayed in the confirmation prompt, or the disk capacity in bytes if it has no serial.
5. Remove the stick only after the writer reports that it finished flushing and the complete readback matched. If any stage fails after writing starts, the stick is not verified and must not be booted.

DEVICE is the disk identifier listed by the utility, not a partition (Linux sdb, macOS disk2, Windows PhysicalDrive2). Never substitute the internal disk. The program does not download or execute remote images and does not require a temporary extracted image. The SHA-256 sidecar authenticates transmission integrity, not the provenance or signature of the release.

Platform support and limitations

• Linux: Enumerates removable USB whole disks through sysfs, correlates active mounts and swaps, and verifies the opened block-device identity before writing. Run with the required block device access (usually sudo). Mounted disks are refused; unmount them separately first. The legacy script remains available until all release images ship the new binary.
• macOS: Discovers external physical disks using diskutil ... -plist, checks disk properties and attempts diskutil unmountDisk before opening /dev/rdiskN. Run with administrator permissions. Use only USB/removable devices, and unmount mounted volumes before running.
• Windows (unqualified): Lists PhysicalDriveN devices through Windows storage management, refuses anything other than external USB media, and checks the boot/system/read-only flags, serial/model identity and capacity again before commitment. A native device-control bridge uses IOCTL_STORAGE_QUERY_PROPERTY to verify the USB bus and IOCTL_DISK_GET_LENGTH_INFO for capacity. It enumerates volume GUIDs (including volumes without drive letters), obtains a pure, sorted lock plan from the Rust writer, and holds every FSCTL_LOCK_VOLUME / FSCTL_DISMOUNT_VOLUME handle until completion. It opens the raw physical disk with no buffering and write-through enabled, writes aligned whole-sector blocks, flushes, and computes SHA-256 of an aligned full readback. A stale backup GPT at the old end of a larger disk is cleared. Failures leave the disk unverified. The bridge uses the Windows-included PowerShell/.NET compiler to call the native APIs and therefore requires an elevated, unrestricted Windows PowerShell session; it may refuse execution under Constrained Language Mode or where volume extent enumeration is unavailable. This has not had an MSVC check or an end-to-end Windows disk test. Do not treat it as a qualified release writer yet.

On every platform, --dry-run never opens a target for writing. Do not use an unverified or modified image; the utility checks the *.sha256 sidecar, XZ block and index checksums, and the output it reads back. Hardware write/readback checks must be performed on a sacrificial removable stick before release. Disk and capacity observations can change between discovery and commit; the utility checks them again and refuses changed selections. The Windows/macOS builds and native-device behavior remain unverified until built and tested on those systems.

Windows-specific safety and testing

Unlike Linux, ordinary mounted USB data volumes are not an automatic refusal on Windows: the native writer must enumerate, lock and dismount them first. A protected system or boot disk, an internal/non-USB disk, bad identity, insufficient capacity or unaligned image is still rejected before destructive access. A volume extent read failure, unknown volume, lock failure or dismount failure aborts without proceeding to raw writes. The lock-order list is checked for malformed/duplicate volume GUIDs and is exercised by g3_07_volume_lock_order_refuses_duplicates_and_malformed_guids; geometry and protected disk refusal contracts are covered by g3_07_sector_alignment_for_native_windows_io, g3_07_volume_mount_policy_refuses_system_and_non_usb, g3_07_windows_inventory_system_flags_override_usb_bus, g3_07_non_usb_boot_and_bad_geometry_refused_before_open and g3_07_dry_run_does_not_invoke_native_writer.

Those are portable tests, not physical-device evidence. Before distribution, run an MSVC check, a non-destructive Windows dry-run, a sacrificial USB image write/readback, injected lock and flush failures, automatic-mount race and disk replacement tests, on at least Windows 10 and Windows 11. Disk enumeration is fail-closed if volume extent information is not readable. Do not use an unqualified writer on media that contains data you need.