docs: add ARCHITECTURE.md documenting repo design and structure

[drbenvincent]

Summary

Add ARCHITECTURE.md documenting CausalPy's internal design — the layered structure, module responsibilities, and extension points — so contributors (human and AI) can understand where things live without reading thousands of lines of source.

Fixes #843

Changes

• ARCHITECTURE.md (new): Covers the experiment layer (BaseExperiment contract, all 10 experiment classes), the two-backend model system (PyMC + scikit-learn), the reporting layer (EffectSummary, Bayesian vs OLS output paths), the pipeline system (Step protocol, validate-before-run), the checks/sensitivity system (9 checks with applicable_methods), the formula interface (step/ramp transforms), the data layer (load_data dispatcher), support modules, test organization, and extension points for adding new experiments/models/checks.
• CONTRIBUTING.md: Added a checklist item requiring ARCHITECTURE.md updates for structural PRs.
• AGENTS.md: Added an "Architecture documentation" section with a reference to ARCHITECTURE.md and the update policy.

Also consolidates #562 (Create developer-focused RESEARCH.md), which was closed as a near-duplicate.

Testing

Documentation-only change — no code modified, no tests needed. prek run --all-files passes.

Checklist

• ARCHITECTURE.md describes the current codebase accurately
• CONTRIBUTING.md PR checklist updated
• AGENTS.md update policy added
• prek run --all-files passes

[drbenvincent]

Would be very grateful for a review on this @ulfaslak. It's the first time I've tried to properly create a code repo overview in order to guide an agent. Your experience might highlight unnecessary contents in ARCHITECTURE.md, like the directory layout maybe?

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 94.26%. Comparing base (cd89079) to head (edc2d12).

Additional details and impacted files

@@           Coverage Diff           @@
##             main     #845   +/-   ##
=======================================
  Coverage   94.26%   94.26%           
=======================================
  Files          78       78           
  Lines       12005    12005           
  Branches      699      699           
=======================================
  Hits        11317    11317           
  Misses        496      496           
  Partials      192      192           

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[read-the-docs-community]

Documentation build overview

📚 causalpy | 🛠️ Build #32277936 | 📁 Comparing edc2d12 against latest (cd89079)

  🔍 Preview build  

1 files changed

± 404.html

[drbenvincent]

Superseded by #924, which covers the same scope (ARCHITECTURE.md + AGENTS.md reference) with updated content reflecting the current codebase.