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/cookbook.md

@@ -0,0 +1,26 @@
+# Cookbook
+
+Short, focused recipes for the patterns that come up in practice.
+Each recipe is self-contained and small enough to copy into your own
+project.
+
+## Recipes
+
+- [Parallelize evaluation with rayon](./cookbook/parallel.md) — when
+  your `evaluate` is non-trivial, the `parallel` feature pays for
+  itself almost immediately.
+- [Tune a model with expensive evaluations](./cookbook/expensive-evaluations.md)
+  — `BayesianOpt`, `Tpe`, and `Hyperband` for the 50–500-eval
+  regime.
+- [Compare two algorithms on your problem](./cookbook/compare.md) —
+  multi-seed harness pattern straight from `examples/compare.rs`.
+- [Optimize a permutation (TSP-style)](./cookbook/permutation.md) —
+  `AntColonyTsp` with a distance matrix.
+- [Constrain your search with `Repair`](./cookbook/constraints.md) —
+  bounds, simplex projection, custom repair.
+- [Pick one answer off a Pareto front](./cookbook/pick-one.md) — the
+  a-posteriori weighted-decision pattern from the `jiggly_tuning`
+  example.
+- [Write your own algorithm](./cookbook/custom-optimizer.md) —
+  implement `Optimizer<P>` from scratch, à la the
+  `examples/custom_optimizer.rs` walkthrough.