Unify CPM workflow around spec() and cpm()

.Rbuildignore

@@ -12,3 +12,7 @@
 ^[.]?air[.]toml$
 ^\.vscode$
 ^touchstone$
+^doc$
+^Meta$
+^touchstone$
+^\.agents($|/)

.agents/skills/cpmr-r-development/SKILL.md

@@ -0,0 +1,45 @@
+---
+name: cpmr-r-development
+description: Use when working in the cpmr repository to preserve its spec()/cpm() API, staged CPM configuration, direct internal flow, AIR formatting, pkgdown site checks, full test coverage, and final devtools::check() validation.
+---
+
+# cpmr R Development
+
+Use this skill for code, tests, docs, review, and release-quality validation in this repository.
+
+## API and design rules
+
+- Public entry points are `spec()` and `cpm()`. Do not reintroduce `fit()`, `fit_resamples()`, `cpm_spec()`, or `cpm_resamples()`.
+- Keep CPM model definition separate from execution settings.
+  `spec()` holds staged CPM choices; `cpm()` holds runtime settings such as `resamples`, `covariates`, `return_edges`, and `na_action`.
+- Keep validation and normalization at public constructors and workflow entry points. Internal runtime paths should trust staged objects instead of re-validating them.
+- Prefer direct, stepwise code. Avoid extra helper layers unless they remove real duplication or clarify a stable boundary.
+- Private helpers should usually come after their primary callers so the main workflow reads top-down.
+- Keep `tests/testthat` aligned with the current `R/` module boundaries. When `R/` files are merged, renamed, or deleted, rename or regroup the corresponding tests so the test layout does not preserve outdated file or concept names. If several source files are intentionally collapsed into one module, collapse the corresponding tests too instead of preserving the older split.
+- After user-facing API, workflow, summary, or documentation changes, review `NEWS.md` against the current `main` branch. Keep only entries that are still true for the branch being worked on, and remove stale wording carried over from abandoned designs.
+- Version changes are release tasks, not routine development chores. Use `usethis::use_version()` when preparing a release bump, and `usethis::use_dev_version()` when starting the next development cycle after a release. During ordinary development, do not change the development version unless explicitly asked.
+
+## CPM architecture
+
+- Treat CPM as a staged workflow: screen edges, summarize selected signal, then fit the outcome model.
+- The default user workflow is fold-based through `cpm()`.
+- Keep train-only computations leakage-safe. Anything learned from training data and reused at assessment time belongs in the fitted runtime state, not in public configuration.
+
+## Code quality flow
+
+Run this sequence after meaningful changes:
+
+1. `devtools::document()`
+2. `devtools::test()`
+3. `pkgdown::build_site(preview = FALSE, install = TRUE)`
+4. `cov <- covr::package_coverage()`
+5. `covr::percent_coverage(cov)` must be `100`
+6. If coverage is short, inspect `covr::zero_coverage(cov)` and close the gap
+7. `devtools::check()`
+
+## Tooling notes
+
+- Format with `air`, for example `air format .` or `air format R/file.R`.
+- Because this repository tracks pkgdown configuration, update `_pkgdown.yml` when exported topics or public narratives change.
+- On Windows, use Quarto or the RStudio-bundled Pandoc if `devtools::check()` or `pkgdown` needs Pandoc.
+- Build the pkgdown site with installation enabled when vignettes call `library(cpmr)`.

.agents/skills/cpmr-r-development/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "cpmr R Development"
+  short_description: "Use for cpmr API and validation workflows."
+  default_prompt: "Use this skill when working in the cpmr repository. Preserve the public spec()/cpm() API, keep staged CPM configuration separate from runtime settings, prefer direct stepwise code over extra helper layers, and validate changes with air, devtools::document(), devtools::test(), pkgdown::build_site(preview = FALSE, install = TRUE), 100% coverage, then devtools::check()."

.gitattributes

@@ -0,0 +1,11 @@
+# Keep repository text files on LF across platforms.
+* text=auto eol=lf
+
+# Treat common package artifacts as binary.
+*.png binary
+*.jpg binary
+*.jpeg binary
+*.gif binary
+*.pdf binary
+*.rds binary
+*.RData binary

.github/workflows/document.yaml

