Initial commit.

AGENTS.md

@@ -0,0 +1,90 @@
+# AGENTS.md
+
+Guidelines for AI coding agents working in this repository.
+
+## Project overview
+
+A collection of Python CLI tools for working with OpenStreetMap data. Each
+tool is a standalone Python script using Click for the CLI interface and
+Requests for HTTP calls.
+
+## Repository layout
+
+```
+osm-pt-geojson  - Fetch a public transport route relation, list stops, export GeoJSON
+README.md       - User-facing documentation
+AGENTS.md       - This file
+```
+
+New tools are added as individual scripts at the repo root.
+
+## Code conventions
+
+- Python 3, shebang `#!/usr/bin/python3`
+- CLI via [Click](https://click.palletsprojects.com/)
+- HTTP via [Requests](https://requests.readthedocs.io/)
+- Parse XML with lxml if needed; prefer the OSM JSON API where possible
+- Scripts have no `.py` extension and are executable
+- Errors go to stderr; data output goes to stdout
+- GeoJSON output uses `ensure_ascii=False`
+- All modules, functions, and test functions must have docstrings
+
+## OSM API
+
+Tools fetch data from the public OSM API:
+
+```
+https://www.openstreetmap.org/api/0.6/
+```
+
+No authentication is required for read-only access. Include a descriptive
+`User-Agent` header in all requests.
+
+## Type checking
+
+All scripts use type hints. Run mypy in strict mode to check:
+
+```
+mypy --strict osm-pt-geojson
+```
+
+## Testing
+
+Run the test suite with:
+
+```
+pytest tests/
+```
+
+Tests use the `responses` library to mock HTTP calls and never hit the live OSM
+API. Fixture data is stored in `tests/fixtures/` as saved API responses.
+
+Because tool scripts have hyphens in their names and no `.py` extension, they
+cannot be imported with the normal `importlib.util.spec_from_file_location`.
+Use `importlib.machinery.SourceFileLoader` instead:
+
+```python
+import importlib.machinery
+import importlib.util
+
+_loader = importlib.machinery.SourceFileLoader("osm_pt_geojson", "osm-pt-geojson")
+_spec = importlib.util.spec_from_loader("osm_pt_geojson", _loader)
+assert _spec
+osm = importlib.util.module_from_spec(_spec)
+_loader.exec_module(osm)
+```
+
+### Example relations used during development
+
+| ID       | Description                             |
+|----------|------------------------------------------|
+| 15083963 | M11 Istanbul Metro (subway)              |
+| 18892969 | Bus A1: Bristol Airport → Bus Station    |
+
+## Dependencies
+
+Install with pip:
+
+```
+pip install click requests
+```