# Contributing

## Setup

Use the shared Python 3.12 virtual environment:

```bash
source ~/.pyenv/python3.12-venv/bin/activate
python -m pip install -r requirements.txt
```

If you install another package for repository work, add its direct dependency
to `requirements.txt`.

## Repository layout

- Put notebooks in `notebooks/`.
- Put reusable Python and Bash utilities in `scripts/`.
- Put local input files in `data/`.
- Put generated artifacts in `results/`.

The contents of `data/` and `results/` are ignored. Do not force-add test
databases, raw test results, generated exports, or notebook outputs.

`__SAV__/` is unrelated legacy material and is outside the active project.

## Working with notebooks

Notebooks must execute from top to bottom in a fresh kernel. Use relative paths,
document data assumptions, and move reusable logic into tested scripts.

Before handing off a change:

```bash
python -m pytest
python -m pytest --nbmake notebooks
jupyter nbconvert --ClearOutputPreprocessor.enabled=True --inplace path/to/notebook.ipynb
```

Run only the checks relevant to the files present in the repository, and report
anything that could not be run.

## Review requirement

Python scripts, Bash scripts, and notebook code-cell changes require review and
approval by a separate background agent. Address material findings and rerun
affected checks before completion. If a reviewer is unavailable, the change may
be handed off only with the status `review pending`.

Documentation, dependency declarations, and ignore rules do not require this
background review when no Python, Bash, or notebook code cells changed.

The `master` branch is not protected. That does not remove the review
requirement or authorize an agent to commit or push without an explicit request.