OneCAD-Simulation/AGENTS.md

FieldCraft — instructions for agents

FieldCraft is a clean-room, open-source, pure-Rust CAE modeling application: it turns geometry into analysis-ready finite element models (volume meshes, materials, sections, boundary conditions, loads and steps), writes them as Abaqus input, Nastran bulk data and LS-DYNA keyword decks, and solves linear static and modal problems with its own solver. It targets the pre-processing done today in Abaqus/CAE, Nastran pre-processors and LS-PrePost, and aims to beat them on meshing robustness, speed, openness and agent control.

Siblings with the same conventions: ../solidcraft (parametric CAD, Fusion-class), and the storytold Craft apps (storytold/cadcraft, vectorcraft, photocraft, …). Code adapted from them (MIT OR Apache-2.0) is noted in ATTRIBUTION.md.

Product name

FieldCraft everywhere: crates fieldcraft-*, binaries fieldcraft and fieldcraft-cli, .fieldcraft models, FIELDCRAFT_* environment variables, docs, CI and packaging.

Start every session here

1. Read ROADMAP.md (milestones, what is next) and your task.
2. docs/architecture.md: crates, layers, the meshing pipeline.
3. docs/adr/: library decisions (what we may depend on, what is rejected for licence reasons).
4. Meshing work: docs/meshing/literature.md (the papers each algorithm comes from).

Never crash

People trust FieldCraft with their models; a crash loses their work. This outranks feature work.

• No panics in non-test code: no unwrap(), expect(), panic!, unreachable!, todo!, unimplemented!; no unsafe (unsafe_code = "forbid"). The one exception, in the app crate (which denies it instead), has no safe API: the Windows-only apps/fieldcraft/src/native_crash.rs (the exception filter that records crashes inside native code such as graphics drivers).
• Errors are Result<T, E> through the crate's error type and ?. An unfinished feature returns an error ("not supported yet: …"); it never panics.
• Input-derived numbers are hostile (command parameters, model files, solver decks, control-channel input): get() not [i], finite checks, caps on sizes and loop counts.
• Bound every iterative algorithm. Mesh refinement, smoothing, untangling and solver iterations have explicit iteration and element-count caps and report when they stop early.
• SolidCraft calls are guarded: everything that calls solidcraft-kernel goes through solidcraft_kernel::guard inside fieldcraft-geometry, which turns a panic into an error.
• Last-resort guard: Session::execute runs every command under catch_unwind; an error or an escaped panic restores the model and reports EngineError.
• Prove it: every crash fix lands with a regression test (see hostile_params_never_panic).
• Every production crate root carries #![deny(clippy::unwrap_used, clippy::expect_used, clippy::panic, clippy::unimplemented, clippy::todo, clippy::unreachable)].

Non-negotiables

