# Hermes Portable Rescue — Architecture Document

**Status:** Draft v1.0  
**Author:** Kanban Orchestrator (t_25bcd02c)  
**Date:** 2026-07-04  
**Dependencies:** Research T1 (boot-env), T2 (llm-strat), T3 (pc-repair-workflows)  

---

## Table of Contents

1. [Executive Summary](#1-executive-summary)
2. [Chosen Boot Environment](#2-chosen-boot-environment)
3. [USB Layout & Filesystem](#3-usb-layout--filesystem)
4. [LLM Strategy](#4-llm-strategy)
5. [Tool Packaging Strategy](#5-tool-packaging-strategy)
6. [Portable Hermes Runtime Structure](#6-portable-hermes-runtime-structure)
7. [Auto-Launch Flow on Boot](#7-auto-launch-flow-on-boot)
8. [Diagnostic Pipeline Order](#8-diagnostic-pipeline-order)
9. [Build Pipeline](#9-build-pipeline)
10. [Risks & Mitigations](#10-risks--mitigations)

---

## 1. Executive Summary

Hermes Portable Rescue is an **LLM-driven autonomous diagnostic and repair USB toolkit**. The target user inserts a USB drive into a broken Windows PC, boots from it, and an AI agent auto-launches, diagnoses the system (BSOD analysis, hardware inventory, stress tests, disk health), and guides the repair process.

**Architecture at a glance:**

| Component | Decision | Rationale |
|-----------|----------|-----------|
| **Bootloader** | Ventoy | GPL-licensed, MS-signed Secure Boot, multi-ISO capable |
| **Primary OS** | Custom Arch Linux ISO (archiso) | glibc-based, Python-native, full package manager, latest kernel |
| **Secondary OS** | WinPE ISO (optional) | Native chkdsk/sfc/dism for Windows-targeted repairs |
| **Persistence** | NTFS data partition | Survives across sessions, readable from Windows |
| **LLM Runtime** | llama.cpp (CPU) | Offline-capable, no GPU needed |
| **LLM Model (Primary)** | Qwen2.5-7B-Instruct Q4_K_M (~4.3 GB) | Best-in-class structured reasoning at 7B size |
| **LLM Model (Fallback)** | Phi-3-mini-3.8B Q4_K_M (~2.2 GB) | Runs on any hardware (4 GB+ RAM) |
| **API Fallback** | opencode.go / Ollama | Unlocks GPT-4-class reasoning when network is available |
| **USB Size Target** | 32 GB minimum (64 GB ideal) | Fits OS + both models + tools + output space |

---

## 2. Chosen Boot Environment

### Primary: Ventoy + Custom Arch Linux ISO

**Ventoy** serves as the bootloader foundation. It installs a tiny (~10 MB) bootloader on the USB, and ISOs are simply copied as files to the FAT32 partition. Ventoy handles UEFI, Legacy BIOS, and Secure Boot via Microsoft-signed shim.

**Arch Linux (archiso)** was chosen as the live environment for the following reasons:

- **glibc-based** — full Python 3.11+ compatibility (unlike Alpine's musl)
- **Rolling release** — latest kernel (6.x), best driver support for NVMe, USB3, modern chipsets
- **archiso tooling** — fully customizable ISO builds (pre-install Python, pip, all tools)
- **Package manager (pacman)** — can install additional tools live (TTY-only if needed)
- **~800 MB base** — leaves room for models and tools on a 32 GB USB
- **GPL-licensed** — completely free to redistribute (no WinPE licensing headaches)

### Secondary: WinPE ISO (Optional Add-on)

A WinPE-based ISO (such as Hiren's Boot CD PE, ~2.5 GB) can be included as a companion for:

- Running native Windows tools (chkdsk, sfc, DISM, diskpart)
- BitLocker management (manage-bde)
- Any scenario where Windows-native tooling is strictly required

### Why NOT WinPE as Primary

- **Restrictive licensing** for redistribution
- **Python bootstrap is fragile** — must bundle embedded distribution + VC runtime DLLs + pip
- **No package manager** — all dependencies must be pre-bundled
- **Higher engineering cost** for less capability

### Boot Selection Flow

```
Ventoy Boot Menu
  ├── 1. Hermes Rescue (Arch Linux) — DEFAULT, auto-boot after 10s
  │     └── Auto-launches Hermes agent
  ├── 2. Windows PE (Optional) — Manual selection
  │     └── Manual tool use
  └── 3. Boot from local disk — Bypass rescue
```

---

## 3. USB Layout & Filesystem

```
USB Drive (≥32 GB)
━━━ EFI System Partition (FAT32, ~500 MB)
    └── Ventoy bootloader (EFI/BOOT/, EFI/ventoy/)
━━━ ISO/ (FAT32 or exFAT, copy ISOs here)
    ├── hermes-rescue-linux.iso          ~1 GB  (custom Arch Linux)
    ├── hirens-boot-cd-pe.iso            ~2.5 GB (optional WinPE)
    └── memtest86plus.iso                ~20 MB  (RAM tester, optional)
━━━ DATA/ (NTFS, uses remainder of drive)
    ├── hermes/
    │   ├── config.yaml                  — Hermes agent config
    │   ├── models/
    │   │   ├── qwen2.5-7b-q4_k_m.gguf  — Primary LLM (~4.3 GB)
    │   │   └── phi3-mini-q4_k_m.gguf    — Fallback LLM (~2.2 GB)
    │   ├── logs/
    │   │   └── session_YYYYMMDD_HHMMSS.log
    │   ├── diagnostics/
    │   │   ├── hardware_report_*.json
    │   │   ├── bsod_analysis_*.json
    │   │   ├── stress_test_*.json
    │   │   └── driver_scan_*.json
    │   ├── backups/
    │   │   ├── registry/                — Registry hive exports
    │   │   ├── system_files/            — File-level backups
    │   │   └── disk_images/             — DD/partclone images
    │   └── scripts/
    │       ├── custom_recovery.sh       — User-customizable repair script
    │       └── post_diagnostic_hook.sh  — Runs after diagnostics complete
    └── hermes_agent.squashfs            — Bundled Hermes runtime (see §6)
```

### Partition Table

| Partition | Size | FS | Label | Purpose |
|-----------|------|----|-------|---------|
| /dev/sda1 | ~500 MB | FAT32 | VTOYEFI | Ventoy boot + EFI |
| /dev/sda2 | ~16 GB | FAT32/exFAT | VTOYISO | ISOs (Ventoy reads ISOs from any partition) |
| /dev/sda3 | Remainder | NTFS | DATA | Persistence, config, models, logs |

**Why NTFS for DATA:** Windows-readable without extra tools, supports large files (models), journaled for crash recovery.

---

## 4. LLM Strategy

### Decision: Hybrid Local-First + API Fallback

```
                    ┌──────────────┐
                    │  User boots  │
                    │  from USB    │
                    └──────┬───────┘
                           │
                    ┌──────▼───────┐
                    │  Hermes CLI  │
                    │  auto-starts │
                    └──────┬───────┘
                           │
              ┌────────────┴────────────┐
              │                         │
     ┌────────▼────────┐      ┌─────────▼─────────┐
     │   Qwen2.5-7B    │      │  Network Available?│
     │   Q4_K_M (LOCAL)│      │         │          │
     │   ~5 GB RAM     │      │    YES  │  NO      │
     │   ~15-25 tok/s  │      │         │          │
     └────────┬────────┘      └────┬────┘          │
              │                    │               │
              │         ┌──────────▼──┐            │
              │         │ API Fallback│            │
              │         │(opencode.go│            │
              │         │  or Ollama) │            │
              │         └──────────┬──┘            │
              │                    │               │
              └────────┬───────────┘               │
                       │                           │
                       └──────┬────────────────────┘
                              │
                    ┌─────────▼────────┐
                    │  Fallback:       │
                    │  Phi-3-mini Q4   │
                    │  ~2.9 GB RAM     │
                    │  (if primary     │
                    │   won't load)    │
                    └─────────────────┘
```

### Local Models

| Role | Model | Quant | File Size | RAM Needed | tok/s |
|------|-------|-------|-----------|------------|-------|
| **Primary** | Qwen2.5-7B-Instruct | Q4_K_M | ~4.3 GB | ~5.0 GB | 15-25 |
| **Fallback** | Phi-3-mini-4k-instruct | Q4_K_M | ~2.2 GB | ~2.9 GB | 25-40 |

**Model selection rationale:**
- Qwen2.5-7B offers best-in-class **structured reasoning** for BSOD analysis (parsing bugcheck codes, parameter dumps) and **instruction following** for multi-step diagnostic workflows
- Phi-3-mini as fallback covers 4 GB RAM systems where Qwen won't fit
- Both run **CPU-only** via llama.cpp — no GPU required

### API Fallback

When the target PC has internet access, the agent can fall back to:
- **opencode.go** (recommended) — for complex multi-step diagnosis
- **Ollama server** query — if the user has Ollama on their home network
- **OpenAI-compatible API** — for any compatible provider

The API fallback enables GPT-4-class reasoning for edge cases the local model cannot handle (unusual BSOD codes, complex driver chains, recovery planning).

### USB Storage Budget

| Component | 32 GB USB | 64 GB USB |
|-----------|-----------|-----------|
| OS ISO | 1.0 GB | 1.0 GB |
| Primary model (Qwen Q4_K_M) | 4.3 GB | 4.3 GB |
| Fallback model (Phi-3 Q4_K_M) | 2.2 GB | 2.2 GB |
| Tools + Runtime | 2.0 GB | 2.0 GB |
| WinPE ISO (optional) | 2.5 GB | 2.5 GB |
| **Total (with WinPE)** | **12.0 GB** | **12.0 GB** |
| **Remaining for output** | **~20 GB** | **~52 GB** |

Both model files fit comfortably on 32 GB+ USB.

---

## 5. Tool Packaging Strategy

### Bundled on the Arch Linux ISO

Pre-installed via pacman into the custom ISO:

**Core diagnostics:**
- `smartmontools` — SMART health checks
- `dmidecode` — DMI/BIOS information
- `lshw` — full hardware inventory
- `lspci` / `lsusb` — PCI/USB device enumeration
- `ddrescue` — disk rescue imaging
- `testdisk` / `photorec` — partition recovery + file recovery
- `ntfs-3g` — NTFS read/write
- `dislocker` — BitLocker volume access
- `parted` / `gpart` — partition management

**Stress & burn-in:**
- `stress-ng` — CPU/RAM stress testing (with thermal monitoring)
- `memtest86+` (separate ISO on USB, bootable via Ventoy) — dedicated RAM test

**Network & connectivity:**
- `curl` / `wget` — HTTP/HTTPS
- `openssh` — SSH client for remote support
- `networkmanager` — WiFi/Ethernet management

**Python ecosystem:**
- `python` (3.11+)
- `python-pip`
- `python-setuptools`
- `python-virtualenv`

### Bundled in the DATA partition

- **Hermes runtime** (`hermes_agent.squashfs`) — squashfs archive of the Hermes Python environment with all dependencies
- **GGUF model files** (`models/`) — Qwen2.5-7B + Phi-3-mini
- **Config** (`config.yaml`) — Hermes agent configuration
- **SquashFS mount script** — mounts runtime at boot

### Not Bundled (Downloaded on Demand if Network Available)

- Full OS updates (kernel, packages via pacman)
- Additional models (if user wants larger quantizations)
- Windows driver packages (sourced from vendor websites)

---

## 6. Portable Hermes Runtime Structure

```
DATA/hermes_agent.squashfs  (compressed, ~200-400 MB)
  ├── venv/
  │   ├── bin/
  │   │   ├── python3          — Python 3.11 interpreter
  │   │   ├── hermes           — Hermes CLI entry point
  │   │   └── llama-cli        — llama.cpp inference binary (static)
  │   └── lib/python3.11/
  │       └── site-packages/
  │           ├── hermes/      — Hermes agent core
  │           ├── pyyaml/      — YAML config parsing
  │           ├── requests/    — HTTP client
  │           └── [deps]       — All pip dependencies
  ├── src/hermes_portable/
  │   ├── __init__.py
  │   ├── diagnostics/
  │   │   ├── hardware.py      — Hardware enumeration (T6)
  │   │   ├── bsod.py          — Minidump parser & LLM analysis (T7)
  │   │   ├── drivers.py       — Driver scanner (T8)
  │   │   ├── backup.py        — Backup/restore engine (T9)
  │   │   └── stress.py        — Stress test orchestration (T10)
  │   ├── llm/
  │   │   ├── engine.py        — llama.cpp wrapper
  │   │   └── prompts.py       — Diagnostic prompt templates
  │   └── agent/
  │       ├── pipeline.py      — Diagnostic pipeline orchestrator
  │       └── repair.py        — Guided repair flow
  ├── config.yaml              — Default agent config
  └── boot/
      └── autorun.sh           — Entry point script (§7)
```

**Why SquashFS:** Compressed read-only filesystem keeps the runtime compact. The runtime is mounted read-only, with all mutable state going to `DATA/hermes/`. This prevents corruption from unclean shutdown.

---

## 7. Auto-Launch Flow on Boot

```
USB Boot (via Ventoy)
        │
        ▼
Arch Linux ISO boots
        │
        ▼
systemd starts (custom archiso)
        │
        ▼
┌───────────────────────────────┐
│  1. Mount DATA partition      │  Mounts /dev/sda3 (NTFS) to /mnt/data
│     (ntfs-3g /dev/sda3 /mnt/data)
└───────────────┬───────────────┘
                │
                ▼
┌───────────────────────────────┐
│  2. Mount Hermes runtime      │  Mounts squashfs to /mnt/hermes
│     (mount -o loop /mnt/data/  │
│      hermes_agent.squashfs    │
│      /mnt/hermes)             │
└───────────────┬───────────────┘
                │
                ▼
┌───────────────────────────────┐
│  3. Initialize Python venv    │  Symlinks or bind-mounts venv
│     from squashfs             │
└───────────────┬───────────────┘
                │
                ▼
┌───────────────────────────────┐
│  4. Detect LLM model          │  Checks /mnt/data/hermes/models/
│     (fallback logic)          │  for Qwen GGUF → tries to load
│                                │  → falls back to Phi-3-mini
│                                │  → if both fail, pure API mode
└───────────────┬───────────────┘
                │
                ▼
┌───────────────────────────────┐
│  5. Network detection         │  Checks internet connectivity
│     (curl --connect-timeout 5 │  If up: enable API fallback
│      https://1.1.1.1)         │  If down: local-only mode
└───────────────┬───────────────┘
                │
                ▼
┌───────────────────────────────┐
│  6. Launch Hermes agent       │  hermes --config /mnt/data/hermes/
│     (auto-diagnostic mode)    │  config.yaml diagnose
└───────────────┬───────────────┘
                │
                ▼
┌───────────────────────────────┐
│  7. Display diagnostic        │  TUI or terminal output
│     progress & results        │  Session logged to /mnt/data/hermes/logs/
└───────────────────────────────┘
```

### Init System Detail

The custom ISO will use a **oneshot systemd service** (`hermes-autorun.service`) that runs the autorun script after the live environment boots. The ISO is configured for:

- **Auto-login** to a TTY (no X server needed — saves RAM and boot time)
- **Quiet boot** (no verbose kernel messages)
- **10-second Ventoy timeout** before auto-selecting Hermes Rescue

The autorun/service does NOT require user interaction to start the diagnostic pipeline — it launches immediately on boot.

---

## 8. Diagnostic Pipeline Order

The pipeline follows a **risk-tiered approach** — non-destructive, read-only diagnostics first, then progressively more invasive tests.

### Phase 1: Inventory & Health Check (Non-Destructive)

```
Step 1: Hardware Inventory
  ├── CPU: model, cores, frequency
  ├── RAM: total, slot layout, speed (dmidecode)
  ├── GPU: model, VRAM, driver
  ├── Disks: model, capacity, interface, media type (lshw + lsblk)
  └── Network: adapters, MAC, IP (ip link, lspci)

Step 2: SMART Health (All Physical Disks)
  ├── Read smartctl -a for each disk
  ├── Check: reallocated_sectors, pending_sectors, raw_read_error_rate
  ├── Check: temperature, power_on_hours, wear_level (SSDs)
  └── Flag: PASS / WARNING / FAIL

Step 3: Boot Configuration Analysis
  ├── List Windows installations (if any NTFS volumes found)
  ├── Check BCD store (via ntfs-3g mount → bcdedit or registry)
  ├── Check for BitLocker protection
  └── Report: bootable? encrypted? last successful boot?
```

**Actions if Phase 1 completes clean:** Stop here. Report "System appears healthy."

### Phase 2: Targeted Diagnostics (Data-Driven)

```
Step 4: BSOD/Minidump Analysis (if Windows installed)
  ├── Locate .dmp files in C:\Windows\Minidump\
  ├── Locate MEMORY.DMP in C:\Windows\
  ├── Parse dump headers for bugcheck code + parameters
  ├── LLM: interpret stop code, identify likely driver/cause
  └── Suggest: driver rollback, update, hardware test

Step 5: Disk Integrity Check (if NTFS partitions detected)
  ├── Attempt ntfsfix (non-destructive repair)
  ├── Check filesystem consistency (ntfs-3g debug flags)
  └── Report: clean / fixable / needs chkdsk from Windows

Step 6: Registry Sanity Check (if Windows installed)
  ├── Mount SYSTEM hive (via ntfs-3g)
  ├── Check for: corrupted hives, missing critical keys
  └── Extract: driver version info, startup programs
```

### Phase 3: Interactive Repair (User-Initiated)

```
Step 7: Offer Repair Actions (LLM-guided, user confirms each)
  ├── Boot repair: mount BCD → rebuildbcd
  ├── System file repair: sfc /scannow (requires WinPE)
  ├── Image repair: DISM /RestoreHealth (requires WinPE + source)
  ├── Registry backup: export current hives
  ├── System Restore: enumerate restore points
  ├── Driver rollback: identify problematic drivers → guide rollback
  └── BitLocker recovery: unlock + suspend (if recovery key available)

Step 8: Backup (Before Any Destructive Action)
  ├── Registry hive export (all hives)
  ├── Critical user data backup (Documents, Desktop, AppData)
  ├── Full disk image (ddrescue) — optional, space-permitting
  └── Verify backup integrity (hash comparison)

Step 9: Stress Tests (If Hardware Issue Suspected)
  ├── CPU stress: stress-ng --cpu 0 --timeout 300s
  ├── RAM test: prompt to reboot into MemTest86+
  └── GPU test: basic OpenGL/compute test
```

### Phase 4: Recovery & Verification

```
Step 10: Apply Repairs (With Rollback)
  ├── Each repair step is logged with undo information
  ├── Before/after state comparison
  └── Verification test after each change

Step 11: Final Report
  ├── What was found
  ├── What was fixed
  ├── What needs manual attention
  ├── USB session logs path
  └── Recommendations for long-term health
```

---

## 9. Build Pipeline

The build process follows this order:

```
1. Build Arch Linux custom ISO (archiso)
   └── Pre-install Python 3.11+, pip, all diagnostic tools
   └── Configure auto-login + systemd autorun service
   └── Set up Hermes autorun service
   └── Output: hermes-rescue-linux.iso

2. Build Hermes runtime squashfs
   └── Create Python venv with Hermes + dependencies
   └── Bundle diagnostic source modules
   └── Include static llama.cpp binary
   └── Compress into squashfs
   └── Output: hermes_agent.squashfs

3. Download LLM model GGUF files
   └── Qwen2.5-7B-Instruct Q4_K_M from Hugging Face
   └── Phi-3-mini-4k-instruct Q4_K_M from Hugging Face

4. Prepare USB
   └── Partition: FAT32 (VTOYEFI + VTOYISO) + NTFS (DATA)
   └── Install Ventoy to USB
   └── Copy ISOs, models, runtime, config
   └── Verify bootability

5. Test (on real hardware)
   └── Cycle through: boot → autorun → diagnostic pipeline → repair → verify
   └── Test on: gaming PC, business PC, VM with simulated failures
```

### Build Scripts (in `build/`)

| Script | Purpose | Dependencies |
|--------|---------|-------------|
| `build-iso.sh` | Build custom Arch ISO via archiso | archiso, Docker |
| `build-runtime.sh` | Build Hermes runtime squashfs | Python 3.11, squashfs-tools |
| `download-models.sh` | Download GGUF models from Hugging Face | curl, Hugging Face hub |
| `prepare-usb.sh` | Partition + install Ventoy + copy files | Ventoy, parted, mkfs.* |
| `verify-boot.sh` | QEMU boot test of the ISO | qemu-system-x86_64 |

---

## 10. Risks & Mitigations

| Risk | Likelihood | Impact | Mitigation |
|------|-----------|--------|------------|
| Secure Boot blocks boot | Medium | High | Ventoy's shim is MS-signed; Arch ISO uses shim-signed |
| Python package incompatibility on Arch | Low | Medium | Pin package versions in build; test with target Python 3.11 |
| Target PC has only 4 GB RAM | Medium | Medium | Phi-3-mini fallback runs in ~2.9 GB; API mode if both models fail |
| USB3 boot fails on old hardware | Low | Medium | Ventoy handles USB2 fallback; test on multiple machines |
| BitLocker prevents disk access | Medium | Medium | dislocker works on Win 10/11 BitLocker; requires recovery key |
| NTFS partition corruption on unclean shutdown | Medium | Low | Data is session-based logs; corruption affects last session only |
| llama.cpp crashes on unsupported CPU | Low | Medium | Detect CPU features (AVX2) before loading model; fallback to API |
| User has no network for API fallback | Medium | Low | Local model handles 95% of diagnostics offline |
| Arch ISO too large for 32 GB USB | Low | Medium | Base is ~800 MB + tools ~200 MB = ~1 GB; models fit comfortably |
| Windows repair needs native Win tools | Medium | Low | Optional WinPE ISO on the same USB; user can reboot into it |

---

## Appendix A: Research Sources

### T1 — Boot Environment Research
- Microsoft Learn: WinPE technical documentation
- Ventoy project (GitHub, 65k+ stars)
- Arch Linux wiki: archiso
- Alpine Linux documentation
- SystemRescue homepage
- Hiren's Boot CD PE forum
- Medicat USB Discord community

### T2 — LLM Strategy Research
- Llama.cpp quantization benchmarks (community)
- Qwen2.5-7B technical report (Alibaba)
- Phi-3 technical report (Microsoft)
- OpenRouter model comparison data
- Hugging Face Open LLM Leaderboard

### T3 — PC Repair Workflows Research
- Microsoft Learn: bootrec, DISM, SFC, WinRE, chkdsk
- Microsoft KB: registry backup/restore
- Sysnative forums, BleepingComputer, TenForums
- ERUNT project documentation
- Hiren's Boot CD PE tool inventory
- Community knowledge: gaming vs business failure patterns

---

## Appendix B: Quick-Reference Command Set

### Boot Repair Commands (via WinPE)
```
bootrec /fixmbr        — Repair MBR
bootrec /fixboot       — Repair boot sector
bootrec /scanos        — Scan for Windows installations
bootrec /rebuildbcd    — Rebuild BCD store
bcdboot C:\Windows     — Copy boot files to EFI partition
```

### System File Repair Commands (via WinPE)
```
sfc /scannow           — System File Checker
DISM /Online /Cleanup-Image /RestoreHealth   — Component Store Repair
DISM /Online /Cleanup-Image /ScanHealth      — Component Store Scan
DISM /Online /Cleanup-Image /CheckHealth     — Component Store Check
chkdsk C: /f /r        — Check disk + repair + recover bad sectors
```

### Registry & Backup Commands
```
regedit /e backup.reg  — Export entire registry
reg save HKLM\SYSTEM system.hiv    — Save SYSTEM hive
reg restore HKLM\SOFTWARE software.hiv  — Restore SOFTWARE hive
rstrui.exe             — System Restore wizard
wbadmin start backup   — Command-line backup
```