diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 0000000..2154553
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,32 @@
+# Repository Guidelines
+
+## Project Structure & Module Organization
+- `raw_dgm1/`: source DGM1 tiles (`.tif` + `.tfw`) named `dgm1_<utm_zone>_<easting>_<northing>.tif`.
+- `work/`: transient artifacts such as `dgm.vrt` and intermediate `_tmp.tif` files; safe to regenerate.
+- `export_unity/`: delivery assets; `height_png16/` holds 16-bit heightmaps, `tile_index.csv` maps tile IDs to world bounds and global min/max.
+- `export_heightmaps.py`: main Python pipeline that mosaics the VRT, rescales to UInt16, and writes Unity-friendly tiles.
+
+## Build, Test, and Development Commands
+- Create/refresh VRT (run in repo root):  
+  `gdalbuildvrt work/dgm.vrt raw_dgm1/*.tif`
+- Export Unity-ready heightmaps and manifest:  
+  `python3 export_heightmaps.py`
+- Inspect a tile for sanity (optional spot check):  
+  `gdalinfo export_unity/height_png16/dgm1_32_328_5511.png | head`
+- Dependencies: GDAL with Python bindings (`osgeo`) available on PATH/PYTHONPATH.
+
+## Coding Style & Naming Conventions
+- Python: 4-space indentation, snake_case identifiers, and module-level constants for tunables (e.g., `TILE_SIZE_M`, `OUT_RES`).
+- Keep tile IDs stable and lower_snake_case to align with file naming and manifest entries.
+- Prefer small, composable functions if extending the pipeline; keep GDAL options explicit.
+
+## Testing & Validation
+- No formal test suite yet; validate changes by re-running `export_heightmaps.py` on a small subset and diffing outputs.
+- For correctness, compare `gdalinfo` stats of regenerated PNGs against expectations and spot-check manifest bounds.
+- When altering scaling or bounds logic, document rationale in comments and update an example command in this guide if needed.
+
+## Commit & Pull Request Guidelines
+- Use short, imperative commit messages (e.g., “add resampling flag”, “document export flow”); follow existing history style.
+- PRs should summarize scope, list commands executed (`gdalbuildvrt`, `export_heightmaps.py`), and call out data changes or new dependencies.
+- Avoid committing large raw datasets if not required; prefer documenting download steps or using `.gitignore` for temporary exports.
+- Include screenshots or brief notes when changes affect Unity import workflows or manifest formats.
diff --git a/README.md b/README.md
index e69de29..3d0c96c 100644
--- a/README.md
+++ b/README.md
@@ -0,0 +1,38 @@
+## GeoData Heightmap Export
+
+This repository converts DGM1 elevation tiles into Unity-ready 16-bit PNG heightmaps and a placement manifest. It relies on GDAL for mosaicking, resampling, and scaling to UInt16 ranges Unity expects.
+
+### Prerequisites
+- GDAL installed with Python bindings (`osgeo` importable).
+- Python 3.9+ available on PATH.
+- DGM1 source tiles placed in `raw_dgm1/` as `dgm1_<utm_zone>_<easting>_<northing>.tif` (with matching `.tfw` files).
+
+### Repository Layout
+- `raw_dgm1/` — input rasters (not versioned).
+- `work/` — intermediates such as `dgm.vrt` and `_tmp.tif` files; safe to delete/regenerate.
+- `export_unity/height_png16/` — final 16-bit PNG heightmaps for Unity import.
+- `export_unity/tile_index.csv` — manifest mapping tile IDs to world bounds and global min/max used for scaling.
+- `export_heightmaps.py` — main export script.
+- `AGENTS.md` — contributor guide.
+
+### Quick Start
+1. Build the VRT mosaic from raw tiles:
+   ```bash
+   gdalbuildvrt work/dgm.vrt raw_dgm1/*.tif
+   ```
+2. Export Unity heightmaps and manifest:
+   ```bash
+   python3 export_heightmaps.py
+   ```
+3. Import the PNGs into Unity Terrains using `tile_index.csv` for placement and consistent height scaling (0–65535).
+
+### Key Commands
+- Refresh VRT: `gdalbuildvrt work/dgm.vrt raw_dgm1/*.tif`
+- Run export pipeline: `python3 export_heightmaps.py`
+- Inspect an output tile: `gdalinfo export_unity/height_png16/<tile>.png | head`
+
+### Workflow Notes
+- The script computes a global min/max from the VRT to scale all tiles consistently; adjust `OUT_RES`, `RESAMPLE`, or `TILE_SIZE_M` in `export_heightmaps.py` if your AOI or target resolution changes.
+- `_tmp.tif` files in `work/` are transient; you can delete `work/` to force a clean rebuild.
+- Keep file names stable to avoid churn in Unity scenes; re-exports overwrite in place.
+- Large raw datasets are intentionally excluded from version control—document download sources or scripts instead of committing data.***