# AGENTS.md — replication package

Instructions for AI coding assistants (and people) changing this package.
Read README.md first for what the package reproduces.

## The contract

Every analysis is a self-contained script:

```
code/<name>/
  <name>.py          reads data/ (or another script's output/), writes ONLY to output/
  output/<name>.json the result, shipped as the expected output
```

1. Locate files relative to the script:
   `PACKAGE_ROOT = Path(__file__).resolve().parents[2]`, then `PACKAGE_ROOT / "data"`.
   Never assume the package folder's name or the working directory.
2. Treat `data/` as read-only. Never edit it by hand or from a script.
3. Write only into your own `output/`, as JSON with a `meta` block
   (`script`, `generated` timestamp) and the results.
4. Start the script with a docstring: why it exists, which exhibit it
   reproduces, inputs, outputs.

## Adding or changing an analysis

1. Create `code/<name>/<name>.py` following the contract (copy
   `code/examples/father_rank_by_decade/` for a new question).
2. Register it in `code/manifest.py` with its outputs and the exhibit(s) it
   reproduces (or "Supplementary").
3. Run `python code/run_all.py --only <name>` and inspect the output.
4. Update the exhibit table in README.md and the script table in code/README.md.

## Verifying

`python code/run_all.py --check` must end with "All N script(s) reproduced
the shipped results." It refuses to verify against outputs a previous plain
run overwrote (checked via `code/shipped_outputs.sha256`, generated when the
package is built — never edit it). Report failures and "NOT VERIFIED" lines
verbatim.
Never edit an output file by hand, and never state a number you did not get
by running the code.

## Environment

`conda env create -f code/environment.yml` gives Python ≥ 3.11 with
pandas, numpy, scipy, statsmodels and matplotlib.