@@ -0,0 +1,46 @@
+# Workflow derived from https://github.com/r-lib/actions/tree/v2/examples
+# Need help debugging build failures? Start at https://github.com/r-lib/actions#where-to-find-help
+on:
+  push:
+    paths: ["R/**"]
+
+name: document.yaml
+
+permissions: read-all
+
+jobs:
+  document:
+    runs-on: ubuntu-latest
+    env:
+      GITHUB_PAT: ${{ secrets.GITHUB_TOKEN }}
+    permissions:
+      contents: write
+    steps:
+      - name: Checkout repo
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Setup R
+        uses: r-lib/actions/setup-r@v2
+        with:
+          use-public-rspm: true
+
+      - name: Install dependencies
+        uses: r-lib/actions/setup-r-dependencies@v2
+        with:
+          extra-packages: any::roxygen2
+          needs: roxygen2
+
+      - name: Document
+        run: roxygen2::roxygenise()
+        shell: Rscript {0}
+
+      - name: Commit and push changes
+        run: |
+          git config --local user.name "$GITHUB_ACTOR"
+          git config --local user.email "$GITHUB_ACTOR@users.noreply.github.com"
+          git add man/\* NAMESPACE DESCRIPTION
+          git commit -m "Update documentation" || echo "No changes to commit"
+          git pull --ff-only
+          git push origin

.github/workflows/pkgdown.yaml

@@ -44,6 +44,5 @@ jobs:
         if: github.event_name != 'pull_request'
         uses: JamesIves/github-pages-deploy-action@v4.5.0
         with:
-          clean: false
           branch: gh-pages
           folder: docs

.gitignore

@@ -5,3 +5,9 @@
 .DS_Store
 .quarto
 docs
+/doc/
+/Meta/
+.agents/*
+!.agents/skills/
+!.agents/skills/cpmr-r-development/
+!.agents/skills/cpmr-r-development/**

DESCRIPTION

@@ -11,6 +11,8 @@ Description: Connectome Predictive Modelling (CPM) (Shen et al. (2017)
 License: MIT + file LICENSE
 URL: https://github.com/psychelzh/cpmr, https://psychelzh.github.io/cpmr/
 BugReports: https://github.com/psychelzh/cpmr/issues
+Depends:
+    R (>= 4.4.0)
 Imports:
     generics,
     Rfast,
@@ -21,10 +23,10 @@ Suggests:
     rmarkdown,
     testthat (>= 3.0.0),
     withr
-VignetteBuilder: 
+VignetteBuilder:
     knitr
 Config/testthat/edition: 3
 Config/testthat/parallel: true
 Encoding: UTF-8
 Roxygen: list(markdown = TRUE)
-RoxygenNote: 7.3.2
+RoxygenNote: 7.3.3

NAMESPACE

@@ -1,9 +1,14 @@
 # Generated by roxygen2: do not edit by hand
 
 S3method(print,cpm)
+S3method(print,cpm_spec)
 S3method(print,cpm_summary)
 S3method(summary,cpm)
 S3method(tidy,cpm)
 export(cpm)
+export(cpm_construction_strength)
+export(cpm_model_lm)
+export(cpm_selection_cor)
+export(spec)
 export(tidy)
 importFrom(generics,tidy)

NEWS.md

@@ -1,12 +1,34 @@
 # cpmr (development version)
 
+## Breaking changes
+
+* `cpm()` now uses a staged specification created by `spec()`. The old
+  `thresh_method`, `thresh_level`, `kfolds`, and `bias_correct` arguments have
+  been replaced by `spec`, `resamples`, and staged helper constructors.
+* Removed the deprecated `confounds` alias. Use `covariates` instead.
+* The returned `cpm` object now stores workflow state under `spec`,
+  `settings`, `predictions`, and `folds`. Code that accessed the old
+  `real`, `pred`, or `params` fields must be updated.
+
 ## Enhancements
 
-* Clarified `print.cpm()` output when edges are not stored and hardened `summary.cpm()` fold fallback for legacy objects.
+* Added `spec()` together with `cpm_selection_cor()`,
+  `cpm_construction_strength()`, and `cpm_model_lm()` to make screening,
+  summarization, and outcome-model choices explicit.
+* `cpm()` now accepts integer or manual assessment plans through `resamples`,
+  while keeping leave-one-out assessment as the default when `resamples` is
+  `NULL`.
+* `summary.cpm()` and `tidy.cpm()` now focus on correlation-based reporting,
+  with pooled and fold-wise correlation tables plus optional edge summaries.
+* Reworked package documentation and pkgdown navigation around the
+  `spec()` + `cpm()` workflow, including a native getting-started vignette.
 
 ## Maintenance
 
-* Stabilized GitHub Actions uploads for Codecov coverage and Test Analytics by generating and uploading JUnit test results from an explicit workspace path.
+* Simplified the internal CPM workflow around fold-based execution and aligned
+  `tests/testthat` with the current `R/` modules.
+* Hardened assessment-fold validation and leakage-safe preprocessing so each
+  fold must retain at least 3 complete-case training observations.
 
 # cpmr 0.1.1