# Agent rulebook — Rods Cursor solver

This file is the **canonical** instruction set for AI agents working in this repository. Read it before changing code or docs.

## Authoritative docs (read order)

1. **[Agents/MATH_SPEC.md](Agents/MATH_SPEC.md)** — Equations, discretization, BCs, paper citations (`references/papers/README.md`). **Do not invent math** not grounded there or in a cited calibration test.
2. **[Agents/COMPUTE_PLAN.md](Agents/COMPUTE_PLAN.md)** — Living handoff: repo map, current gaps vs `MATH_SPEC.md`, deferred work, jump table.
3. **[README.md](README.md)** — Human/agent quickstart, API examples, validation commands.

## Product intent

Build a **transparent, deterministic** rod-string / dynamometer solver stack: **C** is the authoritative numerics engine (predictive + diagnostic, FDM + FEA); **Node (`solver-api`)** is XML/IO, orchestration, card QA, and API versioning; **TypeScript (`gui-ts`)** is workflow and visualization (not the primary solver).

Outcomes:

- Physically explainable outputs, not black-box curves.
- **Dynamometer cards** (polished + downhole) as the central engineering surface.
- Preserve **inspectability** of imported XML (`rawFields`, `unsupportedFields`, `verbose`).
- Multi-model workflows: run **FDM** and **FEA**, compare, surface discrepancies and assumptions.

## Architecture (non-negotiable)

| Layer        | Responsibility |
|-------------|----------------|
| `solver-c/` | All heavy numerics: damped wave FDM, bar FEM, trajectory preprocess, diagnostic transfer, gravity/buoyancy, deviated-well friction proxies, iterative diagnostic FEA when enabled. |
| `solver-api/` | HTTP, `parseCaseXml`, SI normalization, JSON → C stdin, surface-card QA, response shaping (`schemaVersion`, `comparison`, `verbose`, `pumpMovement`). |
| `gui-ts/`   | UI: import, plots, 3D survey when implemented, warnings. **No** primary PDE solve in TS except temporary shims during migration (avoid new TS numerics). |

Same C binaries power Docker, local `make test`, and CI.

## Guardrails

- **Determinism:** identical inputs → identical outputs (regression tests and golden hashes depend on this).
- **API fields:** do not remove `verbose`, `pumpMovement`, or `comparison` without bumping `schemaVersion` and documenting migration.
- **No undocumented “magic” multipliers.** If a simplification is not in `MATH_SPEC.md`, tag it `heuristic` in code comments and add a ticket in `COMPUTE_PLAN.md` or a calibration test in `docs/engineering/validation.md`.
- **XML:** never fabricate field names or values not read from a real case file. Unknown fields stay in `rawFields` / `unsupportedFields`.
- **Units:** internal solve uses **SI** (`docs/engineering/units.md`). Convert at the API/parser boundary.
- **Papers:** grounding lives in `references/papers/README.md` (Romero & Almeida; Everitt & Jennings; SPE-173970 Araujo et al.; Eisner et al.).

## GUI (product)

The GUI is first-class for end users: continuous visibility of survey and cards, 3D trajectory when implemented, side-by-side solver comparison. Agent work may still touch **compute-only** paths without GUI in a given PR; do not add new numerics in the GUI.

## When you change the solver

1. Update `MATH_SPEC.md` if equations or BCs change.
2. Update `COMPUTE_PLAN.md` gap table / status.
3. Run `make test` and golden regression (`solver-api` tests include golden hash where configured).
4. If C CLI or JSON contract changes, update `README.md`, `docker-compose.yml` gcc lines, and root `Dockerfile` compile commands.

## Repository map (compute)

| Path | Role |
|------|------|
| `solver-c/src/solver.c` | FDM predictive + shared numerics |
| `solver-c/src/solver_fea.c` | FEA predictive + diagnostic iteration (when applicable) |
| `solver-c/src/solver_diagnostic.c` | Diagnostic FDM (surface card BC) |
| `solver-c/src/trajectory.c` | Survey → curvature / inclination on rod grid (SPE-173970 style) |
| `solver-c/src/json_stdin.c` | Minimal JSON stdin parser for C drivers |
| `solver-api/src/solverClient.js` | Build SI JSON, `execFile` C with stdin |
| `solver-api/src/xmlParser.js` | Parse case + SI conversion |
| `solver-api/src/app.js` | Routes, comparison payload, `schemaVersion` |
| `data/cases/base-case.xml` | Canonical regression case |
| `data/golden/` | Golden response fingerprints |

---

*Merged from legacy `Agents/Instructions.md`. Product vision details are maintained in `README.md`.*