Add install-to-usb ghostdrive MVP

.editorconfig

@@ -0,0 +1,19 @@
+root = true
+
+[*.sh]
+indent_style = space
+indent_size = 2
+end_of_line = lf
+insert_final_newline = true
+charset = utf-8
+
+[Makefile]
+indent_style = tab
+end_of_line = lf
+insert_final_newline = true
+charset = utf-8
+
+[*.md]
+end_of_line = lf
+insert_final_newline = true
+charset = utf-8

.github/workflows/ci.yml

@@ -0,0 +1,38 @@
+name: ci
+
+on:
+  pull_request:
+  push:
+    branches:
+      - main
+
+jobs:
+  lint:
+    runs-on: ubuntu-24.04
+    steps:
+      - uses: actions/checkout@v4
+      - run: sudo apt-get update
+      - run: sudo apt-get install -y python3-pip
+      - run: python3 -m pip install --user check-jsonschema
+      - run: ~/.local/bin/check-jsonschema --help
+      - run: PATH="$HOME/.local/bin:$PATH" scripts/validate-config.sh config/defaults.yaml
+
+  test:
+    runs-on: ubuntu-24.04
+    steps:
+      - uses: actions/checkout@v4
+      - run: sudo apt-get update
+      - run: sudo apt-get install -y bats ansible python3-pip
+      - run: python3 -m pip install --user check-jsonschema
+      - run: PATH="$HOME/.local/bin:$PATH" make ci-check
+
+  verify-boot:
+    runs-on: ubuntu-24.04
+    steps:
+      - uses: actions/checkout@v4
+      - run: sudo apt-get update
+      - run: sudo apt-get install -y qemu-system-x86 ovmf bats
+      - run: bats tests/bats/boot_smoke_signals.bats
+      - run: truncate -s 128M /tmp/ghostdrive-boot-smoke.img
+      - run: if scripts/verify/boot_smoke_bios.sh --image /tmp/ghostdrive-boot-smoke.img --timeout-seconds 10; then echo "unexpected BIOS smoke success for blank image"; exit 1; fi
+      - run: if scripts/verify/boot_smoke_uefi.sh --image /tmp/ghostdrive-boot-smoke.img --timeout-seconds 10; then echo "unexpected UEFI smoke success for blank image"; exit 1; fi

.gitignore

@@ -0,0 +1,3 @@
+.worktrees/
+.env
+.env.*

Makefile

@@ -0,0 +1,8 @@
+.PHONY: test ci-check
+
+test:
+	bats tests/bats
+
+ci-check:
+	scripts/validate-config.sh config/defaults.yaml
+	bats tests/bats

README.md

@@ -1,2 +1,111 @@
 # ghostdrive
-A bootable USB with everything to start hacking
+
+Ghostdrive builds a reproducible Ubuntu engineering USB image using an install-to-USB pipeline.
+
+## V1 Scope
+
+- Linux build host only.
+- Ubuntu LTS target only (`24.04`, `x86_64`).
+- Install-to-USB architecture (not live+persistence mode).
+- Curated baseline provisioning through Ansible.
+- Golden image capture and restore workflow.
+
+## Safety and Security Rules
+
+- All destructive operations require an explicit `--device` argument.
+- For non-CI runs, require an interactive human confirmation after printing the selected block device before any destructive write step.
+- Validate configuration before install or CI checks.
+- Keep secrets out of the repository.
+- Generalize a target filesystem before capture to avoid cloned identity collisions.
+
+## Prerequisites
+
+Install required tools on a Linux host:
+
+```bash
+sudo apt-get update
+sudo apt-get install -y \
+	bats \
+	ansible \
+	qemu-system-x86 \
+	ovmf \
+	zstd \
+	python3-pip
+python3 -m pip install --user check-jsonschema
+export PATH="$HOME/.local/bin:$PATH"
+command -v check-jsonschema
+```
+
+If `command -v check-jsonschema` prints nothing, your shell is missing `$HOME/.local/bin` on PATH.
+
+## Quickstart
+
+1. Validate config:
+
+```bash
+scripts/validate-config.sh config/defaults.yaml
+```
+
+2. Prepare install orchestration for a target device:
+
+```bash
+scripts/build/install_to_usb.sh \
+	--config config/defaults.yaml \
+	--device /dev/sdX \
+	--workdir .ghostdrive-work
+```
+
+For non-CI usage, review the printed `/dev/sdX` target and complete the interactive confirmation before allowing the install step to proceed.
+
+3. Apply curated baseline to the mounted target root filesystem:
+
+```bash
+scripts/provision/apply_baseline.sh --target-root /mnt/ghostdrive-root
+```
+
+4. Generalize and capture a golden image:
+
+```bash
+scripts/image/generalize.sh --root /mnt/ghostdrive-root
+scripts/image/capture.sh --device /dev/sdX --output artifacts/ghostdrive.img.zst
+scripts/image/write_manifest.sh --image artifacts/ghostdrive.img.zst --output artifacts/ghostdrive.manifest.json
+```
+
+5. Restore to another USB device:
+
+```bash
+scripts/image/restore.sh \
+	--image artifacts/ghostdrive.img.zst \
+	--manifest artifacts/ghostdrive.manifest.json \
+	--device /dev/sdY
+```
+
+## Verification
+
+Run all local checks:
+
+```bash
+make test
+```
+
+CI-oriented checks:
+
+```bash
+make ci-check
+```
+
+Boot smoke checks (BIOS + UEFI):
+
+```bash
+truncate -s 128M /tmp/ghostdrive-boot-smoke.img
+scripts/verify/boot_smoke_bios.sh --image /tmp/ghostdrive-boot-smoke.img --timeout-seconds 10
+scripts/verify/boot_smoke_uefi.sh --image /tmp/ghostdrive-boot-smoke.img --timeout-seconds 10
+```
+
+## Documentation
+
+- `docs/architecture.md`
+- `docs/provisioning.md`
+- `docs/cloning-workflow.md`
+- `docs/threat-model.md`
+- `docs/compatibility-matrix.md`

