## Context

Targeting the Raspberry Pi 3B (1GB RAM) running Raspbian x64 Lite. The goal is a "Finalize on Reboot" strategy where the user is disconnected from SSH and reconnects to the newly created WiFi Access Point.

## Goals / Non-Goals

**Goals:**
- Create a `curl | bash` compatible script.
- Support a custom Git repository URL as a script argument.
- Use `whiptail` for a professional, interactive UI.
- Ensure the system remains accessible via Ethernet if WiFi configuration fails.

**Non-Goals:**
- **Automated SSH Key Setup**: We will rely on the user's existing SSH credentials.
- **Firewall Configuration**: Advanced `iptables` or `ufw` setup is out of scope for this version.

## Decisions

### 1. Delivery Workflow
The script will be invoked as:
`curl -sSL <URL>/setup.sh | sudo bash -s -- <REPO_URL>`
This allows the script to be hosted on Gitea/GitHub and pull the application code dynamically.

### 2. Networking Architecture
- **wlan0**: Configured as a static Access Point (`192.168.4.1`).
- **eth0**: Remains a DHCP client for failsafe rescue.
- **mDNS (Link-Local)**: Avahi will be configured to broadcast `mpvj.local` even on IPv4 Link-Local (169.254.x.x) to support direct Pi-to-Laptop cable connection without a router.
- **WiFi Region**: The script will interrogate and set the `country_code` in `wpa_supplicant.conf` to prevent `hostapd` from being "soft-blocked" by the kernel.

### 3. Build Strategy (The "Safe" Build)
To handle the 1GB RAM limitation on Pi 3B:
1. **Disk Check**: Verify at least 2GB of free space before starting.
2. **Swap Scaling**: Temporarily increase swap to 1GB using `dphys-swapfile`.
3. **Concurrency Limiting**: Run `npm config set jobs 1` and `node --max-old-space-size=512` during the build phase to prevent OOM (Out of Memory) panics.
4. **Hybrid Detection**: Skip the build entirely if a pre-compiled `frontend/dist` folder is detected in the repository.

### 4. Configuration Templating
The script will use "Heredocs" to overwrite system configuration files with the user's validated input (SSID, Password, Hostname, Country Code).

## Risks / Trade-offs

- **[Risk] SSH Disconnection** → **Mitigation**: The script performs all updates and installs *before* staging the network changes and requires a final user confirmation before rebooting.
- **[Risk] SD Card Wear** → **Mitigation**: The swap increase is temporary and only used during the installation/build phase.
- **[Risk] Invalid WiFi Password** → **Mitigation**: The script includes a validation loop to ensure WPA2 passwords are at least 8 characters.