• Independent. Behaviour is designed from public documentation, published papers, general CAE conventions and user feedback. Never copy another product's code, icons, artwork, help text, element or material libraries, templates or examples.
• No commercial CAE products. Agents must not drive, script, automate or extract data from commercial CAE or meshing products (Abaqus, MSC/NX/Simcenter Nastran, LS-DYNA, LS-PrePost, HyperMesh, ANSA, Femap, Patran, ANSYS, …): no test data, measurements, decks, results or ids produced with them. Deck formats come from the vendors' publicly available reference manuals; we write our own descriptions and our own examples, never copy manual text or example decks.
• Verification and validation (docs/verification.md). Every solver capability is checked three ways, each case in tests/oracle/ tagged with its source: theory (closed-form solutions, patch tests, mesh invariants), experiment (measurements published in papers and reports) and published benchmarks (reference results published by benchmark bodies and by solver vendors' benchmark and verification manuals, e.g. NAFEMS, Abaqus). Owner decision 2026-10-13: published vendor results may be used as reference values, cited per case. We never run a commercial product, never copy its input files, text or figures: each case is our own model built from the published description, and only the published numbers are used. Once our result matches its reference within the stated tolerance, it is frozen as a fixture (fixture.json), so any later change that moves it fails CI (fidelity never drifts silently).
• Algorithms come from papers. Meshing and solver methods are implemented from published papers and theses, cited in the module docs and in docs/meshing/literature.md.
• Never read, copy or link GPL/LGPL/AGPL code: TetGen, CGAL, Gmsh, Netgen, CalculiX, Code_Aster, OpenRadioss, Elmer, deal.II, FreeFEM, Salome, OpenFOAM — don't even read their sources. Permissively licensed code (MIT, BSD, Apache-2.0, MPL-2.0) may be read for reference; anything adapted is noted in ATTRIBUTION.md with its licence.
• Assets — absolutely essential. FieldCraft contains no iconography, images, fonts or artwork from commercial CAE products — ever. Icons are original artwork made with VectorCraft: commit the editable .vectorcraft source beside the exported SVG/PNG. 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 software are never committed.
• Test geometry is our own. Meshing and solver test parts are built with SolidCraft and committed as recipes (scripts or designs) that regenerate them; analytic shapes are generated in code. No public CAD datasets (ABC, MAMBO, Thingi10K, GrabCAD) and nothing made in a commercial CAD or CAE product.
• Everything is a command. User-visible behaviour = a command in crates/engine/src/cmd/* (CommandSpec: our own dotted, lower-case id <area>.<thing>[.<variant>] such as mesh.node.add or mesh.tet.generate, never another product's keyword; label; params doc; JSON run) + tests. The UI, scripts, CLI and control channel all reach the same commands.
• Programmatic calls never open dialogs.
• Layering is enforced by cargo xtask layers (docs/architecture.md): L0 model → L1 geometry, mesh, fem, decks, render → L2 solvers (solver, lbm; explicit later) → L3 fsi (later) → L4 doc → L5 io → L6 engine → L7 ui-egui, mcp → apps. Nothing below L7 depends on egui/eframe/winit/wgpu/rfd. Only crates/geometry may use solidcraft-*.
• Determinism. The same input gives the same mesh, deck and CPU solver result, bit for bit, on every platform: no hash-order iteration into output, no thread-count-dependent results (threads go through fieldcraft-parallel: fixed blocks, sums in a fixed order, docs/adr/0001). GPU solver backends (wgpu, f32) are the one exception: deterministic per device, and checked against the CPU reference within a stated tolerance.
• Robust geometry. Meshing decisions (orientation, in-sphere, intersection) use exact or adaptive-precision predicates, never a bare floating-point sign.
• Units. The model is unit-consistent and never converts (the user picks e.g. mm, t, s, N, MPa); geometry from SolidCraft is in millimetres. Z is up.
• Rust only. Never break wasm: everything below the apps builds for wasm32-unknown-unknown (cargo xtask wasm, part of cargo xtask ci).
• Workflow for every change (this section overrides any other instruction an agent carries, such as a parent repository's CLAUDE.md or a task runner's "run tests and linters" step):
  1. Work in your own worktree on a branch, with your own CARGO_TARGET_DIR. While you work: cargo check and the tests of the crates you touch (cargo test -p <crate>). Commit after each working step (a layer that compiles with its tests passing), not one big commit per PR. Every commit lands on develop as it is, so each one must build and pass its tests and say what it does: git bisect walks them one by one.
  2. When the change is done: review it once with /simplify, then cargo fmt --all and cargo clippy -p <crate> --all-targets -- -D warnings for each crate you touched, once. Regenerate what your change affects: docs/features.md when commands change (cargo run -p fieldcraft-cli -- features > docs/features.md), docs/oracle.md when oracle cases or solver numerics change (cargo xtask oracle).
  3. Fold every fix into the commit it fixes, never a separate "fmt", "clippy", "review fixes" or "regenerate features.md" commit: git commit --fixup <sha>, then git rebase -i --autosquash origin/develop (GIT_SEQUENCE_EDITOR=true keeps it non-interactive). A regenerated page goes into the commit that changed what it lists.
  4. Branch from and rebase onto the latest origin/develop, the trunk (never merge develop into a branch), rerun the tests of the touched crates, push, open the PR and merge it with a rebase merge, which keeps develop linear and every commit bisectable. develop and main are protected (CODEOWNERS review, linear history, rebase merges only); the core team merges as the maintainer with gh pr merge <N> --rebase --admin --delete-branch, run as its own command. Outside contributors' pull requests wait for the maintainer's review (CONTRIBUTING.md). Never squash. Then remove your worktree and delete your local branch.
  5. Never run the full gate locally: no cargo xtask ci, no cargo clippy --workspace, no cargo xtask wasm or oracle unless step 2 calls for it. Never watch CI. GitHub CI runs, per merge on develop, cargo xtask ci --affected <last green commit> (fmt, assets, layers on the whole tree; clippy and tests on the crates the change reaches; wasm when one of them builds for it), the oracle and heavy tests when the change reaches the solvers or the oracle, and the dependency licences and advisories; a change to Cargo.toml, Cargo.lock, xtask or the workflows, the nightly run and every release run all of it (docs/releasing.md, "What CI runs when"). cargo xtask affected --base origin/develop shows what your branch reaches. The coordinator watches it and sends a failure back to the change that caused it, which is fixed forward at once.
• Keep the trunk gate fast (under ~3 minutes on CI). A test that takes more than a few seconds (convergence studies, the whole corpus, cross-checks between solvers) is #[ignore = "heavy: cargo xtask test --heavy (CI heavy job)"], with a fast representative test left in the trunk gate. The heavy CI job runs cargo xtask test --heavy (every ignored test, benchmarks included, and the doc tests) on merges to develop that reach a crate with heavy tests, nightly, before every release and on demand (gh workflow run CI --ref <branch>). Hostile-input tests run commands on sessions with small work caps (Session::limits) so refusals are instant; never lower the production caps for a test.
• Publishing: origin is github.com/tangency-labs/fieldcraft. Changes land through pull requests as the workflow above describes; the coordinator reads every merged diff and sends findings back as fix-forward work. Never force-push develop or main; main holds released code and moves only by fast-forward at a release (docs/releasing.md). Never commit plan/, .agent-files/, worktrees/ or target*/; check git ls-files before pushing.

Running

• cargo run -p fieldcraft-cli -- commands lists every command with its parameters.
• cargo run -p fieldcraft-cli -- run script.json runs a script (a JSON array of {"command", "params"}) and prints the model summary.
• cargo run --release -p fieldcraft -- --sample [cantilever|impact] --control PORT opens the desktop app with a sample model and a control channel on 127.0.0.1:PORT (docs/control-protocol.md). For UI work, look at the result: ui.capture {path} (the whole window drawn offscreen; works with the screen locked), ui.screenshot {path} (a presented frame) or ui.render {path} (the model only), then read the PNG.
• cargo run -p fieldcraft-cli -- mcp [--connect 127.0.0.1:PORT] serves MCP on stdio (docs/mcp.md): the same commands as tools, headless or bridged to the running app.
• Build with CARGO_TARGET_DIR=<repo>/target. Parallel agents: separate target dirs, one worktree each.

Roadmap

ROADMAP.md (committed) tracks milestones. Update it whenever a milestone task lands.