developer

OmniSim Developer Docs

This directory is the implementation-facing documentation set for OmniSim contributors. It is meant to be read while changing code, validating a fix, or planning subsystem work.

⚠️ WREN IS DELETED (2026-08-23) — READ THIS BEFORE TRUSTING ANY RENDERING DOC HERE

976b9449d deleted the WREN renderer (src/wren/, include/wren/, src/omnisim/wren/ and 86 shaders). wgpu-native is the only renderer — for the main view and for every Camera, RangeFinder and Lidar device, which now render offscreen and therefore work windowed, minimised, under OMNISIM_NO_WINDOW=1, and with no GL context at all.

There is no fallback renderer. renderBackend "wren" and WorldInfo.defaultRenderBackend "wren" still PARSE — an undeclared field is a hard load ERROR, so they had to — but they are warned no-ops that render wgpu anyway, as are OMNISIM_FORCE_WREN and OMNISIM_LEGACY's render arm. A host whose wgpu-native cannot initialise now has no renderer at all: one loud log line, and physics and controllers carry on unaffected.

Read every "WREN remains canonical / is the default / is the fallback" line in this docs set the way the ODE banner below asks you to read its equivalents — as a record of the migration while it was running, not as a description of the machine. The migration plans (engine-migration-plan.md, default-flip-plan.md) are the clearest cases: they are dated working documents and their mid-flight statements were true when written. The current-state reference is wgpu-renderer-status.md.

What survives of WREN, and is not a mistake: resources/wren/ (ten Cyberbotics gizmo meshes and overlay textures the wgpu GUI still reads), the frozen reference images at tests/rendering/wren_reference/, and the separately-vendored wrenjs build behind the --stream browser viewer, which is independent of the engine deletion and permanently diverges in look from the desktop view — recorded and accepted.

⚠️ ODE IS DELETED (2026-08-08) — READ THIS BEFORE TRUSTING ANY PHYSICS DOC HERE

bdc02139 deleted the vendored ODE library (src/ode/, include/ode/, 106,283 lines). Newton with SolverMuJoCo is the only physics backend, in a CPU (mj_step) and a batched-GPU (mujoco_warp) profile. XPBD was removed too (94f04222), the physics-plugin C ABI was deleted (a0ed801c), and so was the Fluid node (f0574cbe).

There is no fallback backend. OMNISIM_FORCE_ODE, OMNISIM_LEGACY, OMNISIM_ALLOW_ODE_FALLBACK, physicsBackend "ode" and defaultPhysicsBackend "ode" no longer select a working backend. Anywhere in this docs set that says "falls back to ODE", "silently runs ODE", "ODE is the fallback", or "both backends" is describing a machine that no longer exists. Many pages carry dated correction banners; some do not yet.

🔴 But "no ODE" is NOT the same as "asking for ODE fails loudly" — verified in source, and this is the trap to know. A world that still pins physicsBackend "ode" loads fine and runs with no physics at all, silently: OmSolid::effectivePhysicsBackendName treats an explicit "ode" as a choice that always wins, and hands the Solid an inert stub. (Refusing these at construction was tried and reverted — it wrongly refused 4 of 4 defaultPhysicsBackend "ode" worlds.) The same silent-stub path is taken by a clone where the Newton runtime is simply absent; only an installed-but-broken runtime is refused with a FATAL. Consequence: set OMNISIM_REQUIRE_NEWTON=1 on any deploy, CI or benchmark run whose result you intend to trust, and prove Newton drove a world by asserting the .newton.json sidecar — never by exit code and never by a tail-scraped log line.

Three consequences that change how you read the evidence here:

1. There is no second IN-ENGINE path to cross-check the plumbing. Note the narrow wording — lane 1's oracle is analytic ground truth, which is untouched, and bare mujoco and pybullet still run as independent arms. What is gone is the ability to run one .wbt through two integrations and diff. Lane 1's generator also emitted an ode_pin per scene, so the lane cannot be run exactly as designed. Frozen values survive in tests/goldens/ode_oracle_goldens.json — a golden file, not an oracle: it detects that Newton changed, it cannot adjudicate which engine was right. Several other goldens, control arms and frozen fixtures died the same way (the damage golden husky_head_on_ode.wbt, AgentBench Phase W's four defaultPhysicsBackend "ode" fixtures, lane 1's t*_odepin worlds).
2. ODE was removed while its INTEGRATION still scored better on lane 1, and while it was the faster single-world backend. ⚠️ Read that precisely: omnisim-ode outscored omnisim-newton, which compares two integrations — not two solvers. Bare MuJoCo scored fine on the same scenes, and the four defects behind Newton's deficit were in our own scene-graph-to-solver plumbing and were fixed in e7b9fb11. So do not say "ODE was more accurate than MuJoCo" (never measured), and equally do not let "ODE was a legacy tier" creep back in. Retirement was a capability, maintenance and licensing decision; the per-step cost advantage was real and is history. Full scope: ../benchmarks/correctness-scope.md.
3. ⚠ A load-only sweep cannot see wrong physics. The campaign's sharpest lesson: tests/api scored 140/140 PASS while all 140 of those worlds were NUE and had gravity projected to exactly zero — nothing in them ever fell. Post-fix (c77cbe98) the honest score is 128/139. Wherever a doc here leans on a load-and-step PASS as physics evidence, distrust the framing. run-headless --fail-on-runaway exists for exactly this reason.

Full record, the six kernel blockers and their outcomes, and the defects the deletion left behind (contact sound and the contact-points GUI overlay are dead; the three that were open then are since RESOLVED — Hinge2Joint motors 2026-08-17, force-TouchSensor 2026-08-13/15, BallJoint motors 2026-09-01): ode-retirement-campaign.md.

• agent-benchmarks.md — canonical suite for scoring an OmniLink engine on real robot control (ground-truth verified, engine-substitution proof). Current: Gemini 5/6 hard, Grok 2/6.
• agent-safety-model.md — what stops a robot doing something unexpected; e-stop, arena guard, and the gaps that are still open.

Start Here

