# Contributing

Thanks for helping improve this project. The goal is **deterministic, explainable** rod-string / dynamometer simulation: C is the numerical source of truth; Node orchestrates; the GUI is workflow and visualization.

## Before you start

Read (in order):

1. [AGENTS.md](AGENTS.md)
2. [Agents/MATH_SPEC.md](Agents/MATH_SPEC.md)
3. [Agents/COMPUTE_PLAN.md](Agents/COMPUTE_PLAN.md)

## Local development

### Prerequisites

- `gcc`, `make`
- Node.js 20+ and `npm`
- Docker (optional, for compose / CI image)

### Build C drivers (JSON on stdin)

From the repository root, follow the `gcc` commands in [README.md](README.md) or use CMake:

```bash
cmake -S solver-c -B solver-c/build
cmake --build solver-c/build
```

The API expects `solver-c/solver_main` and `solver-c/solver_fea_main` in the repo root layout (see `docker-compose.yml` and `solver-api`).

### Run tests

```bash
make test
```

This runs `solver-api` Vitest, `gui-ts` Vitest, and `solver-c/test_solver`.

## Pull requests

- Keep changes focused; avoid drive-by refactors.
- If you change solver equations or boundary conditions, update [Agents/MATH_SPEC.md](Agents/MATH_SPEC.md) and the gap table in [Agents/COMPUTE_PLAN.md](Agents/COMPUTE_PLAN.md).
- If you change the JSON contract or HTTP responses, bump `schemaVersion` only with an explicit migration plan (see [AGENTS.md](AGENTS.md)).

## Coding style

- Match existing formatting and naming in each package (`solver-c`, `solver-api`, `gui-ts`).
- Prefer small, test-backed changes for numerics.

## Security

See [SECURITY.md](SECURITY.md).