chore: update helper files

Author: be-marc

AGENTS.md

@@ -75,13 +75,22 @@ Rscript -e "devtools::check()"
 - Every user-facing function should be exported and have roxygen2 documentation.
 - Wrap roxygen comments at 120 characters.
 - Write one sentence per line.
-- If a sentence exceeds the limit, break at a comma or other appropriate point.
+- If a sentence exceeds the limit, break at a comma, "and", "or", "but", or other appropriate point.
 - Internal functions should not have roxygen documentation.
 - Always re-document the package after changing a roxygen2 comment.
 - Don’t hand-edit generated artifacts: `man/`, or `NAMESPACE`.
-- Roxygen templates live in `man-roxygen/`
+- Never edit `README.md` directly -- it is generated from `README.Rmd`. Always edit `README.Rmd` and then run `devtools::build_readme()` to regenerate `README.md`.
+- When adding a new S3 method (such as `print.<ClassName>`), always run `devtools::document()` afterwards to re-generate the NAMESPACE.
+- Environment variables and options are documented in package-level documentation (typically `R/package.R`).
+- Roxygen templates live in `man-roxygen/`. Use `@template` to avoid duplicating common parameter descriptions.
+  Only create new templates for sections that will likely be re-used.
+- For functions, always document the return value (section `#' @return`).
 - Bibliographic references go in `R/bibentries.R` and are cited with `` `r format_bib("key")` ``.
 
+## Pkgdown
+
+- When adding a new exported function, ensure it's in the `_pkgdown.yml` file.
+
 ## `NEWS.md`
 
 - Every user-facing change should be given a bullet in `NEWS.md`.
@@ -104,6 +113,6 @@ Rscript -e "devtools::check()"
 - Use cspell to check against typos, and add needed words to .cspell/project-words.txt if reasonable
 
 ## Further agents files
-- Read and respect all files in the `.agents` folder
+- Read and respect all files in the `extra-rules` folder
 
 

.agents/mlr3.md extra-rules/mlr3.md.agents/mlr3.md renamed to extra-rules/mlr3.md

@@ -59,6 +59,32 @@ There is a distinction between `default` and `init` values:
 - A parameter tagged `"required"` causes an error if not set. A required parameter cannot have a `default` (that would be contradictory).
 - paradox does type-checking and range-checking automatically; `get_values()` checks that required params are present. Additional feasibility checks are rarely needed.
 
+#### Public fields as active bindings
+
+Public fields on R6 classes are exposed as active bindings backed by a private `.field`.
+
+For mutable fields, the binding returns the private value when called without arguments and validates the new value with an `assert_*()` call when set:
+
+```r
+id = function(rhs) {
+  if (missing(rhs)) {
+    return(private$.id)
+  }
+  private$.id = assert_id(rhs)
+},
+```
+
+For read-only fields, call `assert_ro_binding(rhs)` to raise an error on any assignment attempt:
+
+```r
+task_type = function(rhs) {
+  assert_ro_binding(rhs)
+  private$.data$task_type
+},
+```
+
+The private slot must be declared in the `private` list as `.id = NULL` (or an appropriate default).
+
 #### Core dependencies
 
 `data.table`, `checkmate`, `mlr3misc`, `paradox`, `R6`, and `cli` are imported wholesale. Use their functions directly without `::`. Key mlr3misc utilities: `map()`, `map_chr()`, `invoke()`, `calculate_hash()`, `str_collapse()`, `%nin%`, `%??%`.