• quickstart.md: first local build, runtime setup, and the basic fast-path commands.
• architecture.md: short architectural map of the desktop shell, runtime, parser, renderer, and controller layers.
• agent-map.md: repository navigation guide for coding agents and humans doing targeted code search.
• simulator-comparison.md: how OmniSim compares to Isaac Sim/Lab, Gazebo, MuJoCo/MJX, Webots, Genesis, ManiSkill, PyBullet, CoppeliaSim, and Unity/Colosseum — licence, physics, rendering, RL, ROS, hardware floor, and maintenance status, with each claim marked verified / unaudited / vendor-claim. Carries the honest losses (ROS 2 support is new and has no ros2_control, not photoreal, sim-to-real unproven) and the defensible positioning paragraph. The throughput companion is ../benchmarks/performance-comparison.md. Read before making any public comparative claim.
• OmniBench — "how do I benchmark this?" and "what are our measured numbers?" both end here. The repo's runnable cross-simulator physics benchmark: three lanes (correctness against analytic ground truth, throughput to the post-Genesis credibility checklist, and determinism / train==deploy parity / agent-driveability), four engines as of its first campaign (MuJoCo 3.8.1, PyBullet, OmniSim/ODE, OmniSim/Newton — ODE deleted 2026-08-08, so three now), a machine fingerprint on every row, and one command to reproduce: python tests/benchmarks/omnibench/run_all.py. Contract + the five binding honesty rules: SPEC.md. First campaign, two machines: ../benchmarks/omnibench-2026-07-24.md. Quote OmniSim numbers from there, with the machine id attached — it supersedes the ad-hoc 2026-06-14 probes wherever they disagree (see the header box of ../benchmarks/performance-comparison.md). Two results worth knowing before you write anything comparative: omnisim-ode was the best-scoring integration in lane 1 (⚠️ not a solver result — bare MuJoCo scored fine on the same scenes and the deficit was in our own plumbing, fixed in e7b9fb11; ../benchmarks/correctness-scope.md), and cheaper per step than Newton at every scene size measured — Newton's win is batching — and the suite found five real Newton-integration bugs, all fixed (e7b9fb11) and cross-machine validated. ⚠ Both ODE facts are now historical and unrepeatable (bdc02139): lane 1 has lost its oracle, and the honest form of the batching claim — K-world Newton against K sequential ODE runs — is no longer buildable. Never quote a Newton-vs-ODE ratio as current.
• ../benchmarks/lane4-capability-matrix.md: ⚠️ READ THIS BEFORE TELLING ANYONE WHAT OMNISIM CAN SIMULATE — it is generated from measurements and it overrides the prose, including AGENTS.md. OmniBench lane 4 (tests/benchmarks/omnibench/lane4/) executes one probe per capability — object primitives, joints and actuation modes, devices, world-level contracts — each with a committed .wbt and an assertion in physical units, plus a per-machine scaling envelope and a CPU-only (no-CUDA-visible) probe. Its verdicts are works / degraded / broken / absent, and broken is the one nothing else in the suite can see: present in the schema, accepted at load, measurably doing nothing — exactly what a bare run-headless PASS reports as success. The lane also audits the documentation against itself and raises a finding when the two disagree in either direction. Two rules bind anyone reading it: a broken verdict is not publishable until it has been chased to a mechanism (most of the lane's early findings were its own calibration errors), and an instrument that never fired has not been shown to work — the constraint-overflow detector currently reports cliff_detector_validated: false and its silence must not be read as a pass.
• ../benchmarks/determinism-scope.md: ⚠️ READ THIS BEFORE WRITING ANY DETERMINISM OR REPRODUCIBILITY CLAIM — it is the source of truth and it overrides every other doc. What OmniSim actually reproduces run-to-run, per configuration: bitwise on newtonSolver "mujoco" (CPU mj_step, verified at 336 contacts with ten live controllers) — the only live row; bitwise on ODE and on Newton/XPBD in the historical record, both now unverifiable because those configurations were deleted (bdc02139, 94f04222), which also means the CPU-bitwise result has lost its independent corroborating backend; refuted on the GPU newtonSolver "mujoco_warp" path (0 bitwise of 24 same-config cold pairs, 9.152 m apart by 1000 steps, mechanism traced to wp.atomic_add contact-slot claiming); untested cross-machine. Also carries the false positive that briefly inflated the claim (a recorder that skipped undeffed nodes graded a stationary sun marker as bitwise) and the rule it cost us twice: an assertion that has never gone red should be assumed broken until you make it go red on purpose.
• agent-edge-validation-plan.md: ⚠️ "do agents actually get more done here?" — the programme, written BEFORE the runs so the retreat cannot be improvised. On 2026-07-26 the first A/B of our own agent surface against a bare POSIX shell had the shell win or tie every run, so the claim that an agent gets more done on OmniSim is currently unsupported by any measurement we hold. Nothing in the file is a result. The contract it implements is tests/benchmarks/agentbench/SPEC.md.
• webots-control-baseline.md: how to stand up upstream Webots R2025a as the CONTROL arm of that programme (Phase W) — same file format, same base engine, no harness. If an agent does as well on plain Webots, everything we built on top buys nothing. The cheapest decisive experiment we have, and the harshest; includes the traps that would otherwise invalidate the comparison.
• tests/benchmarks/omnilink_long_horizon/SPEC.md: the long-horizon lane — one natural-language objective to Mission Captain, which must inspect its roster, delegate a self-contained mission to Husky Maze, and close only against a completed delegation ledger. Measures the production PRO-agent stack, not a scripted controller and not an LLM judge.
• ros2-integration.md: ⭐ the ROS 2 story — a non-goal until 2026-08-17, now a shipped sidecar. OmniSim implements the ROS 2 simulation_interfaces standard (v2.1.0) plus /clock, /tf, JointState, /odom and cmd_vel, as packages/omnisim-ros2/ — with the engine still ROS-free (no rclcpp in src/omnisim/, no ROS in the engine Makefiles). This doc keeps the reversed decision's history, says which parts of the old reasoning survive, and lists the limitations plainly — ⛔ chief among them that Tier 3 ros2_control covers velocity-commanded bases only: diff_drive_controller is verified on the Husky, MoveIt is blocked by OmniSim's arm bridge answering 409 busy to a setpoint stream, and Nav2 has been up since 2026-08-31 (planning only; run the engine with --engine-mode realtime for sensor stacks). The MCP front door to the same HTTP surface is packages/omnisim-mcp/.

Robot Learning & Motion

Read in this order. ⭐ shadowing.md is the FLAGSHIP method; rl-current-state.md is the CANONICAL status (never quote a result from any other doc).

• shadowing.md: ⭐ SHADOWING — the flagship algorithm for legged-robot motion (maintainer directive 2026-07-03). READ THIS FIRST for any new motion-control / imitation effort. Train in-engine (train == deploy bit-exact) to shadow a ghost (a dynamically-feasible reference) via corridors + WBMATCH + GHOST-MORPH. The thesis: ghost feasibility, not RL tuning, is the bottleneck — so verify the reference before you learn. Implementation: projects/policies/training/. Training is in-engine and LOCAL — there is no cloud path.
• ghost-design-rules.md: ⭐ the ghost doctrine — the FOUR GATES + the CORRIDOR-vs-TORQUE LAW + the 7 design rules, and the ghost toolchain. Gates 1–3 (closure / support / FWP) are static; gate 4 (ghost_funnel.py) asks whether a deploy-grade PD plant can actually track the reference. The LAW: a tracking corridor must exceed τ_ff/kp, or the reference is untrackable BY CONSTRUCTION — it retro-explains every corridored run that failed. Run ghost_validator.py on ANY new ghost before training.
• skill-library.md: the SKILL LIBRARY — the standard way to make a skill and compose skills. Wraps Shadowing + BATON into one pipeline (design → validate → preview → train → verify → register → sequence); a skill (walk / turn / carry / stand / climb, + H1 / Go2 / OmniQuad) is one versioned manifest binding its ghost + validator verdict + deploy env + champion checkpoint + provenance. Front door: projects/policies/skills/skill_lib.py (list/sequence/preview/train/verify-demos + handover/blendable/adapt/freeze). Start here to add a new skill or build a BATON demo.
• policy-switching.md: BATON — runtime handover between separately-trained Shadowing specialists (walk / stand / carry / turn). The handover machinery ships and is live-verified (four sequences: box_delivery, box_delivery_classic, walk_turn_walk, turn_solo; the 90° footwork turn is SOLVED, 72a7bb19). ⚠️ The switching-beats-a-monolith thesis remains an open hypothesis — the success-vs-horizon experiment is unrun. Read its "Where BATON stands vs the field" section before making any novelty claim.
• sim-to-deploy-rl-recipe.md: how to cross the mujoco_warp→OmniSim-Newton gap (domain randomization) — the deploy stage of the pipeline.
• g1-improved-shadow.md: earlier "achievable shadow" work (record/retarget feasible references).

Daily Workflow Guides

• build-and-iteration.md: what each public build target really does, when a relink is required, and how to keep rebuilds narrow.
• header-hygiene-and-rebuild-reduction.md: practical rules for shrinking header blast radius and avoiding unnecessary recompilation.
• validation-playbook.md: which validation lane to use for a given change, including smoke tests, test groups, and headless runs.
• ci-and-fast-feedback.md: how to structure cheap PR-default checks, targeted subsystem lanes, and later-stage regression gates.
• test-harness-and-scenario-architecture.md: how the current smoke, benchmark, and legacy test harness layers fit together and how they should evolve.
• profiling-playbook.md: how to collect and compare performance logs and benchmark runs.
• benchmark-authoring.md: how to add stable benchmark worlds and keep them useful over time.
• tool-design-for-agents.md: ⭐ the tool contract is a first-order term in agent task success, and the cheapest one to fix — suspect the tool before the prompt. An LLM has no independent access to the world, so a tool returning the value it was asked for installs a false belief the agent then reports confidently; its honesty is bounded above by the tool's. Measured here with the model held constant: turn at 56.7% of commanded → mean |err| 0.44°, n=8 with no prompt/model/config change (52f3f6ca), and the swarm showcase 2/4 → 4/4 purely by adding drive_to_xy. ⚠️ It is not established as dominant over model choice — those measurements hold the model constant, and the converse experiment (same tools, varying model) shows a 4/4-to-0/4 spread; the model ladder that would rank the two is Phase M of agent-edge-validation-plan.md and has not been run. Four properties (complete-before-return, achieved-not-commanded, the tool owns the geometry, publish your own error), the external literature, and the limits. Normative form: PROTOCOL.md §5.4.1; short form: pattern 9 in agents/AGENT_PATTERNS.md. Read before adding or changing any bridge verb.
• simulation-authoring-for-coding-agents.md: current best workflow and recommended simulator changes for agent-friendly world and scenario authoring.
• urdf-import-debugging.md: how to diagnose URDF import loss, joint-frame mismatches, and bad settling behavior.
• step-to-urdf.md: convert a STEP/STP CAD assembly into a colour-correct OmniSim URDF robot (scripts/dev/step_to_urdf.py), with the orientation trap and numerical verification.

For the agent-facing HTTP harness itself, see scripts/harness/README.md and AGENTS.md §5.

Deep Dives

• performance-handbook.md: the top-level map for build, load, runtime, rendering, sensor, and contributor-facing performance work.
• module-dependency-map.md: where the current subsystem boundaries actually are, where they leak, and how to keep new code in the right layer.
• controller-protocol.md: packet format, lifecycle states, and transport-level controller behavior.
• controller-ipc-and-step-loop.md: controller transport, scheduling, and step-loop coupling risks plus the cleanup path.
• startup-reset-and-asset-lifecycle.md: world-load, reset, and asset-download critical-path behavior and how to separate them.
• observability-and-performance-telemetry.md: what the current performance log captures, what it misses, and the next telemetry milestones.
• world-loading-and-template-performance.md: parser, node reader, template regeneration, dictionary, and startup-path performance.
• template-regeneration-and-dictionary-coherence.md: why PROTO regeneration, DEF/USE maintenance, and downstream UI costs are still tightly coupled.
• the internal parity plan (internal — excluded from the public snapshot, so not linked here): ⭐ how OmniSim goes head-to-head with Isaac Sim / Isaac Lab, and what it deliberately refuses to build. Six scoped workstreams with engineer-week estimates -- fix our own house (72% -> ~87% measured capability), make a robot driveable over HTTP (our harness has 34 endpoints and none commands a robot; the batched IK has zero callers), synthetic data, one importer for USD+MJCF+URDF, the asset library Isaac's licence forbids them from shipping, multi-GPU, and a ROS 2 simulation_interfaces sidecar. Three of the six gaps were mis-scoped in our own favour -- perception annotators already ship, USD parsing is already vendored and works, and the "declared friction is unreliable above 45 degrees" claim was a probe bug (a cube topples above 45 at ANY friction). ⚠️ Carries the NVIDIA SLA §8.9 constraint: we may not publish measured benchmarks of their software, so the "cite their figures, never measure them" posture is now policy. Sim-to-real is out of scope.
• engine-migration-plan.md: the master plan — physics arm now COMPLETE and its "forever-fallback" contract retired. Newton-canonical physics + wgpu-canonical renderer, originally with ODE+WREN as forever-fallbacks; ⚠ the ODE half of that promise was deliberately broken by the retirement campaign (bdc02139), so read the physics sections as history — ⚠ and the rendering arm is history too (corrected 2026-09-01, per the banner at the top of this file: WREN was deleted 2026-08-23 and wgpu is the only renderer, so "WREN still canonical, wgpu opt-in" describes the plan mid-flight, not the machine). Covers vision, sequencing (six phases α→ζ), performance targets (research-grounded), compatibility contract, the full physics arm phase status (P0–P9 + Phases A–E + CUDA/granular/particles/damage adjacent subsystems), the full rendering arm phase status (R0–R6 + Tier 1–5 fidelity tracks + §16.2 re-litigation triggers), the decision log, and the 2×2 test matrix. Replaces eleven prior plans (six physics-roadmap absorbed, five rendering-roadmap absorbed).
• core-evolution-plan.md: the answer to "should we rewrite the core in Rust?" turned into a measured plan — five data-verified weaknesses (core size, Qt bleed, silent-failure controller IPC, language gravity, format inheritance) with the Qt de-coupling (Phase Q) and fail-fast IPC handshake (Phase I) as the active workstreams. Companion to engine-migration-plan.md; owns the shrink ledger and ratchets.
• physics-and-determinism.md: physics throughput, contact complexity, multithreading, and determinism tradeoffs.
• physics-contact-and-collision-complexity.md: deeper guidance on contact-joint pressure, collision filtering, truncation, and physics authoring hazards.
• real-grasp-and-the-cold-first-load-trap.md: how we got a real (no-weld) friction bin grasp working, and the COLD-FIRST-LOAD trap it exposed — a fresh process under-tracks articulation targets, so precise grasps/insertions fail on the first load but work after a reload. Read this before concluding a headless grasp/contact "can't work."
• runtime-hotspots.md: deeper runtime, controller, parser, and synchronization review with concrete bottlenecks and bug risks.
• scene-tree-selection-and-runtime-mutation.md: why selection churn, layout invalidation, and runtime mutation still leak into desktop-shell cost.
• rendering-and-visual-quality.md: current rendering stack, visual quality issues, and the highest-value rendering improvements (the authoring-guide companion to engine-migration-plan.md §14).
• omniworld-user-guide.md: user-facing guide to the omniworld procedural generation library — CLI, Python API, determinism contract, and the currently landed slice of the plan.
• omniworld-biome-cookbook.md: contributor guide to writing a new biome — walkthrough of a shipped recipe, zone priority rules, and a step-by-step template.
• performance-anti-patterns.md: recurring design and implementation mistakes that slow builds, runtime, validation, or contributor iteration.
• rollback.md: baseline and recovery workflow.
• copyright-headers.md: per-file copyright header convention for unmodified Webots files, modified Webots files, and net-new OmniLink files.
• codebase-stats.md: the honest, reproducible answer to "how many lines did we write?" — ~120k lines of original source (mostly Python) + ~33k lines of reworked Webots C++ on top of the import, with the exact git commands to regenerate the numbers.

Engine migration (Newton physics + wgpu render)

Companion docs to engine-migration-plan.md (the master plan, in Deep Dives above). For current code-verified status, read its §8.1 "Status refresh — 2026-06-08" — the canonical snapshot the others point to.

• newton-ode-replacement-plan.md: ⚠ SUPERSEDED — the Newton capability-completeness plan (W0–W7), the coverage-meter-driven climb from ~35–40% toward ~100% faithful world coverage. Overtaken by ode-retirement-campaign.md: the climb was never completed on the meter's terms, and ODE was deleted anyway. ⚠ Note the substitution honestly — a fidelity meter was replaced by a load-and-step corpus sweep, so the ≥99%-faithful question was never actually answered and now has no oracle.
• default-flip-plan.md: the safety harness + sequencing for flipping the default physics/render backend without breaking the simulator (legacy kept as fallback + oracle).

RL training & sim-to-deploy

• rl-current-state.md: CANONICAL — the single source of truth for RL status; read its top banner FIRST. If any other doc, script comment, or commit disagrees with this file, this file is right — including everything in this index. ⛔ Never quote an RL result (distance, survival, fall count, WBMATCH) from another doc; quote this one. The narrative rl-journey.md defers to it, and the method docs (shadowing.md, ghost-design-rules.md, policy-switching.md, skill-library.md) describe how, not how well.
• sim-to-deploy-rl-recipe.md: the default RL recipe for any new robot deploying to OmniSim Newton. Heavy-DR pure PPO on GPU mujoco_warp + the dump-the-deploy-MJCF trick. Absorbs much of the sim-to-deploy gap by training to be invariant to the wrapper drift — but for stability-margin bipeds a residual deploy gap can remain (see G1). Includes the 5-speedup template (~132 k env-steps/s on the original training box).
• train-deploy-gap.md: synthesis + recipe — read after rl-current-state.md. Frames the train→deploy problem as two gaps (pipeline-parity vs durability), gives the enumerated + re-verified divergence table (COM, qd, launch-IC, contact), and the Unitree gold-standard obs/action/reward recipe as the durability answer. Routes to the owners below.
• g1-single-source-of-truth.md: the model single-source contract — g1_physics.json + g1_physics_spec.py + prim URDF → CI conformance; the three-way golden parity proof; the "import the spec, never re-declare a constant" rule.
• cross-machine-determinism.md: "the robot behaves differently on my other PC" — the guarantee tiers (bit-identical / near / statistical) and the one-command checks. The variance sources found live (torch resolves from the SYSTEM site-packages via the _pth fallback; stale dist-info metadata; stale binary; thread nondeterminism; chaos), the deploy numerics pin, audit_dist_info.py, golden_compare.py (BUG-vs-CHAOS), and machine_conformance.py (the Tier-C machine-vs-machine gate).
• g1-stand-rl-playbook.md: full case study — the 8-iteration journey from "G1 can't stand 1 second" to a robust stand. (The OmniSim Newton deploy now stands indefinitely — solved 2026-06-10 with the deeper-squat NOMINAL; see rl-journey.md §2 / the deploy-regression note. Earlier editions of this doc that say "holds to t ≈ 1.55 s" predate that fix.)
• omniquad-residual-rl.md: the quadruped recipe (residual on a model walker). Use for quadrupeds only — doesn't port to bipeds without modification (see G1 playbook).

Archived

Plans whose work is done, superseded designs, campaign logs and stale pages are no longer kept in the tree. docs/ARCHIVE.md lists every page removed on 2026-09-02 with the commit that still holds it (git show <sha>:<path>); nothing there is current, and the live code is authoritative.

Machine-Readable Guidance

• search-map.json: repository-local search guidance for agents and tools.

Suggested Reading Order

If you are:

• making a legged robot perform a motion (walk, turn, carry, climb): read shadowing.md, then ghost-design-rules.md, then skill-library.md — and check rl-current-state.md for what is actually working today
• composing skills into a demo (a BATON sequence): read skill-library.md, then policy-switching.md
• building locally for the first time: read quickstart.md, then build-and-iteration.md
• changing simulator code in src/omnisim: read architecture.md, then validation-playbook.md
• trying to keep rebuilds narrow: read header-hygiene-and-rebuild-reduction.md, then module-dependency-map.md
• changing PROTO regeneration or DEF/USE behavior: read template-regeneration-and-dictionary-coherence.md
• changing controller, IPC, or step scheduling code: read controller-ipc-and-step-loop.md
• improving startup or reset behavior: read startup-reset-and-asset-lifecycle.md
• changing renderer code in src/omnisim/render (or src/omnisim/nodes/OmWgpuSceneRenderer.*): read wgpu-renderer-status.md and rendering-and-visual-quality.md, then profiling-playbook.md
• looking for what's left to implement across all rendering subsystems: read engine-migration-plan.md §14
• debugging runtime behavior, controller synchronization, or parser issues: read runtime-hotspots.md, then world-loading-and-template-performance.md
• debugging imported URDF robot structure or settling issues: read urdf-import-debugging.md
• improving runtime or physics throughput: read performance-handbook.md and physics-and-determinism.md
• looking for what's left to implement across all physics subsystems: read engine-migration-plan.md §13
• improving contact-heavy or unstable physics worlds: read physics-contact-and-collision-complexity.md
• improving texture memory, uploads, or overlays: read wgpu-renderer-status.md (the texture cache is src/omnisim/render/OmWgpuTextureCache.*)
• improving scene-tree, selection, or editor responsiveness: read scene-tree-selection-and-runtime-mutation.md
• improving PR and CI turnaround: read ci-and-fast-feedback.md, then validation-playbook.md
• improving tests, smoke lanes, or benchmark structure: read test-harness-and-scenario-architecture.md
• adding or changing a bridge verb / any tool an LLM will call: read tool-design-for-agents.md FIRST, then PROTOCOL.md §5.4.1
• building or improving simulation worlds, PROTOs, or agent-driven scenarios: read simulation-authoring-for-coding-agents.md, then ../WORLD_RECIPE.md
• using or extending the agent-facing HTTP harness: read ../../scripts/harness/README.md and ../../AGENTS.md (section 5)
• improving measurement fidelity: read observability-and-performance-telemetry.md
• improving sensors or device-heavy worlds: read wgpu-renderer-status.md (offscreen Camera / RangeFinder / Lidar) and profiling-playbook.md
• reviewing a risky optimization or refactor: read performance-anti-patterns.md
• working through the broader modernization effort: read core-evolution-plan.md

Scope

These docs are intentionally pragmatic:

• they describe the codebase as it exists now
• they call out the fast paths that are actually available today
• they note where a path is a wrapper over legacy makefiles rather than a fully modular system

When the code and docs disagree, update the docs in the same change.

• Making a friction grasp hold — the settings a two-finger grip needs (the defaults do not hold one), the two controller rules, and how to prove a hold without getContactPoints. Runnable minimal example under worlds/starter/.

Plans and notes not linked elsewhere

Standalone plans, briefs and research notes under docs/developer/ that no other doc links to (indexed 2026-09-02 so they stay findable; each line is the file's own first heading/paragraph, condensed):

• release-model.md — Release Model: how OmniSim is published to the public repo (snapshot, tags, the release workflow)
• omniworld-format.md — the .omniworld world-file format: what it is, why .wbt is read forever, and what the new extension signals
• newton-capability-frontier.md — the Newton capability frontier: what Newton can do, what OmniSim reaches today, and what closing each gap would cost
• omniarm6-toss-shadowing.md — OmniArm 6 toss-to-place: Shadowing on a manipulator, to place past a bolted-down arm's reach
• omniquad-shadowing-motions.md — three OmniQuad motions produced through the shadowing pipeline, each from a feasible ghost
• sponsors-automation.md — GitHub Sponsors automation: the private runbook behind the daily SPONSORS.md refresh (PAT, workflow, fresh-fork setup)

Reference moved out of AGENTS.md (2026-09-02)

AGENTS.md is now a ≤45 KB bootstrap that every agent session reads whole. Every rule it summarises lives verbatim — markers, dates, commit hashes and self-correction history intact — in these four files, which AGENTS.md links per item:

• agents-first-moves.md — the full "First moves by task type" table, one section per row
• agents-hard-won-rules.md — the full "Hard-won rules" bullets, one section per rule
• harness-endpoint-reference.md — the full §5 endpoint cheatsheet, one section per endpoint
• agents-reference-sections.md — the full text of every other §0–§11 passage the bootstrap shortens

Environment-variable reference (2026-09-02)

• ../reference/environment-variables.md — every OMNISIM_* variable the tree READS, generated from the code by scripts/dev/gen_env_reference.py (read kind: presence-gated vs value-parsed, read sites, harvested description); docs/tests/test_env_reference.py fails when it drifts