Add AGENTS.md agent instructions

[roninsightrx]

Summary

Renames CLAUDE.md to AGENTS.md and extends it. AGENTS.md is the harness-agnostic convention, so any AI coding agent picks up the repo instructions rather than only one vendor's tool. The content was rewritten to refer to "agents" / "AI coding agents" instead of a specific product.

What the file contains

• Commands — devtools::load_all() / test() / document() / check(), pkgdown::build_site(), plus notes on running a subset of tests with devtools::test(filter = ...) (which also sources tests/testthat/setup.R), and on recompiling after src/*.cpp edits.
• Architecture — the sim() → sim_core() → Boost odeint pipeline, and the branch in sim() that routes to the ADVAN analytical path instead when analytical is given.
• Key files — annotated map of the main R/ entry points, including model_library.R, shift_state_indices.R and the nlmixr2/NONMEM interop files.
• C++ layer — the two distinct compilation paths (src/ at package install time vs. user ODE models compiled at runtime), and the -D_HAS_AUTO_PTR_ETC=0 flag in src/Makevars.
• Model definition formats — custom C++ strings, model_library.R entries, JSON5 literature models in inst/models/, API models, and the model-as-package scaffold in inst/template/.
• ODE conventions — A[0] vs A[1] indexing and how shift_state_indices() handles both, as_is, declare_variables, pk_code, state_init.
• Testing patterns — setup.R compiles shared models once per session and tests should reuse those objects; expensive fixtures are gated on NOT_CRAN; the suite stays offline by pointing model_from_api() at local fixtures.
• CI, dependencies, repo conventions — including that this is a CRAN package, so R CMD check --as-cran must stay clean and new hard dependencies need justification.

Function and file references were checked against the source.

Also

AGENTS.md is added to .Rbuildignore so R CMD check --as-cran does not report it as a non-standard top-level file (CLAUDE.md was not ignored previously).

🤖 Generated with Claude Code

[roninsightrx]

Changes requested: several factual errors would send coding agents to the wrong execution paths.

• AGENTS.md:60 and AGENTS.md:73: sim() never dispatches to sim_core(). In R/sim.R it calls the compiled ode directly (or the ADVAN path), while sim_core() is a separate fast entry point that consumes a design such as the object returned by sim(..., return_design = TRUE). Replace the pipeline and file description with those sibling paths.
• AGENTS.md:79 and AGENTS.md:119: R/calculate_parameters.R does not apply IIV or IOV; it is a convenience wrapper around sim_ode() for calculating model-specific/effective parameters. IIV sampling and application are in R/sim.R (mvrnorm2() plus the omega_type handling), while IOV bin/parameter handling is generated from R/new_ode_model.R and executed by the compiled solver. Point agents to those files instead. Also name the accepted IIV modes as exponential and normal; additive describes the formula but is not a supported omega_type value.
• AGENTS.md:114: pk_code does not run before every derivative step. inst/cpp/sim.cpp invokes it initially and once per event interval before integration; RK4 evaluates the ODE multiple times within that interval. Change this to “runs at each event/before each integration interval” so agents do not put per-derivative logic there.
• AGENTS.md:140-142: test_install_default_literature_model.R neither installs a package nor uses an explicit temp directory or skip_on_cran(); it mocks model_from_api() and tests dispatch. Only the package-installing test in test_model_from_api.R has the described temp-dir and CRAN gating behavior. Narrow this guidance accordingly.

Reviewed by Codex

[roninsightrx]

Thanks — verified all four findings against the source; all were correct and all are now fixed in dce5eb2.

1. sim() → sim_core() (lines 60, 73) — Confirmed: R/sim.R:520 calls ode(...) directly, and sim_core() takes a sim_object design. Pipeline diagram and both file descriptions now describe them as sibling entry points, with sim_core() documented as consuming a sim(..., return_design = TRUE) design.

2. calculate_parameters.R / IIV modes (lines 79, 119) — Confirmed: it is a sim_ode() wrapper for effective parameters. The variability section now points at R/sim.R (mvrnorm2() at :346 plus the omega_type block at :471-488) for IIV, and R/new_ode_model.R (generated kappa_* bin logic) plus the compiled solver for IOV. additive replaced with the actual accepted value normal.

3. pk_code timing (line 114) — Confirmed: inst/cpp/sim.cpp:193 calls it once at init and :223 once per event interval before sim_cpp(). Reworded to per-event/per-integration-interval, with an explicit note not to put per-derivative logic there.

4. Test gating (lines 140-142) — Confirmed: test_install_default_literature_model.R mocks model_from_api() and has no temp dir or skip_on_cran(). Narrowed to the single installing test in test_model_from_api.R ("Can install a package from json").

Also re-ran the documented commands to confirm they work: devtools::test(filter = "advan") (53 pass), testthat::test_file("tests/testthat/test_advan.R") (49 pass), and devtools::test(filter = "install_default_literature_model") (5 pass). File stays harness-agnostic and is only ~17 lines longer.

🤖 Generated with Claude Code

[roninsightrx]

Approval verdict: all four prior findings are resolved, and the revised guidance matches the simulation paths, variability handling, pk_code timing, and test behavior in the source. No new inaccuracies or harness-specific references found. GitHub does not permit the authenticated PR author to submit an approval review, so this verdict is recorded as a review comment.

Reviewed by Codex

[JordanBrooks33]

lgtm