[ocots]

Page-by-page documentation review

A critical re-reading of every hand-written docs page, one at a time: correctness of every claim, prose and progression, links, and executed code. v2.0.4 is the reference: what it explained (derivations, analytic values, figures, summary tables) is kept, and the presentation is improved.

Draft until every page has been through. One commit per page.

Principles

• Execute as much as possible. Every claim that can run in the build runs, visible or hidden. Analytic values are checked with hidden @asserts, so a wrong value fails the build.
• Probes for the rest. Claims the build cannot execute (errors when a package is not loaded, other environments, session rules, silent output, external URLs) are checked by the scripts in docs/probes/ (julia --project=docs docs/probes/run.jl). A probe for a known upstream bug checks the current behaviour, so it fails when the fix is released, as a reminder to update the page.
• Bugs go upstream. Each bug found gets an issue in the package concerned, and a one-line note with the link in the page. No history or maintainer notes in the pages.

Progress (45 / 45)

Section	Pages	Status
Home, Getting started	index, installation, first problem, guided tour	✅
Modelling	formulation, abstract syntax, functional API, control-free problems, inspect, with AI	✅
Solve	overview, initial guess, choosing a method, options, explicit mode, GPU	✅
Results	solution, plot, plot with Makie, save & load	✅
Flows	overview, from an OCP, from Hamiltonians, simulation, accessors, multi-phase, constrained arcs, shooting	✅
Geometry	overview, lift, Lie derivative and bracket, Poisson bracket, @Lie, AD backend	✅
Examples	gallery, energy, time, control-free, control and variable, turnpike, singular control, state constraint, logo	✅
Reference	ecosystem, migration	✅

Mechanics

• During the review, a local draft = true and a @meta Draft = false marker on the page under review made only that page execute. Neither is committed: docs/make.jl has draft = false, as on main.
• Plan, decisions and per-page log: .reports/ (git-ignored).

Before merging

• draft = false in docs/make.jl, full build green (every page executes).
• No @meta Draft marker left.
• julia --project=docs docs/probes/run.jl passes (11 / 11), after updating the probes and notes of the upstream fixes released in the meantime.
• Link texts and titles swept (Flows overview, Geometry overview, control-free problems).

🤖 Generated with Claude Code

[ocots]

Status: page 1/45 (index.md) validated and committed.

This first commit is larger than the following ones will be — besides the index.md review it also carries three infra fixes found along the way (environment download 404 on dev, logo .png→.svg + dark mode, dark-mode figure filter).

Next: getting-started/installation.md, then the rest of the sidebar in order. One commit per page. The PR stays in draft until the end.

[ocots]

Status: pages 1–16 of 45 pushed

Getting started, Modelling and Solve are done (22 commits). Results has started: the Solution object page is committed locally, and will be pushed with the rest of the section.

What changed, across the pages

• Executed rather than written. Many julia blocks became @example blocks, and analytic values are checked by hidden @asserts: the energy double integrator (u = 6 − 12t, J = 6, p₀ = (12, 6)), the minimum-time problem with a speed limit (t_f = 25/12), the harmonic oscillator, the guided tour, and the 7 macro/functional pairs (identical solutions).
• Restored from v2.0.4: the wagon figures, the "Understanding default values" note, the describe of every strategy, the scheme table, the official-documentation links, the summary tables of the Solution page, the cross-spec initial-guess cases.
• Corrected: integrator advice on the installation page, :exa and vector-form dynamics/constraints (they work), the sign and scale of the multipliers, the "Reading the display" section, variable(sol) (a number for a 1-D variable), the state-constraint notation (c(x) ≥ 0 with + μc).
• New: "Notation and conventions" (Formulation), "Structure" and "Labels" (abstract syntax), a real failing solve, the keyword form of route_to, CPU vs GPU defaults, the half-step shift of the direct costate, dual(sol, ocp, :start) = p(t₀), and the fact that a flow returns a Solution.
• Infrastructure: binder/ removed (notebook and script downloads instead), ExaModels/MadNLP InterLinks moved to madsuite-org with real inventories, the 40/60 columns CSS restored, docs/probes/ (10 probes, all passing).

