rods/AGENTS.md

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 — 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 — Living handoff: repo map, current gaps vs MATH_SPEC.md, deferred work, jump table.
3. 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.