Update AGENTS.md

Signed-off-by: Tomas Pereira de Vasconcelos <tomasvasconcelos1@gmail.com>

Author: tpvasconcelos

AGENTS.md

@@ -1,44 +1,22 @@
 # ridgeplot Development Guide for AI Agents
 
-`ridgeplot` is a Python package that provides a simple interface for plotting beautiful and interactive ridgeline plots within the extensive Plotly ecosystem.
+`ridgeplot` is a Python package for beautiful, interactive ridgeline plots built on Plotly.
 
-This file provides guidance for AI assistants working with the ridgeplot codebase.
+## Start Here
 
-## Public API Overview
+- Read this file first, then the most relevant source file(s).
+- Prefer local docs and tests over memory; do not guess behavior.
+- If requirements are unclear or risky, ask a concrete question before changing code.
 
-The library only exposes three public functions to end users.
+## Stack and Style Constraints
 
-Two of these functions are toy dataset loaders (`ridgeplot.datasets.load_probly()` and
-`ridgeplot.datasets.load_lincoln_weather()`) but they are not the focus on the project and are only exposed for backwards compatibility reasons.
+- Python >=3.10
+- Plotly graph objects (dependency is `plotly>=5.20`)
+- Line length 100, formatting with ruff
+- Docstrings are NumPy style
+- Type annotations are modern and throughout with strict checking via pyright
 
-The third function (`ridgeplot.ridgeplot()`) is a Plotly Figure (
-`plotly.graph_objects.Figure`) factory function, and it's the focus of this project. See its docstring at
-`src/ridgeplot/_ridgeplot.py` for full details.
-
-## .cursor rules directory
-
-You can check
-`.cursor/rules` before providing recommendations or generating code. This directory contains the authoritative rules for all development aspects.
-
-To find the relevant rules:
-
-1. Find ALL .md files in `.cursor/rules`
-2. Read ALL relevant rules files, based on the filetypes/languages/libraries/tasks/folders involved (e.g., .tsx, .css, .java, React,
-   `//web/src/pages/home`, etc)
-3. If unsure, read metadata (first 5 lines) of any .mdc file to check rule scope/description/keywords
-
-**For common tasks, you can check these specific files:**
-
-- Bazel/testing: `.cursor/rules/bazel-test-execution.mdc`
-- Java code: `.cursor/rules/java-conventions.mdc`
-- TypeScript/web: `.cursor/rules/web-conventions.mdc`
-- Pull requests: `.cursor/rules/pull-request-conventions.mdc`
-
-**Documentation:** https://ridgeplot.readthedocs.io/en/stable/
-
-**Python Version**: Requires Python 3.10+
-
-## Common Commands
+## Quick Commands
 
 ### Environment Setup
 
@@ -50,7 +28,7 @@ make init
 # Use a different Python version if needed (default is python3.10)
 BASE_PYTHON=python3.14 make init
 
-# Offline mode (uses cached packages only) -  useful when the internet is down
+# Offline mode (uses cached packages only)
 OFFLINE=1 make init
 
 # Activate the virtual environment
@@ -60,7 +38,7 @@ source .venv/bin/activate
 ### Running Tests
 
 ```bash
-# Run all test suits (unit + e2e + cicd_utils)
+# Run all test suites (unit + e2e + cicd_utils)
 tox -m tests
 
 # Run a specific test suite
@@ -99,7 +77,7 @@ tox -e typing
 tox -e docs-static
 ```
 
-## Architecture Overview
+## Project Map
 
 ```
 src/ridgeplot/
@@ -137,63 +115,68 @@ cicd_utils/               # CI/CD helper modules
 └── ridgeplot_examples/   # Example implementations for docs/testing
 ```
 
-### Key Data Flow
+## Public API
 
