roadtrip-skill: Instructions file for Codex

AGENTS.md — Universal Rulebook

Vendor-agnostic technical rules for working in this repo. Applies to any AI agent or human. For product/domain background see CONTEXT.md.

Branching Rule

• When creating git branches, if current base branch is not default branch (main), you should prompt user to specify base branch
• When submitting pull request (PR), you should set PR base branch as the current local base branch, instead of the browser github's default base branch

Hard constraints

• Python 3.8+ standard library only for assets/, scripts/, and tools/. No third-party pip packages at runtime (urllib, json, re, math, …). Do not add runtime dependencies. Sole exception: mcp_server/ depends on the mcp SDK (declared in pyproject.toml) — never let it leak into the other dirs. Dev dependencies are pytest plus mcp for tests/test_mcp_server.py, which auto-skips when mcp is absent so the stdlib+pytest baseline stays green.
• Zero required API keys. Everything must run and test with no keys and no network. Keys (NPS_API_KEY, OCM_API_KEY, OPENWEATHER_API_KEY) are read from env vars only and are strictly optional upgrades.
• Use python3 (there is no python on the standard dev machine).

Commands

# One-time: venv + test dependency (only pytest is needed)
python3 -m venv .venv && . .venv/bin/activate && pip install pytest

# Run the full test suite (CI runs exactly this)
python3 -m pytest tests/ -v

# Run a single test file / test
python3 -m pytest tests/test_generate.py -v
python3 -m pytest tests/test_helper.py -k drive_intensity -v

# Render a tripData JSON into the single-file HTML (the core output step)
python3 assets/generate.py assets/tripData.example.json -o trip.html

# Exercise helpers / clients standalone (each has a __main__ demo)
python3 scripts/helper.py "from Las Vegas, 7 days, 2 adults, gas, southwest loop"
python3 scripts/helper.py --compare
python3 tools/charging_client.py --corridor
python3 tools/routing_client.py 36.17,-115.14 37.30,-113.03

# Render the other bundled demo trips
python3 assets/generate.py assets/tripData.tahoe.json -o assets/preview-tahoe.html
python3 assets/generate.py assets/tripData.pnw.json   -o assets/preview-pnw.html

# Probe other data sources directly
python3 tools/border_client.py US MX --rental
python3 tools/parks_client.py --countdown 2026-09-12
python3 tools/charging_client.py --leg 165 280
python3 tools/places_client.py "Zzyzx, CA"   # place-name existence gate ("ABC" → no-match)

# MCP server: serve over stdio / run its tests (the one part that needs the mcp SDK)
pip install -e ".[dev]"                      # mcp SDK + pytest
python3 -m mcp_server.server
python3 -m pytest tests/test_mcp_server.py -v