Update Quickstart: bootstrap is primary path, ISO is workflow artifact

The bootstrap/rebase path is the primary install method since:
- The OCI image is always available at ghcr.io (cosign-signed)
- The ISO exceeds GitHub Releases' 2GB limit (available as workflow
  artifact with 90-day retention)
- OVA/QCOW2 require local build from the OCI image

README Quickstart now shows:
- Bootstrap as the recommended path (install Fedora, run script, reboot)
- Build VM locally as second option (scripts/vm/build-qcow2.sh)
- Development mode as third option

Quickstart doc (docs/install/quickstart.md) rewritten with:
- Honest artifact availability table explaining what's where
- Bootstrap as Path A with full copy-paste commands
- VM build as Path B with local build instructions
- ISO/OVA/QCOW2 availability note at the top
- Verification section uses cosign verify (not ISO checksum)

Releases & Packages section updated with Bootable ISO subsection
explaining workflow artifact availability and local VM build commands.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: SecAI-Hub

README.md

@@ -46,30 +46,34 @@ Built on [uBlue](https://universal-blue.org/) (Fedora Atomic / Silverblue). All
 
 ## Quickstart
 
-Download, verify, boot, run the setup wizard. See [docs/install/quickstart.md](docs/install/quickstart.md) for full details.
-
-| Method | Time | Best For |
-|--------|------|----------|
-| [**ISO**](docs/install/quickstart.md#path-a-install-from-iso-real-pc) (Recommended) | ~30 min | Real PC, full security |
-| [**OVA**](docs/install/quickstart.md#path-b-import-vm--virtualbox--vmware-ova) | ~15 min | Try it first (VirtualBox/VMware) |
-| [**QCOW2**](docs/install/quickstart.md#path-c-import-vm--kvm--proxmox--qemu-qcow2) | ~15 min | KVM / Proxmox |
-| [**Rebase**](docs/install/quickstart.md#path-d-advanced--rebase-from-existing-fedora) | ~45 min | Existing Fedora Silverblue |
-
-After boot, the setup wizard guides you through profile selection, system verification, and model import.
-
-### Advanced / Operator Install
-
-For production deployments with digest pinning and signing policy configuration:
+Install [Fedora Silverblue 42](https://fedoraproject.org/silverblue/), then run the bootstrap script. The script configures cosign signature verification **before** the first image pull — no unverified data is ever fetched.
 
 ```bash
-# Review the bootstrap script, then run with a pinned digest
+# 1. Download and review the bootstrap script
 curl -sSfL https://raw.githubusercontent.com/SecAI-Hub/SecAI_OS/main/files/scripts/secai-bootstrap.sh \
   -o /tmp/secai-bootstrap.sh
 less /tmp/secai-bootstrap.sh
-sudo bash /tmp/secai-bootstrap.sh --digest sha256:RELEASE_DIGEST
+
+# 2. Run the bootstrap (use --digest from the latest release for production)
+sudo bash /tmp/secai-bootstrap.sh
+
+# 3. Reboot and open the setup wizard
 sudo systemctl reboot
+# Then open http://127.0.0.1:8480
 ```
 
+The setup wizard guides you through privacy profile selection, system verification, and model import.
+
+| Method | Time | Best For | Details |
+|--------|------|----------|---------|
+| **Bootstrap** (Recommended) | ~30 min | Real PC or VM | Install Fedora Silverblue, run script, reboot |
+| **Build VM locally** | ~45 min | VirtualBox / VMware / KVM | `scripts/vm/build-qcow2.sh` builds a QCOW2 from the OCI image |
+| **Development** | ~10 min | Service development only | No OS features; see [dev guide](docs/install/dev.md) |
+
+See [docs/install/quickstart.md](docs/install/quickstart.md) for full step-by-step instructions, VM build details, and verification commands.
+
+For production deployments with digest pinning: `sudo bash secai-bootstrap.sh --digest sha256:RELEASE_DIGEST`
+
 See [bare metal](docs/install/bare-metal.md) | [virtual machine](docs/install/vm.md) | [development](docs/install/dev.md) | [recovery](docs/install/recovery-bootstrap.md)
 
 ### Get Your First Model
@@ -198,13 +202,26 @@ Tagged releases (`v*`) are built by the [Release workflow](.github/workflows/rel
 | `SHA256SUMS` | Checksums for all release artifacts |
 | `SHA256SUMS.sig` | Cosign signature over checksums |
 | `IMAGE_DIGEST` | OCI image digest for this release |
-| `IMAGE_REF_PINNED` | Fully qualified digest-pinned image reference |
 | `RELEASE_MANIFEST.json` | Machine-readable release manifest (binaries, SBOMs, provenance, build metadata) |
+| `secai-os-*.iso.sig` | Cosign signature for the bootable ISO |
 
 Go services shipped as release binaries: `airlock`, `registry`, `tool-firewall`, `gpu-integrity-watch`, `mcp-firewall`, `policy-engine`, `runtime-attestor`, `integrity-monitor`, `incident-recorder`.
 
 Python services (`ui`, `agent`, `quarantine`, `diffusion-worker`, `search-mediator`) are baked into the OCI image and do not ship as standalone binaries.
 
+### Bootable ISO
+
+A signed bootable ISO is built by every tagged release using [build-container-installer](https://github.com/JasonN3/build-container-installer). The ISO exceeds GitHub's 2 GB release asset limit, so it is available as a **workflow artifact** (90-day retention) from the [Release workflow runs](https://github.com/SecAI-Hub/SecAI_OS/actions/workflows/release.yml). The cosign signature (`.iso.sig`) is published to the GitHub Release for verification.
+
+To build a QCOW2 or OVA locally from the OCI image:
+
+```bash
+bash scripts/vm/build-qcow2.sh        # produces output/secai-os.qcow2
+bash scripts/vm/build-ova.sh           # produces output/secai-os.ova
+```
+
+Requires a Linux host with `virt-install`, `qemu-img`, and `libvirt`.
+
 ### Verify a Release
 
 ```bash

docs/install/quickstart.md

@@ -1,131 +1,116 @@
 # Quickstart
 
-Get SecAI OS running in the fewest steps possible. Choose the path that fits your hardware.
+Get SecAI OS running in the fewest steps possible. Choose the path that fits your situation.
 
 ## Choose Your Install Path
 
 | Method | Time | Difficulty | Best For |
 |--------|------|-----------|----------|
-| **ISO** (Recommended) | ~30 min | Easy | Real PC, full security |
-| **VM Import (OVA)** | ~15 min | Easy | Try it first (VirtualBox/VMware) |
-| **VM Import (QCOW2)** | ~15 min | Easy | KVM / Proxmox / QEMU |
-| **Rebase** (Advanced) | ~45 min | Moderate | Existing Fedora Silverblue |
+| **Bootstrap** (Recommended) | ~30 min | Easy | Real PC or VM, full security |
+| **VM Build** | ~45 min | Moderate | Local evaluation in VirtualBox/VMware/KVM |
+| **Development** | ~10 min | Easy | Service development only (no OS features) |
+
+> **Note on ISO/OVA/QCOW2:** The release pipeline builds a signed bootable ISO, but it exceeds GitHub's 2 GB release asset limit. Pre-built VM images (OVA/QCOW2) require build infrastructure not yet provisioned. For now, the bootstrap path below is the primary install method. See [Artifact Availability](#artifact-availability) for details.
 
 ---
 
-## Path A: Install from ISO (Real PC)
+## Path A: Bootstrap Install (Real PC or VM)
+
+This is the recommended path. It installs Fedora Silverblue, then rebases to SecAI OS with full signature verification. You get the complete security stack: Secure Boot, TPM2, encrypted vault, and all 25+ defense layers.
 
-This gives you the full security stack including Secure Boot, TPM2, and hardware isolation.
+**1. Install Fedora Silverblue**
 
-**1. Download the ISO**
+Download [Fedora Silverblue 42](https://fedoraproject.org/silverblue/) and install it on your hardware or in a VM. A minimal install is fine — SecAI OS replaces the desktop.
 
-Go to the [latest release](https://github.com/SecAI-Hub/SecAI_OS/releases/latest) and download `secai-os-<version>-x86_64.iso`.
+**2. Run the bootstrap script**
 
-**2. Write to USB**
+The bootstrap script configures cosign signature verification **before** the first image pull — no unverified data is ever fetched.
 
-Linux/macOS:
 ```bash
-sudo dd if=secai-os-*.iso of=/dev/sdX bs=4M status=progress
-sync
+# Download and review the script (always review before running as root)
+curl -sSfL https://raw.githubusercontent.com/SecAI-Hub/SecAI_OS/main/files/scripts/secai-bootstrap.sh \
+  -o /tmp/secai-bootstrap.sh
+less /tmp/secai-bootstrap.sh
+
+# Run the bootstrap
+sudo bash /tmp/secai-bootstrap.sh
 ```
 
-Windows: Use [Rufus](https://rufus.ie) — select the ISO, choose your USB drive, and click Start.
+For production, pin to an exact image digest from the [latest release](https://github.com/SecAI-Hub/SecAI_OS/releases/latest):
 
-**3. Boot from USB**
+```bash
+sudo bash /tmp/secai-bootstrap.sh --digest sha256:RELEASE_DIGEST
+```
 
-Restart your computer. Enter the boot menu (usually F12, F2, or Esc) and select the USB drive. Follow the installer prompts.
+**3. Reboot**
 
-**4. First boot**
+```bash
+sudo systemctl reboot
+```
 
-After installation completes and the system reboots, open a browser to:
+**4. Open the UI**
+
+After reboot, open a browser to:
 ```
 http://127.0.0.1:8480
 ```
 
-**What you should see:** The SecAI OS setup wizard. It will ask you to choose a privacy profile, verify system health, and import your first AI model.
+**What you should see:** The SecAI OS setup wizard. It asks you to choose a privacy profile, verifies system health, and walks you through importing your first AI model.
 
 ---
 
-## Path B: Import VM — VirtualBox / VMware (OVA)
-
-For evaluation. Note: VM installs cannot use TPM2 sealing or Secure Boot chain verification.
-
-**1. Download the OVA**
+## Path B: Build a VM Image Locally
 
-Go to the [latest release](https://github.com/SecAI-Hub/SecAI_OS/releases/latest) and download `secai-os-<version>.ova`.
+If you want a self-contained VM image without installing Fedora first, you can build one from the OCI image using the included scripts. This requires a Linux host with KVM/QEMU.
 
-> OVA may not be available in every release. If absent, use Path C (QCOW2) or Path A (ISO).
+**1. Clone the repo and build**
 
-**2. Import**
-
-- **VirtualBox:** File → Import Appliance → select the OVA → Import
-- **VMware:** File → Open → select the OVA → Import
+```bash
+git clone https://github.com/SecAI-Hub/SecAI_OS.git
+cd SecAI_OS
 
-**3. Start the VM and open the UI**
+# Build QCOW2 (requires: virt-install, qemu-img, libvirt)
+bash scripts/vm/build-qcow2.sh
 
-Start the VM. After boot, open a browser to the VM's IP on port 8480:
+# Optionally convert to OVA for VirtualBox/VMware
+bash scripts/vm/build-ova.sh
 ```
-http://<vm-ip>:8480
-```
-
-If using NAT networking, forward port 8480 from the VM to your host, then use `http://127.0.0.1:8480`.
-
-**What you should see:** The setup wizard with profile selection, system check, and model import.
-
----
 
-## Path C: Import VM — KVM / Proxmox / QEMU (QCOW2)
+The build scripts pull the signed OCI image and create a bootable disk with root + encrypted vault partitions. Credentials are randomly generated and printed at build time.
 
-**1. Download the QCOW2**
-
-Go to the [latest release](https://github.com/SecAI-Hub/SecAI_OS/releases/latest) and download `secai-os-<version>.qcow2`.
-
-> QCOW2 may not be available in every release. If absent, use Path A (ISO).
-
-**2. Create a VM**
+**2. Start the VM**
 
 ```bash
-# Example: create and start a KVM VM using the downloaded disk
+# KVM/QEMU
 virt-install \
   --name secai-os \
   --memory 16384 \
   --vcpus 4 \
-  --disk path=secai-os-*.qcow2,format=qcow2 \
+  --disk path=output/secai-os.qcow2,format=qcow2 \
   --import \
   --os-variant fedora42 \
   --network default \
   --noautoconsole
+
+# Or import the OVA into VirtualBox/VMware
 ```
 
 **3. Access the UI**
 
 ```bash
-# Find the VM's IP
 virsh domifaddr secai-os
-# Open in browser
-xdg-open http://<vm-ip>:8480
+# Open http://<vm-ip>:8480 in your browser
 ```
 
-**What you should see:** The setup wizard.
+> **Security note:** VM installs cannot use TPM2 vault key sealing and the host hypervisor has visibility into guest memory. VMs are suitable for evaluation, not sensitive workloads. See [support-lifecycle.md](../support-lifecycle.md) for the full support matrix.
 
 ---
 
-## Path D: Advanced — Rebase from Existing Fedora
-
-If you already have Fedora Silverblue (F42+), you can rebase directly. This is the operator path.
+## Path C: Development Mode
 
-See [bare-metal.md](bare-metal.md) for the full bootstrap flow with digest pinning and signing policy configuration.
+Run individual services locally for development without rebasing your OS. No security features (sandboxing, firewall, vault) are active.
 
-```bash
-# Quick version (evaluation only — use --digest for production)
-curl -sSfL https://raw.githubusercontent.com/SecAI-Hub/SecAI_OS/main/files/scripts/secai-bootstrap.sh \
-  -o /tmp/secai-bootstrap.sh
-less /tmp/secai-bootstrap.sh   # Review first
-sudo bash /tmp/secai-bootstrap.sh
-sudo systemctl reboot
-```
-
-After reboot, open `http://127.0.0.1:8480` and run the setup wizard.
+See [dev.md](dev.md) for setup instructions.
 
 ---
 
@@ -135,14 +120,20 @@ Regardless of install path, the setup wizard guides you through:
 
 1. **Choose your privacy level** — Maximum Privacy (default), Web-Assisted Research, or Full Lab
 2. **System check** — verifies core services are running
-3. **Import a model** — upload a `.gguf` model file (it goes through the 7-stage quarantine pipeline automatically)
+3. **Import a model** — upload a `.gguf` model file (it passes through the 7-stage quarantine pipeline automatically)
 4. **Start chatting** — once the model is promoted, you're ready
 
 ---
 
 ## Verify Your Install (Optional)
 
-After downloading any release artifact, you can verify its integrity.
+After running the bootstrap, you can verify the image signature:
+
+```bash
+cosign verify --key cosign.pub ghcr.io/secai-hub/secai_os:latest
+```
+
+To verify release artifacts (Go binaries, SBOMs, checksums):
 
 **Linux / macOS:**
 ```bash
@@ -153,22 +144,34 @@ sha256sum -c SHA256SUMS --ignore-missing
 **Windows (PowerShell):**
 ```powershell
 Invoke-WebRequest -Uri "https://github.com/SecAI-Hub/SecAI_OS/releases/latest/download/SHA256SUMS" -OutFile SHA256SUMS
-$expected = (Get-Content SHA256SUMS | Select-String "secai-os").Line.Split()[0]
-$actual = (Get-FileHash "secai-os-*.iso" -Algorithm SHA256).Hash.ToLower()
-if ($expected -eq $actual) { "OK: checksum matches" } else { "FAIL: checksum mismatch" }
+Get-Content SHA256SUMS
 ```
 
-For advanced verification (cosign signatures, SLSA3 provenance), see [sample-release-bundle.md](../docs/sample-release-bundle.md) or run:
+For advanced verification (cosign detached signatures, SLSA3 provenance attestation), see [sample-release-bundle.md](../sample-release-bundle.md) or run:
 ```bash
 make verify-release
 ```
 
 ---
 
+## Artifact Availability
+
+| Artifact | Where | Status |
+|----------|-------|--------|
+| **OCI image** | `ghcr.io/secai-hub/secai_os:latest` | Always available, cosign-signed |
+| **Go binaries + SBOMs** | [GitHub Releases](https://github.com/SecAI-Hub/SecAI_OS/releases/latest) | Always available |
+| **ISO** | Release workflow artifact (90-day retention) | Built in CI; too large (~4 GB) for GitHub Releases |
+| **ISO signature** | [GitHub Releases](https://github.com/SecAI-Hub/SecAI_OS/releases/latest) | `.iso.sig` file for verification |
+| **QCOW2 / OVA** | `scripts/vm/build-qcow2.sh` / `build-ova.sh` | Build locally; CI build requires self-hosted KVM runner |
+
+The ISO is produced by every tagged release and is available as a [workflow artifact](https://github.com/SecAI-Hub/SecAI_OS/actions/workflows/release.yml) with 90-day retention. Its cosign signature (`.iso.sig`) is published to GitHub Releases for verification. For permanent ISO hosting, an external storage solution is needed.
+
+---
+
 ## Next Steps
 
 - [Import a GGUF Model](../examples/import-gguf-model.md)
 - [Enable Web Search](../examples/enable-web-search.md)
 - [Vault Management](../examples/lock-unlock-vault.md)
 - [Security Dashboard](http://127.0.0.1:8480/security) — verify your appliance health
-- [Why is this safe?](../docs/why-is-this-safe.md) — plain-language security explanation
+- [Why is this safe?](../why-is-this-safe.md) — plain-language security explanation