Feat: linux preflight structured diagnostics

.github/workflows/test-linux.yml

@@ -74,6 +74,9 @@ jobs:
           bash tests/contracts/test-installer-contracts.sh
           bash tests/contracts/test-preflight-fixtures.sh
 
+      - name: Linux install preflight tests
+        run: bash tests/test-linux-install-preflight.sh
+
       - name: Installer Simulation Harness
         run: |
           bash scripts/simulate-installers.sh

dream-server/Makefile

@@ -24,6 +24,9 @@ test: ## Run unit and contract tests
 	@bash tests/contracts/test-installer-contracts.sh
 	@bash tests/contracts/test-preflight-fixtures.sh
 	@echo ""
+	@echo "=== Linux install preflight ==="
+	@bash tests/test-linux-install-preflight.sh
+	@echo ""
 	@echo "=== AMD/Lemonade contracts ==="
 	@bash tests/contracts/test-amd-lemonade-contracts.sh
 

dream-server/docs/EXTENSION-PR-BRANCHING.md

@@ -0,0 +1,23 @@
+# Extension changes: branch targets (main vs resources/dev)
+
+Dream Server splits **core runtime** (installer, `dream-server/` compose, CLI, shipped extensions under `dream-server/extensions/`) from the larger **extensions library** under `resources/dev/extensions-library/` (catalog of optional services, workflows, and templates).
+
+Use this guide when coordinating PRs that touch extensions or integrations.
+
+## Quick rules
+
+| Change | Target branch | Notes |
+|--------|---------------|--------|
+| Installer, `dream-cli`, compose base files, dashboard, dashboard-api, **shipped** `dream-server/extensions/services/*` used by default installs | **main** (via normal PR flow) | Follow [EXTENSIONS.md](EXTENSIONS.md) for manifest/schema. |
+| Catalog-only updates: new or updated entries under **`resources/dev/extensions-library/`** (extra services, workflows, templates) | Often **`resources/dev`** or team policy for catalog branches | Does not change core install until wired by installer/catalog pipeline; coordinate with maintainers. |
+| Docs-only (troubleshooting, field reports) | **main** | Unless your team batches docs on a doc branch. |
+| **Both** core behavior and catalog | Split PRs or one PR with explicit maintainer agreement | Easier review when core and catalog are separate. |
+
+## Linux / Windows parity
+
+Platform-specific installer scripts (`installers/`, `dream-server/installers/windows/`) usually land on **main** with tests. Cross-platform doc additions (e.g. [LINUX-TROUBLESHOOTING-GUIDE.md](LINUX-TROUBLESHOOTING-GUIDE.md)) should stay aligned with the same check IDs and behavior as the scripts they reference.
+
+## Questions?
+
+- Default extensions and schema: [EXTENSIONS.md](EXTENSIONS.md)
+- Installer layout: [INSTALLER-ARCHITECTURE.md](INSTALLER-ARCHITECTURE.md)

dream-server/docs/FIELD-INSTALL-REPORT-LINUX.md

