docs: establish public QuantumD documentation

.github/workflows/docs.yml

@@ -0,0 +1,54 @@
+name: QuantumD Documentation
+
+on:
+  pull_request:
+    paths:
+      - "docs/**"
+      - "mkdocs.yml"
+      - "requirements-docs.txt"
+      - ".github/workflows/docs.yml"
+
+  push:
+    branches:
+      - main
+    paths:
+      - "docs/**"
+      - "mkdocs.yml"
+      - "requirements-docs.txt"
+      - ".github/workflows/docs.yml"
+
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    name: Build documentation
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+          cache: pip
+          cache-dependency-path: requirements-docs.txt
+
+      - name: Install documentation dependencies
+        run: |
+          python -m pip install --upgrade pip
+          python -m pip install -r requirements-docs.txt
+
+      - name: Build documentation strictly
+        run: python -m mkdocs build --strict
+
+      - name: Upload rendered site
+        uses: actions/upload-artifact@v4
+        with:
+          name: quantumd-documentation-site
+          path: site/
+          if-no-files-found: error

.gitignore

@@ -30,3 +30,4 @@ fix_*.py
 **/evidence/reports/
 **/evidence/executions/
 **/evidence/ibm-smoke/
+site/

docs/concepts/evidence-graph.md

@@ -0,0 +1,39 @@
+# Evidence graph
+
+The Evidence Graph is the durable record of governed execution.
+
+## Local graph
+
+~~~text
+QVERIFY ──> QEXEC
+~~~
+
+`QVERIFY` records the verified project and executable authorization.
+`QEXEC` records the executed circuit, backend, shots, result artifact,
+and receipt.
+
+## Managed hardware graph
+
+~~~text
+QVERIFY
+   │
+   ▼
+QPLAN ──> QAPPROVAL ──> QSUB ──> IBM JOB ──> QEXEC
+~~~
+
+## Core bindings
+
+The verifier checks that:
+
+- Cryptographic signatures are valid.
+- The signing-key lineage is consistent.
+- Authorization binds to the exact verification record.
+- Source and manifest identities have not changed.
+- Execution binds to the authorized workload.
+- Logical and executed circuit identities match the evidence.
+- The result artifact hash is correct.
+- Observed shots equal authorized shots.
+- Authorization predates execution.
+
+The graph is intended to be verifiable independently of the system that
+originally produced it.

docs/concepts/trust-boundary.md

@@ -0,0 +1,33 @@
+# Trust boundary
+
+QuantumD treats code generation and governed execution as different
+security domains.
+
+~~~text
+UNTRUSTED OR EXTERNAL                QUANTUMD TRUST BOUNDARY
+
+AI-generated code  ────────────────> Project verification
+Notebook changes  ────────────────> Policy evaluation
+User configuration ───────────────> Exact workload binding
+                                     Signed evidence
+                                     Authorized execution
+                                     Independent verification
+~~~
+
+## What crosses the boundary
+
+A project crosses the boundary only after QuantumD establishes the exact
+identity of its source, manifest, target, and execution parameters.
+
+## What does not cross automatically
+
+- A generated circuit is not automatically trusted.
+- A passing simulation is not hardware authorization.
+- A local signing key is not an organization-managed identity.
+- An IBM credential is not approval to submit every workload.
+- A completed job is not accepted until its result is evidence-bound.
+
+## Fail-closed behavior
+
+Missing, mismatched, expired, replayed, or corrupted evidence causes
+denial instead of best-effort execution.

docs/concepts/trust-modes.md

@@ -0,0 +1,48 @@
+# Trust modes
+
+QuantumD separates local development from real hardware authority.
+
+## `UNCONFIGURED`
+
+No valid signing provider is available. Governed execution is denied.
+
+## `LOCAL_DEVELOPMENT`
+
+Available now.
+
+- Project-local signing identity.
+- Aer simulation only.
+- Offline verification.
+- No GCP requirement.
+- No IBM contact.
+- Hardware authorization prohibited.
+
+## `KMS_GOVERNED`
+
+Available for the existing organization-managed execution path.
+
+- Organization-controlled signing through Google Cloud KMS.
+- Managed approval and evidence lineage.
+- IBM hardware execution subject to policy and account access.
+- Intended for controlled production workflows.
+
+When KMS is configured, it takes precedence over local-development trust.
+
+## `SELF_MANAGED_HARDWARE`
+
+Planned for Phase 5B.
+
+This mode will allow a developer to use an encrypted local signing
+identity and their own IBM Quantum account without requiring GCP.
+
+Planned controls include:
+
+- Explicit hardware enablement.
+- Encrypted IBM credential storage.
+- Signing-key creation and import.
+- Backend and shot limits.
+- Cost ceilings.
+- Expiring, single-use approval.
+- Exact workload and result binding.
+
+A `LOCAL_DEVELOPMENT` identity will never automatically gain this scope.