Upstream issues filed

Issue	What	Status
CTBase.jl#565	solve(ocp, :gpu) routing ignored the parameter (MadNLP{CPU})	✅ fixed (#566), released in v0.30.6
CTSolvers.jl#230	Flow(…; alg=Vern9()) failed without OrdinaryDiffEqTsit5	✅ fixed (#231), release pending
CTModels.jl#431	accessor hints (final_time, initial_time, mayer, lagrange)	✅ fixed (#432), release pending
CTDirect.jl#638	:exa with an explicit time_grid: crash, or silently uniform	open
CTDirect.jl#639	constraint multipliers: scale (quadrature weights) and sign differ between boxes, path and boundary constraints; derivation in the comments	open, maths to check first
CTDirect.jl#640	costate time stamps: p(t_i + h/2), or p(t_{i+1}) with Gauss–Legendre	open, maths to check first
CTDirect.jl#405 (comment)	under :exa, path and boundary duals are zeros, without a warning	open
CTParser.jl#352	the "move the term" hint always quotes the same constraint	open
CTParser.jl#353	ẋ(t) = … (single =): misleading error	open
CTParser.jl#354	trace mode prints internal gensyms	open
CTParser.jl#355	:exa rejects the scheme aliases	open
OptimalControl.jl#964	init + initial_guess: misleading error in descriptive mode	open
OptimalControl.jl#965	which initial-guess helpers to re-export	open, to decide

Once the CTSolvers and CTModels releases are out

• Bump the docs environment.
• Drop the "keep OrdinaryDiffEqTsit5 loaded" advice and the CTModels#431 notes.
• Add OrdinaryDiffEqVerner and execute a Flow(…; alg=Vern9()) example.
• Flip the two probes that check the old behaviour.

Next

Results (Plot, Plot with Makie, Save & load), then Flows, Geometry and the examples, where the remaining correctness items are (state-constraint example, shooting, multi-phase flows).

[ocots]

Status: Flows section done (28 / 45)

Pages 23–28 are pushed (1df71d69 … 67d581e9). Every page executes, and the analytic values are checked by hidden @asserts.

Page	What changed
From Hamiltonians	v2.0.4 introduction restored (extremals). One extremal of the double integrator is computed with each of the six constructors, and the results are asserted equal. The claimed "silent mis-dispatch" was wrong: the actual behaviour is a MethodError. For SciML flows, the parameter p is the flow's variable.
Simulation	Open and closed loop are checked against the exact solutions. Controls are evaluated on the energy problem: u = 6 − 12t costs 6 and reaches the target; u = 1 costs 1/2 and ends at (−1/2, 1). A table says what each kind of flow returns (Solution, state trajectory, costate, objective); every row is checked.
Accessors	Every accessor is evaluated on the extremal at x = (−1, 0), p = (12, 6), e.g. 𝐇 = 18. The availability table was rebuilt from measurements.
Multi-phase	B2: the point call of a concatenation returns [x; p], so the code reads zf[1:2]. A vector jump on a Hamiltonian flow acts on the costate, and this is checked. The v2.0.4 L¹ off–bang example is restored, with p₀ and t₁ in closed form.
Constrained arcs	Both v2.0.4 examples are restored, in function form: the order-1 constraint (Bonnard–Faubourg–Launay–Trélat; t₁ = 0.9, t₂ = 1.6) and Bryson–Denham (costate jumps of 18, J = 4). Each is compared with the direct solve. The Symbol form constraint=:label is documented with a caveat.
Shooting	B8: transversality is p·f = 1 in the Mayer form. unsafe=true is explained on a blow-up example. The guess is taken from the direct solve (dual(sol, ocp, :start), switch read off the control, t_f), and Newton converges to (1, 1, 1, 2).