-1. User calls `ridgeplot(samples=...)` or `ridgeplot(densities=...)`
-2. If samples provided → KDE (`_kde.py`) or histogram binning (`_hist.py`) produces densities
-3. Densities are normalised if `norm` parameter is set
-4. `create_ridgeplot()` in `_figure_factory.py` builds the Plotly Figure:
-    - Resolves colorscale and computes colors for each trace
-    - Creates trace objects (area or bar) for each density
-    - Applies layout settings (spacing, padding, axes)
-5. Returns a `plotly.graph_objects.Figure` that users can further customise
+The public API exposes one main function: `ridgeplot.ridgeplot(...) -> go.Figure`
 
-### Type System
+The `ridgeplot()` docstring in `src/ridgeplot/_ridgeplot.py` contains the API contract.
 
-The codebase uses extensive type annotations. Key types in `_types.py`:
+`ridgeplot.datasets.load_probly()` and
+  `ridgeplot.datasets.load_lincoln_weather()` are legacy loaders kept for
+  backwards compatibility only.
 
-- **Samples/Densities**: Ragged 3D arrays `[rows][traces_per_row][values]`
-- **ShallowSamples/ShallowDensities**: 2D arrays (one trace per row)
-- **ColorScale**: `Collection[tuple[float, Color]]`
-- **Type guards**: `is_shallow_samples()`, `is_densities()`, etc.
+## Key Data Flow
 
-## Code Style Guidelines
+1. Users call `ridgeplot(samples=...)` or `ridgeplot(densities=...)`.
+2. If samples are provided, KDE in `_kde.py` or histogram binning in `_hist.py`
+   produces densities.
+3. Densities are normalised if the `norm` parameter is set.
+4. `create_ridgeplot()` in `_figure_factory.py` builds the Plotly Figure by
+   resolving colors, creating traces, and applying layout settings.
+5. The function returns a `plotly.graph_objects.Figure`.
 
-### General
+## Key Files to Know
 
-- **Python version**: 3.10+ (uses modern typing features)
-- **Line length**: 100 characters
-- **Formatting**: Ruff (replaces black, isort, flake8)
-- **Imports**: Always include `from __future__ import annotations`
-- **Docstrings**: NumPy style
-- **Type annotations**: Use full and modern type annotations throughout with strict pyright checking
+| File                               | Purpose                     |
+|------------------------------------|-----------------------------|
+| `src/ridgeplot/_ridgeplot.py`      | Main `ridgeplot()` function |
+| `src/ridgeplot/_figure_factory.py` | Figure construction logic   |
+| `src/ridgeplot/_types.py`          | All type aliases and guards |
+| `tests/unit/test_ridgeplot.py`     | Core function tests         |
+| `cicd_utils/ridgeplot_examples/`   | Example scripts for docs    |
+| `docs/`                            | User and developer docs     |
+| `tox.ini`                          | CI environment definitions  |
+| `ruff.toml`                        | Linting configuration       |
 
-### Type Annotations
+Documentation: https://ridgeplot.readthedocs.io/en/stable/
 
-- All functions must be fully typed
-- Use `TYPE_CHECKING` blocks for import-only types
-- Uses **pyright** in strict mode (see `pyrightconfig.json`)
-- Use type guards for runtime type narrowing (see `_types.py`)
-- Follow this general principle for user-facing code: be contravariant in the input type and covariant in the output type
-
-## Working with This Codebase
+## Workflow Expectations
 
 ### When Adding New Features
 
-1. Start with `_ridgeplot.py` to understand the main entry point
-2. Add new parameters following the existing patterns (with proper deprecation handling)
-3. Update type annotations in `_types.py` if introducing new data structures
-4. Add tests in `tests/unit/` with good coverage
-5. Update documentation in docstrings following the existing conventions
+1. Start with `src/ridgeplot/_ridgeplot.py` to understand the entry point.
+2. Add parameters following existing patterns and deprecation handling.
+3. Update types in `src/ridgeplot/_types.py` when introducing new structures.
+4. Add tests in `tests/unit/` with good coverage.
+5. Update docstrings to match the new behavior.
 
 ### When Fixing Bugs
 
