diff --git a/docs/gpx-extensions.md b/docs/gpx-extensions.md
new file mode 100644
index 0000000..3b231e1
--- /dev/null
+++ b/docs/gpx-extensions.md
@@ -0,0 +1,101 @@
+# trails.cool GPX Extensions
+
+trails.cool uses a custom XML namespace to store planning metadata in GPX files. This allows round-tripping through export, import, and Journal save without losing information.
+
+## Namespace
+
+```
+xmlns:trails="https://trails.cool/gpx/1"
+```
+
+Declared on the root `<gpx>` element whenever any extension is present.
+
+---
+
+## `<trails:poi>` — POI metadata on waypoints
+
+Stored inside `<wpt><extensions>`. Carries the OpenStreetMap node ID and key tags for waypoints that were snapped to a POI in the Planner.
+
+### Syntax
+
+```xml
+<wpt lat="52.52" lon="13.405">
+  <name>Bike Shop Berlin</name>
+  <extensions>
+    <trails:poi osmId="123456">
+      <trails:tag k="phone" v="+49 30 12345"/>
+      <trails:tag k="website" v="https://example.com"/>
+      <trails:tag k="opening_hours" v="Mo-Fr 09:00-18:00"/>
+      <trails:tag k="addr:street" v="Unter den Linden"/>
+      <trails:tag k="addr:housenumber" v="1"/>
+      <trails:tag k="addr:postcode" v="10117"/>
+      <trails:tag k="addr:city" v="Berlin"/>
+    </trails:poi>
+  </extensions>
+</wpt>
+```
+
+### Attributes
+
+| Attribute | Required | Description |
+|-----------|----------|-------------|
+| `osmId`   | no       | OSM node ID (integer). Present when the waypoint was snapped to a known OSM node. |
+
+### Child elements
+
+Each `<trails:tag>` stores one OSM tag. The following keys are persisted:
+
+| Key | Description |
+|-----|-------------|
+| `phone` / `contact:phone` | Phone number |
+| `website` | Website URL |
+| `opening_hours` | OSM opening hours string (e.g. `Mo-Fr 09:00-18:00`) |
+| `addr:street` | Street name |
+| `addr:housenumber` | House number |
+| `addr:postcode` | Postal code |
+| `addr:city` | City |
+| `amenity` | OSM amenity value (e.g. `bicycle_shop`) |
+| `tourism` | OSM tourism value (e.g. `camp_site`) |
+| `shop` | OSM shop value |
+
+### Display
+
+The Journal route detail page renders a **Waypoints** section when at least one waypoint has POI metadata. Phone numbers become `tel:` links; websites become `https:` links.
+
+---
+
+## `<trails:planning>` — Planning metadata on routes
+
+Stored inside the top-level `<extensions>` element. Carries no-go areas defined in the Planner.
+
+### Syntax
+
+```xml
+<extensions>
+  <trails:planning>
+    <trails:nogo>
+      <trails:point lat="52.51" lon="13.40"/>
+      <trails:point lat="52.51" lon="13.41"/>
+      <trails:point lat="52.52" lon="13.41"/>
+    </trails:nogo>
+  </trails:planning>
+</extensions>
+```
+
+### Elements
+
+| Element | Description |
+|---------|-------------|
+| `<trails:planning>` | Container for all planning metadata. |
+| `<trails:nogo>` | A no-go area polygon. Requires at least 3 `<trails:point>` children. Multiple `<trails:nogo>` elements are allowed. |
+| `<trails:point lat="…" lon="…"/>` | A vertex of the no-go polygon. |
+
+No-go areas are passed to BRouter when computing routes, which routes around them. They are preserved through export/import and Journal save.
+
+---
+
+## Compatibility
+
+These extensions are **forward-compatible**: parsers that don't know the `trails:` namespace will ignore the `<extensions>` blocks and load the file as a normal GPX. Geometry, waypoint names, and elevation data are always stored in standard GPX elements.
+
+The namespace URI `https://trails.cool/gpx/1` is versioned. If the schema changes incompatibly, the minor version will increment.