feat: v0.5.0 — comprehensive documentation release

Theme: documentation and project polish. No public-API changes; this
is the v0.5 release that elevates heuropt's docs/onboarding/governance
to bar-setting status.

Adds:
- mdbook user guide at docs/book/ with intro, getting-started,
  defining-problems, choosing-an-algorithm, cookbook (7 recipes),
  comparison vs other libraries, stability/SemVer, migration guides.
  Deploys to https://swaits.github.io/heuropt/ via .github/workflows/
  docs.yml.
- Runnable rustdoc examples on every algorithm (35 of them), all
  exercised by cargo test --doc.
- Three real-world examples: portfolio.rs (multi-obj with budget
  constraint), hyperparam_tuning.rs (BO + TPE), scheduling.rs
  (permutation via SA + SwapMutation against Smith's-rule oracle).
- Governance: CONTRIBUTING.md, SECURITY.md, CODE_OF_CONDUCT.md
  (adopting builderscode.org's Builder's Code of Conduct), GitHub
  issue templates, PR template.

Polishes:
- README hero with badges + user-guide link.
- lib.rs crate-level docs.
- CHANGELOG entry for 0.5.0.

Bumps Cargo.toml to 0.5.0.

docs/book/src/introduction.md

@@ -0,0 +1,82 @@
+# Introduction
+
+heuropt is a practical Rust toolkit for **heuristic optimization** — the
+art of searching for good answers when the problem is too gnarly to
+solve analytically.
+
+The kinds of problems heuropt is built for:
+
+- **Single-objective:** "find the parameters that minimize the loss of
+  this model." Hyperparameter tuning. Curve fitting. Calibration.
+- **Multi-objective:** "find the trade-off curve between cost and
+  accuracy." Engineering design. Portfolio optimization. Fleet
+  scheduling.
+- **Many-objective (4+):** the same idea but with enough objectives
+  that classical Pareto methods break down. Power-grid planning.
+  Airfoil design. Multi-criteria recommendation.
+
+If your problem is differentiable and convex, you don't need this
+crate — use a gradient solver. heuropt is for the *messy* problems:
+landscapes with lots of local minima, decisions that aren't continuous
+(permutations, bit vectors), or evaluations that are noisy / expensive
+/ black-box.
+
+## Why heuropt
+
+There are other Rust optimization crates and many more in Python (pymoo,
+hyperopt, optuna, DEAP). heuropt's design priorities:
+
+1. **Approachable code.** No trait objects in the public API. No
+   GATs, HRTBs, generic-RNG plumbing. A junior Rust engineer should
+   be able to read `RandomSearch` and write a new optimizer by
+   implementing only the `Optimizer<P>` trait.
+2. **One concrete RNG type.** Seeded determinism is a property tested
+   across the crate; identical inputs always produce identical
+   outputs.
+3. **Algorithms that work.** Every algorithm is benchmarked against
+   the canonical test problems (ZDT, DTLZ, Rastrigin, Rosenbrock,
+   Ackley) and the results are checked into [examples/compare-results.md](https://github.com/swaits/heuropt/blob/main/examples/compare-results.md)
+   so you can see what each algorithm's strengths actually are.
+4. **Testing as a first-class concern.** 316+ unit / integration /
+   property tests, eight cargo-fuzz targets in CI, gungraun
+   instruction-count benchmarks. The fuzzers find real bugs and the
+   property tests check actual invariants.
+
+## What's in the box
+
+heuropt v0.5 ships **35 algorithms** spanning:
+
+- Single-objective continuous: `RandomSearch`, `HillClimber`,
+  `OnePlusOneEs`, `SimulatedAnnealing`, `GeneticAlgorithm`,
+  `ParticleSwarm`, `DifferentialEvolution`, `Tlbo`, `CmaEs`,
+  `IpopCmaEs`, `SeparableNes`, `NelderMead`.
+- Single-objective other types: `Umda` (binary), `TabuSearch`
+  (any), `AntColonyTsp` (permutation).
+- Multi-objective (2–3): `Paes`, `Nsga2`, `Spea2`, `Mopso`, `Ibea`,
+  `SmsEmoa`, `HypE`, `EpsilonMoea`, `PesaII`, `AgeMoea`, `Knea`,
+  `Moead`.
+- Many-objective (4+): `Nsga3`, `Rvea`, `Grea`.
+- Sample-efficient / multi-fidelity: `BayesianOpt`, `Tpe`,
+  `Hyperband`.
+
+Plus the operators (SBX, PolynomialMutation, BoundedGaussianMutation,
+LevyMutation, BitFlipMutation, SwapMutation, ClampToBounds,
+ProjectToSimplex), the metrics (hypervolume, spacing), and the Pareto
+utilities (dominance, fronts, crowding distance, Das–Dennis reference
+points, the `ParetoArchive`) that you'd expect.
+
+## How to use this guide
+
+If you're new to heuropt, read it linearly:
+
+1. [Five-minute walkthrough](./getting-started.md) — install, define
+   a problem, run an optimizer, look at the result.
+2. [Defining a problem](./defining-problems.md) — the `Problem`
+   trait in depth: single- vs multi-objective, constraints, custom
+   decision types.
+3. [Choosing an algorithm](./choosing-an-algorithm.md) — the
+   decision tree, expanded with the reasoning behind each branch.
+
+If you're already up and running, jump into the [cookbook](./cookbook.md)
+for recipes, or [comparison](./comparison.md) for how heuropt stacks
+up against other libraries.