Recommendations for release

[grantdadams]

• Replace integer-coded modes with strings + match.arg(). [fit_mod()] takes estimateMode = 0..4, msmMode = 0..2, suitMode = 0..6, avgnMode = 0..2, and initMode accepts both a string and an integer. That dual-form is a footgun; integer codes are a documentation tax. Standardize on strings everywhere, with match.arg() validation at the top of each function. Keep the integer→string mapping in [R/0-constants.R] as the single source of truth, exported as named vectors so an assessor can introspect Rceattle::estimate_modes.

• Give every build_*() return value a class and a print method. [build_hcr()], build_srr(), build_M1(), build_growth() all return bare lists. A user assembling a complex run can't quickly see what they configured. fit_control() already does this — propagate the pattern.

• Split or theme-ify [plot_timeseries()]. 24 arguments is too many to learn. Bundle aesthetics into a ceattle_theme(line_col, lwd, lty, alpha, legend.pos, ...) object passed as one arg. Keep data/model/range args at top level. Audit the rest of the plot_* family for the same shape.

• Add a build_data() constructor and a predict() method. Currently the in-R data path (per the Data without Excel vignette) is "assemble the list by hand." A build_data() factory that validates structure with the same checks as [4-data_check.R] makes programmatic workflows (especially MSE/simulation) far less error-prone. A predict.Rceattle(fit, newenv = ...) method would also be high-value for the environmental-linkages research use case — much better than re-running sim_mod() to score new covariate scenarios.

• Add as.data.frame.Rceattle() that returns long-format derived quantities (year, species, sex, age, quantity, value, lwr, upr). Right now [6-rename_output.R] does fragile renaming work that an assessor will inevitably want to bypass for custom plots — give them a tidy escape hatch.

Misc footguns to fix:

• initMode accepts both string and int — pick strings, deprecate the int form gracefully.
• niter = 3 default for the multispecies loop is undocumented at the call site; document or validate convergence and bump if needed.
• data_check() ([4-data_check.R]) is good but throws individual stop()s — consider collecting errors and reporting them all at once so users fix five problems instead of five sequential debug cycles.
  Internal codebase
• Audit the 8 FIXMEs in the TMB code — at minimum convert each to a tracked issue with a one-line context note. The selectivity-bound and time-varying-mode FIXMEs in particular look like they could bite an operational user.
• Co-locate the mode constants with their validators. [R/0-constants.R] defines reverse maps that aren't enforced uniformly — wire them into a single validate_modes() function called from fit_mod()/build_* entry points.
• The wide-array indexing in [2-build_map.R] (e.g., (sp - 1) * 4 + 1:3 at lines 393–411 for growth, similar gymnastics at lines 134–142 for recruitment betas) is the single biggest readability hazard I'd want gone before more parameterizations land. Section 5 below addresses this directly.

Tests:

• a) a plotting smoke test (just "does each plot_* render without error on a fitted model fixture")
• b) Excel I/O roundtrip with a malformed file
• c) projection/forecast edge cases. Env-covariate parameter recovery exists already per [tests-Dynamics/test-env-linkages.R] — extend it once you adopt the unified design below.

Documentation gaps for an operational release

• 5-minute quickstart: bare minimum end-to-end — load data, fit single-species, plot SSB, produce reference points. Ideally as the README's first runnable block.
• Migration guide v3 → v4: NEWS.md has the changes but they're scattered. One vignette mapping old names to new (the Pyrs → ration_data etc. renames in 4.0.1, the fit_control consolidation in 4.0.3) saves every existing user a day.
• Troubleshooting / FAQ: convergence failures, "why is my SSB exploding," and "how do I diagnose a misconfigured fleet" — operational users hit these, and right now the only recourse is reading source.
• Cheatsheet of mode constants and their meanings — one printable PDF page