Location Awareness

## ⚠️ IMPORTANT: All commands use `scripts/location.sh`

Every command must be run via `scripts/location.sh`. Example:

**User asks:** "How long to walk home?"  
**You run:**
```bash
scripts/location.sh eta home --mode walk
```
**Output:** `4.6 km, about 45 min walk`  
**You reply with the output directly.**

Do NOT run `eta` or other subcommands directly — they don't exist as standalone commands.

## Quick Reference — What to Run

| User says | Run this (copy exactly) | Reply with |
|-----------|----------|------------|
| "Where am I?" | `scripts/location.sh status` | Zone name only |
| "Map" / "map link" | `scripts/location.sh herewego` | Just the URL |
| "What are my coordinates?" | `scripts/location.sh status` | Lat/lon from output |
| "How long to walk home?" | `scripts/location.sh eta home --mode walk` | Distance + duration |
| "How long to bike to X?" | `scripts/location.sh eta X --mode bike` | Distance + duration |
| "How far is X by car?" | `scripts/location.sh eta X --mode car` | Distance + duration |
| "Remind me to X when I get to Y" | `scripts/location.sh remind "X" Y` | Brief confirm |
| "What reminders do I have?" | `scripts/location.sh reminders` | Bullet list or "None" |
| "List my places" | `scripts/location.sh places` | Bullet list |
| "List places nearby" | `scripts/location.sh places --near` | Sorted by distance |
| "List my pubs downtown" | `scripts/location.sh places --region downtown --category pub` | Filtered list |
| "Save this spot as X" | `scripts/location.sh addplace "X"` | Confirm |
| "Delete place X" | `scripts/location.sh delplace X` | Confirm |
| "Disable the grocery rule" | `scripts/location.sh disable grocery` | Confirm |
| "List my geofence rules" | `scripts/location.sh geofences` | Bullet list |
| "When was I last at X?" | `scripts/location.sh history X` | Date/time |
| "Where have I been today?" | `scripts/location.sh history --days 1` | List of places |
| "Find me a cafe nearby" | `scripts/location.sh nearby cafe` | POI list with distances |
| "Any pubs within 1km?" | `scripts/location.sh nearby pub 1000` | Filtered POI list |
| "How long was I at work this week?" | `scripts/location.sh stats --days 7` | Hours per place |

**Response style:** Terse. No preamble. No "Here's your location:". Just the answer.

## All Commands

All via `scripts/location.sh <command>`:

| Command | Description |
|---------|-------------|
| `status` | Current location, geofences inside, map link |
| `herewego` | Just the HERE WeGo map link |
| `check` | Check for triggered actions/reminders (used by cron) |
| `places [--near] [--region R] [--category C]` | List saved places |
| `geofences` | List all geofences with full details |
| `remind <text> <place_id>` | Add one-shot location reminder |
| `reminders` | List pending reminders |
| `addplace <name> [radius] [--region R] [--category C]` | Save current location |
| `editplace <id> [--name] [--radius] [--region] [--category] [--action] [--cooldown]` | Modify a place |
| `delplace <id>` | Delete a place |
| `enable <id>` / `disable <id>` | Toggle geofence on/off |
| `history [place] [--days N]` | When was I last at a place? |
| `nearby <category> [radius]` | Find nearby POIs (cafe, pub, restaurant, etc.) |
| `stats [--days N]` | Time spent at each place, visit counts |
| `proximity <text> <place/lat> [lon] [radius]` | Alert when approaching a location |
| `eta <place> [--mode walk\|bike\|car]` | Travel time and distance to a place |

**Note:** `eta` accepts saved place names, coordinates (`lat,lon`), or any place name (geocoded via OpenStreetMap, biased to current location).

**Note:** `status` returns the zone name if in a known place, otherwise reverse geocodes to a street address (e.g., "123 Main Street, Downtown").

## Concepts

**Geofences** — Saved places with lat/lon, radius, and optional action. Persistent.

**Reminders** — One-shot alerts tied to a place. Deleted after delivery.

**Region/Category** — Optional tags for filtering (e.g., "downtown", "pub").

---

## Setup (for administrators)

### Provider Configuration

Edit `scripts/config.json`:

**Home Assistant (default):**
```json
{
  "provider": "homeassistant",
  "homeassistant": {
    "url": "https://your-ha.example.com",
    "token": "your-long-lived-token",
    "entity_id": "device_tracker.phone"
  }
}
```

**OwnTracks:**
```json
{
  "provider": "owntracks",
  "owntracks": {
    "url": "https://owntracks.example.com",
    "user": "username",
    "device": "phone"
  }
}
```

**Generic HTTP:**
```json
{
  "provider": "http",
  "http": {
    "url": "https://your-api.com/location",
    "headers": {"Authorization": "Bearer token"}
  }
}
```

**GPSLogger (file-based):**
```json
{
  "provider": "gpslogger",
  "gpslogger": {
    "file": "/path/to/location.json"
  }
}
```

Secrets support: `"env:VAR_NAME"` (reads from environment variable) or plain string.

**Alternative:** Configure entirely via environment variables (no config.json needed):

| Provider | Env variables |
|----------|--------------|
| `LOCATION_PROVIDER` | `homeassistant`, `owntracks`, `http`, or `gpslogger` (default: `homeassistant`) |
| **Home Assistant** | `HA_URL`, `HA_TOKEN`, `HA_ENTITY_ID` |
| **OwnTracks** | `OWNTRACKS_URL`, `OWNTRACKS_USER`, `OWNTRACKS_DEVICE`, `OWNTRACKS_TOKEN` |
| **HTTP** | `LOCATION_HTTP_URL` |
| **GPSLogger** | `GPSLOGGER_FILE` |

Env vars take precedence over config.json values. Set them in `~/.openclaw/.env` or your shell environment.

**Output format:** Most query commands output human-readable text by default. Add `--json` for JSON output (useful for scripting).

### Travel Speeds

Customize walking/biking speeds for ETA calculations in `scripts/config.json`:

```json
{
  "speeds_kmh": {
    "walk": 6,
    "bike": 15
  }
}
```

### Geofence Config

Edit `scripts/geofences.json`:

```json
{
  "geofences": [
    {
      "id": "grocery",
      "name": "Grocery Store",
      "lat": 40.7128,
      "lon": -74.0060,
      "radius_m": 30,
      "action": "shopping_tasks",
      "cooldown_hours": 4,
      "enabled": true,
      "region": "downtown",
      "category": "shop"
    }
  ],
  "location_reminders": [],
  "proximity_alerts": []
}
```

### Automatic Notifications (OpenClaw Cron)

Use OpenClaw's built-in cron to run periodic location checks. Add a job to `~/.openclaw/cron/jobs.json`:

```json
{
  "name": "Location Check",
  "schedule": "*/5 * * * *",
  "prompt": "Run scripts/location.sh check --json and notify me of any triggered actions, reminders, or proximity alerts.",
  "channel": "signal",
  "to": "+1234567890",
  "wakeMode": "now"
}
```

This keeps scheduling within OpenClaw rather than requiring external systemd services.