control-toolbox · ocots · Sep 2, 2026 · Sep 2, 2026
diff --git a/BREAKING.md b/BREAKING.md
@@ -4,12 +4,27 @@ Chronological, newest first. Each `CHANGELOG.md` entry links back here for the f
 record; this file never duplicates a release's own compat table, only what a caller must
 change or be aware of.
 
+- [Non-breaking notes (2.2.1-beta)](#non-breaking-notes-221-beta)
 - [Non-breaking notes (2.2.0-beta)](#non-breaking-notes-220-beta)
 - [Breaking changes: v2.0 → v2.1.0-beta](#breaking-changes-v20--v210-beta)
 - [Breaking changes: v1.x → v2.0](#breaking-changes-v1x--v20)
 
 ---
 
+## Non-breaking notes (2.2.1-beta)
+
+Documentation infrastructure only. **Nothing to migrate** — OptimalControl's API and runtime
+behaviour are unchanged, and the change is invisible to anyone who only *uses* the package.
+
+For contributors who build the documentation locally:
+
+- `docs/make.jl` now defaults to `draft = false`, so every page executes its `@example` /
+  `@repl` blocks. Set `draft = true` in `make.jl` for a fast local build that skips
+  execution; opt a single page out of execution with `Draft = true` in its `@meta` block.
+- The docs build has no `warnonly` fallback any more: an unresolved `@ref` / `@extref`, or a
+  broken `@example` / `@repl`, now fails the build rather than warning.
+- The docs environment moves to CTBase `0.30.4-beta` and CTModels `0.19.4-beta`.
+
 ## Non-breaking notes (2.2.0-beta)
 
 ### `using ExaModels` now clashes with OptimalControl

diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -8,6 +8,26 @@ Versions follow [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ---
 
+## [2.2.1-beta] — 2026-09-02
+
+Documentation-infrastructure follow-up to the 2.2.0-beta site rewrite. No change to OptimalControl's API or runtime behaviour; nothing to migrate — see [BREAKING.md](BREAKING.md).
+
+### 📚 Documentation
+
+- **The docs build resolves every `@extref` and `@ref`.** Two long-standing backlogs closed:
+  - `_strategy_parameter` cross-referenced `CTBase.Strategies.parameter` by method signature (`parameter(T, default)` / `parameter(T)`), but CTBase's auto-generated reference indexes the function under a single anchor, so neither link resolved — collapsed to the one anchor ([#944](https://github.com/control-toolbox/OptimalControl.jl/pull/944)).
+  - the four `Plots.plot(::CTModels.Solutions.Solution)` `@extref` links were CTModels' plotting-extension docstrings referencing an anchor that cannot exist (extension methods are not in any inventory); fixed upstream and shipped in [CTModels 0.19.4-beta](https://github.com/control-toolbox/CTModels.jl/pull/428).
+
+- **`makedocs` no longer sets `warnonly`** ([#952](https://github.com/control-toolbox/OptimalControl.jl/pull/952)). With both backlogs cleared — the `@ref`/`DOCPCache` pair ([CTDirect#630](https://github.com/control-toolbox/CTDirect.jl/issues/630)) and the `@extref` set above — an unresolved cross-reference now fails the build instead of warning. Verified with the sibling inventories resolved remotely, as on CI.
+
+- **`docs/make.jl` runs `draft = false` by default** ([#949](https://github.com/control-toolbox/OptimalControl.jl/pull/949)). The build used to ship `draft = true` globally with a `@meta Draft = false` block repeated in 43 pages to opt each one back into execution — a double negative that also blocked a fast `draft = true` pass for link/nav checks. Now the default executes every page; flip the one flag in `make.jl` for a fast local build, or set `Draft = true` in a single page's `@meta` to exclude it. The guided-tour `Draft = false` Literate injection is removed.
+
+- **The local sibling `objects.inv` path is only tried outside CI** ([#951](https://github.com/control-toolbox/OptimalControl.jl/pull/951)) — CI never has the sibling repos checked out, so it was logging seven `Failed to load inventory` warnings on every run before falling back to the remote inventory. Local-dev ordering (local-first) is unchanged.
+
+### 📦 Dependencies
+
+- Picks up **CTBase `0.30.4-beta`** (`Descriptions` error-message fixes, re-exported) and **CTModels `0.19.4-beta`** (the `@extref` docstring fix). `docs/src/assets/Manifest.toml` regenerated to match.
+
 ## [2.2.0-beta] — 2026-08-28
 
 Dependency realignment onto the released control-toolbox ecosystem, the v2.0 → v2.1 compatibility shims, and a full documentation-site rewrite. No breaking change to OptimalControl's own API; two near-breaking notes — see [BREAKING.md](BREAKING.md).
@@ -40,10 +60,6 @@ Dependency realignment onto the released control-toolbox ecosystem, the v2.0 →
 
 - The documentation site was rewritten onto a new sitemap (getting started, modelling, solve, results, flows, geometry, an examples gallery, and a thematic API reference) and a v2.0 → v2.1 migration page added. The retired v2.0 manuals are kept under `docs/attic/`
 
-- **`_strategy_parameter` docstring no longer emits an unresolvable `@extref`** ([#943](https://github.com/control-toolbox/OptimalControl.jl/issues/943)). It cross-referenced `CTBase.Strategies.parameter` by method signature (`parameter(T, default)` / `parameter(T)`), but CTBase's auto-generated reference indexes the function under a single anchor, so neither link resolved. Collapsed to the one anchor; `docs/make.jl`'s `warnonly` comment refreshed. The remaining `@extref` warnings (`Plots.plot(::CTModels.Solutions.Solution)`) are fixed upstream in [CTModels 0.19.4-beta](https://github.com/control-toolbox/CTModels.jl/issues/427).
-
-- **`docs/make.jl` runs `draft = false` by default** ([#948](https://github.com/control-toolbox/OptimalControl.jl/issues/948)). The build used to ship `draft = true` globally with a `@meta Draft = false` block repeated in 43 pages to opt each one back into execution — a double negative that also blocked a fast `draft = true` pass for link/nav checks. Now the default executes every page; flip the one flag in `make.jl` for a fast local build, or set `Draft = true` in a single page's `@meta` to exclude it. The guided-tour `Draft = false` Literate injection is removed.
-
 ### 📦 Dependencies
 
 - **Realigned on the released ecosystem** — every sibling resolves from the General registry with no `Pkg.develop`: CTBase `0.28`→`0.29`, CTModels `0.15`→`0.18`, CTSolvers `0.4`→`0.5`, CTFlows `0.16`→`0.17`, CTParser `0.8`→`0.9`, CTLie `0.1`→`0.2`; CTDirect stays pinned to `1` (the major alone, per the pinning-granularity rule)

diff --git a/Project.toml b/Project.toml
@@ -1,6 +1,6 @@
 name = "OptimalControl"
 uuid = "5f98b655-cc9a-415a-b60e-744165666948"
-version = "2.2.0-beta"
+version = "2.2.1-beta"
 authors = ["Olivier Cots <olivier.cots@toulouse-inp.fr>"]
 
 [deps]

diff --git a/docs/api-coverage.md b/docs/api-coverage.md
@@ -1,8 +1,8 @@
 # API coverage matrix
 
 **Status**: living cross-reference · **Measured against**: `names(OptimalControl)` on
-OptimalControl 2.2.0-beta (`[compat]` floors CTBase 0.30, CTModels 0.19, CTFlows 0.18,
-CTLie 0.2, CTSolvers 0.5, CTDirect 1, CTParser 0.9)
+OptimalControl 2.2.1-beta (`[compat]` floors CTBase 0.30, CTModels 0.19, CTFlows 0.18,
+CTLie 0.2, CTSolvers 0.5, CTDirect 1, CTParser 0.9) — unchanged from 2.2.0-beta
 
 ## What this is
 

diff --git a/docs/make.jl b/docs/make.jl
@@ -247,21 +247,13 @@ with_api_reference(src_dir, ext_dir) do api_pages
     return makedocs(;
         draft=draft,
         remotes=nothing, # Disable remote links. Needed for DocumenterReference
-        # Not fully zero: 2 unresolved @ref remain (DOCPCache, category :cross_references),
-        # tracked at control-toolbox/CTDirect.jl#630 — drop :cross_references once that lands.
-        # The @extref backlog (category :external_cross_references, registered by
-        # DocumenterInterLinks, not Documenter itself) is cleared: the CTBase.Strategies.parameter
-        # links were this repo's own signature-suffixed docstring (#943, fixed here) and the
-        # Plots.plot(::CTModels.Solutions.Solution) links were CTModels' extension docstrings
-        # (control-toolbox/CTModels.jl#427, fixed in CTModels 0.19.4-beta). Once that release is
-        # in docs/Manifest.toml, :external_cross_references can be dropped from this list so a
-        # future unresolved @extref fails the build. See .reports/campaign/D-api-reference.md.
-        #
-        # :example_block is deliberately *not* here: with `draft = false` every page
-        # executes, and a genuinely broken `@example` / `@repl` block must fail the build.
-        # Verified: an error introduced into any executing block still fails with
-        # :example_block under this exact warnonly list.
-        warnonly=[:cross_references, :external_cross_references],
+        # No `warnonly`: every unresolved cross-reference fails the build. The historical
+        # backlog is cleared — the `@ref`/`DOCPCache` pair (control-toolbox/CTDirect.jl#630,
+        # closed) and the `@extref` set (`CTBase.Strategies.parameter` #943; CTModels'
+        # extension docstrings control-toolbox/CTModels.jl#427, shipped in CTModels
+        # 0.19.4-beta). With `draft = false` a broken `@example` / `@repl` also fails
+        # (:example_block). Verified with the sibling inventories resolved remotely (as on
+        # CI). See .reports/campaign/D-api-reference.md.
         sitename="OptimalControl.jl",
         format=DocumenterVitepress.MarkdownVitepress(;
             repo=repo_url, devbranch="main", devurl="dev", sidebar_drawer=true

diff --git a/docs/src/assets/Manifest.toml b/docs/src/assets/Manifest.toml