YannBerthelot · YannBerthelot · Sep 11, 2026 · Sep 11, 2026 · Sep 11, 2026 · Sep 11, 2026
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -23,7 +23,7 @@ than by commit.
   and phase lag are the closed loop's frequency response), `plane_energy`
   (altitude and airspeed together, which removes the spare actuator), and
   `plane3d_racetrack` (a holding pattern, which is heading hold and a sustained
-  coordinated turn in one task). Twenty-two in total.
+  coordinated turn in one task). Twenty-one in total.
 - **Environment versioning.** `EnvSpec.version` and `spec.versioned_name` give
   every environment a public identity such as `plane-v1`, stamped in
   `data/env_versions.json` by `scripts/stamp_env_versions.py`.
@@ -68,7 +68,7 @@ than by commit.
   (`target_gym.render_kit`), and the README gallery regenerated and extended to
   every environment.
 - **Seven per-environment figure/video runners consolidated** into one
-  registry-driven module, which covers all twenty-two environments rather than
+  registry-driven module, which covers all twenty-one environments rather than
   eight.
 - The PyPI development status classifier moves from `3 - Alpha` to
   `4 - Beta`. Not a promise of an API freeze, which stays deferred; a statement

diff --git a/README.md b/README.md
@@ -8,6 +8,7 @@
 <p align="center"><i>Reach the target. Then hold it.</i></p>
 
 <p align="center">
+  <a href="https://yannberthelot.github.io/TargetGym/"><img alt="Documentation" src="https://img.shields.io/badge/docs-yannberthelot.github.io%2FTargetGym-blue"></a>
   <a href="https://pypi.org/project/target-gym/"><img alt="PyPI" src="https://img.shields.io/pypi/v/target-gym?color=blue"></a>
   <a href="https://pypi.org/project/target-gym/"><img alt="Python" src="https://img.shields.io/pypi/pyversions/target-gym"></a>
   <a href="https://github.com/YannBerthelot/TargetGym/actions"><img alt="CI" src="https://img.shields.io/github/actions/workflow/status/YannBerthelot/TargetGym/python-app.yml?branch=main&label=tests"></a>
@@ -268,7 +269,10 @@ method and lists what each model is validated against.
 | **[Model review checklist](docs/model-review-checklist.md)** | Thirteen checks for any plant model |
 | **[Testing](docs/testing.md)** | Suite organisation |
 
