feat(core): add phase 1 narrative for core orchestration modules

Add literate programming phase 1 documentation for:
- main.sh: wrapper orchestration and user journey
- config.sh: configuration management and defaults
- sanity.sh: preflight safety checks

Decision: UEFI-only support to reduce complexity. BIOS would
require separate /boot partition and additional testing burden
disproportionate to modern hardware usage.

Decision: LUKS2 as default encryption for improved security
tooling, with clear guidance for LUKS1 fallback if GRUB boot
fails. Auto-detection rejected due to version fragmentation.

Decision: Interactive configuration as default. Presets are
out of scope for phase 1 to keep the flow understandable.

The user journey documents the complete end-to-end flow from
live medium boot to first encrypted boot, establishing clear
handoff points between wrapper and installer.

src/config.sh

@@ -0,0 +1,31 @@
+# === Motivation ===
+# Centralize user-provided inputs to avoid scattered magic values.
+# === Problem Statement ===
+# Disk targets, encryption mode, filesystem choice, and host metadata need a single source of truth.
+# === Scope ===
+# In scope: definition of configurable parameters and validation expectations.
+# Out of scope: parsing implementation and storage mechanism.
+# === Concepts ===
+# Preset: a named set of config values for repeatable installs.
+# Interactive input: prompting the user for values at runtime.
+# === Decisions ===
+# Keep defaults conservative and require explicit confirmation for destructive values.
+# Surface all critical values before any destructive phase begins.
+# Default to LUKS2 with an explicit LUKS1 fallback for bootloader compatibility.
+# Default filesystem is btrfs, with opt-in alternatives.
+# Default bootloader is GRUB for Void compatibility.
+# Passphrase-only is the supported unlock method.
+# Swap defaults to a file (works with both btrfs and ext4).
+# Mandatory values are DISK, HOSTNAME, and size inputs where no safe default exists.
+# Interactive prompts are the default input mechanism; no preset formats are defined yet.
+# === Alternatives Considered ===
+# Hard-coded values rejected because they do not scale across machines.
+# === Constraints ===
+# Config must be readable and editable without specialized tools.
+# Target boot mode is UEFI only; BIOS is out of scope.
+# === Open Questions ===
+# Should we support config file presets for batch installations, or keep it fully interactive?
+# How should we validate user-provided disk paths to prevent typos?
+# Should swap size have intelligent defaults based on RAM size, or always ask?
+# === Success Criteria ===
+# Users can clearly see and confirm target disk, encryption type, and filesystem choice.

src/main.sh

@@ -0,0 +1,43 @@
+# === Motivation ===
+# Provide a reproducible wrapper around the Void installer for encrypted setups.
+# Reduce manual, error-prone steps while keeping user control over installer choices.
+# === Problem Statement ===
+# The stock installer does not automate disk preparation for encrypted layouts.
+# We need a guided wrapper that prepares the target disk before the installer runs.
+# === Scope ===
+# In scope: orchestration of phases, user confirmations, mode selection.
+# Out of scope: replacing the official installer UI, package selection, BIOS support.
+# === Concepts ===
+# Wrapper: a script that executes pre-install tasks then hands off to the installer.
+# Phases: sanity, disk layout, encryption, filesystems, mounts, installer, post-install.
+# === User Journey ===
+# 1. User boots Void live medium and runs the wrapper script.
+# 2. Sanity checks validate environment (UEFI mode, root privileges, target disk exists).
+# 3. User provides configuration: target disk, encryption mode, filesystem choice, hostname.
+# 4. User reviews planned layout, encryption settings, and filesystem choices.
+# 5. User confirms destructive operation with explicit disk identifier confirmation.
+# 6. Wrapper prepares disk: partition → encrypt → format → mount.
+# 7. Wrapper pauses and instructs user to run official installer using existing mounts.
+# 8. User completes installer, selecting packages and configuring system preferences.
+# 9. After installer exits, wrapper performs post-install configuration (crypttab, dracut, GRUB).
+# 10. User reboots into encrypted Void system, enters passphrase at boot.
+# === Decisions ===
+# Keep the official installer in the loop because it handles system configuration choices.
+# Prefer a phase-based flow to make recovery and retries understandable.
+# Target x86_64 only to keep the scope focused.
+# Default to a UEFI-first flow with an ESP.
+# Start with a fully interactive flow; presets are out of scope for now.
+# Provide a dry-run mode to review planned actions before execution.
+# === Alternatives Considered ===
+# Full automation without the official installer rejected due to maintenance burden.
+# Manual instructions only rejected because they remain error-prone.
+# === Constraints ===
+# Must be safe for destructive operations and require explicit confirmation.
+# Must support UEFI boot flow; BIOS is out of scope.
+# === Open Questions ===
+# Should the wrapper support resuming from a failed phase, or always start from scratch?
+# How should the wrapper handle pre-existing partitions on the target disk?
+# Should the dry-run mode generate a detailed execution plan, or just show configuration summary?
+# === Success Criteria ===
+# A user can run the wrapper, confirm disk intent, and reach the installer with correct mounts.
+# The narrative of each phase is clear enough to audit and adapt.

src/sanity.sh

@@ -0,0 +1,25 @@
+# === Motivation ===
+# Prevent catastrophic mistakes before any disk operations.
+# === Problem Statement ===
+# The wrapper must ensure it is running in a safe context with the intended target.
+# === Scope ===
+# In scope: checks for privileges, environment, and target disk presence.
+# Out of scope: detailed hardware inventory.
+# === Concepts ===
+# Preflight: a set of checks that must pass before continuing.
+# === Decisions ===
+# Fail fast on missing privileges or ambiguous disk selection.
+# Require a typed confirmation of the target disk identifier.
+# Reject unsupported architectures; x86_64 is the only supported target.
+# Reject non-UEFI boot modes; BIOS systems are out of scope.
+# Provide a dry-run mode to review planned actions before execution.
+# === Alternatives Considered ===
+# Proceeding with warnings only rejected due to data loss risk.
+# === Constraints ===
+# Checks must run without relying on network access.
+# === Open Questions ===
+# Should we check for minimum disk size requirements before proceeding?
+# How do we detect if the system was booted in UEFI mode reliably?
+# Should we warn if the target disk contains existing partitions, or just require explicit confirmation?
+# === Success Criteria ===
+# The wrapper refuses to proceed if the target disk is unclear or unsafe.