diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index d3b01c62c..55bfb4c99 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -72,7 +72,7 @@ desktop integration and how to distinguish an old executable on `PATH`.
## How the code is laid out
-The [README](README.md#architecture) has the layer table. The short version:
+The [architecture page](docs/architecture.md) has the layer table. The short version:
- `crates/geom`: vectors, planes, meshes, measures.
- `crates/sketch`: our own constraint solver, plus profile finding.
diff --git a/README.md b/README.md
index 5229cdd14..802132430 100644
--- a/README.md
+++ b/README.md
@@ -46,281 +46,65 @@
## Download
-- **Windows:** download and run the [installer][windows-msi].
- Also for [ARM64][windows-arm64-msi] and [32-bit][windows-x86-msi] PCs, or as a
- [portable zip][windows-portable] that runs without installing.
- With [WinGet](https://learn.microsoft.com/windows/package-manager/winget/):
- `winget install bherbruck.SolidCraft`.
-- **macOS:** open the [disk image][macos-dmg] and drag SolidCraft into Applications
- (Apple silicon and Intel).
-- **Linux:** download the [AppImage][linux-appimage], allow it to run as a program and open it.
- Or install the [.deb][linux-deb] (Ubuntu, Debian, Mint) or [.rpm][linux-rpm] (Fedora,
- openSUSE), or use [Flatpak](https://docs.solidcraft.io/guide/getting-started.html#linux-flatpak).
- With Snap: `sudo snap install solidcraft` ([Snap Store][snap-store], or the [.snap file][linux-snap]).
- For ARM64: [AppImage][linux-arm64-appimage], [.deb][linux-arm64-deb], [.rpm][linux-arm64-rpm].
+- **Windows:** the [installer][windows-msi], or `winget install bherbruck.SolidCraft`.
+- **macOS:** the [disk image][macos-dmg] (Apple silicon and Intel).
+- **Linux:** the [AppImage][linux-appimage], or `sudo snap install solidcraft` ([Snap Store][snap-store]).
- **Web:** [try it in your browser][web-app], no install.
-The downloads aren't signed yet. On Windows, if SmartScreen warns you, choose **More info**, then
-**Run anyway**. On macOS, the first time, right-click SolidCraft in Applications and choose **Open**.
-
-**On SolidCraft 0.11 to 0.14?** Its **Update now** can't install 0.15.0 or later, because the
-releases moved to a new address. Download the new version once from the links above; after that,
-updating from inside SolidCraft works again ([details](https://docs.solidcraft.io/guide/updates.html#updating-from-011-to-014)).
-
-Older versions, checksums and other formats are on the [releases page](https://github.com/tangency-labs/solidcraft/releases).
-Install details, upgrading from earlier builds and building from source are in
-[Getting started](https://docs.solidcraft.io/guide/getting-started.html).
-
-[badge-windows]: https://img.shields.io/badge/Windows-Download-0078D6?style=for-the-badge&logo=data%3Aimage%2Fsvg%2Bxml%3Bbase64%2CPHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHZpZXdCb3g9IjAgMCAyNCAyNCIgZmlsbD0id2hpdGUiPjxwYXRoIGQ9Ik0yIDJoOS41djkuNUgyek0xMi41IDJIMjJ2OS41aC05LjV6TTIgMTIuNWg5LjVWMjJIMnpNMTIuNSAxMi41SDIyVjIyaC05LjV6Ii8%2BPC9zdmc%2B
-[badge-macos]: https://img.shields.io/badge/macOS-Download-333333?style=for-the-badge&logo=apple&logoColor=white
-[badge-linux]: https://img.shields.io/badge/Linux-AppImage-E95420?style=for-the-badge&logo=linux&logoColor=white
-[badge-snap]: https://img.shields.io/badge/Snap-Snap_Store-82BEA0?style=for-the-badge&logo=snapcraft&logoColor=white
-[badge-web]: https://img.shields.io/badge/Web-Try_in_browser-2EA44F?style=for-the-badge&logo=data%3Aimage%2Fsvg%2Bxml%3Bbase64%2CPHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHZpZXdCb3g9IjAgMCAyNCAyNCIgZmlsbD0ibm9uZSIgc3Ryb2tlPSJ3aGl0ZSIgc3Ryb2tlLXdpZHRoPSIyIj48Y2lyY2xlIGN4PSIxMiIgY3k9IjEyIiByPSIxMCIvPjxwYXRoIGQ9Ik0yIDEyaDIwTTEyIDJhMTUgMTUgMCAwIDEgMCAyME0xMiAyYTE1IDE1IDAgMCAwIDAgMjAiLz48L3N2Zz4%3D
-[windows-msi]: https://github.com/tangency-labs/solidcraft/releases/latest/download/solidcraft-windows-x64.msi
-[windows-arm64-msi]: https://github.com/tangency-labs/solidcraft/releases/latest/download/solidcraft-windows-arm64.msi
-[windows-x86-msi]: https://github.com/tangency-labs/solidcraft/releases/latest/download/solidcraft-windows-x86.msi
-[windows-portable]: https://github.com/tangency-labs/solidcraft/releases/latest/download/solidcraft-windows-x64-portable.zip
-[macos-dmg]: https://github.com/tangency-labs/solidcraft/releases/latest/download/solidcraft-macos-universal.dmg
-[linux-appimage]: https://github.com/tangency-labs/solidcraft/releases/latest/download/solidcraft-linux-x86_64.AppImage
-[linux-deb]: https://github.com/tangency-labs/solidcraft/releases/latest/download/solidcraft-linux-x86_64.deb
-[linux-rpm]: https://github.com/tangency-labs/solidcraft/releases/latest/download/solidcraft-linux-x86_64.rpm
-[linux-arm64-appimage]: https://github.com/tangency-labs/solidcraft/releases/latest/download/solidcraft-linux-aarch64.AppImage
-[linux-arm64-deb]: https://github.com/tangency-labs/solidcraft/releases/latest/download/solidcraft-linux-aarch64.deb
-[linux-arm64-rpm]: https://github.com/tangency-labs/solidcraft/releases/latest/download/solidcraft-linux-aarch64.rpm
-[linux-snap]: https://github.com/tangency-labs/solidcraft/releases/latest/download/solidcraft-linux-x86_64.snap
-[snap-store]: https://snapcraft.io/solidcraft
-[web-app]: https://solidcraft.io/app
-
-**Documentation:** the [SolidCraft book](https://docs.solidcraft.io/) (user guide,
-developer guide and command reference; sources in [docs/book](docs/book)).
-
-**Community:** chat with users and contributors on [Discord](https://discord.gg/FtU4NQNVDH).
-
-**Status: early but usable for simple parts.** 75 of 76 public reference parts
-match their analytic or FreeCAD-computed volume, area, centre of mass and bounding box
-([docs/oracle.md](docs/oracle.md)); the other is a tracked bug.
-These checks do not establish complete geometric or workflow equivalence. The commands SolidCraft has
-are listed by area in [docs/features.md](docs/features.md); status and plans are in [ROADMAP.md](ROADMAP.md).
-Open work and known bugs are in [GitHub issues](https://github.com/tangency-labs/solidcraft/issues),
-and help is welcome: see [CONTRIBUTING.md](CONTRIBUTING.md).
-
-## Built with SolidCraft
-
-
-
-*SELENE, a scientific rover built entirely through SolidCraft's MCP server by
-[@0xlillith](https://github.com/0xlillith/solidcraft-rover): 3,323 editable timeline steps that
-rebuild with no errors, replayed here at 2× speed.
-[Full video](https://github.com/tangency-labs/solidcraft/raw/refs/heads/main/docs/screenshots/rover-build.mp4)
-· [download the editable model](https://github.com/0xlillith/solidcraft-rover/releases/tag/v1.0.0).*
+ARM64 and 32-bit builds, portable zip, .deb, .rpm, Flatpak and the other packages are on the
+[downloads page](docs/downloads.md). The downloads aren't signed yet: on Windows choose
+**More info**, then **Run anyway** in SmartScreen; on macOS right-click SolidCraft and choose **Open**
+the first time. On SolidCraft 0.11 to 0.14, download once by hand; see
+[updating](https://docs.solidcraft.io/guide/updates.html#updating-from-011-to-014).
## What works
-- **Current-view DXF export** from File → Export Current View as DXF, with hidden edges
- omitted or dashed, shown body placements and the current camera. See [view DXF](docs/view-dxf.md).
+Early but usable for simple parts: 75 of 76 public reference parts match their analytic or
+FreeCAD-computed volume, area, centre of mass and bounding box ([oracle](docs/oracle.md)); the
+other is a tracked bug.
-- **Sketches** on origin planes, offset planes or planar faces: lines, rectangles, circles,
- arcs, polygons, slots, ellipses, fit/control splines, conics and text; construction geometry,
- projection, trimming, fillets and chamfers, including corners at the origin.
- New face attachments retain supported construction identities and chosen occurrences;
- missing sources expose an explicit plane repair workflow. See [face attachments](docs/face-attachments.md).
- Explicitly closed fit splines and closed associative offsets use periodic C2 interpolation.
- Supported convex line-and-arc offsets retain their identity when an inset consumes corner
- arcs, and linked extrusions follow the current boundary. Breaking the association freezes
- the boundary and keeps existing extrusions usable.
- Curve drawing and picking adapt together to zoom and display scale, including small circles
- at Fit and sketches in placed components.
-- **Constraints and dimensions** solved by our own solver. Points the constraints fix relative
- to known geometry are placed exactly by construction (loci intersections and rigid-cluster
- decomposition, after Owen 1991 and Fudos–Hoffmann 1997); Levenberg–Marquardt solves the rest,
- and the rank of its Jacobian gives the remaining degrees of freedom. Constraints: coincident,
- point on curve, horizontal/vertical, parallel, perpendicular, tangent, curvature (G2), equal,
- concentric, collinear, midpoint, symmetry, fix; linear, aligned, horizontal, vertical,
- point-to-line, radius, diameter, angle, arc sweep, arc length and slot length dimensions driven
- by parameters. Over-constraining edits are rejected; fully constrained geometry turns black.
- Dragging solves the sketch every frame and rebuilds the model once, when the drag ends.
- Select a line or its two endpoints, type its dimension and press Enter to commit one undo
- step; with Sketch Dimension it's D, click, type, Enter. Fit keeps sketch geometry clear of the palette and navigation controls.
-- **Profiles** found automatically, including regions split by lines and holes inside outlines.
- Newly captured complete adaptive boundaries retain their outer and hole source identities
- when spline span counts change. Partial or ambiguous boundaries do not qualify.
-- **Features** on a parametric timeline: extrude, revolve, sweep, loft, fillet/chamfer,
- shell, draft, holes, threads, patterns, mirror, split, combine, move and construction geometry.
- The timeline rebuilds incrementally; features can be edited, suppressed, renamed, reordered
- and deleted. Supported geometry and current limitations are described in [ROADMAP.md](ROADMAP.md).
- New revolves preserve symmetric and two-sided angular placement across reversed axes;
- older designs retain their saved convention when reopened or edited.
-- **Parameters and configurations** with unit-aware expressions (`2 * width + 5 mm`,
- `angle / 2`), ordered rules, feature suppression and per-row body materials/appearances.
-- **Assemblies** with nested components and occurrences, joints, motion studies, contact sets,
- interference and material-aware mass properties. Recorded body transfers preserve modelling
- history and world placement; 3D sketch wires retain their coordinate frames through edits.
-- **Sheet metal** with flanges, hems, fold/unfold/refold, material cutouts, flat patterns,
- retained shallow prismatic pockets, exact line/arc/circle DXF outlines and bend tables;
- plastic enclosure features and rules. Pocket depth and side survive unfold/refold and appear
- separately from through-hole outlines in the flat preview and DXF.
-- **Files**: design containers (`.solidcraft`) with lossless binary mesh payloads;
- plain JSON remains supported for opening, Save As and export. Desktop Open can show a saved
- provisional picture from warm geometry caches while rebuilding before editing; caches never
- replace the parametric design. Export to STEP (AP242 with body names, colours and
- components as assemblies; revolved faces as native planes, cylinders, cones, spheres and tori),
- IGES 5.3 (manifold solid B-reps with names and colours), 3MF, STL (binary/ASCII) and OBJ, and
- assemblies with joints as URDF for robot simulators (docs/urdf.md);
- 3MF, STL, OBJ and glTF 2.0 (`.glb`/`.gltf`, its node tree as components and its materials as
- appearances) import as mesh bodies (they render, measure, move and export; solid features
- need B-rep bodies). The `mesh.convert` command reconstructs supported closed constant-section parts
- as parametric solids with planar and circular cylindrical faces;
- STEP import (AP203/AP214/AP242 solids, assemblies, units, names, colours) and IGES import
- (manifold solid B-reps, or trimmed and bounded surfaces sewn into solids) as a base feature
- that later features build on — open a `.step`/`.stp`/`.igs`/`.iges` file, insert one into a
- design, or drop it on the window ([docs/step-import.md](docs/step-import.md)); FreeCAD
- `.FCStd` and Rhino `.3dm` solids import the same way through
- [cadmpeg](https://github.com/cadmpeg/cadmpeg) in the desktop app and CLI.
-- **Render:** opaque surfaces can use metal fraction, roughness and dielectric IOR in the
- integrated product viewport and CPU preview PNGs. Existing simple colors remain supported.
- Fixed direct lighting is a preview; HDRI, refraction and texture maps are not implemented.
- See [opaque surfaces](docs/render-opaque-pbr.md).
-- **Display meshes** from our own tessellation planner: each face becomes a plan of (u, v)
- points and triangles that shares its edge nodes with its neighbours, so the mesh is watertight.
- Facets follow the chord tolerance, the facet angle and a longest side, with cells at most 2:1
- along straight directions. Box-bounded and four-cornered faces mesh as structured grids.
- Trimmed faces are cut into four-sided patches: squares around holes, butterflies in round
- faces, motorcycle traces from concave corners (after Lyon et al. 2019). Each patch then meshes
- as a Coons grid. Intersection edges are evaluated by Newton on both surfaces. A compute shader
- evaluates the plans for the whole scene in one dispatch, with a CPU fallback when the GPU
- can't build it. Planning and evaluating the 78 reference bodies takes about 65 ms, 50–65×
- faster than the previous mesher.
-- **Desktop app** (egui + wgpu): toolbar with workspace tabs, browser, timeline, 3D viewport with
- axis view and navigation bar, sketch tools, feature dialogs, command palette, and a JSON-lines
- control channel so agents and tests can drive it.
- Feature errors and Help can open an editable **Create Issue** draft with relevant context
- and an optional reviewed screenshot; opening GitHub does not submit the report.
-- **Headless CLI** `solidcraft-cli`: run command scripts, measure (volume, area, centre of mass,
- face/edge/vertex counts), export, render PNG snapshots and replay reference recipes.
- A snapshot can draw a body see-through and another solid in a colour of its own, and cut
- the model at a plane, so a picture shows the body a cut would remove inside the material
- it meets.
-- **MCP server** `solidcraft-cli mcp`: AI agents model, measure and look at parts headless or
- in the running app (see below).
+- **Sketches and constraints:** lines, arcs, splines, text and more, solved by our own constraint solver, with parameter-driven dimensions.
+- **Features:** extrude, revolve, sweep, loft, fillet, chamfer, shell, draft, holes, threads, patterns, mirror, split and combine on an editable parametric timeline.
+- **Parameters and configurations** with unit-aware expressions.
+- **Assemblies** with joints, motion studies, contact sets, interference and mass properties.
+- **Sheet metal** with flanges, hems, fold/unfold and flat patterns, and plastic enclosure features.
+- **Files:** STEP, IGES, 3MF, STL, OBJ and glTF in and out where supported, URDF export, `.solidcraft` designs.
+- **Desktop app, browser app, headless CLI and MCP server**, all running the same commands.
-## Build and run
+The full list is in [docs/capabilities.md](docs/capabilities.md) and [docs/features.md](docs/features.md);
+status and plans are in [ROADMAP.md](ROADMAP.md). See also [what people built](docs/showcase.md),
+[3D mouse support](docs/3d-mouse.md) and the [architecture](docs/architecture.md).
+
+## Build from source
```sh
-cargo run --release -p solidcraft -- --sample # desktop app with a sample part
-cargo run --release -p solidcraft-cli -- commands # the command registry
+cargo run --release -p solidcraft -- --sample # desktop app with a sample part
+cargo run --release -p solidcraft-cli -- commands # the command registry
cargo run --release -p solidcraft-cli -- run examples/bracket.json --out bracket.step
-cargo run --release -p solidcraft-cli -- snapshot examples/bracket.json --out bracket.png
-cargo run --release -p solidcraft-cli -- snapshot part.solidcraft --out preview.png --tool Pin --section z=12
-cargo run --release -p solidcraft-cli -- render examples/render-studio.json --out product.png
-cargo run --release -p solidcraft -- part.step # open a STEP file as a new design
-cargo run --release -p solidcraft-cli -- eval part.step # measure an imported STEP file
-cargo xtask ci # fmt, clippy, tests, icons, assets, layers, wasm
+cargo xtask ci # fmt, clippy, tests, icons, assets, layers, wasm
```
-UI artwork changes follow the [icon specification](assets/icons/ui/STYLE_GUIDE.md).
-The [included review tool](assets/icons/ui/README.md) discovers new icons and keeps
-unaccepted artwork Open; run `cargo xtask icons` to check the collection.
-
-Windows builds: `cargo xwin build --release --target x86_64-pc-windows-msvc -p solidcraft`.
-
-On Windows, macOS and Linux, SolidCraft detects a connected 3D mouse through its HID multi-axis
-controller interface: a 3Dconnexion SpaceNavigator or SpaceMouse, or a homemade device that
-declares itself one. Move the cap to pan and zoom, and tilt or twist it to rotate the 3D view.
-While editing a sketch, the cap pans and zooms without changing the sketch view. The Navigation
-page in Preferences has an on/off switch, a speed control and, for each of the cap's six axes, an
-invert switch and a speed for the 3D mouse. The web app reads
-it too, through the browser; Firefox needs a 3DxWare setting first (see
-[Getting started › 3D mouse in the browser](docs/book/src/guide/getting-started.md#3d-mouse-in-the-browser)).
-
-With 3DxWare on Windows, SolidCraft follows 3DxWare's profile for it when there is one, and
-3DxWare's object mode (tilt to roll, twist to spin) until there is. The mouse-wheel turns that
-3DxWare makes from the cap's motion are ignored, so the view doesn't zoom in steps as the cap tilts.
-
-On Linux SolidCraft reads the 3D mouse through `spacenavd` when that daemon runs (its socket
-`/var/run/spnav.sock`), so what you set in `spnavcfg` (swapped or inverted axes, sensitivity, dead
-zones) applies as it does in other programs, and no udev rule is needed. With nothing set there,
-the motion is the same as without the daemon. Without `spacenavd`, SolidCraft reads `/dev/hidrawN`
-directly, so the logged-in user needs access to the device. A udev rule that adds the `uaccess`
-tag does that, for example
-`/etc/udev/rules.d/70-3d-mouse.rules` for USB devices with 3Dconnexion's vendor id, and for its
-Bluetooth ones (where `idVendor` isn't set, so the HID id is matched instead):
-
-```
-SUBSYSTEM=="hidraw", ATTRS{idVendor}=="256f", TAG+="uaccess"
-SUBSYSTEM=="hidraw", KERNELS=="0005:256F:*", TAG+="uaccess"
-```
-
-Older SpaceNavigators use Logitech's vendor id `046d`, so add a rule with their product id (see
-`lsusb`) instead of matching every Logitech device. A homemade device needs a rule with its own
-vendor and product id. Reload with `sudo udevadm control --reload && sudo udevadm trigger`, then
-replug the device. The Flatpak sandbox does not expose hidraw devices, so the 3D mouse only works
-with native builds there for now.
-
-SolidCraft finds the axes from the device's report descriptor, so it doesn't matter how a device
-lays them out: translation and rotation in separate reports (3Dconnexion's wired devices), all six
-in one (its wireless ones and most homemade devices), after the buttons, or narrower than 16 bits.
-Each axis is scaled from the range the descriptor declares.
-
-On macOS SolidCraft talks to the 3Dconnexion driver (3DxWare) when it is installed, through the
-driver's client API (`crates/threedx-client`; the framework is loaded at run time, never bundled).
-The driver keeps the device to itself, and sends it only to a program it can identify: SolidCraft
-as an `.app` (the packaged app). Without the driver, or with its helper not running, SolidCraft reads the device through IOKit like on Windows.
-
-SolidCraft does not follow 3DxWare's profile on macOS. Its default is 3DxWare's object mode.
-
-In the browser: `cd apps/solidcraft-web && trunk build --release --public-url ./` (WebGPU, or
-WebGL2 with `?webgl`; `?sample` opens the sample part).
-
-Agents can control the document open in a browser tab through `window.solidcraft.execute(...)`
-and `window.solidcraft.request(...)`; see the [browser command API](docs/browser-api.md).
-
-## Scripts
-
-A script is a JSON list of commands, the same ones the UI runs:
-
-```json
-{"commands": [
- {"command": "sketch.create", "params": {"plane": "XY"}},
- {"command": "sketch.rectangle.two_point", "params": {"p0": [0, 0], "p1": [40, 30]}},
- {"command": "solid.extrude", "params": {"distance": 20}},
- {"command": "solid.fillet", "params": {"edges": [[0, 0, 10]], "radius": 3}}
-]}
-```
+More commands, the Windows cross-build and the browser build are in [docs/building.md](docs/building.md).
## AI agents (MCP)
-`solidcraft-cli mcp` is a [Model Context Protocol](https://modelcontextprotocol.io) server on
-stdio. Headless it runs its own design session; with `--connect 127.0.0.1:PORT` it drives the app
-started with `solidcraft --control PORT`, so you can watch the agent model. Tools:
-`list_commands`, `execute`, `batch`, `inspect_design`, `measure`, `body_topology`,
-`set_parameter`, `screenshot` (returns the image), `export`, `crash_reports`, `undo`, `redo`,
-`new_design`, `open`, `save`. Tool calls reach files only in the open design's folder (when it lies inside your home
-folder, never home itself or a hidden folder), SolidCraft's recovery folder and folders given with
-`--allow-path DIR`. Claude Code: `claude mcp add solidcraft -- solidcraft-cli mcp`. Details, client
-configuration and an example session: [docs/mcp.md](docs/mcp.md).
+`solidcraft-cli mcp` is a [Model Context Protocol](https://modelcontextprotocol.io) server. Headless it
+runs its own design session, or with `--connect` it drives the running app so you can watch.
+Claude Code: `claude mcp add solidcraft -- solidcraft-cli mcp`. Tools, access rules and an
+example session: [docs/mcp.md](docs/mcp.md).
-## Architecture
+## Scripts
-
-| Layer | Crates | Role |
-|---|---|---|
-| L0 | `geom` | vectors, planes, profiles, meshes and their measures |
-| L1 | `sketch`, `kernel`, `render` | constraint solver and profiles; the B-rep kernel boundary (truck); view math and the headless scene description |
-| L2 | `doc` | parameters, expressions, the feature timeline and its incremental evaluation |
-| L3 | `io` | design files, STL/OBJ/STEP/3MF export, STEP and 3MF/STL/OBJ/glTF import features |
-| L4 | `engine` | the session and the command registry (everything is a command) |
-| L5 | `gpu`, `ui-egui`, `mcp` | compute-shader evaluation of display tessellation plans; the swappable desktop front end; the MCP server (headless or bridged to the app) |
-| apps | `solidcraft`, `solidcraft-cli` | desktop app, headless CLI |
-
+A script is a JSON list of the same commands the UI runs, executed with `solidcraft-cli run`.
+Format and example: [docs/scripts.md](docs/scripts.md). Pages can also be driven through the
+[browser command API](docs/browser-api.md).
## Contributing
-SolidCraft uses a familiar parametric CAD workflow: constrained
-sketches, solid features, an editable timeline, parameters and assemblies. See the
-[roadmap](ROADMAP.md) for supported operations and current limitations.
-
-See [CONTRIBUTING.md](CONTRIBUTING.md): how to build and test, the code map, the clean-room
-and licence rules, and where help is wanted most.
+Help is welcome. [CONTRIBUTING.md](CONTRIBUTING.md) covers how to build and test, the code map,
+the clean-room and licence rules, and where help is wanted most. Open work is in
+[GitHub issues](https://github.com/tangency-labs/solidcraft/issues); chat is on
+[Discord](https://discord.gg/FtU4NQNVDH).
## Sponsors
@@ -337,3 +121,14 @@ SolidCraft is independent. Behaviour is designed from public documentation, gene
conventions and user feedback. Reference tests use analytic values and open-source tools.
SolidCraft is not affiliated with, sponsored by or endorsed by Autodesk. Autodesk and
Fusion are trademarks of Autodesk, Inc.
+
+[badge-windows]: https://img.shields.io/badge/Windows-Download-0078D6?style=for-the-badge&logo=data%3Aimage%2Fsvg%2Bxml%3Bbase64%2CPHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHZpZXdCb3g9IjAgMCAyNCAyNCIgZmlsbD0id2hpdGUiPjxwYXRoIGQ9Ik0yIDJoOS41djkuNUgyek0xMi41IDJIMjJ2OS41aC05LjV6TTIgMTIuNWg5LjVWMjJIMnpNMTIuNSAxMi41SDIyVjIyaC05LjV6Ii8%2BPC9zdmc%2B
+[badge-macos]: https://img.shields.io/badge/macOS-Download-333333?style=for-the-badge&logo=apple&logoColor=white
+[badge-linux]: https://img.shields.io/badge/Linux-AppImage-E95420?style=for-the-badge&logo=linux&logoColor=white
+[badge-snap]: https://img.shields.io/badge/Snap-Snap_Store-82BEA0?style=for-the-badge&logo=snapcraft&logoColor=white
+[badge-web]: https://img.shields.io/badge/Web-Try_in_browser-2EA44F?style=for-the-badge&logo=data%3Aimage%2Fsvg%2Bxml%3Bbase64%2CPHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHZpZXdCb3g9IjAgMCAyNCAyNCIgZmlsbD0ibm9uZSIgc3Ryb2tlPSJ3aGl0ZSIgc3Ryb2tlLXdpZHRoPSIyIj48Y2lyY2xlIGN4PSIxMiIgY3k9IjEyIiByPSIxMCIvPjxwYXRoIGQ9Ik0yIDEyaDIwTTEyIDJhMTUgMTUgMCAwIDEgMCAyME0xMiAyYTE1IDE1IDAgMCAwIDAgMjAiLz48L3N2Zz4%3D
+[windows-msi]: https://github.com/tangency-labs/solidcraft/releases/latest/download/solidcraft-windows-x64.msi
+[macos-dmg]: https://github.com/tangency-labs/solidcraft/releases/latest/download/solidcraft-macos-universal.dmg
+[linux-appimage]: https://github.com/tangency-labs/solidcraft/releases/latest/download/solidcraft-linux-x86_64.AppImage
+[snap-store]: https://snapcraft.io/solidcraft
+[web-app]: https://solidcraft.io/app
diff --git a/docs/3d-mouse.md b/docs/3d-mouse.md
new file mode 100644
index 000000000..383da9294
--- /dev/null
+++ b/docs/3d-mouse.md
@@ -0,0 +1,46 @@
+# 3D mouse
+
+On Windows, macOS and Linux, SolidCraft detects a connected 3D mouse through its HID multi-axis
+controller interface: a 3Dconnexion SpaceNavigator or SpaceMouse, or a homemade device that
+declares itself one. Move the cap to pan and zoom, and tilt or twist it to rotate the 3D view.
+While editing a sketch, the cap pans and zooms without changing the sketch view. The Navigation
+page in Preferences has an on/off switch, a speed control and, for each of the cap's six axes, an
+invert switch and a speed for the 3D mouse. The web app reads
+it too, through the browser; Firefox needs a 3DxWare setting first (see
+[Getting started › 3D mouse in the browser](book/src/guide/getting-started.md#3d-mouse-in-the-browser)).
+
+With 3DxWare on Windows, SolidCraft follows 3DxWare's profile for it when there is one, and
+3DxWare's object mode (tilt to roll, twist to spin) until there is. The mouse-wheel turns that
+3DxWare makes from the cap's motion are ignored, so the view doesn't zoom in steps as the cap tilts.
+
+On Linux SolidCraft reads the 3D mouse through `spacenavd` when that daemon runs (its socket
+`/var/run/spnav.sock`), so what you set in `spnavcfg` (swapped or inverted axes, sensitivity, dead
+zones) applies as it does in other programs, and no udev rule is needed. With nothing set there,
+the motion is the same as without the daemon. Without `spacenavd`, SolidCraft reads `/dev/hidrawN`
+directly, so the logged-in user needs access to the device. A udev rule that adds the `uaccess`
+tag does that, for example
+`/etc/udev/rules.d/70-3d-mouse.rules` for USB devices with 3Dconnexion's vendor id, and for its
+Bluetooth ones (where `idVendor` isn't set, so the HID id is matched instead):
+
+```
+SUBSYSTEM=="hidraw", ATTRS{idVendor}=="256f", TAG+="uaccess"
+SUBSYSTEM=="hidraw", KERNELS=="0005:256F:*", TAG+="uaccess"
+```
+
+Older SpaceNavigators use Logitech's vendor id `046d`, so add a rule with their product id (see
+`lsusb`) instead of matching every Logitech device. A homemade device needs a rule with its own
+vendor and product id. Reload with `sudo udevadm control --reload && sudo udevadm trigger`, then
+replug the device. The Flatpak sandbox does not expose hidraw devices, so the 3D mouse only works
+with native builds there for now.
+
+SolidCraft finds the axes from the device's report descriptor, so it doesn't matter how a device
+lays them out: translation and rotation in separate reports (3Dconnexion's wired devices), all six
+in one (its wireless ones and most homemade devices), after the buttons, or narrower than 16 bits.
+Each axis is scaled from the range the descriptor declares.
+
+On macOS SolidCraft talks to the 3Dconnexion driver (3DxWare) when it is installed, through the
+driver's client API (`crates/threedx-client`; the framework is loaded at run time, never bundled).
+The driver keeps the device to itself, and sends it only to a program it can identify: SolidCraft
+as an `.app` (the packaged app). Without the driver, or with its helper not running, SolidCraft reads the device through IOKit like on Windows.
+
+SolidCraft does not follow 3DxWare's profile on macOS. Its default is 3DxWare's object mode.
diff --git a/docs/architecture.md b/docs/architecture.md
new file mode 100644
index 000000000..d0e93cc62
--- /dev/null
+++ b/docs/architecture.md
@@ -0,0 +1,13 @@
+# Architecture
+
+
+| Layer | Crates | Role |
+|---|---|---|
+| L0 | `geom` | vectors, planes, profiles, meshes and their measures |
+| L1 | `sketch`, `kernel`, `render` | constraint solver and profiles; the B-rep kernel boundary (truck); view math and the headless scene description |
+| L2 | `doc` | parameters, expressions, the feature timeline and its incremental evaluation |
+| L3 | `io` | design files, STL/OBJ/STEP/3MF export, STEP and 3MF/STL/OBJ/glTF import features |
+| L4 | `engine` | the session and the command registry (everything is a command) |
+| L5 | `gpu`, `ui-egui`, `mcp` | compute-shader evaluation of display tessellation plans; the swappable desktop front end; the MCP server (headless or bridged to the app) |
+| apps | `solidcraft`, `solidcraft-cli` | desktop app, headless CLI |
+
diff --git a/docs/book/src/dev/architecture.md b/docs/book/src/dev/architecture.md
index 61912142a..72f03d2c6 100644
--- a/docs/book/src/dev/architecture.md
+++ b/docs/book/src/dev/architecture.md
@@ -3,7 +3,7 @@
SolidCraft is a Cargo workspace in layers. A crate only depends on crates in lower layers, and
`cargo xtask layers` fails the build otherwise.
-{{#include ../../../../README.md:architecture}}
+{{#include ../../../architecture.md:architecture}}
The web app, `apps/solidcraft-web`, is the desktop front end compiled to wasm with
[trunk](https://trunkrs.dev). `xtask` holds the repository's own tooling: `cargo xtask ci`,
diff --git a/docs/building.md b/docs/building.md
new file mode 100644
index 000000000..3548b5d9f
--- /dev/null
+++ b/docs/building.md
@@ -0,0 +1,28 @@
+# Building and running
+
+```sh
+cargo run --release -p solidcraft -- --sample # desktop app with a sample part
+cargo run --release -p solidcraft-cli -- commands # the command registry
+cargo run --release -p solidcraft-cli -- run examples/bracket.json --out bracket.step
+cargo run --release -p solidcraft-cli -- snapshot examples/bracket.json --out bracket.png
+cargo run --release -p solidcraft-cli -- snapshot part.solidcraft --out preview.png --tool Pin --section z=12
+cargo run --release -p solidcraft-cli -- render examples/render-studio.json --out product.png
+cargo run --release -p solidcraft -- part.step # open a STEP file as a new design
+cargo run --release -p solidcraft-cli -- eval part.step # measure an imported STEP file
+cargo xtask ci # fmt, clippy, tests, icons, assets, layers, wasm
+```
+
+UI artwork changes follow the [icon specification](../assets/icons/ui/STYLE_GUIDE.md).
+The [included review tool](../assets/icons/ui/README.md) discovers new icons and keeps
+unaccepted artwork Open; run `cargo xtask icons` to check the collection.
+
+Windows builds: `cargo xwin build --release --target x86_64-pc-windows-msvc -p solidcraft`.
+
+
+In the browser: `cd apps/solidcraft-web && trunk build --release --public-url ./` (WebGPU, or
+WebGL2 with `?webgl`; `?sample` opens the sample part).
+
+Agents can control the document open in a browser tab through `window.solidcraft.execute(...)`
+and `window.solidcraft.request(...)`; see the [browser command API](browser-api.md).
+
+See [CONTRIBUTING](../CONTRIBUTING.md) for the test and review workflow.
diff --git a/docs/capabilities.md b/docs/capabilities.md
new file mode 100644
index 000000000..00c98dc42
--- /dev/null
+++ b/docs/capabilities.md
@@ -0,0 +1,99 @@
+# What works
+
+The full feature summary, moved out of the README. The commands by area are in [features.md](features.md); status and plans are in [ROADMAP](../ROADMAP.md).
+
+**Status: early but usable for simple parts.** 75 of 76 public reference parts
+match their analytic or FreeCAD-computed volume, area, centre of mass and bounding box
+([oracle.md](oracle.md)); the other is a tracked bug.
+These checks do not establish complete geometric or workflow equivalence. The commands SolidCraft has
+are listed by area in [features.md](features.md); status and plans are in [ROADMAP.md](../ROADMAP.md).
+Open work and known bugs are in [GitHub issues](https://github.com/tangency-labs/solidcraft/issues),
+and help is welcome: see [CONTRIBUTING.md](../CONTRIBUTING.md).
+
+
+- **Current-view DXF export** from File → Export Current View as DXF, with hidden edges
+ omitted or dashed, shown body placements and the current camera. See [view DXF](view-dxf.md).
+
+- **Sketches** on origin planes, offset planes or planar faces: lines, rectangles, circles,
+ arcs, polygons, slots, ellipses, fit/control splines, conics and text; construction geometry,
+ projection, trimming, fillets and chamfers, including corners at the origin.
+ New face attachments retain supported construction identities and chosen occurrences;
+ missing sources expose an explicit plane repair workflow. See [face attachments](face-attachments.md).
+ Explicitly closed fit splines and closed associative offsets use periodic C2 interpolation.
+ Supported convex line-and-arc offsets retain their identity when an inset consumes corner
+ arcs, and linked extrusions follow the current boundary. Breaking the association freezes
+ the boundary and keeps existing extrusions usable.
+ Curve drawing and picking adapt together to zoom and display scale, including small circles
+ at Fit and sketches in placed components.
+- **Constraints and dimensions** solved by our own solver. Points the constraints fix relative
+ to known geometry are placed exactly by construction (loci intersections and rigid-cluster
+ decomposition, after Owen 1991 and Fudos–Hoffmann 1997); Levenberg–Marquardt solves the rest,
+ and the rank of its Jacobian gives the remaining degrees of freedom. Constraints: coincident,
+ point on curve, horizontal/vertical, parallel, perpendicular, tangent, curvature (G2), equal,
+ concentric, collinear, midpoint, symmetry, fix; linear, aligned, horizontal, vertical,
+ point-to-line, radius, diameter, angle, arc sweep, arc length and slot length dimensions driven
+ by parameters. Over-constraining edits are rejected; fully constrained geometry turns black.
+ Dragging solves the sketch every frame and rebuilds the model once, when the drag ends.
+ Select a line or its two endpoints, type its dimension and press Enter to commit one undo
+ step; with Sketch Dimension it's D, click, type, Enter. Fit keeps sketch geometry clear of the palette and navigation controls.
+- **Profiles** found automatically, including regions split by lines and holes inside outlines.
+ Newly captured complete adaptive boundaries retain their outer and hole source identities
+ when spline span counts change. Partial or ambiguous boundaries do not qualify.
+- **Features** on a parametric timeline: extrude, revolve, sweep, loft, fillet/chamfer,
+ shell, draft, holes, threads, patterns, mirror, split, combine, move and construction geometry.
+ The timeline rebuilds incrementally; features can be edited, suppressed, renamed, reordered
+ and deleted. Supported geometry and current limitations are described in [ROADMAP.md](../ROADMAP.md).
+ New revolves preserve symmetric and two-sided angular placement across reversed axes;
+ older designs retain their saved convention when reopened or edited.
+- **Parameters and configurations** with unit-aware expressions (`2 * width + 5 mm`,
+ `angle / 2`), ordered rules, feature suppression and per-row body materials/appearances.
+- **Assemblies** with nested components and occurrences, joints, motion studies, contact sets,
+ interference and material-aware mass properties. Recorded body transfers preserve modelling
+ history and world placement; 3D sketch wires retain their coordinate frames through edits.
+- **Sheet metal** with flanges, hems, fold/unfold/refold, material cutouts, flat patterns,
+ retained shallow prismatic pockets, exact line/arc/circle DXF outlines and bend tables;
+ plastic enclosure features and rules. Pocket depth and side survive unfold/refold and appear
+ separately from through-hole outlines in the flat preview and DXF.
+- **Files**: design containers (`.solidcraft`) with lossless binary mesh payloads;
+ plain JSON remains supported for opening, Save As and export. Desktop Open can show a saved
+ provisional picture from warm geometry caches while rebuilding before editing; caches never
+ replace the parametric design. Export to STEP (AP242 with body names, colours and
+ components as assemblies; revolved faces as native planes, cylinders, cones, spheres and tori),
+ IGES 5.3 (manifold solid B-reps with names and colours), 3MF, STL (binary/ASCII) and OBJ, and
+ assemblies with joints as URDF for robot simulators (urdf.md);
+ 3MF, STL, OBJ and glTF 2.0 (`.glb`/`.gltf`, its node tree as components and its materials as
+ appearances) import as mesh bodies (they render, measure, move and export; solid features
+ need B-rep bodies). The `mesh.convert` command reconstructs supported closed constant-section parts
+ as parametric solids with planar and circular cylindrical faces;
+ STEP import (AP203/AP214/AP242 solids, assemblies, units, names, colours) and IGES import
+ (manifold solid B-reps, or trimmed and bounded surfaces sewn into solids) as a base feature
+ that later features build on — open a `.step`/`.stp`/`.igs`/`.iges` file, insert one into a
+ design, or drop it on the window ([docs/step-import.md](step-import.md)); FreeCAD
+ `.FCStd` and Rhino `.3dm` solids import the same way through
+ [cadmpeg](https://github.com/cadmpeg/cadmpeg) in the desktop app and CLI.
+- **Render:** opaque surfaces can use metal fraction, roughness and dielectric IOR in the
+ integrated product viewport and CPU preview PNGs. Existing simple colors remain supported.
+ Fixed direct lighting is a preview; HDRI, refraction and texture maps are not implemented.
+ See [opaque surfaces](render-opaque-pbr.md).
+- **Display meshes** from our own tessellation planner: each face becomes a plan of (u, v)
+ points and triangles that shares its edge nodes with its neighbours, so the mesh is watertight.
+ Facets follow the chord tolerance, the facet angle and a longest side, with cells at most 2:1
+ along straight directions. Box-bounded and four-cornered faces mesh as structured grids.
+ Trimmed faces are cut into four-sided patches: squares around holes, butterflies in round
+ faces, motorcycle traces from concave corners (after Lyon et al. 2019). Each patch then meshes
+ as a Coons grid. Intersection edges are evaluated by Newton on both surfaces. A compute shader
+ evaluates the plans for the whole scene in one dispatch, with a CPU fallback when the GPU
+ can't build it. Planning and evaluating the 78 reference bodies takes about 65 ms, 50–65×
+ faster than the previous mesher.
+- **Desktop app** (egui + wgpu): toolbar with workspace tabs, browser, timeline, 3D viewport with
+ axis view and navigation bar, sketch tools, feature dialogs, command palette, and a JSON-lines
+ control channel so agents and tests can drive it.
+ Feature errors and Help can open an editable **Create Issue** draft with relevant context
+ and an optional reviewed screenshot; opening GitHub does not submit the report.
+- **Headless CLI** `solidcraft-cli`: run command scripts, measure (volume, area, centre of mass,
+ face/edge/vertex counts), export, render PNG snapshots and replay reference recipes.
+ A snapshot can draw a body see-through and another solid in a colour of its own, and cut
+ the model at a plane, so a picture shows the body a cut would remove inside the material
+ it meets.
+- **MCP server** `solidcraft-cli mcp`: AI agents model, measure and look at parts headless or
+ in the running app (see below).
diff --git a/docs/downloads.md b/docs/downloads.md
new file mode 100644
index 000000000..c784b6cbe
--- /dev/null
+++ b/docs/downloads.md
@@ -0,0 +1,44 @@
+# Downloads
+
+Every platform and package. The links point at the latest release.
+
+- **Windows:** download and run the [installer][windows-msi].
+ Also for [ARM64][windows-arm64-msi] and [32-bit][windows-x86-msi] PCs, or as a
+ [portable zip][windows-portable] that runs without installing.
+ With [WinGet](https://learn.microsoft.com/windows/package-manager/winget/):
+ `winget install bherbruck.SolidCraft`.
+- **macOS:** open the [disk image][macos-dmg] and drag SolidCraft into Applications
+ (Apple silicon and Intel).
+- **Linux:** download the [AppImage][linux-appimage], allow it to run as a program and open it.
+ Or install the [.deb][linux-deb] (Ubuntu, Debian, Mint) or [.rpm][linux-rpm] (Fedora,
+ openSUSE), or use [Flatpak](https://docs.solidcraft.io/guide/getting-started.html#linux-flatpak).
+ With Snap: `sudo snap install solidcraft` ([Snap Store][snap-store], or the [.snap file][linux-snap]).
+ For ARM64: [AppImage][linux-arm64-appimage], [.deb][linux-arm64-deb], [.rpm][linux-arm64-rpm].
+- **Web:** [try it in your browser][web-app], no install.
+
+
+The downloads aren't signed yet. On Windows, if SmartScreen warns you, choose **More info**, then
+**Run anyway**. On macOS, the first time, right-click SolidCraft in Applications and choose **Open**.
+
+**On SolidCraft 0.11 to 0.14?** Its **Update now** can't install 0.15.0 or later, because the
+releases moved to a new address. Download the new version once from the links above; after that,
+updating from inside SolidCraft works again ([details](https://docs.solidcraft.io/guide/updates.html#updating-from-011-to-014)).
+
+Older versions, checksums and other formats are on the [releases page](https://github.com/tangency-labs/solidcraft/releases).
+Install details, upgrading from earlier builds and building from source are in
+
+[Getting started](https://docs.solidcraft.io/guide/getting-started.html).
+[windows-msi]: https://github.com/tangency-labs/solidcraft/releases/latest/download/solidcraft-windows-x64.msi
+[windows-arm64-msi]: https://github.com/tangency-labs/solidcraft/releases/latest/download/solidcraft-windows-arm64.msi
+[windows-x86-msi]: https://github.com/tangency-labs/solidcraft/releases/latest/download/solidcraft-windows-x86.msi
+[windows-portable]: https://github.com/tangency-labs/solidcraft/releases/latest/download/solidcraft-windows-x64-portable.zip
+[macos-dmg]: https://github.com/tangency-labs/solidcraft/releases/latest/download/solidcraft-macos-universal.dmg
+[linux-appimage]: https://github.com/tangency-labs/solidcraft/releases/latest/download/solidcraft-linux-x86_64.AppImage
+[linux-deb]: https://github.com/tangency-labs/solidcraft/releases/latest/download/solidcraft-linux-x86_64.deb
+[linux-rpm]: https://github.com/tangency-labs/solidcraft/releases/latest/download/solidcraft-linux-x86_64.rpm
+[linux-arm64-appimage]: https://github.com/tangency-labs/solidcraft/releases/latest/download/solidcraft-linux-aarch64.AppImage
+[linux-arm64-deb]: https://github.com/tangency-labs/solidcraft/releases/latest/download/solidcraft-linux-aarch64.deb
+[linux-arm64-rpm]: https://github.com/tangency-labs/solidcraft/releases/latest/download/solidcraft-linux-aarch64.rpm
+[linux-snap]: https://github.com/tangency-labs/solidcraft/releases/latest/download/solidcraft-linux-x86_64.snap
+[snap-store]: https://snapcraft.io/solidcraft
+[web-app]: https://solidcraft.io/app
diff --git a/docs/scripts.md b/docs/scripts.md
new file mode 100644
index 000000000..fdaa8105a
--- /dev/null
+++ b/docs/scripts.md
@@ -0,0 +1,15 @@
+# Scripts
+
+
+A script is a JSON list of commands, the same ones the UI runs:
+
+```json
+{"commands": [
+ {"command": "sketch.create", "params": {"plane": "XY"}},
+ {"command": "sketch.rectangle.two_point", "params": {"p0": [0, 0], "p1": [40, 30]}},
+ {"command": "solid.extrude", "params": {"distance": 20}},
+ {"command": "solid.fillet", "params": {"edges": [[0, 0, 10]], "radius": 3}}
+]}
+```
+
+Run one with `solidcraft-cli run script.json --out part.step`; see [building](building.md) and the [command list](features.md).
diff --git a/docs/showcase.md b/docs/showcase.md
new file mode 100644
index 000000000..95907585a
--- /dev/null
+++ b/docs/showcase.md
@@ -0,0 +1,9 @@
+# Built with SolidCraft
+
+
+
+*SELENE, a scientific rover built entirely through SolidCraft's MCP server by
+[@0xlillith](https://github.com/0xlillith/solidcraft-rover): 3,323 editable timeline steps that
+rebuild with no errors, replayed here at 2× speed.
+[Full video](https://github.com/tangency-labs/solidcraft/raw/refs/heads/main/screenshots/rover-build.mp4)
+· [download the editable model](https://github.com/0xlillith/solidcraft-rover/releases/tag/v1.0.0).*