ansible/inventory/local.ini

@@ -0,0 +1,2 @@
+[ghostdrive_target]
+target ansible_connection=chroot ansible_host=/__ghostdrive_target_root_required__

ansible/roles/curated_default/defaults/main.yml

@@ -0,0 +1,6 @@
+---
+curated_default_packages:
+  - git
+  - curl
+  - vim
+  - build-essential

ansible/roles/curated_default/tasks/main.yml

@@ -0,0 +1,5 @@
+---
+- name: Install curated baseline packages
+  ansible.builtin.package:
+    name: "{{ curated_default_packages }}"
+    state: present

ansible/site.yml

@@ -0,0 +1,6 @@
+---
+- name: Apply Ghostdrive curated baseline
+  hosts: ghostdrive_target
+  become: true
+  roles:
+    - curated_default

config/defaults.yaml

@@ -0,0 +1,3 @@
+ubuntu_release: "24.04"
+target_arch: "x86_64"
+baseline_profile: "curated-default"

config/schema.json

@@ -0,0 +1,27 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "type": "object",
+  "required": [
+    "ubuntu_release",
+    "target_arch",
+    "baseline_profile"
+  ],
+  "properties": {
+    "ubuntu_release": {
+      "enum": [
+        "24.04"
+      ]
+    },
+    "target_arch": {
+      "enum": [
+        "x86_64"
+      ]
+    },
+    "baseline_profile": {
+      "enum": [
+        "curated-default"
+      ]
+    }
+  },
+  "additionalProperties": true
+}

docs/architecture.md

@@ -0,0 +1,34 @@
+# Architecture
+
+Ghostdrive v1 is an install-to-USB pipeline for Ubuntu 24.04 x86_64.
+
+## Modules
+
+- Installer Orchestrator: `scripts/build/install_to_usb.sh`
+- Seed Renderer: `scripts/build/render_autoinstall_seed.sh`
+- Provisioner: `scripts/provision/apply_baseline.sh` and `ansible/`
+- Image Pipeline: `scripts/image/generalize.sh`, `scripts/image/capture.sh`, `scripts/image/write_manifest.sh`, `scripts/image/restore.sh`
+- Verifier: `scripts/verify/boot_smoke_bios.sh`, `scripts/verify/boot_smoke_uefi.sh`, and Bats tests under `tests/bats/`
+
+## Data Flow
+
+1. Validate the user configuration (`scripts/validate-config.sh`) against `config/schema.json`.
+2. Prepare install orchestration for a specific target block device.
+3. Apply the curated baseline profile with Ansible to the target root filesystem.
+4. Generalize machine identity artifacts before capture.
+5. Capture a compressed image and write checksum/size metadata.
+6. Restore the image to additional USB devices.
+7. Verify behavior in CI and with boot smoke checks.
+
+## Constraints
+
+- Build host: Linux only.
+- Target OS and architecture: Ubuntu 24.04 LTS x86_64.
+- Output model: fully installed USB image.
+- Repository policy: no secrets in source control.
+
+## Operational Boundaries
+
+- Device writes are destructive and require explicit `--device` selection.
+- Image scripts require real block devices and image files.
+- Boot smoke scripts validate firmware-level boot signals for BIOS and UEFI paths.

