Skip to content

SolidCraft: an open-source parametric 3D CAD application built in pure Rust. Desktop, web, and automation through MCP.

docs: CLAUDE.md carries the current shared agent rules (#1822) (#1859)

DuBearteddc6aa63012b
diff --git a/CLAUDE.md b/CLAUDE.md
index 5ed78acd54..82492953b9 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -65,8 +65,8 @@ People trust SolidCraft with their designs; a crash loses their work. **This out
nothing from FreeCAD is linked, vendored or shipped.) The sketch solver and the blend
operations are our own.
- **Assets — absolutely essential.** SolidCraft contains **no iconography, images, fonts or
- artwork from commercial CAD products — ever.** Every icon is drawn in code
- (`crates/ui-egui/src/icons.rs`). Any file asset must be original or openly licensed and **must have a row in ATTRIBUTION.md**
+ artwork from commercial CAD products — ever.** Every UI icon is drawn in collected code
+ (`assets/icons/ui/source/`, compiled through `crates/ui-egui/src/icons.rs`). Any file asset must be original or openly licensed and **must have a row in ATTRIBUTION.md**
(`cargo xtask assets` enforces it). Screenshots of commercial CAD software are never committed.
Breaking this rule is the most serious mistake you can make in this repo.
- **Everything is a command.** User-visible behaviour = a command in `crates/engine/src/cmd/*`
@@ -81,6 +81,10 @@ People trust SolidCraft with their designs; a crash loses their work. **This out
egui/eframe/winit/wgpu/rfd. **The UI crate is swappable.** Only `crates/kernel` may use `truck`.
- **The UI is thin**: panels read engine state and act through `app.run(id, params)` /
`app.start(id)`. Colours come from `theme::Tokens`.
+- **One set of camera controls**: every page or canvas with a camera (viewport, Render
+ preview, future flat pattern or drawing pages) calls `navigation::handle` with its `NavCaps`
+ (orbit off for flat 2D pages). New canvases must use `navigation::handle`; never hand-roll
+ camera input (a test rejects it).
- **Rust only.** Units are millimetres and radians internally; Z is up. The one exception is
JavaScript the browser requires: the service worker `apps/solidcraft-web/sw.js` (browsers only
run service workers as JavaScript) and the small inline scripts in `apps/solidcraft-web/index.html`.
@@ -96,6 +100,29 @@ People trust SolidCraft with their designs; a crash loses their work. **This out
- **Never break wasm**: everything below the apps must build for `wasm32-unknown-unknown`
(`cargo xtask wasm`, part of `cargo xtask ci`).
+## Showing and following through on changes
+
+- Help reviewers see what is broken or changed. For observable CAD, UI or model behavior,
+ issues and PRs must include actual descriptive screenshots or a short recording from a
+ small reproduction. This includes kernel, geometry, assembly and backend changes whose
+ effects can be shown in the app. Coding agents should run the app and capture this evidence
+ themselves; do not ask a human for evidence the agent can produce. Show the actual failure
+ or result, preferably before and after, with brief reproduction steps, expected/actual
+ behavior and annotations that point out the relevant detail.
+- Flowcharts and Mermaid diagrams cannot substitute for screenshots or recordings of visible
+ behavior. Use diagrams for architectural reasoning when actual screenshots cannot illustrate
+ the point. Changes with no useful observable behavior do not need screenshot or video evidence.
+- Use a small public-safe example and check for private designs, paths, account details or
+ other sensitive content before sharing. Attach media to the issue/PR or link to an accessible
+ recording; do not commit generated screenshots or videos just to provide review evidence.
+- Throughout the work and before handoff, check current upstream commits and the relevant
+ PR's merge status. Keep your branch current with upstream merges, resolve conflicts without
+ discarding others' work, and re-run validation when integration changes the result. Use
+ `git pull --rebase origin main` before pushing as above; never force-push. Report the checked
+ upstream/PR state, any conflicts resolved and the validation performed. If a PR remains open,
+ keep monitoring it while the task is active and make its pending status clear at handoff;
+ do not claim it merged without checking.
+
## Claim = a draft PR
- Before working on issue #N, check nobody has it: `gh pr list -R bherbruck/solidcraft --state open --search "#N"`.
- If none, branch from the latest `origin/main`, `git commit --allow-empty -m "claim: #N"`, push,