-1. Write a failing test first
-2. Fix the issue with minimal changes
-3. Ensure all existing tests pass
-4. Check type annotations are correct
+1. Write a failing test first.
+2. Fix the issue with minimal changes.
+3. Ensure tests and type checks pass.
+4. Verify docstrings remain accurate.
 
-### Common Patterns
+### Type Annotations
+
+- Uses **pyright** in strict mode (see `pyrightconfig.json`)
+- All functions must be fully typed, following modern Python typing practices and existing project conventions.
+- Use `TYPE_CHECKING` blocks for import-only types
+- Use type guards for runtime type narrowing (see `_types.py`)
+- Follow this general principle for user-facing code: be contravariant in the input type and covariant in the output type
+- Add type aliases close to their usage. If widely used, place in `_types.py`.
+
+## Common Patterns
 
 **Handling deprecated parameters:**
 
@@ -221,44 +204,29 @@ def _coerce_to_densities(...):
     from ridgeplot._kde import estimate_densities  # statsmodels is slow to import
 ```
 
-### Testing Tips
+## Testing Notes
 
 - Use `--no-cov` flag during development for faster test runs
-- Run specific tests: `tox -e pytest -- tests/unit/test_ridgeplot.py -k "test_name" --no-cov`
+- Run targeted tests via: `tox -e pytest -- tests/unit/test_foo.py -k "test_bar" --no-cov`
 - The `tests/e2e/artifacts/` directory contains expected Plotly Figure JSON for e2e tests
-- `conftest.py` patches `fig.show()` to prevent browser windows during tests
 
-### Key Files to Know
+## .cursor Rules
 
-| File                               | Purpose                     |
-|------------------------------------|-----------------------------|
-| `src/ridgeplot/_ridgeplot.py`      | Main `ridgeplot()` function |
-| `src/ridgeplot/_figure_factory.py` | Figure construction logic   |
-| `src/ridgeplot/_types.py`          | All type aliases and guards |
-| `tests/unit/test_ridgeplot.py`     | Core function tests         |
-| `cicd_utils/ridgeplot_examples/`   | Example scripts for docs    |
-| `tox.ini`                          | CI environment definitions  |
-| `ruff.toml`                        | Linting configuration       |
+Check `.cursor/rules` before changing platform or version support. The only
+current rule is for adding or dropping Python versions at
+`.cursor/rules/dropping-and-or-adding-support-for-python-versions/RULES.md`.
 
 ## CI/CD Pipeline
 
-Tests run on GitHub Actions across:
-
-- Python versions: 3.10, 3.11, 3.12, 3.13, 3.14
-- Operating systems: Ubuntu, macOS, Windows
-
-Coverage is uploaded to Codecov with:
-
-- Overall: 98% minimum
-- Diff coverage: 100% for new code
+GitHub Actions runs tests on Python 3.10–3.14 across Ubuntu, macOS, and Windows.
+Codecov minimums are 98% overall and 100% diff coverage for new code.
 
 ## Notes for AI Assistants
 
-1. **Always run tests** after making changes: `tox -e pytest -- <path> --no-cov`
-2. **Check types** with: `tox -e typing`
-3. **Format code** with: `pre-commit run ruff-format --all-files`
-4. **Respect existing patterns** - this is a mature codebase with consistent style
-5. **Don't add unnecessary abstractions** - keep changes minimal and focused
-6. **Preserve deprecation warnings** - the library maintains backward compatibility
-7. **Update docstrings** when changing function signatures
-8. **Use type guards** for runtime type narrowing instead of assertions
+1. Run tests after changes when feasible, starting with the smallest relevant
+   subset.
+2. Run `tox -e typing` if types are touched or errors are likely.
+3. Run `pre-commit run ruff-format --all-files` to format code.
+4. Preserve deprecation behavior and public API stability.
+5. Keep changes minimal and aligned with existing patterns.
+6. Respect existing patterns - this is a mature codebase with consistent style.