docs: establish public alpha onboarding

ALPHA_TESTING.md

@@ -112,3 +112,9 @@ Do not include:
 - confidential workloads
 - sensitive evidence
 - regulated or classified information
+
+## Submit feedback
+
+After completing the evaluation, open the repository's **Alpha evaluation
+feedback** issue form. Do not include credentials, private keys, cloud account
+identifiers, confidential workloads, or sensitive evidence.

README.md

@@ -1,5 +1,180 @@
 # QuantumD
 
+[![CI](https://github.com/WindDAnalytics/quantumd/actions/workflows/ci.yml/badge.svg)](https://github.com/WindDAnalytics/quantumd/actions/workflows/ci.yml)
+[![Documentation](https://github.com/WindDAnalytics/quantumd/actions/workflows/docs.yml/badge.svg)](https://github.com/WindDAnalytics/quantumd/actions/workflows/docs.yml)
+[![Python](https://img.shields.io/badge/python-3.10%2B-blue.svg)](https://www.python.org/)
+[![License](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](LICENSE)
+[![Status](https://img.shields.io/badge/status-public%20alpha-orange.svg)](CHANGELOG.md)
+
 > **QuantumD exists to produce trustworthy evidence, not favorable quantum results.**
 
-QuantumD is the trust and execution layer for AI-generated quantum software. It enforces a strict zero-trust boundary around quantum execution: AI may generate the quantum program, but QuantumD independently evaluates it before trusting or executing it.
+QuantumD is the trust and execution layer for AI-generated quantum software.
+It verifies the exact workload, enforces execution policy, binds authorization
+to what actually runs, and produces evidence that can be checked independently.
+
+AI may generate a circuit or computational workflow. QuantumD decides whether
+that exact workload is permitted to execute and whether the resulting evidence
+supports the claimed run.
+
+## What QuantumD proves
+
+QuantumD binds together:
+
+- the project source and manifest
+- the verification decision
+- the authorized backend and shot count
+- the logical and executed circuit identities
+- the result artifact
+- the execution receipt
+- the signing-key lineage
+- the order of authorization and execution
+
+A successful job identifier or a complete cloud log is not enough. QuantumD
+checks the chain connecting reviewer intent, authorization, execution, and
+results.
+
+## Run the public alpha
+
+QuantumD `0.7.4a0` is published on TestPyPI. Use an isolated Python environment
+and download only the QuantumD wheel from TestPyPI. Dependencies are then
+resolved from the default Python Package Index.
+
+```bash
+python3.12 -m venv .venv
+source .venv/bin/activate
+python -m pip install --upgrade pip
+
+python -m pip download \
+  --no-deps \
+  --only-binary=:all: \
+  --index-url https://test.pypi.org/simple/ \
+  quantumd==0.7.4a0
+
+echo \
+  "761a865a5aaf655f570fa3ae6f1d0f9b1b09cb89ee5519ac1843b738d251b7d2  quantumd-0.7.4a0-py3-none-any.whl" \
+  | sha256sum --check
+
+python -m pip install \
+  ./quantumd-0.7.4a0-py3-none-any.whl
+```
+
+Create and execute a governed local project:
+
+```bash
+quantumd quickstart my-first-quantumd-project
+```
+
+Inspect the trust posture and independently verify the evidence:
+
+```bash
+quantumd doctor my-first-quantumd-project
+
+quantumd verify-chain \
+  my-first-quantumd-project \
+  --latest
+```
+
+The local quickstart is intentionally restricted:
+
+```text
+Trust mode:             LOCAL_DEVELOPMENT
+Trust scope:            LOCAL_SIMULATION_ONLY
+Hardware authorization: PROHIBITED
+KMS signing used:       False
+IBM contacted:          False
+Hardware action:        None
+```
+
+Independent verification should finish with:
+
+```text
+[STATUS] COMPLETE EVIDENCE CHAIN VERIFIED
+IBM contacted:   False
+KMS contacted:   False
+Hardware action: None
+```
+
+No Google Cloud account, IBM Quantum account, or hardware access is required
+for the local quickstart.
+
+## The Evidence Graph
+
+A local simulator run produces a compact evidence chain:
+
+```text
+PROJECT -> QVERIFY -> QEXEC
+```
+
+An organization-governed hardware workflow extends the chain:
+
+```text
+PROJECT
+   |
+   v
+QVERIFY -> QPLAN -> QAPPROVAL -> QSUB -> IBM JOB -> QEXEC
+```
+
+Each node binds to the exact records before and after it. Independent
+verification checks signatures, key lineage, workload identity, circuit
+identity, result hashes, shot counts, and execution timing without contacting
+IBM or KMS.
+
+## Trust modes
+
+| Trust mode | Purpose | Hardware authority |
+| --- | --- | --- |
+| `UNCONFIGURED` | No valid signing provider | Prohibited |
+| `LOCAL_DEVELOPMENT` | Project-local simulator evaluation | Prohibited |
+| `KMS_GOVERNED` | Organization-managed authorization and signing | Policy controlled |
+| `SELF_MANAGED_HARDWARE` | Planned developer-managed hardware path | Not yet available |
+
+A local-development identity cannot be promoted into hardware authority.
+Missing, mismatched, replayed, expired, or corrupted evidence causes denial.
+
+## Evaluate QuantumD
+
+QuantumD is recruiting five early evaluators:
+
+1. a quantum developer
+2. a software-supply-chain or security engineer
+3. an ML, data, or scientific-computing engineer
+4. a technical leader from an audit-exposed environment
+5. an educator, researcher, or advanced technical student
+
+Complete the installation and quickstart without a live walkthrough. Then
+submit the structured **Alpha evaluation feedback** issue form.
+
+Read [ALPHA_TESTING.md](ALPHA_TESTING.md) before beginning.
+
+## Documentation
+
+- [Installation](docs/getting-started/installation.md)
+- [Local quickstart](docs/getting-started/quickstart.md)
+- [Evidence Graph](docs/concepts/evidence-graph.md)
+- [Trust boundary](docs/concepts/trust-boundary.md)
+- [Trust modes](docs/concepts/trust-modes.md)
+- [IBM Quantum provider](docs/providers/ibm-quantum.md)
+- [CLI reference](docs/reference/cli.md)
+- [Security policy](SECURITY.md)
+- [Contributing](CONTRIBUTING.md)
+- [Support](SUPPORT.md)
+
+## Alpha boundaries
+
+QuantumD is alpha software. Interfaces and evidence schemas may evolve.
+Pin exact versions and preserve evidence with the version that produced it.
+
+Local simulation is suitable for evaluation and development. QuantumD alpha
+must not be treated as the sole control protecting safety-critical, classified,
+regulated, or financially material operations.
+
+Security concerns must be reported privately under [SECURITY.md](SECURITY.md).
+Do not publish credentials, private keys, confidential workloads, or sensitive
+evidence in issues or Discussions.
+
+## Project
+
+- Website: [quantumd.ai](https://quantumd.ai)
+- License: [Apache License 2.0](LICENSE)
+- Current alpha: `0.7.4a0`
+- Release tag: `v0.7.4-alpha`

docs/alpha-evaluation.md

@@ -0,0 +1,27 @@
+# Alpha evaluation
+
+QuantumD is recruiting five early technical evaluators:
+
+1. a quantum developer
+2. a software-supply-chain or security engineer
+3. an ML, data, or scientific-computing engineer
+4. a technical leader from an audit-exposed environment
+5. an educator, researcher, or advanced technical student
+
+## Evaluation rule
+
+Complete the installation and local quickstart without a live walkthrough.
+Record where the documentation creates confusion, skepticism, or unnecessary
+work.
+
+Use the [installation guide](getting-started/installation.md), then run:
+
+~~~bash
+quantumd quickstart my-first-quantumd-project
+quantumd doctor my-first-quantumd-project
+quantumd verify-chain my-first-quantumd-project --latest
+~~~
+
+Submit the repository's **Alpha evaluation feedback** issue form. Do not
+publish credentials, private keys, cloud identifiers, confidential workloads,
+sensitive evidence, or regulated data.

docs/concepts/trust-modes.md

@@ -30,7 +30,7 @@ When KMS is configured, it takes precedence over local-development trust.
 
 ## `SELF_MANAGED_HARDWARE`
 
-Planned for Phase 5B.
+Planned.
 
 This mode will allow a developer to use an encrypted local signing
 identity and their own IBM Quantum account without requiring GCP.

docs/getting-started/installation.md

@@ -1,61 +1,121 @@
 # Installation
 
-QuantumD can run in Linux, WSL, Cloud Shell, or another compatible Python
-environment.
+QuantumD runs on Linux, Windows Subsystem for Linux, Cloud Shell, and other
+compatible Python environments.
 
-## Install from source
+The public alpha requires Python 3.10 or newer. Python 3.12 is the reference
+environment used by the release and acceptance workflows.
 
-The public repository is the authoritative installation path before the
-production PyPI alpha is released.
+## Install the published alpha
 
-~~~bash
-git clone https://github.com/WindDAnalytics/quantumd.git
-cd quantumd
+Create an isolated environment:
 
-python -m venv .venv
+~~~bash
+python3.12 -m venv .venv
 source .venv/bin/activate
-
 python -m pip install --upgrade pip
-python -m pip install -e .
 ~~~
 
+Download only the exact QuantumD wheel from TestPyPI:
+
+~~~bash
+python -m pip download \
+  --no-deps \
+  --only-binary=:all: \
+  --index-url https://test.pypi.org/simple/ \
+  quantumd==0.7.4a0
+~~~
+
+Verify the published wheel:
+
+~~~bash
+echo \
+  "761a865a5aaf655f570fa3ae6f1d0f9b1b09cb89ee5519ac1843b738d251b7d2  quantumd-0.7.4a0-py3-none-any.whl" \
+  | sha256sum --check
+~~~
+
+Install the downloaded wheel:
+
+~~~bash
+python -m pip install \
+  ./quantumd-0.7.4a0-py3-none-any.whl
+~~~
+
+Because the wheel is installed from a local file, its dependencies resolve
+from the default Python Package Index rather than TestPyPI.
+
+!!! warning "Do not use TestPyPI as the only dependency index"
+
+    Avoid `using TestPyPI as the sole package index`. TestPyPI is
+    a testing service and may contain unrelated or incomplete dependency
+    packages. Download the exact QuantumD artifact first, then install the
+    local wheel.
+
 Confirm the installation:
 
 ~~~bash
 quantumd --help
-quantumd doctor .
 ~~~
 
-## WSL
+## Run the first governed workflow
+
+~~~bash
+quantumd quickstart my-first-quantumd-project
+~~~
+
+Then inspect and independently verify it:
+
+~~~bash
+quantumd doctor my-first-quantumd-project
+
+quantumd verify-chain \
+  my-first-quantumd-project \
+  --latest
+~~~
 
-No Google Cloud account is required for local simulation.
+No Google Cloud account or IBM Quantum account is required for the local
+simulator path.
+
+## Windows Subsystem for Linux
 
 From a WSL terminal:
 
 ~~~bash
 cd ~
-git clone https://github.com/WindDAnalytics/quantumd.git
-cd quantumd
 
-python3 -m venv .venv
-source .venv/bin/activate
-python -m pip install -e .
-~~~
+python3.12 -m venv quantumd-alpha
+source quantumd-alpha/bin/activate
+python -m pip install --upgrade pip
 
-You can then run:
+python -m pip download \
+  --no-deps \
+  --only-binary=:all: \
+  --index-url https://test.pypi.org/simple/ \
+  quantumd==0.7.4a0
+
+python -m pip install \
+  ./quantumd-0.7.4a0-py3-none-any.whl
 
-~~~bash
 quantumd quickstart ~/quantumd-first-run
 ~~~
 
-## Public PyPI target
+## Install from source for development
 
-The intended public-alpha experience is:
+Clone the repository only when contributing or evaluating unreleased changes:
 
 ~~~bash
-pip install -i https://test.pypi.org/simple/ quantumd
-quantumd quickstart
+git clone https://github.com/WindDAnalytics/quantumd.git
+cd quantumd
+
+python3.12 -m venv .venv
+source .venv/bin/activate
+python -m pip install --upgrade pip
+python -m pip install -e ".[dev]"
 ~~~
 
-This documentation does not claim that production PyPI publishing has
-occurred until the release acceptance process is complete. The link above is for the pre-release.
+Run the development acceptance checks:
+
+~~~bash
+python -m pytest -q
+bash scripts/public_alpha_acceptance.sh
+~~~