riggen 0.2.0__tar.gz → 0.2.1.dev0__tar.gz

{riggen-0.2.0 → riggen-0.2.1.dev0}/Cargo.lock

@@ -214,6 +214,15 @@ version = "1.0.104"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "330a5ed07fa54e4702c9d6c4174f74427fc0ef6e214bbd677ae50a5099946470"
 
+[[package]]
+name = "approx"
+version = "0.5.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "cab112f0a86d568ea0e627cc1d6be74a1e9cd55214684db5561995f6dad897c6"
+dependencies = [
+ "num-traits",
+]
+
 [[package]]
 name = "arboard"
 version = "3.6.1"
@@ -572,6 +581,12 @@ dependencies = [
  "syn 3.0.4",
 ]
 
+[[package]]
+name = "byteorder"
+version = "1.5.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "1fd0f2584146f6f2ef48085050886acf353beff7305ebd1ae69500e27c67f64b"
+
 [[package]]
 name = "byteorder-lite"
 version = "0.1.0"
@@ -922,6 +937,12 @@ version = "1.2.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "75b325c5dbd37f80359721ad39aca5a29fb04c89279657cffdda8736d0c0b9d2"
 
+[[package]]
+name = "downcast-rs"
+version = "2.0.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "117240f60069e65410b3ae1bb213295bd828f707b5bec6596a1afc8793ce0cbc"
+
 [[package]]
 name = "dpi"
 version = "0.1.2"
@@ -1092,6 +1113,15 @@ dependencies = [
  "serde",
 ]
 
+[[package]]
+name = "ena"
+version = "0.14.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "eabffdaee24bd1bf95c5ef7cec31260444317e72ea56c4c91750e8b7ee58d5f1"
+dependencies = [
+ "log",
+]
+
 [[package]]
 name = "endi"
 version = "1.1.1"
@@ -1488,6 +1518,28 @@ dependencies = [
  "mint",
 ]
 
+[[package]]
+name = "glam"
+version = "0.33.6"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "21fef0953c54fd3de2f44b743fbf77e044c81a25faee03636dfccc0d35135e23"
+dependencies = [
+ "approx",
+ "libm",
+]
+
+[[package]]
+name = "glamx"
+version = "0.3.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "9847f980afb0628849bcd6a406cdffd29eb9d53fca83e1646005901a9acd4c5c"
+dependencies = [
+ "approx",
+ "glam 0.33.6",
+ "num-traits",
+ "simba",
+]
+
 [[package]]
 name = "glifo"
 version = "0.2.0"
@@ -1629,6 +1681,15 @@ dependencies = [
  "smallvec",
 ]
 
+[[package]]
+name = "hash32"
+version = "0.3.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "47d60b12902ba28e2730cd37e95b8c9223af2808df9e902d4df49588d1470606"
+dependencies = [
+ "byteorder",
+]
+
 [[package]]
 name = "hashbrown"
 version = "0.16.1"
@@ -1649,6 +1710,16 @@ dependencies = [
  "foldhash",
 ]
 
+[[package]]
+name = "heapless"
+version = "0.8.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "0bfb9eb618601c89945a70e254898da93b13be0388091d42117462b265bb3fad"
+dependencies = [
+ "hash32",
+ "stable_deref_trait",
+]
+
 [[package]]
 name = "heck"
 version = "0.5.0"
@@ -2172,6 +2243,26 @@ version = "0.2.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "2bf50223579dc7cdcfb3bfcacf7069ff68243f8c363f62ffa99cf000a6b9c451"
 
+[[package]]
+name = "num-complex"
+version = "0.4.6"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "73f88a1307638156682bada9d7604135552957b7818057dcef22705b4d509495"
+dependencies = [
+ "num-traits",
+]
+
+[[package]]
+name = "num-derive"
+version = "0.4.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "ed3955f1a9c7c0c15e092f9c887db08b1fc683305fdf6eb6684f22555355e202"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "syn 2.0.119",
+]
+
 [[package]]
 name = "num-traits"
 version = "0.2.19"
