location-awareness

# Location Awareness

**This skill provides commands to execute. When the user asks about location, RUN the appropriate command below.**

## ⚠️ 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"`, `"pass:path"`, `"cmd:command"`, or plain string.

**Alternative:** Set `HA_URL` and `HA_TOKEN` environment variables instead of editing config.json.

**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": []
}
```

### Cron Setup (Automatic Notifications)

For automatic location-based notifications, set up a systemd timer:

1. **Configure notification target** (env var):
```bash
export CLAWDBOT_NOTIFY_TARGET="+1234567890"  # or @telegram_user, etc.
```

2. **Create systemd service** (`~/.config/systemd/user/location-check.service`):
```ini
[Unit]
Description=Location check

[Service]
Type=oneshot
Environment=CLAWDBOT_NOTIFY_TARGET=+1234567890
ExecStart=%h/clawd/skills/location-awareness/scripts/location_cron.sh
```

3. **Create timer** (`~/.config/systemd/user/location-check.timer`):
```ini
[Unit]
Description=Run location check every 5 minutes

[Timer]
OnBootSec=2min
OnUnitActiveSec=5min

[Install]
WantedBy=timers.target
```

4. **Enable**: `systemctl --user enable --now location-check.timer`

Notifications use `clawdbot message send`, so they work with any configured channel (Signal, Telegram, etc.).