# Routecraft

Routecraft is a CLI for agents that build bicycle routes one road or path at a time.

The CLI shows connected choices and source evidence. The agent selects each segment. Routecraft validates every change and records an immutable revision.

Routecraft leaves road ranking and route decisions to the agent. It does not generate loops.

## What Routecraft provides

- Road, path, surface, access, speed, control, and bicycle facility data from OpenStreetMap
- Connected route choices that keep each exact segment reference
- Weather, elevation, nearby places, and route comparison data
- Optional Google map, aerial, and Street View images
- Exact edits, hand-drawn connectors, and GPX or GeoJSON export with a Routecraft provenance file
- The same command contracts through a CLI and an MCP server

Source data can be incomplete. Routecraft reports unknown values and never labels a road as safe.

## Requirements

Use Node.js 22 or newer.

## Install from source

```bash
git clone https://github.com/quinnsprouse/routecraft.git
cd routecraft
npm install
npm run build
npm link
routecraft --version
```

## Start an agent session

Create a separate workspace for each route.

```bash
export ROUTECRAFT_HOME="$(mktemp -d)"
routecraft guide next --json
```

Read `result.actions` from `guide next`. After a normal command, follow `result.nextActions` when that field exists.

Each executable action includes the next CLI and MCP calls with their expected results.

Load the bundled network when you want a local demo.

```bash
routecraft guide topic network --json
```

Run the command in `result.bundledDemo.invoke.cli`. Then run the returned `route.create` action and continue through `result.nextActions`.

Use a command guide before you need more options.

```bash
routecraft guide command route.append --json
routecraft guide command route.export --json
```

## Agent skill

Routecraft includes a skill that matches the installed CLI version.

```bash
routecraft skills get core --json
routecraft skills get core --full --json
```

Register `result.path` with the agent host. Use `result.content` when the host accepts inline instructions.

## MCP

Run `routecraft mcp` over standard input and output.

```json
{
  "mcpServers": {
    "routecraft": {
      "command": "routecraft",
      "args": ["mcp"],
      "env": {
        "ROUTECRAFT_HOME": "/absolute/path/to/a/route-workspace"
      }
    }
  }
}
```

Routecraft hides Google imagery commands until `ROUTECRAFT_GOOGLE_MAPS_API_KEY` exists. Run `routecraft provider status --json` to inspect the current setup.

## Data sources

| Data | Source | Required setup |
| --- | --- | --- |
| Roads, paths, surfaces, and access | OpenStreetMap and Overpass | None |
| Place lookup | Nominatim | Explicit public-service consent or a configured endpoint |
| Route weather | Open-Meteo | None for its public noncommercial endpoint |
| Segment elevation | USGS 3DEP | None |
| Map, aerial, and street images | Google Maps Platform | `ROUTECRAFT_GOOGLE_MAPS_API_KEY` |

Personal Strava and Ride with GPS data are not implemented.

## Data license

Routecraft uses road and path data from [OpenStreetMap contributors](https://www.openstreetmap.org/copyright). OpenStreetMap licenses this data under the ODbL.

## Develop

```bash
npm ci
npm run check
npm run package:smoke
```

See [the architecture note](./docs/ARCHITECTURE.md) for the module boundaries and project patterns.

## License

MIT