-Full index: **[docs/](docs/index.md)**.
+Rendered with search and navigation at
+**[yannberthelot.github.io/TargetGym](https://yannberthelot.github.io/TargetGym/)**.
+The links above point at the Markdown in this repository, which reads on
+GitHub and is rewritten for the site at build time.
 
 ---
 

diff --git a/docs/environments/battery.md b/docs/environments/battery.md
@@ -1,6 +1,6 @@
 # Battery
 
-<p align="center"><img src="../videos/battery/pid_output.gif" width="480px"/></p>
+<p align="center"><img src="../../videos/battery/pid_output.gif" width="480px"/></p>
 
 Grid battery storage — equivalent-circuit Li-ion pack tracking a dispatch signal.
 

diff --git a/docs/environments/boiler_drum.md b/docs/environments/boiler_drum.md
@@ -1,6 +1,6 @@
 # Boiler Drum
 
-<p align="center"><img src="../videos/boiler_drum/pid_output.gif" width="480px"/></p>
+<p align="center"><img src="../../videos/boiler_drum/pid_output.gif" width="480px"/></p>
 
 Boiler drum — natural-circulation drum boiler with shrink-and-swell.
 

diff --git a/docs/environments/cement_kiln.md b/docs/environments/cement_kiln.md
@@ -1,6 +1,6 @@
 # Cement Kiln
 
-<p align="center"><img src="../videos/cement_kiln/pid_output.gif" width="480px"/></p>
+<p align="center"><img src="../../videos/cement_kiln/pid_output.gif" width="480px"/></p>
 
 Cement rotary kiln — 1-D axial model with counter-current gas.
 

diff --git a/docs/environments/cstr.md b/docs/environments/cstr.md
@@ -1,6 +1,6 @@
 # CSTR
 
-<p align="center"><img src="../videos/cstr/pid_output.gif" width="480px"/></p>
+<p align="center"><img src="../../videos/cstr/pid_output.gif" width="480px"/></p>
 
 | | |
 |---|---|

diff --git a/docs/environments/distillation.md b/docs/environments/distillation.md
@@ -1,6 +1,6 @@
 # Distillation
 
-<p align="center"><img src="../videos/distillation/pid_output.gif" width="480px"/></p>
+<p align="center"><img src="../../videos/distillation/pid_output.gif" width="480px"/></p>
 
 Binary distillation — Skogestad's "Column A".
 

diff --git a/docs/environments/first_order.md b/docs/environments/first_order.md
@@ -1,6 +1,6 @@
 # First order
 
-<p align="center"><img src="../videos/first_order/pid_output.gif" width="480px"/></p>
+<p align="center"><img src="../../videos/first_order/pid_output.gif" width="480px"/></p>
 
 | | |
 |---|---|

diff --git a/docs/environments/four_tank.md b/docs/environments/four_tank.md
@@ -1,6 +1,6 @@
 # Four-tank
 
-<p align="center"><img src="../videos/four_tank/pid_output.gif" width="480px"/></p>
+<p align="center"><img src="../../videos/four_tank/pid_output.gif" width="480px"/></p>
 
 | | |
 |---|---|

diff --git a/docs/environments/glass_furnace.md b/docs/environments/glass_furnace.md
@@ -1,6 +1,6 @@
 # Glass Furnace
 
-<p align="center"><img src="../videos/glass_furnace/pid_output.gif" width="480px"/></p>
+<p align="center"><img src="../../videos/glass_furnace/pid_output.gif" width="480px"/></p>
 
 Glass furnace (float-glass process) — regenerative end-port fired furnace.
 

diff --git a/docs/environments/hvac.md b/docs/environments/hvac.md
@@ -1,6 +1,6 @@
 # Building HVAC
 
-<p align="center"><img src="../videos/hvac/pid_output.gif" width="480px"/></p>
+<p align="center"><img src="../../videos/hvac/pid_output.gif" width="480px"/></p>
 
 Building HVAC — single thermal zone, ISO 13790 5R1C reduced-order model.
 

diff --git a/docs/environments/patrol.md b/docs/environments/patrol.md
@@ -1,6 +1,6 @@
 # Patrol - MARL formation
 
-<p align="center"><img src="../videos/patrol/pid_output.gif" width="480px"/></p>
+<p align="center"><img src="../../videos/patrol/pid_output.gif" width="480px"/></p>
 
 Close-patrol (formation-keeping) environment: state, parameters and transition.
 

diff --git a/docs/environments/patrol_bearing_only.md b/docs/environments/patrol_bearing_only.md
@@ -1,6 +1,6 @@
 # Patrol - MARL, bearing-only
 
-<p align="center"><img src="../videos/patrol_bearing_only/pid_output.gif" width="480px"/></p>
+<p align="center"><img src="../../videos/patrol_bearing_only/pid_output.gif" width="480px"/></p>
 
 Close-patrol (formation-keeping) environment: state, parameters and transition.
 

diff --git a/docs/environments/ph_neutralization.md b/docs/environments/ph_neutralization.md
@@ -1,6 +1,6 @@
 # pH neutralisation
 
-<p align="center"><img src="../videos/ph_neutralization/pid_output.gif" width="480px"/></p>
+<p align="center"><img src="../../videos/ph_neutralization/pid_output.gif" width="480px"/></p>
 
 pH neutralisation — CSTR with acid, buffer and base streams.
 

diff --git a/docs/environments/plane.md b/docs/environments/plane.md
@@ -1,6 +1,6 @@
 # Altitude hold
 
-<p align="center"><img src="../videos/plane/pid_output.gif" width="480px"/></p>
+<p align="center"><img src="../../videos/plane/pid_output.gif" width="480px"/></p>
 
 | | |
 |---|---|

diff --git a/docs/environments/plane3d_circle.md b/docs/environments/plane3d_circle.md
@@ -1,6 +1,6 @@
 # 3D circle
 
-<p align="center"><img src="../videos/plane3d_circle/pid_output.gif" width="480px"/></p>
+<p align="center"><img src="../../videos/plane3d_circle/pid_output.gif" width="480px"/></p>
 
 3D airplane environment state, parameters, and transition logic.
 

diff --git a/docs/environments/plane3d_figure8.md b/docs/environments/plane3d_figure8.md
@@ -1,6 +1,6 @@
 # 3D figure-8
 
-<p align="center"><img src="../videos/plane3d_figure8/pid_output.gif" width="480px"/></p>
+<p align="center"><img src="../../videos/plane3d_figure8/pid_output.gif" width="480px"/></p>
 
 3D airplane environment state, parameters, and transition logic.
 

diff --git a/docs/environments/plane3d_heading.md b/docs/environments/plane3d_heading.md
@@ -1,6 +1,6 @@
 # 3D heading
 
-<p align="center"><img src="../videos/plane3d_heading/pid_output.gif" width="480px"/></p>
+<p align="center"><img src="../../videos/plane3d_heading/pid_output.gif" width="480px"/></p>
 
 3D airplane environment state, parameters, and transition logic.
 

diff --git a/docs/environments/plane3d_racetrack.md b/docs/environments/plane3d_racetrack.md
@@ -1,6 +1,6 @@
 # 3D holding pattern
 
-<p align="center"><img src="../videos/plane3d_racetrack/pid_output.gif" width="480px"/></p>
+<p align="center"><img src="../../videos/plane3d_racetrack/pid_output.gif" width="480px"/></p>
 
 3D airplane environment state, parameters, and transition logic.
 

diff --git a/docs/environments/plane_energy.md b/docs/environments/plane_energy.md
@@ -1,6 +1,6 @@
 # Altitude and airspeed
 
-<p align="center"><img src="../videos/plane_energy/pid_output.gif" width="480px"/></p>
+<p align="center"><img src="../../videos/plane_energy/pid_output.gif" width="480px"/></p>
 
 | | |
 |---|---|

diff --git a/docs/environments/plane_sine.md b/docs/environments/plane_sine.md
@@ -1,6 +1,6 @@
 # Altitude - sinusoid
 
-<p align="center"><img src="../videos/plane_sine/pid_output.gif" width="480px"/></p>
+<p align="center"><img src="../../videos/plane_sine/pid_output.gif" width="480px"/></p>
 
 | | |
 |---|---|

diff --git a/docs/environments/reactor.md b/docs/environments/reactor.md
@@ -1,6 +1,6 @@
 # Reactor
 
-<p align="center"><img src="../videos/reactor/pid_output.gif" width="480px"/></p>
+<p align="center"><img src="../../videos/reactor/pid_output.gif" width="480px"/></p>
 
 Nuclear reactor — point-kinetics with delayed neutrons, xenon poisoning, thermal feedback, and rate-limited control rods.
 

diff --git a/docs/environments/wind_turbine.md b/docs/environments/wind_turbine.md
@@ -1,6 +1,6 @@
 # Wind Turbine
 
-<p align="center"><img src="../videos/wind_turbine/pid_output.gif" width="480px"/></p>
+<p align="center"><img src="../../videos/wind_turbine/pid_output.gif" width="480px"/></p>
 
 Wind turbine — NREL 5 MW reference turbine, collective-pitch power regulation.
 

diff --git a/docs/index.md b/docs/index.md
@@ -7,12 +7,12 @@ hide:
 
 <p align="center">
   <b>Reach a setpoint. Hold it forever. Against disturbances.</b><br/>
-  Twenty-two JAX environments for <i>target MDPs</i>, the control problems industry actually has.
+  21 JAX environments for <i>target MDPs</i>, the control problems industry actually has.
 </p>
 
 <p align="center">
   <img src="videos/mosaic_flagship.webp" width="100%"/><br/>
-  <sub>One from each family, held on setpoint by its shipped PID baseline.</sub>
+  <sub>One example task from each family, under PID control.</sub>
 </p>
 
 **21 environments**: 9 aircraft, 5 process control, 5 industrial / energy, 2 renewable energy. Every one of them is in the
@@ -29,21 +29,16 @@ Or try it in the browser: [Colab quickstart](https://colab.research.google.com/g
 ```python
 import jax
 import numpy as np
-from target_gym import Plane, PlaneParams
-from target_gym.registry import REGISTRY
+from target_gym import Plane
 
-env, params = Plane(), PlaneParams()
-obs, state = env.reset(jax.random.PRNGKey(0), params)
-
-# Every environment ships a tuned expert, so a learned policy
-# has something real to beat.
-pid = REGISTRY["plane"].make_pid()
-pid.reset()
+env = Plane()
+pid = env.make_pid()          # the shipped baseline, tuned
+obs, state = env.reset(jax.random.PRNGKey(0))
 
 for t in range(200):
-    action = np.atleast_1d(pid(obs))
+    action = np.atleast_1d(pid(np.asarray(obs)))
     obs, state, reward, terminated, truncated, info = env.step(
-        jax.random.PRNGKey(t), state, action, params
+        jax.random.PRNGKey(t), state, action
     )
     if terminated or truncated:
         break

diff --git a/pyproject.toml b/pyproject.toml
@@ -88,8 +88,15 @@ dependencies = [
 ]
 
 [project.urls]
+# PyPI renders these as a labelled sidebar and recognises these key names, so
+# "Documentation", "Issues" and "Changelog" get their own icons. Only Homepage
+# and Repository were declared, which sent everyone arriving from
+# ``pip install`` to the repository root to find the docs themselves.
 Homepage = "https://github.com/YannBerthelot/TargetGym"
+Documentation = "https://yannberthelot.github.io/TargetGym/"
 Repository = "https://github.com/YannBerthelot/TargetGym"
+Issues = "https://github.com/YannBerthelot/TargetGym/issues"
+Changelog = "https://github.com/YannBerthelot/TargetGym/blob/main/CHANGELOG.md"
 
 [dependency-groups]
 test = [

diff --git a/scripts/generate_env_pages.py b/scripts/generate_env_pages.py
@@ -233,7 +233,17 @@ def page(name: str, spec) -> str:
     out = [f"# {title}", ""]
     if video:
         out += [
-            f'<p align="center"><img src="../{video}" width="480px"/></p>',
+            # ``../../``, not ``../``.
+            #
+            # mkdocs serves these with directory URLs, so this page is
+            # ``/environments/<name>/`` and a relative source resolves against
+            # that directory, not against ``/environments/``. With one level the
+            # browser asked for ``/environments/videos/<name>/pid_output.gif``
+            # and got a 404 on every environment page, while the homepage
+            # worked because it sits at the site root. mkdocs rewrites relative
+            # links in Markdown but not inside raw HTML, which is why this has
+            # to be right here.
+            f'<p align="center"><img src="../../{video}" width="480px"/></p>',
             "",
         ]
     if module and module.__doc__: