From 0b491c44166a73afc23434aea86a8bbdc45a321f Mon Sep 17 00:00:00 2001
From: thePR0M3TH3AN <53631862+PR0M3TH3AN@users.noreply.github.com>
Date: Fri, 30 May 2025 17:35:00 -0400
Subject: [PATCH] Enhance AGENTS.md with execution commands and usage
 conventions

Added detailed instructions for invoking Python scripts via the startup wrapper in AGENTS.md. Updated repo-context.txt to reflect the inclusion of AGENTS.md and its contents, providing clarity on project structure and usage guidelines.
---
 AGENTS.md        |  6 ++++
 repo-context.txt | 71 ++++++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 77 insertions(+)

diff --git a/AGENTS.md b/AGENTS.md
index c518b57..90b779d 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -1,5 +1,11 @@
 # AGENTS.md — Guidance for OpenAI Codex
 
+## Execution Commands
+- **Always** invoke Python scripts via the startup wrapper to activate dependencies:
+  
+  ```bash
+  ./startup.sh --offset <months> --end <YYYY-MM-DD> --extend-years <N>
+
 ## Project Overview
 
 This repository, **python\_charts**, provides a framework for fetching economic time series from FRED, storing them locally, and producing custom matplotlib charts with configurable parameters. The core components are:
diff --git a/repo-context.txt b/repo-context.txt
index 61c14ac..afecdf7 100644
--- a/repo-context.txt
+++ b/repo-context.txt
@@ -12,6 +12,7 @@ Generated on: 2025-05-30
         ├── lagged_oil_unrate_chart_styled.py
         ├── pyproject.toml
         ├── refresh_data.py
+    ├── AGENTS.md
     ├── Makefile
     ├── README.md
     ├── requirements.txt
@@ -20,6 +21,76 @@ Generated on: 2025-05-30
 
 ## Important Files
 
+## python_charts/AGENTS.md
+```markdown
+# AGENTS.md — Guidance for OpenAI Codex
+
+## Project Overview
+
+This repository, **python\_charts**, provides a framework for fetching economic time series from FRED, storing them locally, and producing custom matplotlib charts with configurable parameters. The core components are:
+
+* **`startup.sh`**: Single-entrypoint script to bootstrap a Python venv, install dependencies, fetch data, and run specified commands under the venv interpreter.
+* **`Makefile`**: Convenient high-level targets (`install`, `data`, `plot`, `plot-custom`, `test`, `clean`) that funnel through `startup.sh` for reproducible builds.
+* **`scripts/refresh_data.py`**: Downloads UNRATE and DCOILWTICO series into `data/fred.db`.
+* **`scripts/lagged_oil_unrate_chart_styled.py`**: Generates the lagged oil vs. unemployment chart with fixed axes styling and log scale.
+
+Future extensions will add additional custom chart scripts under `scripts/`, all driven by the same bootstrapping and command conventions.
+
+## Usage Conventions
+
+### Primary Commands
+
+* **Bootstrap & default plot**: `./startup.sh` or `make plot` — runs the lagged-oil chart with an 18‑month offset.
+* **Custom plot**: `./startup.sh --offset 12 --end 2025-05-31 --extend-years 5` or `make plot-custom ARGS="--offset 12 --end 2025-05-31 --extend-years 5"`.
+* **Data refresh**: `./startup.sh scripts/refresh_data.py` or `make data`.
+* **Run tests**: `./startup.sh pytest -q` or `make test`.
+
+### Argument Rules
+
+* Arguments beginning with `--` are forwarded to the default chart script.
+* If the first token is a `.py` script or executable, it is invoked under the venv’s Python.
+* Otherwise, commands are executed directly (e.g. linters, test frameworks).
+
+## Coding Standards
+
+* **Python**: Target version 3.12. Use type hints for all function signatures. Follow PEP8 with **Black** formatting.
+* **Bash**: `startup.sh` must use `set -euo pipefail` and always call `$VENV_DIR/bin/python` to avoid system‑Python mismatches.
+* **Makefile**: Use tab‑indented commands. All tasks should funnel to `startup.sh`.
+
+## Testing & Validation
+
+* **Automated tests**: No current tests; add pytest modules under `tests/` following the pattern `test_*.py`.
+* **Data mocking**: For new chart scripts, mock FRED downloads via monkeypatching `pandas_datareader.data.DataReader`.
+
+## Extending with New Charts
+
+1. **Create a new script** under `scripts/`, for example `scripts/custom_chart.py`.
+2. **Implement** a `main()` accepting `--start`, `--end`, `--offset` or custom args using `argparse`.
+3. **Leverage** `startup.sh` invocation: add usage example in your script’s docstring.
+4. **Update** the `Makefile` if you need a dedicated target, otherwise users can call:
+
+   ```bash
+   ./startup.sh python scripts/custom_chart.py --your-args
+   ```
+
+## CI / Codex Integration
+
+* In Codex cloud or CLI tasks, set the **Setup Script** to `./startup.sh install data` to ensure dependencies and data are ready.
+* **Task Commands** should call `make plot` or `make test`, which delegates to `startup.sh`.
+* **AGENTS.md** is automatically loaded by Codex to understand structure and commands.
+
+## PR & Commit Guidelines
+
+* Prefix branches/PRs with `feature/` or `fix/`.
+* Commit messages: `<type>(<scope>): <description>` (e.g. `feat(charts): add custom inflation plot`).
+* Include screenshots or saved chart outputs under `outputs/` for visual verification.
+
+---
+
+*End of AGENTS.md — tailored for python\_charts repo*
+
+```
+
 ## python_charts/README.md
 ```markdown
 # Lagged Oil–Unemployment Chart