docs: enhance README and add formation design documentation

Author: sakobu

README.md

@@ -1,6 +1,15 @@
 # RPO Toolkit
 
-RPO Toolkit is a Rust astrodynamics stack for spacecraft rendezvous and proximity operations that combines a browser-deployable analytical engine for real-time mission design with a nyx-space-backed numerical engine for full-physics validation and Monte Carlo analysis.
+RPO Toolkit is a paper-traceable implementation of spacecraft rendezvous and proximity-operations mission design in Rust. Every algorithm — quasi-nonsingular ROE, J2 and DMF-drag analytical STMs, e/i-separation passive safety, null-space-projected formation design, Brent-refined closest-approach — cites its source equation (Koenig 2017, D'Amico 2010, Meeus) and is validated against nyx-space full-physics propagation to the meter.
+
+The workspace is split into two engines with a compile-time license boundary: a microsecond, browser-deployable analytical core (MIT/Apache) and a full-physics numerical engine (AGPL, via nyx-space) for Lambert transfers, validation, and Monte Carlo. The same mission designer that plans a formation in a browser tab runs Monte Carlo on a server.
+
+## Who this is for
+
+- **Formation-flying and proximity-ops researchers** — paper-traceable implementations of quasi-nonsingular ROE methods (Koenig 2017, D'Amico 2010) with equation-level provenance and full-physics validation.
+- **Rust and frontend engineers building interactive mission-design tools** — microsecond analytical planning in the browser via WASM and full-physics Monte Carlo on the server, both from the same code.
+
+This is a **ground-based mission-design assistant for human analysts** — interactive, advisory, dual-plan — not an autonomous flight-software stack. See _Formation Design_ below for the distinction.
 
 ## Architecture
 
@@ -27,7 +36,7 @@ rpo-nyx (AGPL-3.0)  <--  rpo-cli (AGPL-3.0)
 
 ```bash
 cargo build                     # build workspace
-cargo test                      # 619 tests across 5 crates (587 + 32 ignored full-physics; 619 total with -- --include-ignored)
+cargo test                      # 619 tests across 5 crates (see Testing below)
 ```
 
 Run an example mission (CLI):
@@ -46,6 +55,8 @@ wasm-pack build rpo-wasm --target web
 
 See [CLI Reference](docs/CLI.md) for all commands and flags.
 
+**Full-physics prerequisites.** Running `validate`, `mc`, or any test with `--include-ignored` downloads ~50 MB of ANISE kernels (DE440s, PCK) on first use. Analytical-only operations (`mission` without `--auto-drag`, all WASM functions) have no external dependencies.
+
 ## Mission Pipeline
 
 ```mermaid
@@ -58,7 +69,7 @@ flowchart TD
     D -- "lock in" --> E1["Drag estimation\nfrom perch states\n(~3 s, async)"]
     E1 --> S["Formation safety\nrequirements\n(optional)"]
     E2 --> S
-    S --> F["Waypoint planning\nformation design . safety . POCA . COLA . free-drift . covariance . eclipse\n(microseconds)"]
+    S --> F["Waypoint planning\nformation design . safety . POCA . COLA . free-drift . covariance + mahalanobis . eclipse\n(microseconds)"]
     F -- "iterate" --> F
     F --> G["Validate\nnyx full-physics\n(seconds)"]
     G -- "adjust" --> F
@@ -80,6 +91,23 @@ flowchart TD
 | Full-physics validation      | `validate_mission_nyx()`                                                               | nyx-space  | seconds      |
 | Monte Carlo ensemble         | `run_monte_carlo()`                                                                    | nyx-space  | minutes      |
 
+## Formation Design
+
+What this tool _is_, in one contrast:
+
+```
+PRISMA FSW     : sensor → classify → compute correction → execute maneuver
+                 (autonomous, closed-loop, onboard)
+
+RPO Toolkit    : compute baseline + enriched plans → present both →
+                 analyst decides → replan
+                 (advisory, human-in-the-loop, ground)
+```
+
+The toolkit implements the quasi-nonsingular ROE formation-design vocabulary from D'Amico 2010 — e/i vector separation, null-space waypoint enrichment, perch enrichment, transit monitoring, free-drift abort — as an advisory layer with accept/dismiss affordance. Short maneuver legs naturally produce poor intermediate e/i geometry even when 3D keep-out is fully satisfied, so the tool enforces what must not be violated (keep-out distance, checked at every trajectory sample) and evaluates what requires analyst judgment (passive safety, advisory cards with explicit opt-in).
+
+See [docs/formation-design.md](docs/formation-design.md) for primitive-by-primitive detail and the D'Amico equation-to-function mapping.
+
 ## Performance
 
 Analytical engine benchmarks (Apple M-series, single core, `cargo bench -p rpo-core`):
@@ -106,20 +134,29 @@ Criterion HTML reports are generated in `target/criterion/`.
 
 ## Validated Accuracy
 
-Validated against nyx-space full-physics propagation (US Std Atm 1976, SRP with eclipses, Sun/Moon third-body) for LEO orbits (~400 km, ~52 deg inclination), ~300-400 m-scale formations.
+Validated against nyx-space full-physics propagation — J2 harmonics, US Std Atm 1976 drag, SRP with conical eclipses, Sun/Moon third-body perturbations — for LEO orbits (~400 km altitude, ~51.6° inclination, ISS-class) with ~300 m formation separations.
+
+The table below shows **actual observed errors** from running the bundled validation example — reproducible with one command:
 
-| Scenario                        | Validated Within | Notes                                  |
-| ------------------------------- | ---------------- | -------------------------------------- |
-| J2 STM, single leg (~1 orbit)   | 100 m            | Unmodeled perturbations ~60 m total    |
-| J2 STM, multi-leg (~2-3 orbits) | 200 m            | Includes cross-leg maneuver mismatch   |
-| J2+Drag STM (~1 orbit)          | 200 m            | DMF fit error + unmodeled SRP/3rd-body |
-| Eclipse: Sun direction          | 0.01 deg         | Meeus Ch. 25 vs ANISE DE440s           |
-| Eclipse: entry/exit timing      | 90 s             | Shadow boundary interpolation          |
+```bash
+cargo run -p rpo-cli -- validate --input examples/validate.json              # J2 STM
+cargo run -p rpo-cli -- validate --input examples/validate.json --auto-drag  # J2 + DMF drag
+```
 
-Reproduce with:
+| Scenario                                      | Max        | Mean   | RMS  |
+| --------------------------------------------- | ---------- | ------ | ---- |
+| J2 STM, 3 legs, ~4.5 orbits (no drag)         | **58 m**   | 32 m   | 36 m |
+| J2 + DMF-drag STM, 3 legs (auto-drag)         | 152 m      | 68 m   | 79 m |
+| Eclipse Sun direction (Meeus vs ANISE DE440s) | **0.005°** | 0.005° | —    |
+| Eclipse entry/exit timing                     | 83 s       | 32 s   | —    |
 
-- `cargo run -p rpo-cli -- validate --input examples/validate.json`
-- `cargo run -p rpo-cli -- validate --input examples/validate.json --auto-drag`
+Velocity error stays under 40 mm/s (no-drag) and 55 mm/s (auto-drag) across the same run. Per-leg growth under drag: position RMS grows roughly 3× from leg 1 to leg 3 (41 m → 92 m → 138 m) as DMF linearization accumulates — a known linear-regime characteristic, not a bug.
+
+**Test-suite gates (conservative pass/fail with ~10× margin over observed).** The regression tests enforce `FULL_PHYSICS_SINGLE_LEG_POS_TOL_KM = 500 m`, `DRAG_STM_VS_NYX_POS_TOL_KM = 1 km`, and `FULL_PHYSICS_MULTI_LEG_POS_TOL_KM = 3 km` (all in `rpo-nyx/src/validation/trajectory.rs`); eclipse gates are `SUN_DIRECTION_VALIDATION_TOL_RAD = 3.5e-4 rad` (≈ 0.02°) and `ECLIPSE_TIMING_VALIDATION_TOL_S = 120 s` (`rpo-core/src/constants.rs`).
+
+**Per-component ROE validation against Koenig Table 4 Case 1.** The J2 STM is independently validated against the per-component error bounds in Koenig et al. (2017), Table 4 Case 1. Each quasi-nonsingular ROE component (`δa`, `δλ`, `δex`, `δey`, `δix`, `δiy`) is bounded within ~10× of the published errors — e.g. `KOENIG_T4C1_DA_BOUND_M = 385 m`, `KOENIG_T4C1_DIX_BOUND_M = 9 m`. See the `koenig_table4_j2_stm_accuracy_case1` test in `rpo-nyx/tests/regression_tests.rs`.
+
+**Outside the validated regime:** GEO, HEO, highly eccentric orbits, and formations outside the ROE-linear regime (`δr/r > 0.5%`) are not currently validated against full physics. See _Status & Roadmap_.
 
 ## Library Usage
 
@@ -129,12 +166,12 @@ For the full pipeline (classify -> Lambert -> waypoints -> covariance -> eclipse
 
 ```rust
 use rpo_core::prelude::*;
-use rpo_core::mission::ProximityConfig;
 use rpo_core::elements::{state_to_keplerian, compute_roe};
+use rpo_core::mission::ProximityConfig;
 use hifitime::Epoch;
 use nalgebra::Vector3;
 
-// Define chief and deputy ECI state vectors
+// ~300 m formation at ISS altitude
 let epoch = Epoch::from_gregorian_utc(2024, 1, 1, 0, 0, 0, 0);
 let chief = StateVector {
     epoch,
@@ -147,42 +184,23 @@ let deputy = StateVector {
     velocity_eci_km_s: Vector3::new(-2.380612, 4.123067, 6.006817),
 };
 
-// Classify: proximity or far-field?
 let phase = classify_separation(&chief, &deputy, &ProximityConfig::default())?;
-
-// Build a departure state for the waypoint planner
 let chief_elements = state_to_keplerian(&chief)?;
-let deputy_elements = state_to_keplerian(&deputy)?;
-let roe = compute_roe(&chief_elements, &deputy_elements)?;
-let departure = DepartureState { roe, chief: chief_elements, epoch };
-
-// Define waypoints in RIC frame (radial, in-track, cross-track)
-let waypoints = vec![
-    Waypoint {
-        position_ric_km: Vector3::new(0.0, 2.0, 0.0),
-        velocity_ric_km_s: Some(Vector3::zeros()),
-        tof_s: Some(4200.0),
-    },
-    Waypoint {
-        position_ric_km: Vector3::new(0.0, 0.5, 0.0),
-        velocity_ric_km_s: Some(Vector3::zeros()),
-        tof_s: Some(4200.0),
-    },
-];
-
-// Plan the mission
+let departure = DepartureState {
+    roe: compute_roe(&chief_elements, &state_to_keplerian(&deputy)?)?,
+    chief: chief_elements,
+    epoch,
+};
+let waypoints = vec![Waypoint {
+    position_ric_km: Vector3::new(0.0, 0.5, 0.0),
+    velocity_ric_km_s: Some(Vector3::zeros()),
+    tof_s: Some(4200.0),
+}];
 let mission = plan_waypoint_mission(
-    &departure,
-    &waypoints,
-    &MissionConfig::default(),
-    &PropagationModel::J2Stm,
+    &departure, &waypoints, &MissionConfig::default(), &PropagationModel::J2Stm,
 )?;
-
-println!("Total delta-v: {:.6} km/s", mission.total_dv_km_s);
-println!("Legs: {}", mission.legs.len());
-for (i, leg) in mission.legs.iter().enumerate() {
-    println!("  Leg {}: dv={:.6} km/s, tof={:.0} s", i, leg.total_dv_km_s, leg.tof_s);
-}
+println!("Phase: {phase:?}  dv: {:.3} m/s  legs: {}",
+    mission.total_dv_km_s * 1000.0, mission.legs.len());
 ```
 
 ### TypeScript (WASM)
@@ -198,22 +216,38 @@ import init, {
 
 await init();
 
-// Classify: proximity or far-field?
+// Classify — far-field or proximity?
 const phase = classify_separation(chief, deputy, { roe_threshold: 0.005 });
+if (!("proximity" in phase)) {
+  // Far-field: request a Lambert transfer from rpo-api over WebSocket
+  // (see docs/API.md), then resume from the perch state.
+  throw new Error("Far-field: Lambert transfer required");
+}
 
-// Plan waypoints (analytical -- runs in the browser, no server needed)
+// Plan — a 2-waypoint approach in microseconds
 const mission = plan_waypoint_mission(
   departure,
-  [{ position_ric_km: [0, 0.5, 0], velocity_ric_km_s: null, tof_s: 4200 }],
-  {}, // MissionConfig defaults
+  [
+    { position_ric_km: [0, 0.5, 0], velocity_ric_km_s: null, tof_s: 4200 },
+    { position_ric_km: [0, 0.1, 0], velocity_ric_km_s: [0, 0, 0], tof_s: 4200 },
+  ],
+  {}, // MissionConfig — all fields optional
   "j2", // PropagatorChoice
 );
 
-// Safety analysis (free-drift, POCA, optional COLA)
-const safety = compute_safety_analysis(mission, null, null, "j2");
+// Safety — e/i passive safety + keep-out
+const safety = compute_safety_analysis(
+  mission,
+  { min_distance_3d_km: 0.05, min_ei_separation_km: 0.2 },
+  null,
+  "j2",
+);
+
+// Everything above runs in ~1 ms in the browser. See docs/WASM.md for POCA,
+// COLA, covariance, eclipse, formation enrichment, and the full 18-function API.
 ```
 
-All input/output types have full TypeScript definitions.
+All input/output types have full TypeScript definitions. See [docs/WASM.md](docs/WASM.md) for the complete API reference.
 
 ## Documentation
 
@@ -245,10 +279,15 @@ cargo clippy --workspace -- -D warnings   # lint (pedantic)
 
 Every module traces to specific equations in these papers; see inline doc-comments for mappings.
 
-## Roadmap
+## Status & Roadmap
+
+Solo-authored, actively developed, research-grade Rust. Not on `crates.io` — build from source at the workspace root. Validated for LEO ISS-class orbits (~400 km altitude, ~51.6° inclination) with ~300–400 m formation separations; other regimes are on the roadmap below.
+
+**In progress / next:**
 
-1. **R3F frontend** -- React Three Fiber 3D visualization: orbit arcs, RIC-frame relative motion, maneuver arrows, eclipse timeline, covariance ellipses.
-2. **Extended orbit regimes** -- GEO/HEO validation, finite burns.
+1. **React Three Fiber frontend** — interactive 3D mission designer running in the browser via the WASM analytical engine, WebSocket to `rpo-api` for nyx-dependent operations (Lambert, validation, Monte Carlo). Analytical ops stay sub-frame; numerical ops stream progress.
+2. **Drag-aware formation design** — DMF-rate feedback into waypoint null-space enrichment so drift compensation happens upstream of the analyst advisory rather than as a post-hoc warning.
+3. **Extended orbit regimes** — GEO and HEO validation; appropriate STM extensions; finite-burn modeling for maneuvers that cannot be treated as impulsive.
 
 ## License
 

docs/formation-design.md

@@ -0,0 +1,62 @@
+# Formation Design
+
+This document covers the formation-design vocabulary implemented in `rpo-core`. For the
+architectural positioning (advisory vs enforced, ground-based vs flight software), see the
+**Formation Design** section of [the README](../README.md#formation-design).
+
+The toolkit implements the quasi-nonsingular ROE formation-design vocabulary from D'Amico
+2010 directly:
+
+- **e/i vector separation** (D'Amico Eq. 2.22) — the passive-safety metric. A formation
+  maintains minimum radial/cross-track separation across phasing as long as the eccentricity
+  and inclination vectors are properly separated, independent of along-track drift. The
+  planner computes it; the analyst decides whether to act on it.
+- **Null-space-projected waypoint enrichment** (D'Amico Eq. 2.17, 2.23) — for each
+  user-placed waypoint, the toolkit computes a "safe alternative" ROE that preserves the
+  chosen RIC position _exactly_ but adjusts the approach velocity along the null space of the
+  position-to-ROE map. Improves e/i separation without moving the waypoint. Shown as an
+  advisory card with baseline-vs-enriched comparison.
+- **Perch enrichment** (D'Amico Eq. 2.32) — on departure from a far-field approach, the
+  perch state's e/i vectors can be adjusted to a user-requested minimum R/C separation. The
+  solver returns **both** a baseline (unenriched) and an enriched plan. Default is baseline;
+  the analyst explicitly opts in.
+- **Transit monitoring** (D'Amico Eqs. 2.28–2.30) — per-leg e/i separation profiles along
+  each coast arc with mission-wide minimum flagged. Eq. 2.28 is the J2 secular rate of δα,
+  Eq. 2.29 the integrated form δα(t) that yields the per-leg profile, and Eq. 2.30 is the
+  relative-perigee drift `dφ/du = (3/2)γ(5cos²i−1)`. Red zones identify when the formation
+  would temporarily lose passive-abort capability during a guided approach.
+- **Free-drift abort analysis** (D'Amico Eq. 2.33, bounded-motion criterion) — per-leg
+  diagnostic showing what happens if the departure burn doesn't fire. Eq. 2.33 is the
+  closed-orbit condition `γ·sin(2i)·Δi + (1/7)·Δa/a = 0`; abort analysis evaluates a given
+  ROE state against it. Runs alongside the nominal plan, not after it.
+
+## Why advisory, not enforced
+
+Short maneuver legs naturally produce poor intermediate e/i geometry even when operational
+safety (3D keep-out distance) is fully satisfied. Enforcing e/i as a hard planning constraint
+would reject many otherwise operationally safe guided approaches. The tool enforces what must
+not be violated (keep-out distance, checked at every trajectory sample) and evaluates what
+requires analyst judgment (passive safety, advisory cards with explicit opt-in).
+
+## Primitive → equation mapping
+
+| Primitive                         | Function                                                       | Source                 |
+| --------------------------------- | -------------------------------------------------------------- | ---------------------- |
+| e/i vector passive safety         | `assess_safety()`                                              | D'Amico Eq. 2.22       |
+| Null-space waypoint enrichment    | `enrich_waypoint()` → `accept_waypoint_enrichment()`           | D'Amico Eq. 2.17, 2.23 |
+| Perch enrichment                  | `suggest_enrichment_from_parts()` → `apply_perch_enrichment()` | D'Amico Eq. 2.32       |
+| Transit e/i profile               | (inside `plan_waypoint_mission()` output)                      | D'Amico Eqs. 2.28–2.30 |
+| Free-drift abort + bounded-motion | `compute_free_drift_analysis()`                                | D'Amico Eq. 2.33       |
+
+## See also
+
+Collision avoidance (COLA) is a separate module — reactive burn planning via inverse GVE
+when POCA crosses a threshold, rather than passive-geometry design. Sources: D'Amico §2.4
+(Relative Orbit Control), Eqs. 2.38–2.41, 2.44, 2.50–2.56. Code: `rpo-core/mission/avoidance/`.
+The shared infrastructure is the GVE B matrix (`dv` → `dROE`) at D'Amico Eq. 2.38, which
+lives in `rpo-core/elements/gve.rs` and is used by both formation targeting and avoidance.
+
+## References
+
+- D'Amico, _Autonomous Formation Flying in Low Earth Orbit_, PhD thesis, TU Delft 2010.
+  [PDF](references/Damico_PhD.pdf).