@@ -2598,6 +2689,33 @@ dependencies = [
  "windows-link",
 ]
 
+[[package]]
+name = "parry3d-f64"
+version = "0.30.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "8c5f71cd1d7f0c475116a52c61baa8d0de69fc258bc4debf86cb4c4ca8f35f3f"
+dependencies = [
+ "approx",
+ "arrayvec",
+ "bitflags 2.13.1",
+ "downcast-rs 2.0.2",
+ "either",
+ "ena",
+ "foldhash",
+ "glamx",
+ "hashbrown 0.17.1",
+ "log",
+ "num-derive",
+ "num-traits",
+ "ordered-float",
+ "rstar",
+ "simba",
+ "slab",
+ "smallvec",
+ "spade",
+ "thiserror 2.0.20",
+]
+
 [[package]]
 name = "peniko"
 version = "0.6.1"
@@ -3105,7 +3223,7 @@ version = "0.0.1"
 
 [[package]]
 name = "riggen-app"
-version = "0.2.0"
+version = "0.2.1-dev"
 dependencies = [
  "console_error_panic_hook",
  "eframe",
@@ -3113,6 +3231,7 @@ dependencies = [
  "egui-wgpu",
  "egui_kittest",
  "getrandom 0.3.4",
+ "js-sys",
  "pollster 1.0.1",
  "rfd",
  "riggen-core",
@@ -3126,11 +3245,12 @@ dependencies = [
  "wasm-bindgen-futures",
  "web-sys",
  "web-time",
+ "zip",
 ]
 
 [[package]]
 name = "riggen-core"
-version = "0.2.0"
+version = "0.2.1-dev"
 dependencies = [
  "riggen-mesh",
  "serde",
@@ -3139,8 +3259,9 @@ dependencies = [
 
 [[package]]
 name = "riggen-export"
-version = "0.2.0"
+version = "0.2.1-dev"
 dependencies = [
+ "quick-xml 0.36.2",
  "riggen-core",
  "riggen-mesh",
  "serde",
@@ -3150,16 +3271,17 @@ dependencies = [
 
 [[package]]
 name = "riggen-mesh"
-version = "0.2.0"
+version = "0.2.1-dev"
 dependencies = [
  "glam 0.30.10",
+ "parry3d-f64",
  "stl_io",
  "tobj",
 ]
 
 [[package]]
 name = "riggen-py"
-version = "0.2.0"
+version = "0.2.1-dev"
 dependencies = [
  "pyo3",
  "riggen-core",
@@ -3171,7 +3293,7 @@ dependencies = [
 
 [[package]]
 name = "riggen-viewport"
-version = "0.2.0"
+version = "0.2.1-dev"
 dependencies = [
  "bytemuck",
  "egui",
@@ -3180,6 +3302,12 @@ dependencies = [
  "web-time",
 ]
 
+[[package]]
+name = "robust"
+version = "1.2.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "4e27ee8bb91ca0adcf0ecb116293afa12d393f9c2b9b9cd54d33e8078fe19839"
+
 [[package]]
 name = "ron"
 version = "0.12.2"
@@ -3194,6 +3322,17 @@ dependencies = [
  "unicode-ident",
 ]
 
+[[package]]
+name = "rstar"
+version = "0.13.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "5912b862fa5ffb462607bfd1e35036c458c537921f508c8235a83d5f3987edfe"
+dependencies = [
+ "heapless",
+ "num-traits",
+ "smallvec",
+]
+
 [[package]]
 name = "rustc-hash"
 version = "1.1.0"
@@ -3247,6 +3386,15 @@ version = "1.0.23"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "cf54715a573b99ac80df0bc206da022bcd442c974952c7b9720069370852e21f"
 
+[[package]]
+name = "safe_arch"
+version = "1.2.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "42c6efa15875e6ecb39ca61fb0b0c1a40b84fac5a5ffe71eef7d1000c8eb3f5f"
+dependencies = [
+ "bytemuck",
+]
+
 [[package]]
 name = "same-file"
 version = "1.0.6"
@@ -3384,6 +3532,18 @@ dependencies = [
  "libc",
 ]
 
+[[package]]
+name = "simba"
+version = "0.10.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "f1a7200d82ff1c7b4235efd12f11e2537a402c91cf83a5cb97ce80eef787fde7"
+dependencies = [
+ "approx",
+ "num-complex",
+ "num-traits",
+ "wide",
+]
+
 [[package]]
 name = "simd-adler32"
 version = "0.3.10"
@@ -3518,6 +3678,18 @@ dependencies = [
  "serde",
 ]
 
+[[package]]
+name = "spade"
+version = "2.15.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "9699399fd9349b00b184f5635b074f9ec93afffef30c853f8c875b32c0f8c7fa"
+dependencies = [
+ "hashbrown 0.16.1",
+ "num-traits",
+ "robust",
+ "smallvec",
+]
+
 [[package]]
 name = "spirv"
 version = "0.4.0+sdk-1.4.341.0"
@@ -3823,6 +3995,12 @@ dependencies = [
  "rustc-hash 2.1.3",
 ]
 
+[[package]]
+name = "typed-path"
+version = "0.12.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "8e28f89b80c87b8fb0cf04ab448d5dd0dd0ade2f8891bae878de66a75a28600e"
+
 [[package]]
 name = "typeid"
 version = "1.0.3"
@@ -4028,7 +4206,7 @@ source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "38a91b4eaddff87b1cd1074985e3713da4af2c49742d1b356b2c01670a67a078"
 dependencies = [
  "cc",
- "downcast-rs",
+ "downcast-rs 1.2.1",
  "rustix 1.1.4",
  "scoped-tls",
  "smallvec",
@@ -4381,6 +4559,16 @@ dependencies = [
  "web-sys",
 ]
 
+[[package]]
+name = "wide"
+version = "1.7.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "8cf05ca94c9fba0c51316899caa1d1e74a064fc310a5efa7375e614343d415be"
+dependencies = [
+ "bytemuck",
+ "safe_arch",
+]
+
 [[package]]
 name = "winapi-util"
 version = "0.1.11"
@@ -5004,6 +5192,18 @@ dependencies = [
  "syn 3.0.4",
 ]
 
+[[package]]
+name = "zip"
+version = "8.6.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "2d04a6b5381502aa6087c94c669499eb1602eb9c5e8198e534de571f7154809b"
+dependencies = [
+ "crc32fast",
+ "indexmap",
+ "memchr",
+ "typed-path",
+]
+
 [[package]]
 name = "zlib-rs"
 version = "0.6.7"

{riggen-0.2.0 → riggen-0.2.1.dev0}/Cargo.toml

@@ -3,19 +3,25 @@ resolver = "3"
 members = ["crates/riggen-mesh", "crates/riggen-core", "crates/riggen-export", "crates/riggen-py"]
 
 [workspace.package]
-version = "0.2.0"
+version = "0.2.1-dev"
 edition = "2024"
 license = "MIT OR Apache-2.0"
 
 # `cargo run` is the interactive loop, and an unoptimized wgpu/egui is slow
 # enough to be felt. Deps are built once at full optimization; our own crates
-# stay at `1` so backtraces and stepping still work (docs/01-architecture.md
+# stay at `1` so backtraces and stepping still work (docs/ARCHITECTURE.md
 # §Cargo workspace, carried from RoboCAD).
 [profile.dev]
 opt-level = 1
 
+# `debug = false` for dependencies only: 93% of a debug binary was DWARF for
+# crates nobody steps through (596 MB → 39 MB stripped, measured 2026-09-06),
+# and cargo never collects the old copies, so `target/` reached 76 GB. Their
+# symbol names survive in backtraces — that is the symbol table, not debug
+# info — and our own crates above keep theirs in full.
 [profile.dev.package."*"]
 opt-level = 3
+debug = false
 
 # The wheel is the product (ADR-0002): its size is what `pip install` pulls
 # and its startup is what the user sees. Stripped, thin-LTO, one codegen
@@ -25,6 +31,21 @@ strip = true
 lto = "thin"
 codegen-units = 1
 
+# The web demo (ADR-0017, Architecture §The web build). What the browser
+# pays for
+# is the *download*, not the last few percent of throughput: `opt-level = "s"`
+# and fat LTO over the whole graph trade a little speed for a much smaller
+# `.wasm`, and the viewport still holds 60 fps (the demo's own status bar
+# says so). `panic = "abort"` is deliberately **not** here: eframe's panic
+# handler is what turns a crash into a page that says what happened
+# (`web/main.js`), and unwinding is how it gets the message.
+[profile.web]
+inherits = "release"
+opt-level = "s"
+lto = "fat"
+codegen-units = 1
+strip = true
+
 [workspace.dependencies]
 riggen-mesh = { path = "crates/riggen-mesh" }
 riggen-core = { path = "crates/riggen-core" }
@@ -45,6 +66,16 @@ stl_io = "0.11"
 # build, where it does not compile without a JS shim we have no use for.
 tobj = { version = "4", default-features = false, features = ["use_f64"] }
 
+# Approximate convex decomposition (ADR-0011): Dimforge's pure-Rust V-HACD,
+# `transformation::vhacd`, at f64 — the algorithm `riggen-mesh::decompose`
+# wraps beside our own quickhull. Default features: `default-features =
+# false` drops the crate's own `dim3`/`f64` selection and does not compile,
+# and the default set pulls neither `rayon` nor `serde`. Its `glamx` bridge
+# pins a third glam (0.33) beside our 0.30 and transform-gizmo's 0.32; no
+# parry or glam-0.33 type appears in a riggen signature (ADR-0007's
+# containment, applied again).
+parry3d-f64 = "0.30"
+
 # UI stack pinned together: egui/eframe/egui-wgpu 0.36.x from crates.io, wgpu
 # version dictated by egui-wgpu — never depend on a different wgpu (ADR-0001).
 egui = "0.36"
@@ -72,6 +103,11 @@ web-time = "1"
 # URDF parser: the round-trip FK test reads our own URDF back through it
 # (dev, step 6), and File › Import URDF… is built on it (step 13).
 urdf-rs = "0.9"
+# The XML pull parser behind `xml::parse`, the reading half of the MJCF
+# import (ADR-0015 §2). 0.36 is the version `urdf-rs` already compiles, so
+# this line adds a dependency and no crate. Escaping, CDATA and encodings
+# are exactly what the writer's `escape` must not have to invert by hand.
+quick-xml = "0.36"
 
 # The Python SDK's binding layer (ADR-0009). `abi3-py310`: one extension
 # module for every CPython ≥ 3.10 (`requires-python`), so the wheel matrix
@@ -80,6 +116,14 @@ urdf-rs = "0.9"
 # still links libpython and `cargo clippy --workspace` sees the crate.
 pyo3 = { version = "0.29", features = ["abi3-py310"] }
 
+# Writing the export directory as one file, which is what a browser
+# download is (ADR-0017 §6). `default-features = false`: no compression, no
+# encryption, no time crate — a stored zip is a header, the bytes and a
+# central directory, and the crate is here for the CRC-32 and the offsets,
+# not for an algorithm. Not gated to wasm: the acceptance test that reads
+# the archive back is native.
+zip = { version = "8", default-features = false }
+
 # Only to block on `Instance::enumerate_adapters` in the "is there a GPU at
 # all?" probe of the snapshot harness — `egui_kittest` panics rather than
 # reporting that itself.

{riggen-0.2.0 → riggen-0.2.1.dev0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: riggen
-Version: 0.2.0
+Version: 0.2.1.dev0
 Classifier: Development Status :: 3 - Alpha
 Classifier: Intended Audience :: Science/Research
 Classifier: Topic :: Scientific/Engineering
@@ -26,10 +26,23 @@ Project-URL: Repository, https://github.com/Divelix/riggen
 [![PyPI](https://img.shields.io/pypi/v/riggen)](https://pypi.org/project/riggen/)
 
 **The blazingly fast, lightweight robot assembler for RL researchers.**
-Drop meshes in, get a simulation-ready MJCF or URDF out — in a window, or
-from ten lines of Python.
+Drop meshes in, get a simulation-ready MJCF, URDF or SDF out — in a
+window, or from ten lines of Python.
 
-![The sample arm in riggen: the link tree, the viewport with joint glyphs, the Joints window](https://raw.githubusercontent.com/Divelix/riggen/main/docs/assets/arm.png)
+![The sample arm in riggen, opened in View: the joint tree with its scrubbers, the viewport with joint glyphs](https://raw.githubusercontent.com/Divelix/riggen/main/docs/assets/arm.png)
+
+## Try it in the browser
+
+**[divelix.github.io/riggen](https://divelix.github.io/riggen/)** — the real
+app, wasm, with the sample arm already in it. Orbit it, pose it from the
+joint tree or with the wheel over a joint, drop your own `.stl` / `.obj` / `.riggen` / `.urdf` / `.xml` onto
+the page, and Export to get the same MJCF, URDF and SDF the desktop writes,
+as one zip. Needs a browser with WebGPU (Chrome/Edge 113+, Firefox 141+,
+Safari 26+); the desktop app does not.
+
+Drop a document **together with its meshes** — the browser hands a page one
+flat set of files per drop and no directory, so a `.riggen` on its own can
+only tell you which meshes are missing.
 
 ## Install
 
@@ -47,16 +60,35 @@ without a wheel, `pip install` builds the SDK from source with `cargo` on
 
 ## The first minute
 
-1. `riggen --example arm` opens a four-part arm: link tree on the left,
-   the viewport in the middle, Properties on the right. Orbit with the
-   middle mouse button, zoom with the wheel, `Home` to frame everything.
-2. Drag the sliders in **Window › Joints** — the arm moves; that is the
-   kinematic tree you will build for your own robot.
-3. **File › Export…**, pick MJCF, choose a directory. The dialog lists
-   anything that would stop the export (a link with no mass, a joint with
-   no axis) and writes `arm.xml` beside `meshes/*.stl` when there is
+1. `riggen --example arm` opens a four-part arm in **View**: the joint
+   tree on the left, the viewport with the robot. Drag with the left
+   button to orbit and with the right to pan (shift+left pans too, for a
+   trackpad; the middle button orbits and shift+middle pans), zoom with the
+   wheel, `Home` to frame everything. The five buttons top-right are the
+   **visibility row**: joints, joint names, frames, links, collision
+   geometry. Switching one off takes it out of the picture *and* out of
+   the cursor's reach, so with joints off you get the robot and nothing
+   else — the status bar says what is hidden.
+2. Pose it: drag a joint's bar in the tree, or turn the wheel over it —
+   or over the joint's glyph in the viewport, which steps it by 5° (1°
+   with shift) instead of zooming. A click on a glyph selects the joint;
+   in View a mesh is not a thing to click. That is the kinematic tree you
+   will build for your own robot.
+3. `Tab` (or the **View | Edit** control top-left) switches to **Edit**:
+   the robot at its zero configuration, the link tree, Properties, and the
+   five tools on the toolbar with their keys — `V` select, `G` move, `R`
+   rotate, `J` place joint, `B` align, `Esc` back to select. With
+   **Rotate** up, the wheel over one of the gizmo's three rings steps that
+   ring by 5° — 1° with shift — instead of zooming; with **Move** up, a
+   drag snaps to the vertex, box corner or bore centre under the cursor,
+   looking through the part it is carrying. `Tab` again brings the pose
+   back.
+4. **File › Export…**, tick the formats you want (all three by default),
+   choose a directory. The dialog lists anything that would stop the
+   export (a link with no mass, a joint with no axis) and writes
+   `arm.xml`, `arm.urdf` and `arm.sdf` beside `meshes/*.stl` when there is
    nothing.
-4. Load it:
+5. Load it:
 
    ```sh
    python -c "import mujoco; m = mujoco.MjModel.from_xml_path('out/arm.xml'); print(m.nbody, 'bodies')"
@@ -69,20 +101,32 @@ link under the root (meters or millimetres — the import units are in the
 status bar). Reparent by dragging rows in the tree; **Place joint** puts a
 revolute joint on a bore by clicking its edge; **Align** snaps a part's
 bore concentric with its parent's; Properties computes the inertial from
-the mesh and a material, and fits a hull or primitives for collision.
+the mesh and a material, and fits a hull, convex pieces or primitives for
+collision. Every number there scrubs: drag it, step it with Ctrl+wheel,
+or click and type (`2.86e-5` reads and edits as written). **+ Frame** puts a named frame on a link — a TCP, a sensor
+mount — which Move and Rotate land on a picked feature the same way.
 
 ## What it does
 
 - **Assembles**: STL and OBJ meshes into a kinematic tree — fixed, revolute
-  and prismatic joints, placed by clicking geometry, with limits.
+  and prismatic joints, placed by clicking geometry, with limits — and
+  named frames (a TCP, a sensor mount) placed the same way.
 - **Computes**: mass, centre of mass and the inertia tensor from the mesh
-  and a material density, or from a spec you type; convex hulls and fitted
+  and a material density, or from a spec you type; convex hulls, convex
+  decomposition (V-HACD, so a C-bracket keeps its notch) and fitted
   boxes / cylinders / spheres for collision.
-- **Exports**: MJCF and URDF from the same document, meshes baked to
-  meters as STL, so MuJoCo loads it with zero warnings and its forward
-  kinematics agree with riggen's (that is a CI job, not a hope).
-- **Imports**: an existing URDF, `package://` paths resolved beside the
-  file, to fix and convert it.
+- **Exports**: MJCF, URDF and SDF from the same document, meshes baked to
+  meters as STL — a named frame becomes an MJCF `<site>`, an SDF
+  `<frame>`, and the massless dummy link ROS expects — so MuJoCo loads it
+  with zero warnings and libsdformat, the SDF spec's own parser, reads the
+  `.sdf`, and the forward kinematics of both agree with riggen's (those
+  are CI jobs, not hopes).
+- **Imports**: an existing URDF or MJCF — `package://` paths resolved
+  beside the file, MuJoCo's `<default>` classes and degrees understood, a
+  model spelled across several files opened through its main one
+  (`<include>` and MuJoCo 3's `<frame>` are resolved on the way in) — to
+  fix and convert it. Whatever the file held that the document cannot is
+  named, never dropped in silence.
 - **Stays out of the way**: a native window through wgpu, a document that
   is plain JSON (`.riggen`), undo for everything, and a headless CLI.
 
@@ -92,12 +136,12 @@ the mesh and a material, and fits a hull or primitives for collision.
 usage:
   riggen [FILE...]        open a .riggen document, or drop meshes (.stl, .obj) as links
   riggen --example arm    open the bundled sample arm
-  riggen --export mjcf|urdf|both --out DIR [--fk-samples] INPUT
+  riggen --export mjcf|urdf|sdf|both|all --out DIR [--fk-samples] INPUT
                           write INPUT's export to DIR without opening a window
 
 options:
   --example NAME          open a bundled example: arm (the five-link sample robot)
-  --export FORMAT         headless export of INPUT (.riggen or .urdf): mjcf, urdf or both
+  --export FORMAT         headless export of INPUT (.riggen, .urdf or .xml): mjcf, urdf, sdf, both or all
   --out DIR               where --export writes; created if missing
   --fk-samples            with --export: also write <name>.fk.json, five sampled joint configurations
   --timing                print the time from launch to the first frame on stderr
@@ -106,9 +150,11 @@ options:
 ```
 
 `riggen --export` needs no display, so it runs in CI and in scripts: give
-it a `.riggen` or a `.urdf` and it writes the model, the meshes and, with
+it a `.riggen`, a `.urdf` or an MJCF `.xml` and it writes the model or
+models, the meshes and, with
 `--fk-samples`, five joint configurations with every body's world pose —
-the file `python/tests/test_mjcf_load.py` checks MuJoCo against.
+the file `python/tests/test_mjcf_load.py` checks MuJoCo against and
+`python/tests/test_sdf_load.py` checks libsdformat against.
 
 `python -m riggen` is the same executable, for an environment whose
 `bin/` is not on `PATH`.
@@ -145,6 +191,7 @@ radians, Z-up; `degrees=True` wherever an angle is typed.
 robot.fk({"arm_joint": 0.3})["arm"]                   # Pose((0.0, 0.0, 0.5), rpy=(0.0, 0.3, 0.0))
 arm.inertial                                          # Inertial(mass=…, com=…, inertia=…) from the mesh
 robot.link("arm").joint.limits = (-1.0, 1.0)          # radians; one edit
+robot.link("arm").add_frame("tcp", (0, 0, 0.3))       # an MJCF <site>; frame.world(q) for its pose
 robot.save("pendulum.riggen")                         # the window opens this file
 ```
 
@@ -163,9 +210,11 @@ model = mujoco.MjModel.from_xml_path("out/pendulum.xml")
 ```
 
 `riggen.load(path)` reads a `.riggen`, `riggen.load_urdf(path)` an existing
-URDF (with `packages={"name": "dir"}` for `package://` paths); export writes
-`format="urdf"` or `"both"` too, and `fk_samples=True` adds the five joint
-configurations CI compares against MuJoCo. [`examples/pendulum.py`](examples/pendulum.py)
+URDF (with `packages={"name": "dir"}` for `package://` paths) and
+`riggen.load_mjcf(path)` an MJCF; `format` names a set of writers —
+`"mjcf"`, `"urdf"`, `"sdf"`, `"both"` or `"all"`, the default — and
+`fk_samples=True` adds the five joint configurations CI compares against
+MuJoCo and libsdformat. [`examples/pendulum.py`](examples/pendulum.py)
 is the snippet above as a file; [`examples/arm.py`](examples/arm.py) builds
 the bundled arm from its four STLs with typed joints — its export is
 byte-identical to the app's. Everything is typed (`py.typed`) and
@@ -228,9 +277,9 @@ https://github.com/Divelix/riggen riggen-app`; publishing the workspace to
 crates.io so that `cargo install riggen` works is a later release.
 
 Read, in order: [`SEED.md`](SEED.md) (what and why),
-[`docs/01-architecture.md`](docs/01-architecture.md),
-[`docs/02-data-model.md`](docs/02-data-model.md),
-[`docs/03-roadmap.md`](docs/03-roadmap.md), [`docs/adr/`](docs/adr/) — then
+[`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md),
+[`docs/DATA-MODEL.md`](docs/DATA-MODEL.md),
+[`docs/ROADMAP.md`](docs/ROADMAP.md), [`docs/adr/`](docs/adr/) — then
 [`AGENTS.md`](AGENTS.md) for the rules, agent or human. The SDK's own
 tests are `python/tests/sdk/` (pytest, against the built wheel).