control-toolbox · ocots · Sep 2, 2026 · Sep 2, 2026
diff --git a/docs/src/guide/api-documentation.md b/docs/src/guide/api-documentation.md
@@ -1,9 +1,9 @@
+# [API Documentation Guide](@id guide-api-documentation)
+
 ```@meta
 CurrentModule = CTBase
 ```
 
-# API Documentation Guide
-
 This guide explains how to set up automated API reference documentation generation using the **DocumenterReference** extension of `CTBase.jl`. This is particularly useful for maintaining comprehensive and up-to-date API documentation as your codebase evolves.
 
 ## Overview
@@ -459,6 +459,6 @@ The `DocumenterReference` extension provides a powerful, flexible system for aut
 
 ## See Also
 
-- [Exception Handling](exceptions.md): Documenting exception types
-- [Test Runner Guide](test-runner.md): Testing documentation examples
-- [Coverage Guide](coverage.md): Ensuring documentation coverage
+- [Exception Handling](@ref guide-exceptions): Documenting exception types
+- [Test Runner Guide](@ref guide-test-runner): Testing documentation examples
+- [Coverage Guide](@ref guide-coverage): Ensuring documentation coverage
diff --git a/docs/src/guide/color-system.md b/docs/src/guide/color-system.md
@@ -1,4 +1,4 @@
-# Color System
+# [Color System](@id guide-color-system)
 
 ```@meta
 CurrentModule = CTBase

diff --git a/docs/src/guide/coverage.md b/docs/src/guide/coverage.md
@@ -1,9 +1,9 @@
+# [Coverage Post-processing Guide](@id guide-coverage)
+
 ```@meta
 CurrentModule = CTBase
 ```
 
-# Coverage Post-processing Guide
-
 This guide explains how to generate human-readable and machine-parseable coverage reports using the **CoveragePostprocessing** extension of `CTBase.jl`.
 
 ## ⚠️ Prerequisites
@@ -222,5 +222,5 @@ jobs:
 
 ## See Also
 
-- [Test Runner Guide](test-runner.md): Setting up modular tests
-- [Exception Handling](exceptions.md): Testing exception paths
+- [Test Runner Guide](@ref guide-test-runner): Setting up modular tests
+- [Exception Handling](@ref guide-exceptions): Testing exception paths
diff --git a/docs/src/guide/data.md b/docs/src/guide/data.md
@@ -1,11 +1,11 @@
-# Data: typed function wrappers
+# [Data: typed function wrappers](@id guide-data)
 
 ```@meta
 CurrentModule = CTBase
 ```
 
 The [`CTBase.Data`](@ref CTBase.Data) submodule provides typed wrappers that carry
-a Julia function together with its **trait metadata** (see the [Traits](traits.md)
+a Julia function together with its **trait metadata** (see the [Traits](@ref guide-traits)
 guide). Each wrapper knows, at the type level, whether it depends on time, whether
 it depends on an extra variable, and whether it is evaluated in-place.
 
@@ -48,7 +48,7 @@ In the call patterns, brackets `[…]` denote optional arguments controlled by t
 All ten share the same time-dependence and variable-dependence trait axes.
 `VectorField` and `HamiltonianVectorField` also carry a mutability trait (in-place / out-of-place);
 `ControlLaw` carries a feedback trait;
-`PathConstraint` carries a constraint-kind trait (see [Traits](traits.md)).
+`PathConstraint` carries a constraint-kind trait (see [Traits](@ref guide-traits)).
 
 ---
 
@@ -240,7 +240,7 @@ keyword path — typically those **derived from a
 [`Data.Hamiltonian`](@ref CTBase.Data.Hamiltonian)** by automatic differentiation.
 For a plain user-supplied function that does not accept `variable_costate`, passing
 `true` raises a [`CTBase.Exceptions.PreconditionError`](@ref) (see the
-[Exceptions](exceptions.md) guide).
+[Exceptions](@ref guide-exceptions) guide).
 
 ---
 
@@ -357,7 +357,7 @@ The constructor rejects non-`DynClosedLoop` laws (`OpenLoop`, `ClosedLoop`) with
 ## ControlLaw
 
 A `ControlLaw` wraps a function ``u(\cdots)`` that provides the control input for
-an optimal control problem. The **feedback** trait (see [Traits](traits.md))
+an optimal control problem. The **feedback** trait (see [Traits](@ref guide-traits))
 determines which primal variables the control law depends on, and the
 time/variable traits add `t` and `v` as for other data types.
 
@@ -429,7 +429,7 @@ while dynamic closed-loop control laws carry
 ## PathConstraint
 
 A `PathConstraint` wraps a function ``g(\cdots)`` that evaluates a path constraint
-along the trajectory. The **constraint-kind** trait (see [Traits](traits.md))
+along the trajectory. The **constraint-kind** trait (see [Traits](@ref guide-traits))
 determines which primal variables the constraint depends on, and the
 time/variable traits add `t` and `v` as for other data types.
 
@@ -630,7 +630,7 @@ Hamiltonian path (`ComposedHamiltonian`).
 ## Querying traits
 
 Because the trait metadata lives in the type, it can be recovered from any data
-object through the [Traits](traits.md) accessors — with no runtime cost:
+object through the [Traits](@ref guide-traits) accessors — with no runtime cost:
 
 ```@example data
 Traits.time_dependence(vf2)      # NonAutonomous