docs/getting-started/installation.md

@@ -0,0 +1,61 @@
+# Installation
+
+QuantumD can run in Linux, WSL, Cloud Shell, or another compatible Python
+environment.
+
+## Install from source
+
+The public repository is the authoritative installation path before the
+production PyPI alpha is released.
+
+~~~bash
+git clone https://github.com/WindDAnalytics/quantumd.git
+cd quantumd
+
+python -m venv .venv
+source .venv/bin/activate
+
+python -m pip install --upgrade pip
+python -m pip install -e .
+~~~
+
+Confirm the installation:
+
+~~~bash
+quantumd --help
+quantumd doctor .
+~~~
+
+## WSL
+
+No Google Cloud account is required for local simulation.
+
+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 .
+~~~
+
+You can then run:
+
+~~~bash
+quantumd quickstart ~/quantumd-first-run
+~~~
+
+## Public PyPI target
+
+The intended public-alpha experience is:
+
+~~~bash
+pip install quantumd
+quantumd quickstart
+~~~
+
+This documentation does not claim that production PyPI publishing has
+occurred until the release acceptance process is complete.

docs/getting-started/quickstart.md

@@ -0,0 +1,54 @@
+# Local quickstart
+
+`quantumd quickstart` creates and executes a complete locally governed
+simulator workflow.
+
+## Run it
+
+~~~bash
+quantumd quickstart ./quantumd-first-run --shots 128
+~~~
+
+QuantumD will:
+
+1. Initialize a project.
+2. Create a project-local P-256 signing identity.
+3. Run verification and policy gates.
+4. Authorize only `aer-simulator`.
+5. Execute the verified workload.
+6. Sign the evidence and execution receipt.
+7. Verify the evidence chain offline.
+
+## Inspect the trust posture
+
+~~~bash
+quantumd doctor ./quantumd-first-run
+~~~
+
+The expected local posture is:
+
+~~~text
+Active trust mode:      LOCAL_DEVELOPMENT
+Local trust scope:      LOCAL_SIMULATION_ONLY
+Hardware authorization: PROHIBITED
+~~~
+
+## Verify the chain
+
+~~~bash
+quantumd verify-chain ./quantumd-first-run --latest
+~~~
+
+The verifier performs no network calls for a local chain.
+
+## Local identity
+
+The private identity is project-local and excluded from Git. QuantumD
+stores it beneath:
+
+~~~text
+.quantumd/local-trust/
+~~~
+
+Do not manually replace individual identity files. Partial or mismatched
+identity state is rejected rather than silently repaired.

docs/guides/local-simulation.md

@@ -0,0 +1,35 @@
+# Local simulation
+
+Local simulation is the safest way to begin with QuantumD.
+
+## Create a governed project
+
+~~~bash
+quantumd quickstart ./my-quantumd-project --shots 128
+~~~
+
+## Diagnose the environment
+
+~~~bash
+quantumd doctor ./my-quantumd-project
+~~~
+
+## Verify the latest execution
+
+~~~bash
+quantumd verify-chain ./my-quantumd-project --latest
+~~~
+
+## Security properties
+
+In `LOCAL_DEVELOPMENT` mode:
+
+- The only permitted target is `aer-simulator`.
+- IBM is not contacted.
+- KMS is not contacted.
+- No hardware action is taken.
+- Evidence is signed locally.
+- Verification can be completed offline.
+
+Local evidence is educational and developmental evidence. It is not a
+substitute for organization-managed production authorization.

docs/guides/verifying-a-chain.md

@@ -0,0 +1,33 @@
+# Verify an evidence chain
+
+Use the independent chain verifier to confirm that an execution remains
+cryptographically and logically intact.
+
+## Latest execution
+
+~~~bash
+quantumd verify-chain ./my-project --latest
+~~~
+
+## What success means
+
+A successful verification establishes that:
+
+- The required signatures validate.
+- The signing lineage is internally consistent.
+- Authorization and verification records refer to the same workload.
+- The project source and manifest remain unchanged.
+- The executed circuit and result remain bound to the receipt.
+- The shot count and execution sequence satisfy policy.
+
+## Offline local verification
+
+Local projects cache the public key needed to verify their evidence.
+
+The private signing key is not required to perform verification.
+
+## Failure
+
+Treat any failed check as an evidence-integrity incident. Do not modify
+records to make them pass. Preserve the project and inspect the failing
+node and its predecessor.