Update AGENTS.md with detailed execution command guidelines

Clarify the usage of the `startup.sh` wrapper for running Python scripts, emphasizing the importance of module execution and correct import resolution. Include examples for preferred script invocation and reinforce the need to avoid running `refresh_data.py` in environments without internet access. Adjust language for clarity and consistency throughout the document.

AGENTS.md

@@ -1,13 +1,30 @@
 # AGENTS.md — Guidance for OpenAI Codex
 
 ## Execution Commands
-- **Always** invoke Python scripts via the startup wrapper, which installs dependencies globally and then runs your code under the system Python:
+- **Always** invoke Python scripts via the `startup.sh` wrapper, which installs dependencies globally and then runs your code under the system Python. In particular, don’t run a `.py` file directly if it uses imports like `from scripts.common …`. Instead, run it as a module or let `startup.sh` handle it. For example:
-  
+
   ```bash
+  # Preferred: let startup.sh dispatch to scripts.lagged_oil_unrate_chart_styled
   ./startup.sh --offset <months> --end <YYYY-MM-DD> --extend-years <N>
+
+  # Or explicitly in module mode, so that 'scripts' is on PYTHONPATH:
+  ./startup.sh python -m scripts.lagged_oil_unrate_chart_styled --offset <months> --end <YYYY-MM-DD> --extend-years <N>
 ````
 
-* **Never** call `refresh_data.py` from within a Task Command. This environment has **no internet access**, so attempts to fetch external data will fail. Data in `data/fred.db` must already be present.
+* Running a script this way ensures that `import scripts.common` (and other `scripts.*` imports) resolve correctly.
+
+* If you ever need to call a different script, still invoke it under `./startup.sh`, for example:
+
+  ```bash
+  # Custom-chart example:
+  ./startup.sh python -m scripts.custom_chart --series UNRATE DCOILWTICO --start 2000-01-01 --end 2020-12-31
+  ```
+
+* **Never** call `refresh_data.py` from within a Task Command. This environment has **no internet access**, so attempts to fetch external data will fail. Data in `data/fred.db` must already be present. If you need to refresh data, run it only in an internet-connected shell:
+
+  ```bash
+  python scripts/refresh_data.py --series UNRATE DCOILWTICO --start 1973-01-01
+  ```
 
 ## Policy for Handling UNRATE Null Values
 
@@ -20,7 +37,7 @@ When generating the UNRATE vs. Oil chart, the UNRATE series may include a `NaN`
      ```python
      last_date = unrate.last_valid_index()
      ```
-   * Truncate both `unrate` and `oil` so that any trailing `NaN` row in `unrate` (and corresponding index in `oil`) is removed:
+   * Truncate both `unrate` and `oil` so that any trailing `NaN` row in `unrate` (and the corresponding index in `oil`) is removed:
 
      ```python
      unrate = unrate.loc[:last_date]
@@ -35,7 +52,13 @@ When generating the UNRATE vs. Oil chart, the UNRATE series may include a `NaN`
 
 3. **Implementation in `lagged_oil_unrate_chart_styled.py`**
 
-   * Right after `unrate, oil = fetch_series(start_dt, end_dt, args.db)`, insert:
+   * Right after:
+
+     ```python
+     unrate, oil = fetch_series(start_dt, end_dt, args.db)
+     ```
+
+     insert:
 
      ```python
      last_date = unrate.last_valid_index()
@@ -67,7 +90,7 @@ Future extensions will add additional custom chart scripts under `scripts/`, all
   ./startup.sh
   ```
 
-  Installs/upgrades dependencies globally and runs the default lagged‐oil chart with an 18‐month offset.
+  Installs/upgrades dependencies globally and runs the default lagged-oil chart with an 18-month offset.
 
 * **Custom plot**:
 
@@ -75,13 +98,15 @@ Future extensions will add additional custom chart scripts under `scripts/`, all
   ./startup.sh --offset 12 --end 2025-05-31 --extend-years 5
   ```
 
+  (Equivalent to `./startup.sh python -m scripts.lagged_oil_unrate_chart_styled --offset 12 --end 2025-05-31 --extend-years 5`.)
+
 * **Data refresh (offline environments)**:
 
   * **Do not** run `refresh_data.py` in Codex/CI — data must already be in `data/fred.db`.
-  * To update data in an internet‐connected shell, run:
+  * To update data in an internet-connected shell, run:
 
     ```bash
-    python scripts/refresh_data.py
+    python scripts/refresh_data.py --series UNRATE DCOILWTICO
     ```
 
 * **Run tests**:
@@ -92,15 +117,15 @@ Future extensions will add additional custom chart scripts under `scripts/`, all
 
 ### Argument Rules
 
-* If the first token starts with `--`, it’s forwarded to the default chart script.
+* If the first token starts with `--`, it’s forwarded to the default chart script (`scripts.lagged_oil_unrate_chart_styled`).
-* If the first token names a `.py` script, it’s executed via `python <script>`.
+* If the first token names a `.py` script, it’s executed via `python <script>` only when you explicitly need to bypass `startup.sh`.
 * Otherwise, commands are executed directly (e.g., `pytest`, `flake8`).
 
 ## Coding Standards
 
 * **Python**: Target version ≥ 3.8. Use type hints for all function signatures. Follow PEP8 with Black formatting.
 * **Bash**: `startup.sh` uses `set -euo pipefail`.
-* **Makefile**: Use tab‐indented commands. All targets should funnel through `startup.sh`.
+* **Makefile**: Use tab-indented commands. All targets should funnel through `startup.sh`.
 
 ## Testing & Validation
 
@@ -115,7 +140,7 @@ Future extensions will add additional custom chart scripts under `scripts/`, all
 3. **Invoke** via:
 
    ```bash
-   ./startup.sh python scripts/custom_chart.py --your-args
+   ./startup.sh python -m scripts.custom_chart --your-args
    ```
 4. **Optionally** add a Makefile target if desired.