@@ -0,0 +1,73 @@
+# Field install report (Linux)
+
+Use this template when reporting Linux install problems so maintainers can reproduce and classify issues quickly. **Do not paste secrets** (API keys, passwords, full `.env`).
+
+## Environment
+
+| Field | Your value |
+|-------|------------|
+| Dream Server version / git SHA | |
+| Install command used | e.g. `./install.sh`, `./install.sh --dry-run` |
+| Distribution | Paste **PRETTY_NAME** and **VERSION_ID** from `/etc/os-release` |
+| Kernel | Output of `uname -a` |
+| Architecture | e.g. `x86_64`, `aarch64` |
+| Install type | Bare metal / VM / cloud / WSL2 (if applicable) |
+
+## Hardware
+
+| Field | Your value |
+|-------|------------|
+| GPU | `lspci` line or “CPU only” |
+| NVIDIA | Output of `nvidia-smi` (if any) or “N/A” |
+| RAM | Approximate GB |
+
+## Docker
+
+| Field | Your value |
+|-------|------------|
+| Docker version | `docker --version` |
+| Compose | `docker compose version` or `docker-compose version` |
+| Docker info | Does `docker info` work without sudo? (yes/no) |
+| User in `docker` group? | (yes/no / unknown) |
+
+## Structured preflight (required)
+
+From the `dream-server` directory, run:
+
+```bash
+./scripts/linux-install-preflight.sh --json
+```
+
+Paste the **JSON output** (redact paths if needed). If the command fails, paste the **human** output:
+
+```bash
+./scripts/linux-install-preflight.sh
+```
+
+## Service preflight (after install)
+
+If services are installed, also run:
+
+```bash
+./dream-preflight.sh
+```
+
+Paste the last 40 lines of output (or attach the log path printed at the end).
+
+## Logs to attach (pick what applies)
+
+- Installer log if referenced by the installer.
+- `docker compose` error from the failing command (not the entire daemon log unless asked).
+- For GPU issues: output of `docker info | grep -i nvidia` and relevant `nvidia-smi`.
+
+## Privacy checklist
+
+- [ ] Removed API keys and passwords from pasted content.
+- [ ] Redacted internal hostnames if required by your employer.
+- [ ] Confirmed no private URLs or tokens in compose overrides.
+
+## Related docs
+
+- [LINUX-TROUBLESHOOTING-GUIDE.md](LINUX-TROUBLESHOOTING-GUIDE.md) — maps check IDs to fixes.
+- [INSTALL-TROUBLESHOOTING.md](INSTALL-TROUBLESHOOTING.md)
+- [SUPPORT-MATRIX.md](SUPPORT-MATRIX.md)

dream-server/docs/INSTALL-TROUBLESHOOTING.md

@@ -2,6 +2,8 @@
 
 This guide provides solutions for common issues encountered during the installation of Dream Server.
 
+For **Linux**, run `./scripts/linux-install-preflight.sh` (or `./dream-preflight.sh --install-env`) for a structured report with stable check IDs; see [LINUX-TROUBLESHOOTING-GUIDE.md](LINUX-TROUBLESHOOTING-GUIDE.md) for ID-by-ID fixes.
+
 ## Docker Issues
 
 ### Problem: Docker Not Installed

dream-server/docs/LINUX-PORTABILITY.md

@@ -16,6 +16,9 @@ Services are declared under `extensions/services/<name>/manifest.yaml` for dashb
 
 1. Docker and Compose v2 work; your user can run containers (e.g. member of the `docker` group).
 2. `./install.sh --dry-run` finishes without errors.
-3. After a real install, run `./dream-preflight.sh` and `scripts/dream-doctor.sh` if you use them.
+3. Before or after install, run **`./scripts/linux-install-preflight.sh`** (or `./dream-preflight.sh --install-env`) for a structured environment report with stable check IDs and optional `--json` output.
+4. After a real install, run `./dream-preflight.sh` (service health) and `scripts/dream-doctor.sh` if you use them.
 
-More context: [SUPPORT-MATRIX.md](SUPPORT-MATRIX.md), [TROUBLESHOOTING.md](TROUBLESHOOTING.md).
+More context: [LINUX-TROUBLESHOOTING-GUIDE.md](LINUX-TROUBLESHOOTING-GUIDE.md) (ID-indexed fixes), [FIELD-INSTALL-REPORT-LINUX.md](FIELD-INSTALL-REPORT-LINUX.md) (bug report template), [SUPPORT-MATRIX.md](SUPPORT-MATRIX.md), [TROUBLESHOOTING.md](TROUBLESHOOTING.md).
+
+Extension PRs that touch catalog vs core: [EXTENSION-PR-BRANCHING.md](EXTENSION-PR-BRANCHING.md).

dream-server/docs/LINUX-TROUBLESHOOTING-GUIDE.md