@@ -695,5 +695,5 @@ The same positional form exists for [`Data.Hamiltonian`](@ref CTBase.Data.Hamilt
 - [`Data.VectorField`](@ref CTBase.Data.VectorField), [`Data.Hamiltonian`](@ref CTBase.Data.Hamiltonian), [`Data.PseudoHamiltonian`](@ref CTBase.Data.PseudoHamiltonian), [`Data.ComposedHamiltonian`](@ref CTBase.Data.ComposedHamiltonian), [`Data.HamiltonianVectorField`](@ref CTBase.Data.HamiltonianVectorField), [`Data.ControlledVectorField`](@ref CTBase.Data.ControlledVectorField), [`Data.ComposedVectorField`](@ref CTBase.Data.ComposedVectorField), [`Data.ControlLaw`](@ref CTBase.Data.ControlLaw), [`Data.PathConstraint`](@ref CTBase.Data.PathConstraint), [`Data.Multiplier`](@ref CTBase.Data.Multiplier) — concrete data types.
 - [`Data.AbstractVectorField`](@ref CTBase.Data.AbstractVectorField), [`Data.AbstractHamiltonian`](@ref CTBase.Data.AbstractHamiltonian), [`Data.AbstractPseudoHamiltonian`](@ref CTBase.Data.AbstractPseudoHamiltonian), [`Data.AbstractHamiltonianVectorField`](@ref CTBase.Data.AbstractHamiltonianVectorField), [`Data.AbstractControlledVectorField`](@ref CTBase.Data.AbstractControlledVectorField), [`Data.AbstractControlLaw`](@ref CTBase.Data.AbstractControlLaw), [`Data.AbstractPathConstraint`](@ref CTBase.Data.AbstractPathConstraint), [`Data.AbstractMultiplier`](@ref CTBase.Data.AbstractMultiplier) — abstract supertypes.
 - [`Data.pseudo_hamiltonian`](@ref CTBase.Data.pseudo_hamiltonian), [`Data.control_law`](@ref CTBase.Data.control_law), [`Data.controlled_vector_field`](@ref CTBase.Data.controlled_vector_field) — getters for composed types.
-- [Traits](traits.md) — the three trait axes, the dynamics trait, and call-signature tables.
-- [Exceptions](exceptions.md) — `PreconditionError` and `IncorrectArgument`, raised by the constructors and the `variable_costate` path.
+- [Traits](@ref guide-traits) — the three trait axes, the dynamics trait, and call-signature tables.
+- [Exceptions](@ref guide-exceptions) — `PreconditionError` and `IncorrectArgument`, raised by the constructors and the `variable_costate` path.
diff --git a/docs/src/guide/descriptions.md b/docs/src/guide/descriptions.md
@@ -1,4 +1,4 @@
-# Descriptions: encoding algorithms
+# [Descriptions: encoding algorithms](@id guide-descriptions)
 
 ```@meta
 CurrentModule = CTBase
@@ -88,4 +88,4 @@ CTBase.Descriptions.remove(full, (:descent, :bfgs))
 
 ## See Also
 
-- [Exceptions guide](exceptions.md) — understanding `IncorrectArgument` and `AmbiguousDescription`.
+- [Exceptions guide](@ref guide-exceptions) — understanding `IncorrectArgument` and `AmbiguousDescription`.
diff --git a/docs/src/guide/differentiation.md b/docs/src/guide/differentiation.md
@@ -1,19 +1,19 @@
-# Differentiation: AD backend strategies
+# [Differentiation: AD backend strategies](@id guide-differentiation)
 
 ```@meta
 CurrentModule = CTBase
 ```
 
 The [`CTBase.Differentiation`](@ref CTBase.Differentiation) submodule provides an
 **automatic differentiation (AD) backend** abstraction built on the
-[Strategies](implementing-a-strategy.md) contract. It exposes a small set of
+[Strategies](@ref guide-implementing-a-strategy) contract. It exposes a small set of
 differentiation primitives — gradients, derivatives, partial derivatives and
 Jacobian–vector products — behind a single strategy type, so that consumers
 (Hamiltonian systems, flows, differential geometry) never depend on a concrete
 AD package directly.
 
 !!! tip "Prerequisites"
-    Read the [Implementing a Strategy](@ref) and [Options System](@ref) guides
+    Read the [Implementing a Strategy](@ref guide-implementing-a-strategy) and [Options System](@ref guide-options-system) guides
     first: an AD backend is a strategy with a single `:ad_backend` option.
 
 ```@setup diff
@@ -89,7 +89,7 @@ Strategies.metadata(Differentiation.DifferentiationInterface)
 ## Device parameterization
 
 `DifferentiationInterface` is parameterized on the execution device `P` via the
-[Strategy Parameters](@ref) system. Two built-in parameters are available:
+[Strategy Parameters](@ref guide-strategy-parameters) system. Two built-in parameters are available:
 `Strategies.CPU` and `Strategies.GPU`.
 
 The `:ad_backend` default is **computed from the parameter** — each device gets a
@@ -210,7 +210,7 @@ Differentiation.pushforward(backend, X, Val(1), [1.0, 2.0], [5.0, 6.0])
 ## Hamiltonian gradients
 
 The two domain-specific methods operate directly on a
-[`Data.Hamiltonian`](@ref CTBase.Data.Hamiltonian) (see the [Data](data.md) guide).
+[`Data.Hamiltonian`](@ref CTBase.Data.Hamiltonian) (see the [Data](@ref guide-data) guide).
 [`Differentiation.hamiltonian_gradient`](@ref CTBase.Differentiation.hamiltonian_gradient)
 returns `(∂H/∂x, ∂H/∂p)`, **non-negated** — the caller applies the signs of
 Hamilton's equations (`ẋ = ∂H/∂p`, `ṗ = -∂H/∂x`):
@@ -242,7 +242,7 @@ Differentiation.variable_gradient(
 ## Pseudo-Hamiltonian gradients
 
 The two pseudo-Hamiltonian methods operate directly on a
-[`Data.PseudoHamiltonian`](@ref CTBase.Data.PseudoHamiltonian) (see the [Data](data.md)
+[`Data.PseudoHamiltonian`](@ref CTBase.Data.PseudoHamiltonian) (see the [Data](@ref guide-data)
 guide).
 [`Differentiation.pseudo_hamiltonian_gradient`](@ref CTBase.Differentiation.pseudo_hamiltonian_gradient)
 returns `(∂H̃/∂x, ∂H̃/∂p)`, **non-negated** — the caller applies the signs of
@@ -307,7 +307,7 @@ would also account for `∂H̃/∂u · ∂u/∂v`.
 ## The contract without the extension
 
 Every contract method has a fallback on `AbstractADBackend` that throws
-[`CTBase.Exceptions.NotImplemented`](@ref) (see the [Exceptions](exceptions.md)
+[`CTBase.Exceptions.NotImplemented`](@ref) (see the [Exceptions](@ref guide-exceptions)
 guide). This is what users hit when the AD package is not loaded, and what custom
 backends must override:
 
@@ -324,6 +324,6 @@ Differentiation.gradient(
 ## See also
 
 - [`Differentiation.AbstractADBackend`](@ref CTBase.Differentiation.AbstractADBackend), [`Differentiation.DifferentiationInterface`](@ref CTBase.Differentiation.DifferentiationInterface) — the strategy types.
-- [Implementing a Strategy](@ref), [Options System](@ref) — the contract these build on.
-- [Data](data.md) — `Hamiltonian` and `PseudoHamiltonian` wrappers consumed by the gradient methods.
-- [Exceptions](exceptions.md) — `NotImplemented`, raised by the contract fallbacks.
+- [Implementing a Strategy](@ref guide-implementing-a-strategy), [Options System](@ref guide-options-system) — the contract these build on.
+- [Data](@ref guide-data) — `Hamiltonian` and `PseudoHamiltonian` wrappers consumed by the gradient methods.
+- [Exceptions](@ref guide-exceptions) — `NotImplemented`, raised by the contract fallbacks.
diff --git a/docs/src/guide/exceptions.md b/docs/src/guide/exceptions.md
@@ -1,9 +1,9 @@
+# [Error Handling and CTBase Exceptions](@id guide-exceptions)
+
 ```@meta
 CurrentModule = CTBase
 ```
 
-# Error Handling and CTBase Exceptions
-
 CTBase defines a small hierarchy of domain-specific exceptions to make error
 handling explicit and consistent across the control-toolbox ecosystem.
 
@@ -415,5 +415,5 @@ This makes debugging faster by providing all the information needed to understan
 
 ## See Also
 
-- [Descriptions Tutorial](descriptions.md): Understanding the description system
-- [Test Runner Guide](test-runner.md): Testing exception handling
+- [Descriptions Tutorial](@ref guide-descriptions): Understanding the description system
+- [Test Runner Guide](@ref guide-test-runner): Testing exception handling
diff --git a/docs/src/guide/implementing-a-strategy.md b/docs/src/guide/implementing-a-strategy.md
@@ -1,4 +1,4 @@
-# Implementing a Strategy
+# [Implementing a Strategy](@id guide-implementing-a-strategy)
 
 ```@meta
 CurrentModule = CTBase
@@ -7,7 +7,7 @@ CurrentModule = CTBase
 This guide walks you through implementing a complete strategy family using the `AbstractStrategy` contract. We use **Collocation** and **DirectShooting** discretizers as concrete examples.
 
 !!! tip "Prerequisites"
-    Read the [Options System](@ref) guide first to understand `OptionDefinition`, `StrategyMetadata`, and `StrategyOptions`.
+    Read the [Options System](@ref guide-options-system) guide first to understand `OptionDefinition`, `StrategyMetadata`, and `StrategyOptions`.
 
 ```@setup strategy
 using CTBase: Strategies, Options
@@ -313,7 +313,7 @@ Strategies.build_strategy(
 )
 ```
 
-See [Orchestration & Routing](@ref) for the full multi-strategy routing system.
+See [Orchestration & Routing](@ref guide-orchestration-and-routing) for the full multi-strategy routing system.
 
 ## Introspection
 

diff --git a/docs/src/guide/interpolation.md b/docs/src/guide/interpolation.md
@@ -1,4 +1,4 @@
-# Interpolation
+# [Interpolation](@id guide-interpolation)
 
 ```@meta
 CurrentModule = CTBase
@@ -82,4 +82,4 @@ const_interp
 
 ## See Also
 
-- [Traits guide](traits.md) — the trait-parameter pattern used by `Interpolant`.
+- [Traits guide](@ref guide-traits) — the trait-parameter pattern used by `Interpolant`.
diff --git a/docs/src/guide/options-system.md b/docs/src/guide/options-system.md
@@ -1,9 +1,9 @@
+# [Options System](@id guide-options-system)
+
 ```@meta
 CurrentModule = CTBase
 ```
 
-# Options System
-
 This guide explains the Options module — the foundational layer for defining, validating, extracting, and tracking configuration values throughout CTBase. The Options module is generic and has no dependencies on other CTBase modules.
 
 ```@example options
@@ -331,7 +331,7 @@ Options.is_default(opts, :verbose)
 !!! tip "Direct access shortcut on strategy instances"
     When working with a concrete strategy, `strategy[:key]` is syntactic sugar for
     `Strategies.options(strategy)[:key]` — both return the raw value. See
-    [Implementing a Strategy](@ref) for a complete example.
+    [Implementing a Strategy](@ref guide-implementing-a-strategy) for a complete example.
 
 ## Validation Modes
 

diff --git a/docs/src/guide/orchestration-and-routing.md b/docs/src/guide/orchestration-and-routing.md
@@ -1,4 +1,4 @@
-# Orchestration and Routing
+# [Orchestration and Routing](@id guide-orchestration-and-routing)
 
 ```@meta
 CurrentModule = CTBase
@@ -7,7 +7,7 @@ CurrentModule = CTBase
 This guide explains how the Orchestration module routes user-provided keyword arguments to the correct strategy in a multi-strategy pipeline. It covers the method tuple concept, automatic routing, disambiguation syntax, and the helper functions that power the system.
 
 !!! tip "Prerequisites"
-    Read [Implementing a Strategy](@ref) first. Orchestration builds on top of the strategy metadata system.
+    Read [Implementing a Strategy](@ref guide-implementing-a-strategy) first. Orchestration builds on top of the strategy metadata system.
 
 ```@setup routing
 using CTBase

diff --git a/docs/src/guide/performance.md b/docs/src/guide/performance.md
@@ -1,10 +1,10 @@
+# [Performance & Type Stability](@id guide-performance)
+
 ```@meta
 CurrentModule = CTBase
 Draft = false
 ```
 
-# Performance & Type Stability
-
 This guide explains **how CTBase keeps its runtime-critical code fast**, and how a
 contributor can check that a change has not introduced a regression.
 
@@ -167,7 +167,7 @@ using Test
 
 ## See Also
 
-- [Test Runner Guide](test-runner.md): running the test suite, including the
+- [Test Runner Guide](@ref guide-test-runner): running the test suite, including the
   automatic `JET.test_package` check.
-- [Coverage Post-processing Guide](coverage.md): the complementary "is this code
+- [Coverage Post-processing Guide](@ref guide-coverage): the complementary "is this code
   exercised at all?" question.
diff --git a/docs/src/guide/plotting.md b/docs/src/guide/plotting.md
@@ -1,4 +1,4 @@
-# Plotting Engine
+# [Plotting Engine](@id guide-plotting)
 
 ```@meta
 CurrentModule = CTBase
@@ -258,5 +258,5 @@ index when overlaying with `render!`.
 
 ## See Also
 
-- [Exceptions guide](exceptions.md) — `ExtensionError` when no backend is loaded.
-- [Traits guide](traits.md) — the trait-parameter pattern used by `Interpolant`.
+- [Exceptions guide](@ref guide-exceptions) — `ExtensionError` when no backend is loaded.
+- [Traits guide](@ref guide-traits) — the trait-parameter pattern used by `Interpolant`.
diff --git a/docs/src/guide/strategy-parameters.md b/docs/src/guide/strategy-parameters.md
@@ -1,13 +1,13 @@
+# [Strategy Parameters](@id guide-strategy-parameters)
+
 ```@meta
 CurrentModule = CTBase
 ```
 
-# Strategy Parameters
-
 This guide explains the **Strategy Parameters** system in CTBase. Parameters are singleton types that allow a strategy to specialize its metadata and default options depending on the execution context (e.g., CPU vs GPU).
 
 !!! tip "Prerequisites"
-    Read the [Implementing a Strategy](@ref) guide first. Parameters extend the strategy system with type-based specialization.
+    Read the [Implementing a Strategy](@ref guide-implementing-a-strategy) guide first. Parameters extend the strategy system with type-based specialization.
 
 ```@setup params
 using CTBase: Strategies, Options
@@ -338,10 +338,10 @@ The [`Differentiation.DifferentiationInterface`](@ref CTBase.Differentiation.Dif
 strategy is a real parameterized strategy in CTBase. It is parameterized on
 `{CPU, GPU}` with a computed `:ad_backend` option whose default differs by device
 (`AutoForwardDiff()` on CPU, `AutoMooncake()` on GPU). See the
-[Differentiation](@ref) guide for a full walkthrough.
+[Differentiation](@ref guide-differentiation) guide for a full walkthrough.
 
 ## See Also
 
-- [Implementing a Strategy](@ref) — Strategy contract and metadata
-- [Options System](@ref) — `OptionDefinition`, `StrategyOptions`
+- [Implementing a Strategy](@ref guide-implementing-a-strategy) — Strategy contract and metadata
+- [Options System](@ref guide-options-system) — `OptionDefinition`, `StrategyOptions`
 - `Strategies.AbstractStrategyParameter` — API reference
diff --git a/docs/src/guide/test-runner.md b/docs/src/guide/test-runner.md
@@ -1,9 +1,9 @@
+# [Test Runner Guide](@id guide-test-runner)
+
 ```@meta
 CurrentModule = CTBase
 ```
 
-# Test Runner Guide
-
 This guide explains how to set up a modular testing infrastructure for Julia packages using the **TestRunner** extension of `CTBase.jl`.
 The entry point is [`CTBase.DevTools.run_tests`](@ref), activated by loading the `Test` weak dependency. This setup enables granular test execution and is friendly both for human developers and AI agents.
 
@@ -462,5 +462,5 @@ jobs:
 
 ## See Also
 
-- [Exceptions guide](exceptions.md) — understanding test failures and exceptions.
-- [Coverage guide](coverage.md) — measuring test coverage.
+- [Exceptions guide](@ref guide-exceptions) — understanding test failures and exceptions.
+- [Coverage guide](@ref guide-coverage) — measuring test coverage.
diff --git a/docs/src/guide/traits.md b/docs/src/guide/traits.md
@@ -1,4 +1,4 @@
-# Traits: compile-time properties
+# [Traits: compile-time properties](@id guide-traits)
 
 ```@meta
 CurrentModule = CTBase
@@ -279,4 +279,4 @@ Traits.is_autonomous(3.14)
 
 ## See Also
 
-- [Exceptions guide](exceptions.md) — understanding `IncorrectArgument` and `NotImplemented`.
+- [Exceptions guide](@ref guide-exceptions) — understanding `IncorrectArgument` and `NotImplemented`.
diff --git a/docs/src/guide/unicode.md b/docs/src/guide/unicode.md
@@ -1,4 +1,4 @@
-# Unicode Helpers
+# [Unicode Helpers](@id guide-unicode)
 
 ```@meta
 CurrentModule = CTBase
@@ -60,4 +60,4 @@ CTBase.Unicode.ctindice(12)
 
 ## See Also
 
-- [Exceptions guide](exceptions.md) — understanding `IncorrectArgument`.
+- [Exceptions guide](@ref guide-exceptions) — understanding `IncorrectArgument`.