# Hydra OS laptop preparation

The user authorized autonomous implementation of the agreed scope: preserve all
existing laptop partitions; install Hydra into an explicitly selected partition;
obtain updates from the now-public `Emil_Shanaty/Hydra-OS` Gitea repository; verify
signatures and recover after failed updates; prepare hardware diagnostics; rebuild
and test an ISO including the generated Fastfetch branding. Technical choices are
delegated. Actual laptop partitioning/installation and physical hardware checks
remain operator steps; no physical target is selected or authorized.

## Invariants

- Never modify the physical host's block devices, firmware, services, NixOS
  configuration, networking, existing containers, or existing VM disks.
- All installation/recovery execution tests use freshly created private qcow2s.
- Keep whole-disk installation compatible, but add a distinct existing-partitions
  mode. No automatic partition selection, shrinking, or repartitioning.
- Preserve foreign EFI files, the removable fallback loader, and BootOrder.
- VM disks, profiles, HOME, credentials and network configuration are not runtime
  update payloads. Release trust is installed independently of untrusted discovery.
- Prefer the standard library and already installed OpenSSL; no hosted dependency.
- Hardware detection is evidence about presence, not proof of working devices.
- A runtime rollback must never be described as rollback of Gentoo or its kernel.

## Existing-partitions installation

Keep `--disk` and `--confirm-erase` for fresh whole-disk installations. Add
`--root-partition`, `--esp-partition`, `--confirm-format`, `--root-fs ext4|btrfs`
and opt-in `--register-boot-entry`. A request chooses exactly one mode. Existing
mode formats only the selected root after full identity revalidation, requires an
unmounted existing FAT ESP, and never runs disk-label/partition/ESP-format commands.

Require stable canonical paths, block identities, parent/partition identities and
bounds; reject mounted/active/protected targets, overlaps, aliases, ambiguous
metadata and devices with holders. Unrelated mounted sibling partitions must not
cause false rejection. Btrfs mounts must resolve all backing members conservatively.
Require enough capacity for the installed payload and boot files before erasure.

Write only EFI/HydraOS, refusing an existing collision. Use GRUB --no-nvram without
--removable, disable os-prober, and leave foreign EFI entries and fallback intact.
Explicit registration may create a new entry without modifying BootOrder. Default
output explains manual firmware selection. ESP preflight is read-only and happens
before root formatting; record and verify unchanged foreign file hashes.

Ext4 remains compatible. Optional Btrfs uses @root, @home, @snapshots. The kernel,
/boot and Portage database remain within @root; guest disks under HOME remain in
@home. This layout permits a separately verified system recovery path; it alone
is not a rollback implementation.

## Signed runtime updates

Use a bounded passive ZIP payload, exact-byte Ed25519-signed JSON manifest and
detached signature. Manifest records product, scope, format, channel, architecture,
monotonic sequence, release version, source commit, archive name/size/hash and the
allowlisted installed paths/modes/hashes. OpenSSL verifies using an installed public
key. Private release material stays outside Git, the build context and Nix store.

Gitea discovery is unauthenticated HTTPS on the fixed project origin; it is not a
trust authority. Reject cross-origin/downgrade redirects, malformed URLs, duplicate
JSON/archive entries, traversal/symlinks/special files, excess sizes, tampering and
unsupported formats. Verify the manifest before trusting the archive. Empty releases
are a normal result. No fallback to executing unsigned downloaded Python archives.

CLI: `hydra update check`, `status`, `apply` and `rollback TRANSACTION`, plus a
standalone `hydra-update-recover` available when the runtime itself is damaged.
The trusted engine and recovery bootstrap are outside the runtime update allowlist.
Prefer a protected installed engine imported without arbitrary sys.path entries.
For local tests/support permit an explicit trusted local artifact directory and a
staging-root API; production target checks must still require a Hydra installation.

Serialize mutations with a lock. Before the first destination change, validate all
paths and save original bytes, modes, owners, symlinks and hashes into a durable
private backup; persist a journal and fsync files/directories. Recover prepared or
interrupted transactions from independently validated records. Latest-only explicit
rollback refuses unexpected modifications. Preserve highest accepted sequence when
rolling back current state; block new changes while recovery is pending. Failure
must retain the journal and all backups. Include real fresh-process crash tests.

## Diagnostics and delivery

`hydra doctor` collects a bounded read-only report useful on the live ASUS laptop:
UEFI/Secure Boot, KVM, CPU/RAM, storage visibility, kernel/driver bindings, graphics,
input devices, network/audio tools and required services. Redact serials, MACs,
SSID, IP addresses, usernames and machine IDs by default. Print actionable checks
without implying physical Wi-Fi/audio/brightness/suspend/144Hz delivery were tested.

Rebuild using the isolated existing builder store. Preserve the previous ISO and
firmware. Run whole-disk acceptance plus a distinct preserve-partitions acceptance:
seed foreign EFI/fallback/sibling sentinel files, install into only the target,
compare GPT/BootOrder/sentinels, and boot without ISO. Exercise signed update,
tamper refusal, rollback and recovery with guest data unchanged. Store reports
against exact source/ISO hashes. Publish only intended code/artifacts; private
builder exports, signing keys, VM data and test secrets are never release assets.

Whole-base Portage recovery is a separate design/verification unit. Until its own
bootable test passes, documentation must retain that limitation explicitly.