@@ -0,0 +1,243 @@
+# Linux troubleshooting guide
+
+Structured reference for **Linux install and runtime** issues. When you run `./scripts/linux-install-preflight.sh` or `./dream-preflight.sh --install-env`, each line uses a **check ID**. Use this document to jump from an ID to likely causes and fixes.
+
+**Related:** [INSTALL-TROUBLESHOOTING.md](INSTALL-TROUBLESHOOTING.md), [TROUBLESHOOTING.md](TROUBLESHOOTING.md), [LINUX-PORTABILITY.md](LINUX-PORTABILITY.md), [FIELD-INSTALL-REPORT-LINUX.md](FIELD-INSTALL-REPORT-LINUX.md).
+
+---
+
+## Using the install preflight
+
+From the `dream-server` directory:
+
+```bash
+./scripts/linux-install-preflight.sh
+./scripts/linux-install-preflight.sh --json
+./scripts/linux-install-preflight.sh --json-file /tmp/preflight.json
+./dream-preflight.sh --install-env --json   # same as linux-install-preflight.sh
+```
+
+- **`--strict`** — exit with failure if any check is **warn** or **fail** (useful in automation).
+- **`--dream-root PATH`** — directory used for the disk-space probe (default: dream-server root).
+- **`--min-disk-gb N`** — minimum free space in GB to treat as OK (default: 15).
+
+JSON output includes `schema_version`, `kind: linux-install-preflight`, `distro`, `kernel`, `checks[]`, and `summary`.
+
+---
+
+## Check IDs (alphabetical)
+
+### CGROUP_V2
+
+**Symptoms:** Warning that cgroup v2 was not detected.
+
+**Typical causes:** Older kernels, unusual container hosts, or mis-mounted `/sys/fs/cgroup`.
+
+**Fixes:**
+
+- On normal desktop/server distros from the last several years, cgroup v2 is standard; if Docker works, you can ignore this warning.
+- If Docker fails with cgroup-related errors, ensure you are not mixing rootless Docker with a broken delegated cgroup setup. See your distro’s Docker documentation.
+
+---
+
+### COMPOSE_CLI
+
+**Symptoms:** **Fail** — neither `docker compose` nor `docker-compose` works.
+
+**Typical causes:** Docker Engine installed without the Compose v2 plugin; very old Docker packages; PATH issues.
+
+**Fixes:**
+
+- Install **Docker Compose v2** (plugin): often package `docker-compose-plugin` (Debian/Ubuntu) or equivalent.
+- Legacy: install standalone `docker-compose` v1 if you must (less ideal).
+
+Verify:
+
+```bash
+docker compose version
+# or
+docker-compose version
+```
+
+---
+
+### COMPOSE_FILES
+
+**Symptoms:** Warning — `docker-compose.base.yml` / `docker-compose.yml` missing under the dream-server tree.
+
+**Typical causes:** Running the script from the wrong directory; incomplete checkout.
+
+**Fixes:**
+
+- `cd` into the extracted **dream-server** directory that contains the compose files from the release or git clone.
+- Re-download or re-clone the repository if files are missing.
+
+---
+
+### CURL_INSTALLED
+
+**Symptoms:** **Warn** — `curl` not in PATH.
+
+**Typical causes:** Minimal container or netinst image without `curl`.
+
+**Fixes:**
+
+```bash
+# Debian/Ubuntu
+sudo apt update && sudo apt install -y curl
+
+# Fedora
+sudo dnf install -y curl
+
+# Arch
+sudo pacman -S curl
+```
+
+The installer and many health checks expect `curl`.
+
+---
+
+### DISK_SPACE
+
+**Symptoms:** **Warn** — low free space on `--dream-root` (or default dream-server root).
+
+**Typical causes:** Small root partition; large existing Docker data; wrong path passed to `--dream-root`.
+
+**Fixes:**
+
+- Free space or move the Dream Server data directory to a larger volume (see installer docs for `data/` layout).
+- Point `--dream-root` at the filesystem you intend to use for the install.
+
+---
+
+### DISTRO_INFO
+
+**Symptoms:** **Fail** — `/etc/os-release` missing.
+
+**Typical causes:** Non-Linux environment; severely broken chroot.
+
+**Fixes:**
+
+- Run on a supported Linux distribution. For Windows, use the Windows installer + WSL2; for macOS, use the macOS path.
+
+---
+
+### DOCKER_DAEMON
+
+**Symptoms:** **Fail** — `docker info` does not succeed.
+
+**Typical causes:** Docker service stopped; user lacks permission to the Docker socket; rootless Docker socket not in environment.
+
+**Fixes:**
+
+```bash
+# systemd
+sudo systemctl start docker
+sudo systemctl enable docker
+
+# Permission denied on /var/run/docker.sock
+sudo usermod -aG docker "$USER"
+# then log out and back in (or newgrp docker)
+```
+
+Confirm:
+
+```bash
+docker info
+docker run --rm hello-world
+```
+
+---
+
+### DOCKER_INSTALLED
+
+**Symptoms:** **Fail** — `docker` command not found.
+
+**Typical causes:** Docker Engine never installed; PATH not including Docker binaries.
+
+**Fixes:**
+
+- Install [Docker Engine](https://docs.docker.com/engine/install/) for your distro.
+- Ensure `/usr/bin` (or wherever `docker` lives) is on your `PATH`.
+
+---
+
+### KERNEL_INFO
+
+**Symptoms:** Always **pass** — prints `uname -r` (informational).
+
+**Note:** Use this value when comparing against [SUPPORT-MATRIX.md](SUPPORT-MATRIX.md) or when filing bugs.
+
+---
+
+### JQ_INSTALLED
+
+**Symptoms:** **Warn** — `jq` not installed.
+
+**Typical causes:** Minimal system; skipped optional packages.
+
+**Fixes:**
+
+- The Dream Server installer often installs `jq` automatically when possible. You can install manually:
+
+```bash
+sudo apt install -y jq   # Debian/Ubuntu
+sudo dnf install -y jq   # Fedora
+```
+
+---
+
+### KERNEL_INFO
+
+**Symptoms:** Always **pass** with kernel version (informational).
+
+**Note:** Very old kernels may be incompatible with modern Docker or NVIDIA drivers; if you hit exotic bugs, compare with [SUPPORT-MATRIX.md](SUPPORT-MATRIX.md).
+
+---
+
+### NVIDIA_CONTAINER_RUNTIME
+
+**Symptoms:** **Warn** — `nvidia-smi` works but Docker does not show an NVIDIA runtime.
+
+**Typical causes:** NVIDIA drivers installed but [NVIDIA Container Toolkit](https://docs.nvidia.com/datacenter/cloud-native/container-toolkit/install-guide.html) not configured for Docker.
+
+**Fixes:**
+
+- Install and configure `nvidia-container-toolkit`, then restart Docker:
+
+```bash
+sudo nvidia-ctk runtime configure --runtime=docker
+sudo systemctl restart docker
+```
+
+- Verify: `docker info | grep -i nvidia`
+
+If you are intentionally **CPU-only**, you can ignore this after setting `GPU_BACKEND=cpu` in your capability/install profile.
+
+---
+
+## Common cross-cutting issues
+
+### Firewall blocking local ports
+
+If the dashboard or WebUI is unreachable from another machine, check `ufw` / `firewalld` / `iptables` for the ports in `config/ports.json` (or your `.env` overrides).
+
+### SELinux / AppArmor
+
+Rare compose failures can be policy-related. Check audit logs; temporarily testing with permissive profiles is diagnostic only — prefer documented volume labels and permissions.
+
+### Docker BuildKit / proxy
+
+Corporate proxies may require `HTTP_PROXY` / `HTTPS_PROXY` in Docker’s systemd drop-in or `~/.docker/config.json` for image pulls.
+
+---
+
+## Getting help
+
+When opening an issue, attach a **field install report** (see [FIELD-INSTALL-REPORT-LINUX.md](FIELD-INSTALL-REPORT-LINUX.md)) and the JSON from:
+
+```bash
+./scripts/linux-install-preflight.sh --json
+```
+
+Redact secrets, internal hostnames, and paths you do not want to share.