docs/cloning-workflow.md

@@ -0,0 +1,51 @@
+# Cloning Workflow
+
+This workflow captures a golden image from a prepared USB install and restores it to additional devices.
+
+## 1. Generalize Before Capture
+
+Generalize the mounted target root so clones do not share host identity artifacts.
+
+```bash
+scripts/image/generalize.sh --root /mnt/ghostdrive-root
+```
+
+The generalization step clears machine identity and volatile runtime artifacts:
+
+- `/etc/machine-id`
+- `/var/lib/dbus/machine-id`
+- `/etc/ssh/ssh_host_*`
+- `/var/log/*`
+
+## 2. Capture Compressed Image
+
+```bash
+scripts/image/capture.sh --device /dev/sdX --output artifacts/ghostdrive.img.zst
+```
+
+## 3. Write Artifact Manifest
+
+```bash
+scripts/image/write_manifest.sh --image artifacts/ghostdrive.img.zst --output artifacts/ghostdrive.manifest.json
+```
+
+Manifest fields include image path, SHA-256 checksum, and size in bytes.
+
+## 4. Restore to a New USB Device
+
+```bash
+scripts/image/restore.sh --image artifacts/ghostdrive.img.zst --device /dev/sdY --manifest artifacts/ghostdrive.manifest.json
+```
+
+Restore requires integrity verification on every run. Provide either `--manifest` or `--sha256`.
+
+## 5. Validate Restored Media
+
+- Confirm device partitions and filesystem mount cleanly.
+- Run BIOS and UEFI boot smoke scripts when validating pipeline behavior.
+- Perform first-boot checks on hardware before fleet replication.
+
+## Safety Notes
+
+- `capture.sh` and `restore.sh` require real block devices.
+- Always verify selected `--device` values before running destructive commands.

docs/compatibility-matrix.md

@@ -0,0 +1,19 @@
+# Compatibility Matrix
+
+| Area | Supported in v1 | Notes |
+|---|---|---|
+| Build host OS | Linux | Ubuntu LTS recommended |
+| Build host architecture | x86_64 | CI runs on Ubuntu 24.04 x86_64 |
+| Target OS | Ubuntu 24.04 LTS | Fixed by config schema |
+| Target architecture | x86_64 | Fixed by config schema |
+| Output format | Installed USB image | Captured as compressed `.img.zst` |
+| Provisioning | Ansible curated baseline | `ansible/site.yml` |
+| VM boot verification | BIOS and UEFI smoke checks | QEMU + OVMF |
+| Cross-platform builders | No | Out of scope for v1 |
+| ARM targets | No | Out of scope for v1 |
+
+## Validation Sources
+
+- Config constraints: `config/schema.json`
+- CI checks: `.github/workflows/ci.yml`
+- Boot smoke scripts: `scripts/verify/boot_smoke_bios.sh`, `scripts/verify/boot_smoke_uefi.sh`

docs/provisioning.md

@@ -0,0 +1,39 @@
+# Provisioning Runbook
+
+This runbook applies the curated Ghostdrive baseline to an installed target root filesystem.
+
+## Inputs
+
+- Target root mount path (required): `--target-root`
+- Optional inventory override: `--inventory`
+- Baseline playbook: `ansible/site.yml`
+- Baseline profile in config: `curated-default`
+
+## Prerequisites
+
+- Linux build host.
+- `ansible-playbook` available on `PATH`.
+- Target root filesystem mounted (for example `/mnt/ghostdrive-root`).
+
+## Apply Baseline
+
+```bash
+scripts/provision/apply_baseline.sh --target-root /mnt/ghostdrive-root
+```
+
+The script creates a temporary chroot inventory and runs:
+
+```bash
+ansible-playbook -i ansible/inventory/local.ini -i <tmp-inventory> ansible/site.yml -e target_root=/mnt/ghostdrive-root
+```
+
+## Common Failures
+
+- `--target-root is required`: pass a mount path.
+- `target root does not exist`: mount the target filesystem first.
+- `inventory does not exist`: check the `--inventory` path.
+
+## Post-Run Checks
+
+- Confirm baseline packages and configuration are present on target.
+- Continue to generalization and image capture workflow.