# Getting Started with wheriflo

Welcome! This guide walks you through setting up **wheriflo** so you can create [Wherigo](https://www.wherigo.com/) geocaching cartridges using AI.

> **What is Wherigo?** A Wherigo cartridge is a GPS-based interactive game. Players walk to real-world locations with their phone, and the app tells them a story, asks them questions, and reveals secrets as they explore. Think of it as a location-based choose-your-own-adventure.

> **What does this toolkit do?** It lets you describe the cartridge you want in plain English, and an AI assistant (GitHub Copilot, Claude, or Cursor) writes all the code, tests it, and builds the finished file — ready to upload to [wherigo.com](https://www.wherigo.com/).

---

## How It Works

```mermaid
%%{init: {'theme': 'base', 'themeVariables': {'fontFamily': 'Segoe UI, sans-serif', 'lineColor': '#90a4ae'}}}%%
flowchart TD
    subgraph header[" "]
        direction LR
        title["🧭 wheriflo"]
    end

    subgraph left["  Describe It  "]
        direction TB
        L1("💬 Tell the AI your idea\nin plain English")
        L2("📍 Provide GPS coordinates\nfrom Google Maps")
    end

    subgraph center["  AI Builds It  "]
        direction TB
        C1("🏗️ Scaffold project")
        C2("✍️ Write Lua code")
        C3("🔍 Lint &amp; fix mistakes")
        C4("⚙️ Compile to .gwc")
        C5("🎮 Play-test every path")
    end

    subgraph right["  Play It  "]
        direction TB
        R1("🌐 Test in browser")
        R2("📱 Play on your phone")
        R3("🌎 Publish to wherigo.com")
    end

    left --> center --> right

    style header fill:none,stroke:none
    style title fill:#1a73e8,stroke:#1557b0,color:#fff,font-size:20px,rx:10
    style left fill:#e8f5e9,stroke:#4caf50,rx:10,color:#1b5e20
    style center fill:#e3f2fd,stroke:#1a73e8,rx:10,color:#0d47a1
    style right fill:#fff3e0,stroke:#ff9800,rx:10,color:#e65100
    style L1 fill:#c8e6c9,stroke:#4caf50,rx:8,color:#1b5e20
    style L2 fill:#c8e6c9,stroke:#4caf50,rx:8,color:#1b5e20
    style C1 fill:#bbdefb,stroke:#1a73e8,rx:8,color:#0d47a1
    style C2 fill:#bbdefb,stroke:#1a73e8,rx:8,color:#0d47a1
    style C3 fill:#bbdefb,stroke:#1a73e8,rx:8,color:#0d47a1
    style C4 fill:#bbdefb,stroke:#1a73e8,rx:8,color:#0d47a1
    style C5 fill:#bbdefb,stroke:#1a73e8,rx:8,color:#0d47a1
    style R1 fill:#ffe0b2,stroke:#ff9800,rx:8,color:#e65100
    style R2 fill:#ffe0b2,stroke:#ff9800,rx:8,color:#e65100
    style R3 fill:#ffe0b2,stroke:#ff9800,rx:8,color:#e65100
```

You talk to the AI in plain English. The AI uses **wheriflo** behind the scenes to scaffold, write, check, compile, and test the cartridge. You get a finished `.gwc` file to upload.

---

## What You'll Need

| Requirement | Why | Where to get it |
|---|---|---|
| **Python 3.10+** | Runs the toolkit | [python.org/downloads](https://www.python.org/downloads/) |
| **uv** | Installs the toolkit automatically | [astral.sh/uv](https://docs.astral.sh/uv/getting-started/installation/) |
| **An AI editor** | VS Code + Copilot, Claude Desktop, or Cursor | See setup below |

> **Don't have Python yet?** Download it from [python.org](https://www.python.org/downloads/). On the installer, **check the box that says "Add Python to PATH"** — this is important!

> **What is uv?** It's a fast Python package manager. You only need to install it once. The toolkit uses it to run without cluttering your computer with packages.

---

## The Fast Path (Recommended)

One command installs everything and configures whichever AI clients you
already have — Claude Desktop, Claude Code, VS Code + Copilot, Cursor, or
OpenAI Codex. Open a terminal (PowerShell on Windows, Terminal on Mac) and
paste:

**Windows (PowerShell):**
```powershell
powershell -ExecutionPolicy ByPass -c "irm https://raw.githubusercontent.com/harrisonhoffman1/wheriflo/main/scripts/install.ps1 | iex"
```

**Mac / Linux:**
```bash
curl -LsSf https://raw.githubusercontent.com/harrisonhoffman1/wheriflo/main/scripts/install.sh | sh
```

The installer:
1. Installs **uv** (a Python tool manager) if you don't have it
2. Installs **wheriflo**
3. Finds your AI clients and configures each one automatically

Then **restart your AI client** and try:

> "Create a Wherigo cartridge about the history of my neighborhood. Start at a landmark near me and include 4 stops."

That's the whole setup. If it worked, you can skip straight to
[The Creation Workflow](#the-creation-workflow). If you'd rather set things
up by hand — or the installer couldn't find your client — the sections below
walk through each client manually. You can also re-run the configurator at
any time with `wheriflo setup` (add `--dry-run` to preview).

---

## Setup: VS Code + GitHub Copilot (manual)

This is the manual path if you have VS Code and a GitHub Copilot subscription.

```mermaid
flowchart TD
    A["📥 Install Python"]
    B["📥 Install uv"]
    C["📝 Add MCP config to VS Code"]
    D["🔄 Restart VS Code"]
    E["💬 Open Copilot Chat"]
    F["🎉 Start creating!"]

    A -->|"python.org/downloads"| B
    B -->|"astral.sh/uv"| C
    C -->|"Copy JSON into .vscode/mcp.json"| D
    D --> E
    E -->|"'Create a Wherigo cartridge\nabout...'"| F

    style A fill:#e8f5e9,stroke:#4caf50
    style B fill:#e8f5e9,stroke:#4caf50
    style C fill:#e3f2fd,stroke:#2196f3
    style D fill:#e3f2fd,stroke:#2196f3
    style E fill:#fff3e0,stroke:#ff9800
    style F fill:#c8e6c9,stroke:#4caf50,color:#1b5e20
```

### Step 1: Install Python

1. Go to [python.org/downloads](https://www.python.org/downloads/)
2. Download and run the installer
3. **Important:** Check "Add Python to PATH" during installation
4. Verify it works — open a terminal and type:
   ```
   python --version
   ```
   You should see something like `Python 3.12.x`

### Step 2: Install uv

Open a terminal (PowerShell on Windows, Terminal on Mac) and run:

**Windows (PowerShell):**
```powershell
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
```

**Mac / Linux:**
```bash
curl -LsSf https://astral.sh/uv/install.sh | sh
```

Verify it works:
```
uv --version
```

> **Sandboxed agents:** Some AI coding agents only allow writes inside the
> workspace or temporary directories. If `uvx` reports permission errors under
> `~/.cache/uv` or `~/.local/share/uv/tools`, set both `UV_CACHE_DIR` and
> `UV_TOOL_DIR` to writable paths such as `.uv-cache` and `.uv-tools`.

### Step 3: Add MCP configuration to VS Code

1. Open VS Code
2. Open your project folder (or create a new one)
3. Create a file called `.vscode/mcp.json` in your project with this content:

```json
{
    "servers": {
        "wherigo": {
            "command": "uvx",
            "args": ["wheriflo", "mcp"]
        }
    }
}
```

> **What this does:** It tells VS Code's Copilot Chat where to find the wheriflo. When you ask Copilot to create a Wherigo cartridge, it will automatically use these tools.

If your AI editor runs tools in a sandbox that cannot write to your home
directory, include uv's cache and tool directories in the server environment:

```json
{
    "servers": {
        "wherigo": {
            "command": "uvx",
            "args": ["wheriflo", "mcp"],
            "env": {
                "UV_CACHE_DIR": ".uv-cache",
                "UV_TOOL_DIR": ".uv-tools"
            }
        }
    }
}
```

Use absolute paths if your MCP client launches outside the workspace.

### Step 4: Restart VS Code

Close and reopen VS Code so it picks up the new MCP configuration.

You should see a notification that the "wherigo" MCP server connected. If you don't see it, open the Command Palette (`Ctrl+Shift+P` on Windows, `Cmd+Shift+P` on Mac) and search for "MCP" to check the status.

### Step 5: Start creating!

Open **Copilot Chat** (click the chat icon in the sidebar or press `Ctrl+Shift+I`) and try:

> "Create a Wherigo cartridge about the history of [your neighborhood]. Start at [a landmark near you] and include 4 stops. Make it a mystery with multiple choice questions."

The AI will:
1. Ask you for GPS coordinates (you can get these from Google Maps — right-click any location)
2. Scaffold the project
3. Write all the Lua code
4. Lint it for mistakes
5. Build the `.gwc` file
6. Test every path in the story

You'll get a `.gwz` file ready to upload to [wherigo.com](https://www.wherigo.com/)!

---

## Setup: Claude Desktop

### Step 1: Install Python and uv

Follow Steps 1 and 2 from the VS Code guide above.

### Step 2: Edit Claude's config file

Find your Claude Desktop configuration file:

- **Windows:** `%APPDATA%\Claude\claude_desktop_config.json`
- **Mac:** `~/Library/Application Support/Claude/claude_desktop_config.json`

Add this to the file (create it if it doesn't exist):

**Mac / Linux:**
```json
{
    "mcpServers": {
        "wherigo": {
            "command": "uvx",
            "args": ["wheriflo", "mcp"]
        }
    }
}
```

**Windows:**
```json
{
    "mcpServers": {
        "wherigo": {
            "command": "cmd",
            "args": ["/c", "uvx", "wheriflo", "mcp"]
        }
    }
}
```

> **Why the `cmd /c` on Windows?** Claude Desktop on Windows needs commands wrapped this way. It's a known quirk.

### Step 3: Restart Claude Desktop

Quit and reopen Claude Desktop. You should see a hammer icon (🔨) in the chat input — this means MCP tools are available.

### Step 4: Start creating!

Type the same kind of prompt as in the VS Code example above.

---

## Setup: Claude Code (Terminal)

If you use Claude Code from the terminal:

```bash
claude mcp add wherigo -- uvx wheriflo mcp
```

That's it. Now ask Claude to create a Wherigo cartridge.

---

## Setup: OpenAI Codex

```bash
codex mcp add -- uvx wheriflo mcp
```

That's it. Now ask Codex to create a Wherigo cartridge.

---

## Setup: Cursor

1. Open Cursor Settings
2. Go to **MCP Servers**
3. Add a new server with this JSON:

```json
{
    "mcpServers": {
        "wherigo": {
            "command": "uvx",
            "args": ["wheriflo", "mcp"]
        }
    }
}
```

4. Restart Cursor
5. Open the AI chat and start creating!

---

## The Creation Workflow

Here's what happens when you ask the AI to create a cartridge:

```mermaid
flowchart TD
    A["💬 Tell the AI what you want"]
    B["🏗️ AI scaffolds the project"]
    C["✍️ AI writes the Lua code"]
    D["🔍 AI lints for mistakes"]
    E["⚙️ AI builds .gwc file"]
    F["🌐 AI starts web player"]
    G["🎮 AI play-tests every path"]
    H["🏛️ Validate with Groundspeak compiler"]
    I["✅ Ready to upload!"]

    A --> B
    B --> C
    C --> D
    D -->|"Issues found"| C
    D -->|"Clean"| E
    E -->|"Build errors"| C
    E -->|"Success"| F
    F --> G
    G -->|"Bugs found"| C
    G -->|"All paths work"| H
    H -->|"Compiler rejects"| C
    H -->|"Compiler accepts"| I

    style A fill:#e8f5e9,stroke:#4caf50,color:#1b5e20
    style B fill:#e3f2fd,stroke:#2196f3
    style C fill:#e3f2fd,stroke:#2196f3
    style D fill:#fff3e0,stroke:#ff9800
    style E fill:#fff3e0,stroke:#ff9800
    style F fill:#e3f2fd,stroke:#2196f3
    style G fill:#e3f2fd,stroke:#2196f3
    style H fill:#fce4ec,stroke:#e91e63,color:#880e4f
    style I fill:#c8e6c9,stroke:#4caf50,color:#1b5e20
```

The AI handles all of this automatically. You just describe what you want and answer any questions it asks (like "what GPS coordinates should the first stop be at?").

---

## Validating with the Official Groundspeak Compiler

Before publishing, your cartridge **must** be validated with the official Groundspeak compiler at [wherigo.com](https://www.wherigo.com/). This is the only way to guarantee it will work on all Wherigo player apps.

### Option 1: Automatic (recommended)

If you provide your wherigo.com login credentials, the AI will validate automatically using the `wheriflo_compile` tool.

Add your credentials to the MCP server config as environment variables:

```json
{
    "servers": {
        "wheriflo": {
            "command": "uvx",
            "args": ["wheriflo", "mcp"],
            "env": {
                "WHERIGO_USERNAME": "your_wherigo_username",
                "WHERIGO_PASSWORD": "your_wherigo_password"
            }
        }
    }
}
```

> **Security:** Your credentials are read from environment variables only, never stored on disk, and never logged. The connection uses HTTPS.

> **Don't have an account?** Create a free one at [wherigo.com](https://www.wherigo.com/). You'll need it to publish cartridges anyway.

### Option 2: Manual upload

If you prefer not to enter credentials, you can validate manually:

1. The AI will build a `.gwz` file for you
2. Go to [**wherigo.com/cartridge/compile.aspx**](https://www.wherigo.com/cartridge/compile.aspx)
3. Log in with your wherigo.com account
4. Upload the `.gwz` file
5. If it compiles successfully, download the `.gwc` — that's your final cartridge

---

## Publishing Your Cartridge

Once your cartridge has been validated by the Groundspeak compiler:

1. Go to [wherigo.com](https://www.wherigo.com/) and log in (or ask the AI
   to run `wheriflo publish` — it opens the right page and copies the file
   path to your clipboard)
2. Click "Create a New Cartridge" in your profile
3. Upload the `.gwz` file (wherigo.com compiles it and serves players a
   personalized `.gwc`)
4. Fill in the listing details (title, description, difficulty, terrain)
5. Set it to "Active" when you're ready for players to find it

---

## Testing Your Cartridge

### In the browser (while creating)

The AI automatically starts a web player at `http://localhost:8000` when it uses the `wheriflo_play` tool. You can open this in your browser to see the cartridge running — click through messages, answer questions, and teleport between zones.

### On your phone (field testing)

1. Install the **Wherigo** app on your phone ([iOS](https://apps.apple.com/app/wherigo/id1468535164) / [Android](https://play.google.com/store/apps/details?id=menion.android.whereyougo))
2. Upload your `.gwz` to wherigo.com
3. Search for your cartridge in the app
4. Walk the actual route!

> **Tip:** Always field-test before publishing. GPS accuracy can be tricky near tall buildings, and zone radii may need adjustment.

---

## Getting GPS Coordinates

You'll need GPS coordinates for each stop in your cartridge. The easiest way:

1. Open [Google Maps](https://maps.google.com)
2. Right-click (or long-press on mobile) on a location
3. Click the coordinates that appear — they're copied to your clipboard
4. Give them to the AI: "The first stop should be at 47.6019, -122.3317"

---

## Troubleshooting

### "MCP server not connected"

- Make sure Python and uv are installed (type `python --version` and `uv --version` in a terminal)
- Check that your MCP config file is in the right location and has valid JSON
- Restart your AI editor after adding the config

### "uvx: command not found"

- You need to install uv first — see Step 2 above
- On Windows, you may need to restart your terminal after installing uv

### "`uvx` failed to initialize cache" or "Could not create temporary file"

- This usually means the sandbox cannot write to uv's default directories under your home folder, not that `wheriflo`, Groundspeak, or your cartridge failed
- Set both `UV_CACHE_DIR` and `UV_TOOL_DIR` to writable workspace or temp paths:
  ```bash
  UV_CACHE_DIR=.uv-cache UV_TOOL_DIR=.uv-tools uvx --from wheriflo wheriflo compile path/to/Cartridge.lua
  ```
- For MCP server configs, add the same values to the server `env` block

### "Build failed: compile error"

- The AI will usually fix this automatically. If not, ask it: "The build failed, can you fix the Lua errors?"

### "File not found" errors

- Make sure you're in the right project directory
- The AI should be creating files in your current workspace

---

## Example Prompts

Here are some prompts to try:

> "Create a Wherigo cartridge that's a walking tour of 5 historical landmarks near Times Square, New York. Include fun facts at each stop and a quiz question."

> "Make a mystery Wherigo set in Golden Gate Park, San Francisco. The player is a detective solving a theft. Include 6 stops, clue items, and branching paths based on deductions."

> "Create a simple 3-stop Wherigo for kids in Central Park. Each stop has an animal-themed puzzle. Keep the walking distance under half a mile."

> "Review and improve this cartridge" (with a .lua file open)

---

## Need Help?

- **GitHub Issues:** [wheriflo/issues](https://github.com/harrisonhoffman1/wheriflo/issues)
- **Wherigo community:** [wherigo.com forums](https://www.wherigo.com/)
- **Geocaching community:** [geocaching.com](https://www.geocaching.com/)