New upstream issues

• With saveat, the point call returns the state at the last saved time, not at tf CTFlows.jl#441: with saveat, the point call returns the value at the last saved time, not at t_f, and raises no error. The pages that use saveat warn about it.
• Flow(ocp, law; constraint=:label, …) uses the raw constraint function, ignoring its bound and its side CTFlows.jl#440: constraint=:label uses the raw model function and ignores its bound and side. The issue includes the derivation of the wrong ṗ on the arc.
• Point call of a concatenated Hamiltonian flow: a flat vector [x; p], where a single flow returns (x, p) CTFlows.jl#439 (plus a comment): concatenated Hamiltonian flows return [x; p] instead of (x, p).
• Flow accessors: MethodError or IncorrectArgument depending on the flow, and gradients that only take (t, x, p, v) CTFlows.jl#438: accessors that do not apply raise inconsistent errors, and the gradients accept only the full form.
• variable_costate=true on a trajectory call: raw MethodError, while the old augment=true gets a clear error CTFlows.jl#437: variable_costate=true on a trajectory call raises a raw MethodError.
• OpenLoop(() -> 1.0) is accepted, then fails with a raw MethodError at the first call CTBase.jl#570: OpenLoop(() -> 1) is accepted at construction and fails at the first call.

Probes

11 / 11 pass. The new probes are plot_flow_saveat.jl (#434, #441) and solution_duals.jl (#639, #640, #405).

Next

• Geometry (29–34).
• Examples (35–43), including B1 on the state-constraint example.
• Ecosystem and Migration.
• The pre-merge checklist.

[ocots]

Status: review complete (45 / 45), ready for a final read

All 45 pages are reviewed and pushed (HEAD d3cc96dc). The pre-merge checklist in the description is ticked:

• full build with draft = false: green (15.5 min), every page executes, and the hidden @asserts check the analytic values;
• no @meta Draft marker left;
• docs/probes/run.jl: 11 / 11 pass;
• link texts are the titles of their targets (21 links fixed).

Since the last status

Section	What changed
Geometry (29–34)	v2.0.4 restored: Poisson properties, {H, G} = H⃗·G, d/dt G = ∂ₜG + {H, G}, summary table. The singular control is derived on an example where H₁₀₁ ≠ 0 (u = sin²θ).
Examples (35–43)	Wagon figures, side-by-side formulations and derivations restored; exact values asserted (energy p₀ = (12, 6); time (1, 1, 1, 2); control-free ω = π/2; turnpike J = 3/8; singular-control brackets; logo boundary values). State constraint (B1): function form, (38.4, 9.6, 0.25, 0.75), J = 7.68; Bryson–Denham touch point (J = 2.24) and boundary arc (3a, 1 − 3a, jumps 2/(9a²), J = 4/(9a)).
Reference (44–45)	Ecosystem: role of each package. Migration: titled "Migrating from v2.0", shim messages executed, augment=true and positional constraints documented as now caught.

New upstream issues

• Make the @Lie expansion hygienic: put CTLie and CTBase in the generated code, not their names CTLie.jl#40: @Lie expands to code that needs CTLie and CTBase bound in the caller's module.
• Lift on a HamiltonianVectorField: error message names ad instead of Lift CTLie.jl#41: the error of Lift on a HamiltonianVectorField names ad.

Notes for review

• Examples compute the shooting and the objectives with plain flows, and use flows with saveat only for plots. After CTFlows#442 is released, plots can use the output grid at the call, and plot_flow_saveat.jl will fail as a reminder.
• The objective of a concatenated trajectory is recomputed at the integrator tolerance (relative error about 1e-6), so those asserts use that tolerance.
• X ⋅ f with a plain function X raises a MethodError, not the replacement message; the migration page says so.
• Geometry keeps its 6 pages. The review suggested merging them into 3; I did not do it.