fix: harden public installation across Linux and WSL

.github/workflows/public-install.yml

@@ -0,0 +1,128 @@
+name: QuantumD Public Install Compatibility
+
+on:
+  pull_request:
+    paths:
+      - ".github/workflows/public-install.yml"
+      - "ALPHA_TESTING.md"
+      - "CHANGELOG.md"
+      - "CONTRIBUTING.md"
+      - "README.md"
+      - "docs/getting-started/**"
+      - "mkdocs.yml"
+      - "pyproject.toml"
+      - "scripts/bootstrap_public_alpha.sh"
+      - "src/**"
+  push:
+    branches:
+      - main
+      - master
+      - "feature/**"
+    paths:
+      - ".github/workflows/public-install.yml"
+      - "ALPHA_TESTING.md"
+      - "CHANGELOG.md"
+      - "CONTRIBUTING.md"
+      - "README.md"
+      - "docs/getting-started/**"
+      - "mkdocs.yml"
+      - "pyproject.toml"
+      - "scripts/bootstrap_public_alpha.sh"
+      - "src/**"
+
+permissions:
+  contents: read
+
+concurrency:
+  group: quantumd-public-install-${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  python-compatibility:
+    name: Python ${{ matrix.python-version }} compatibility
+    runs-on: ubuntu-24.04
+    timeout-minutes: 35
+
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version:
+          - "3.10"
+          - "3.11"
+          - "3.12"
+
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
+
+      - name: Set up Python
+        uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
+        with:
+          python-version: "${{ matrix.python-version }}"
+          cache: pip
+          cache-dependency-path: pyproject.toml
+
+      - name: Install source and tests
+        run: |
+          python -m pip install --upgrade pip
+          python -m pip install -e ".[dev]"
+
+      - name: Check parser compatibility
+        run: python -m compileall -q src tests
+
+      - name: Run regression suite
+        run: python -m pytest -q
+
+      - name: Run local quickstart and verification
+        run: |
+          quantumd quickstart "$RUNNER_TEMP/quantumd-project"
+          quantumd doctor "$RUNNER_TEMP/quantumd-project"
+          quantumd verify-chain \
+            "$RUNNER_TEMP/quantumd-project" \
+            --latest
+
+  ubuntu-22-public-bootstrap:
+    name: Ubuntu 22.04 public bootstrap
+    runs-on: ubuntu-22.04
+    timeout-minutes: 40
+
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
+
+      - name: Run exact published-alpha bootstrap
+        run: |
+          QUANTUMD_KMS_KEY_VERSION="projects/poisoned/locations/test/keyRings/test/cryptoKeys/test/cryptoKeyVersions/1" \
+          GOOGLE_APPLICATION_CREDENTIALS="/tmp/nonexistent-quantumd-credentials.json" \
+          bash scripts/bootstrap_public_alpha.sh \
+            --venv "$RUNNER_TEMP/quantumd-alpha" \
+            --project "$RUNNER_TEMP/quantumd-project"
+
+  ubuntu-20-public-bootstrap:
+    name: Ubuntu 20.04 container public bootstrap
+    runs-on: ubuntu-24.04
+    timeout-minutes: 45
+
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
+
+      - name: Run bootstrap in Ubuntu 20.04
+        run: |
+          docker run \
+            --rm \
+            --volume "$PWD:/workspace:ro" \
+            ubuntu:20.04 \
+            bash -lc '
+              set -euo pipefail
+              apt-get update
+              DEBIAN_FRONTEND=noninteractive \
+                apt-get install -y \
+                  build-essential \
+                  ca-certificates \
+                  curl \
+                  git
+              bash /workspace/scripts/bootstrap_public_alpha.sh \
+                --venv /tmp/quantumd-alpha \
+                --project /tmp/quantumd-project
+            '

ALPHA_TESTING.md

@@ -19,50 +19,25 @@ The initial group should include:
 Complete the installation and quickstart without a live walkthrough. Record
 where the documentation creates confusion, skepticism, or unnecessary work.
 
-## Secure TestPyPI installation
+## Secure public-alpha installation
 
-Create an isolated environment:
+Use the [installation guide](docs/getting-started/installation.md). The
+recommended Linux and WSL path is the repository bootstrap:
 
 ```bash
-python3.12 -m venv .venv
-source .venv/bin/activate
-python -m pip install --upgrade pip
-```
-
-Download the exact QuantumD wheel from TestPyPI without resolving dependencies
-from that index:
-
-```bash
-python -m pip download \
-  --no-deps \
-  --only-binary=:all: \
-  --index-url https://test.pypi.org/simple/ \
-  quantumd==0.7.4a0
-```
-
-Install the downloaded wheel. Its dependencies will resolve from the default
-Python Package Index:
-
-```bash
-python -m pip install \
-  ./quantumd-0.7.4a0-py3-none-any.whl
-```
+curl -fsSLO \
+  https://raw.githubusercontent.com/WindDAnalytics/quantumd/main/scripts/bootstrap_public_alpha.sh
 
-Run the first governed local workflow:
-
-```bash
-quantumd quickstart my-first-quantumd-project
+less bootstrap_public_alpha.sh
+bash bootstrap_public_alpha.sh
 ```
 
-Inspect the environment and independently verify the evidence:
+The evaluator should review the script before running it. The bootstrap creates
+an isolated Python 3.12 environment, verifies the exact public wheel, runs the
+local quickstart, and independently verifies the resulting evidence.
 
-```bash
-quantumd doctor my-first-quantumd-project
-
-quantumd verify-chain \
-  my-first-quantumd-project \
-  --latest
-```
+Record the operating system, architecture, Python bootstrap method, installation
+time, and time to the first verified chain.
 
 ## Expected security boundary
 

CHANGELOG.md

@@ -1,5 +1,13 @@
 # Changelog
 
+## Unreleased
+### Public installation hardening
+- Added a guided Linux and WSL bootstrap using a `uv`-managed Python 3.12 environment.
+- Added explicit platform-support labels and a compatibility matrix.
+- Documented Ubuntu 20.04 default-Python and missing-`venv` failure modes.
+- Added compatibility testing for Python 3.10, 3.11, and 3.12.
+- Added public bootstrap acceptance for Ubuntu 22.04 and Ubuntu 20.04 in a container.
+
 ## 0.7.4a0 - 2026-08-02
 
 ### Public-alpha acceptance hardening

CONTRIBUTING.md

@@ -12,13 +12,19 @@ Use Python 3.12 for the reference development environment.
 git clone https://github.com/WindDAnalytics/quantumd.git
 cd quantumd
 
-python3.12 -m venv .venv
+curl -LsSf https://astral.sh/uv/install.sh | sh
+export PATH="$HOME/.local/bin:$PATH"
+
+uv python install 3.12
+uv venv --python 3.12 --seed .venv
 source .venv/bin/activate
 
-python -m pip install --upgrade pip
 python -m pip install -e ".[dev]"
 ```
 
+Contributors who already have Python 3.12 and working standard-library virtual
+environment support may use `python3.12 -m venv .venv`.
+
 Run the regression suite:
 
 ```bash

README.md

@@ -99,16 +99,25 @@ QuantumD `0.7.4a0` is published on TestPyPI. Use an isolated Python environment
 and download only the QuantumD wheel from TestPyPI. Dependencies are installed
 from the default Python Package Index.
 
-### 1. Create an isolated environment
+### 1. Create a supported isolated environment
+
+The recommended Linux and WSL path uses `uv`, so the setup does not depend on
+the operating system's default Python or `venv` package:
 
 ```bash
-python3.12 -m venv .venv
-source .venv/bin/activate
-python -m pip install --upgrade pip
+curl -LsSf https://astral.sh/uv/install.sh | sh
+export PATH="$HOME/.local/bin:$PATH"
+
+uv python install 3.12
+uv venv --python 3.12 --seed ~/.venvs/quantumd-alpha
+source ~/.venvs/quantumd-alpha/bin/activate
+python --version
 ```
 
 QuantumD supports Python 3.10 and newer. Python 3.12 is the reference alpha
-environment.
+environment. Users who already have a supported Python and working `venv` may
+use the standard-library environment path described in the
+[installation guide](docs/getting-started/installation.md).
 
 ### 2. Download and verify the exact wheel
 
@@ -163,9 +172,10 @@ KMS contacted:   False
 Hardware action: None
 ```
 
-For expanded instructions, WSL guidance, checksum details, and source
-development installation, see the
-[installation guide](docs/getting-started/installation.md).
+For expanded instructions, the guided bootstrap, WSL troubleshooting,
+checksum details, and source development installation, see the
+[installation guide](docs/getting-started/installation.md) and
+[platform-support matrix](docs/getting-started/platform-support.md).
 
 ## The Evidence Graph