Point the agent docs at opt-solve and opt-trade, and record three traps

AGENTS.md

@@ -11,7 +11,7 @@ Don't read the whole folder. Route by task:
 | --- | --- |
 | Anything non-trivial, first time in the repo | [`docs/architecture.md`](docs/architecture.md) |
 | Running / building / testing something | [`docs/workflows.md`](docs/workflows.md) |
-| Parameter sweeps, sensitivities, target-metrics → vehicle | [`docs/doe-reverse-engineering.md`](docs/doe-reverse-engineering.md) |
+| Parameter sweeps and sensitivities, solving for a setup from target metrics, trade studies across standard sims (`opt-*`) | [`docs/doe-reverse-engineering.md`](docs/doe-reverse-engineering.md) |
 | Reduced 3/6/10/14DOF dynamics, QSS envelopes, BobLib correlation | [`docs/reduced-order-dynamics.md`](docs/reduced-order-dynamics.md) |
 | QSS racing lines, speed profiles, and transient laps | [`docs/lap-time-simulation.md`](docs/lap-time-simulation.md) |
 | Modelica missing, build fails, BobLib edits | [`docs/boblib-submodule.md`](docs/boblib-submodule.md) |
@@ -75,6 +75,28 @@ above. Keep the set small; a stale doc is worse than no doc.
   [`docs/conventions.md`](docs/conventions.md#vertical-datum-z) and
   [`skills/shark-import/SKILL.md`](skills/shark-import/SKILL.md).
 
+- **An OpenModelica `-override` can be accepted and do nothing.** Static toe and
+  camber feed the wheel's `toHub.R_rel` rotation matrix, which is evaluated at
+  compile time; every mass and CG value goes the same way through
+  `combineMassRecords`. The parameter still reports `isValueChangeable="true"`,
+  the override raises no warning, and the simulated car does not change. Only the
+  variables in `RUNTIME_SAFE_PATHS` (`_4_OptSim/StandardSens/pipeline/overrides.py`)
+  are proven to follow an override; anything else must be compiled. The runner
+  also silently drops an override name it cannot find in the init XML. Before
+  trusting a new override, read that file's comment on how to vet one.
+- **OptSim is three tools, and picking the wrong one wastes hours.**
+  `opt-standard` samples a space to learn what matters, `opt-solve` inverts for the
+  setup that hits target metrics, `opt-trade` compares vehicles you name. None
+  finds a "best" car, and none replaces another. A consumer that needs variable
+  specs or compiled vehicles should use `pipeline/variants.py::VariantStore`,
+  never rewrite the sweep's committed `_doe_config.yaml`: that file records the
+  scope its population was built at, and `opt-search` relies on it.
+- **Git Bash on Windows rewrites container paths.** `make` targets pass
+  `/workspace/...` to Docker, and MSYS turns that into
+  `C:/Program Files/Git/workspace/...`, so the run dies in seconds with a
+  file-not-found. Prefix the command with `MSYS_NO_PATHCONV=1`. The same
+  conversion mangles `git show origin/main:path`.
+
 ## Verifying a change
 
 ```bash

docs/README.md

@@ -11,7 +11,7 @@ Read in this order:
 | [architecture.md](architecture.md) | You need the `_0_` … `_5_` layer map and how data flows between them. Start here. |
 | [simulation-entrypoints.md](simulation-entrypoints.md) | You need to understand the fidelity levels and use cases of VehicleSim, EnvelopeSim, StandardSim, and FourPostSim — or you're publishing results and need to specify which workflow was used. |
 | [workflows.md](workflows.md) | You want to *run* something: app, standard studies, envelopes, sensitivities, tests. |
-| [doe-reverse-engineering.md](doe-reverse-engineering.md) | You are doing DOE work — sweeping parameters or going backwards from target performance metrics to a car. Start here for `make opt-standard`. |
+| [doe-reverse-engineering.md](doe-reverse-engineering.md) | You are doing OptSim work: sweeping parameters (`make opt-standard`), solving for the setup that hits target metrics (`make opt-solve`), or comparing named vehicles across standard sims (`make opt-trade`). It opens with which of the three to reach for. |
 
 | [reduced-order-dynamics.md](reduced-order-dynamics.md) | You are working on 3/6/10/14DOF transient models, QSS envelopes, or BobLib correlation. |
 | [lap-time-simulation.md](lap-time-simulation.md) | You are optimizing a QSS racing line/speed profile or running the same lap as a forward transient. |

docs/architecture.md

@@ -56,11 +56,15 @@ GGV (grip-acceleration) and YMD (yaw moment diagram) generators. Quasi-steady ma
 Output: `generated_results/` (CSVs, PDFs)
 
 ### `_4_OptSim/` — sensitivities and DOE
-- **`StandardSens/`**: sweep StandardSim studies over parameter ranges
+- **`StandardSens/`**: sweep StandardSim studies over parameter ranges, solve for a
+  setup from target metrics (`solve_setup.py`), and compare named vehicles across
+  standard sims (`trade_study.py`). `pipeline/standards.py` is the registry of
+  VehicleSim standards one compiled vehicle can serve; `pipeline/variants.py` is the
+  content-addressed cache of compiled vehicles the solver and trade study share.
 - **`EnvelopeSens/`**: sweep envelope outputs (same ranges)
 - **`_shared/`**: console progress, tornado-plot rendering
 
-See [doe-reverse-engineering.md](doe-reverse-engineering.md) for reverse-lookup (target metrics → car parameters).
+See [doe-reverse-engineering.md](doe-reverse-engineering.md) for all three: the sweep and its reverse lookup, the setup solver, and trade studies.
 
 ### `_5_App/` — browser UI and HTTP server
 Main user entry point: `python -m _5_App.app` (port 8765). Pick/edit vehicle, generate Modelica, launch jobs, view logs and results.

docs/workflows.md

@@ -111,11 +111,21 @@ make opt-standard   # StandardSens pre-screen sensitivities
 make opt-envelope   # EnvelopeSens sensitivities
 make opt-refined    # StandardSens refined response surfaces
 make opt-search METRICS="Metric=value ..."   # reverse lookup, see the DOE doc
+make opt-solve      # solve for the setup that hits configs/solve_config.yaml's targets
+make opt-trade      # compare the vehicles named in configs/trade_study.yaml
 ```
 
+`opt-solve` and `opt-trade` cache compiled vehicles and results under
+`_4_OptSim/Build/StandardSens/{solve,trade}/`, and discard them when BobLib, the
+vehicle or the simulation tooling changes, so a rerun is usually seconds. Which of
+the `opt-*` tools answers which question is the first section of
+[doe-reverse-engineering.md](doe-reverse-engineering.md).
+
 Note the `opt-*` targets set `PYTHONPATH=_4_OptSim:.` and invoke modules as
 `StandardSens.*` / `EnvelopeSens.*`, not `_4_OptSim.StandardSens.*`. If you run
-one by hand, replicate that or the imports of `_shared` will fail.
+one by hand, replicate that or the imports of `_shared` will fail. `PYTHONPATH`
+uses the platform's separator, so on Windows outside the container it is
+`PYTHONPATH="_4_OptSim;."`.
 
 ## Visualizing a run