Demo readiness: honest results, working backends, classical baselines

CHANGELOG.md

@@ -7,11 +7,53 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+Demo-readiness release: every result is computed, and every result is
+checked against a classical reference.
+
+### Added
+- `compare_to_classical` and `ComparisonResult`: benchmark any quantum
+  classifier against a tuned RBF SVM and logistic regression on identical
+  folds, with equal tuning budgets, per-fold preprocessing, hardware circuit
+  counts and the Nadeau-Bengio corrected t-test (protocol of arXiv:2610.42029).
+- `QAOA.solve(adjacency)` for MaxCut with brute-force optimum and
+  approximation ratio; `brute_force_maxcut` and `cut_value` helpers.
+- Built-in H2 (STO-3G, 0.735 Angstrom) Hamiltonian; VQE reports the exact
+  ground energy.
+- `QuantumPortfolioAgent` using CVaR-VQE (Barkoutsos et al. 2020), checked
+  against brute-force selection and a Markowitz reference.
+- `ZFeatureMap`.
+- `examples/showcase.py` and `docs/showcase.md` with real output.
+- `superquantx benchmark` runs `compare_to_classical`.
+- Documentation: benchmarking guide, FAQ, troubleshooting, "What works today"
+  backend table.
+
+### Changed
+- All six gate-model backends (simulator, PennyLane, Qiskit, Cirq, Braket
+  local, pytket) run real circuits; bit order is normalised to big-endian.
+- Fidelity kernels use the requested feature map on every backend and give
+  K(x, x) = 1.
+- `QuantumSVM(gamma=...)` is the kernel bandwidth.
+- `QuantumNN` trains with parameter-shift gradients and a softmax readout.
+- Agents rewritten around real computation; unsupported agent features
+  raise `NotImplementedError` instead of returning made-up numbers.
+- `superquantx list-backends` runs a Bell circuit per backend; versions are
+  read with `importlib.metadata`.
+- Qiskit floor raised; `pytest-asyncio` added to the dev extra.
+
+### Removed
+- Random and RBF fallbacks that silently replaced quantum results.
+- Dead `src/superquantx/algorithms.py` (shadowed by the `algorithms` package).
+- Interactive `input()` prompts from examples.
+- Claims of quantum reinforcement learning, NLP and computer vision support.
+
+### Fixed
+- The library no longer configures the root logger on import.
+- CLI `version` crash, `braket.__version__` crash, literal `\n` output and
+  help examples that used a nonexistent `sqx` command.
+
 ### Planned
-- Quantum reinforcement learning algorithms
-- Quantum natural language processing
-- Fault-tolerant quantum algorithms
-- Quantum federated learning
+- Azure Quantum, Rigetti Forest (pyQuil), NVIDIA cuQuantum and TensorFlow
+  Quantum backends. These are not implemented yet.
 
 ## [0.2.0] - 2026-09-04