docs: add linux hosting validation runbook

docs/linux-hosting-validation.md

@@ -0,0 +1,178 @@
+# Linux Hosting Validation
+
+This runbook defines the operational validation standard for VoxVera's only supported hosting target:
+
+- Linux CLI with `systemd --user`
+
+Everything else remains below that bar until equivalent evidence exists.
+
+## Prerequisites
+
+- `voxvera` installed and on `PATH`
+- `tor` installed
+- `onionshare-cli` available
+- a user account that can run `systemctl --user`
+
+## Quick Verification
+
+Use the helper script first:
+
+```bash
+bash scripts/linux-recovery-check.sh
+```
+
+This checks:
+
+- `platform-status --json`
+- `doctor --json`
+- `autostart status --json`
+- expected Linux support tier and platform id
+- presence of `~/host`
+- Tor and OnionShare discovery
+- autostart artifacts and timer state
+- per-site state for `.onionshare-session`, `onionshare.log`, and `server.pid`
+
+## Core Commands
+
+Install autostart:
+
+```bash
+voxvera autostart
+```
+
+Inspect autostart:
+
+```bash
+voxvera autostart status
+systemctl --user status voxvera-start.timer
+systemctl --user status voxvera-start.service
+```
+
+Remove autostart:
+
+```bash
+voxvera autostart uninstall
+```
+
+Inspect runtime diagnostics:
+
+```bash
+voxvera doctor
+voxvera doctor --json
+```
+
+## Validation Checklist
+
+### 1. Fresh install
+
+Run the Linux installer or install through the supported CLI path, then confirm:
+
+```bash
+voxvera platform-status --json
+voxvera doctor --json
+voxvera autostart status --json
+```
+
+Expected:
+
+- `platform_id` is `linux_cli_systemd`
+- support tier is `supported`
+- `voxvera_cli`, `onionshare_cli`, and `tor_binary` pass
+
+### 2. Build and serve
+
+Create or edit a site, then build and serve it:
+
+```bash
+voxvera build
+voxvera serve
+```
+
+Expected:
+
+- site output appears under `~/host/<folder_name>/`
+- `index.html` and QR code images exist
+- `onionshare.log` is written
+- `.onionshare-session` appears after the hidden service is started
+
+### 3. Identity persistence
+
+Confirm the site keeps its identity across rebuilds:
+
+```bash
+ls -la ~/host/<folder_name>/
+voxvera build --config ~/host/<folder_name>/config.json
+```
+
+Expected:
+
+- `.onionshare-session` still exists after rebuild
+
+### 4. Autostart persistence
+
+Confirm the recovery timer exists and is enabled:
+
+```bash
+voxvera autostart status
+systemctl --user is-enabled voxvera-start.timer
+systemctl --user is-active voxvera-start.timer
+```
+
+Expected:
+
+- timer artifacts exist under `~/.config/systemd/user/`
+- timer is enabled
+
+### 5. Reboot recovery
+
+After a reboot, verify:
+
+```bash
+bash scripts/linux-recovery-check.sh
+systemctl --user status voxvera-start.timer
+journalctl --user -u voxvera-start.service --no-pager -n 50
+```
+
+Expected:
+
+- timer remains enabled
+- service has retried `start-all`
+- configured sites are restorable without manual reconfiguration
+
+### 6. Offline/reconnect recovery
+
+Temporarily disconnect the host from the network, reconnect, then wait through at least one timer interval.
+
+Verify:
+
+```bash
+systemctl --user status voxvera-start.timer
+journalctl --user -u voxvera-start.service --no-pager -n 50
+bash scripts/linux-recovery-check.sh
+```
+
+Expected:
+
+- timer is still active
+- `start-all` retries appear in the service logs
+- Tor becomes reachable again
+
+## Paths That Matter
+
+- `~/.config/systemd/user/voxvera-start.service`
+- `~/.config/systemd/user/voxvera-start.timer`
+- `~/host/<folder_name>/config.json`
+- `~/host/<folder_name>/.onionshare-session`
+- `~/host/<folder_name>/onionshare.log`
+- `~/host/<folder_name>/server.pid`
+
+## Failure Interpretation
+
+If `bash scripts/linux-recovery-check.sh` fails:
+
+- missing `onionshare_cli` or `tor_binary` means the runtime is incomplete
+- missing `host_root` means no sites are built yet
+- missing autostart artifacts means recovery was never installed or was removed
+- `tor_socks_reachable` warning means Tor is not currently reachable even if it is installed
+
+Linux should remain the only supported target until this runbook is repeatable on real hosts without caveats.