# Crimson Mandate — LLM Agent Guide

> Crimson Mandate is a persistent MMO space strategy game. You control ships on a hex grid, mine asteroids, research technologies, build stations, and battle other players. This guide teaches AI agents how to play the game via its API.

## Quick Start

1. Create a guest account via REST API
2. Connect to WebSocket and authenticate
3. Join the game world (auto-spawns starter ship + station)
4. Move your ship, explore, mine, build, fight

---

## Base URL

All REST endpoints use relative paths from the game server:
- Production: `https://crimsonmandate.com`
- REST API prefix: `/api`
- WebSocket: `wss://crimsonmandate.com/ws`

## Authentication

### 1. Create an Account

**Guest (fastest):**
```
POST /api/auth/guest
Body: {}
Response: { token: "jwt...", userId: "uuid", displayName: "Guest_XXXX" }
```

**Register:**
```
POST /api/auth/register
Body: { username: "name", email: "email@example.com", password: "pass" }
Response: { token: "jwt...", userId: "uuid" }
```

**Login:**
```
POST /api/auth/login
Body: { email: "email@example.com", password: "pass" }
Response: { token: "jwt...", userId: "uuid" }
```

### 2. Using the Token

For all REST requests, include the JWT token:
```
Authorization: Bearer <token>
Content-Type: application/json
```

---

## WebSocket Connection

### Connect
```javascript
const ws = new WebSocket("wss://crimsonmandate.com/ws");
```

### Authenticate
Send immediately after connection opens:
```json
{ "type": "auth", "payload": { "sessionId": "<jwt_token>" } }
```

Response:
```json
{ "type": "auth_success", "payload": { "userId": "uuid", "displayName": "..." } }
```

### Keep-Alive
Send pings every 30 seconds:
```json
{ "type": "ping" }
```

### Join the Game World
After auth, join the MMO world:
```json
{ "type": "mmo_join_world", "payload": { "worldId": 1 } }
```

Response: `mmo_world_joined` with your units, stations, planets, and fog of war data. If you're a new player, a starter Scout ship and Fortress station are auto-created near Earth (0,0).

---

## Coordinate System

The game uses **axial hex coordinates** `{ q, r }` with pointy-top hexagons.

- **Earth** is at `(0, 0)` — the center of the map
- **Distance**: `max(|q1-q2|, |r1-r2|, |(q1+r1)-(q2+r2)|)`
- **Neighbors** of `(q,r)`: `(q+1,r)`, `(q-1,r)`, `(q,r+1)`, `(q,r-1)`, `(q+1,r-1)`, `(q-1,r+1)`

### Map Zones (concentric rings from Earth)
| Zone | Radius | PvP Rules |
|------|--------|-----------|
| Core | 0-25 | Safe zone |
| Inner Belt | 25-75 | Station raids only |
| Mid Rim | 75-200 | Full PvP |
| Outer Rim | 200-400 | Full PvP |
| Deep Space | 400-700 | Full PvP |
| The Void | 700-1000 | Full PvP, most dangerous |

---

## Ship Types & Stats

| Ship | HP | Shields | Attack | Defense | Speed | Range | Cost (CR) | Cargo |
|------|----|---------|--------|---------|-------|-------|-----------|-------|
| Scout | 50 | 25 | 5 | 0 | 5 | 1 | 50 | 100 |
| Fighter | 100 | 40 | 15 | 0 | 3 | 1 | 100 | 200 |
| Destroyer | 150 | 60 | 25 | 5 | 4 | 2 | 150 | 400 |
| Bomber | 80 | 20 | 50 | 0 | 2 | 1 | 200 | 150 |
| Space Tug | 50 | 15 | 0 | 0 | 4 | 0 | 75 | 5000 |
| Cruiser | 300 | 120 | 40 | 10 | 2 | 2 | 200 | 1000 |
| Carrier | 400 | 200 | 10 | 15 | 2 | 1 | 500 | 800 |
| Battleship | 500 | 250 | 60 | 20 | 2 | 3 | 800 | 600 |
| Dreadnought | 800 | 400 | 80 | 30 | 1 | 3 | 1200 | 1500 |
| Titan | 1200 | 600 | 100 | 40 | 1 | 4 | 1500 | 3000 |

- **Speed** = hexes moved per game tick (1 tick = 1 second)
- **Range** = attack range in hexes
- **Cost** = credits to build at a station
- **Cargo** = mineral storage capacity
- **Space Tug** cannot attack but has massive cargo and mining efficiency

---

## Core Actions (WebSocket Messages)

All messages follow this format:
```json
{ "type": "<message_type>", "payload": { ... } }
```

### Moving a Ship
```json
{
  "type": "mmo_move_unit",
  "payload": {
    "unitId": "uuid-of-your-ship",
    "targetHex": { "q": 5, "r": -3 }
  }
}
```
The server computes an A* path and the ship moves 1+ hexes per tick (based on speed). You receive position updates in tick broadcasts.

### Building a Ship
Ships are built at planets or stations you own. First, your station needs a ship design.

**Step 1 — Create a design (REST):**
```
POST /api/stations/<stationId>/designs
Body: {
  "name": "My Fighter",
  "baseShipClass": "fighter",
  "techIds": [],
  "markupPct": 0
}
Response: { design: { id, name, baseShipClass, cost, ... } }
```

Valid `baseShipClass` values: `scout`, `fighter`, `cruiser`, `space_tug`

**Step 2 — Build the ship (WebSocket):**
```json
{
  "type": "mmo_build_unit",
  "payload": {
    "planetId": "planet-uuid-or-station-uuid",
    "unitType": "fighter",
    "designId": "design-uuid"
  }
}
```

**Alternative — Buy from station store (WebSocket):**
```json
{
  "type": "mmo_build_unit",
  "payload": {
    "planetId": "station-uuid",
    "unitType": "scout"
  }
}
```
This uses the base ship type directly (no design needed). Cost is deducted from your credits.

### Attacking
```json
{
  "type": "mmo_attack",
  "payload": {
    "attackerId": "your-unit-uuid",
    "targetId": "enemy-unit-uuid",
    "position": { "q": 10, "r": -5 }
  }
}
```
- Your unit must be within attack range of the target
- Combat is resolved each game tick automatically once engaged
- Damage = `attack * accuracy_roll - target_defense`
- Ships that reach 0 HP are destroyed and become wrecks

### Following / Pursuing a Target
```json
{
  "type": "mmo_follow_target",
  "payload": {
    "unitId": "your-unit-uuid",
    "targetId": "target-unit-uuid",
    "mode": "attack"
  }
}
```
- `mode: "follow"` — shadow the target's movement
- `mode: "attack"` — pursue and auto-attack when in range

Stop following:
```json
{ "type": "mmo_clear_follow", "payload": { "unitId": "your-unit-uuid" } }
```

### Disengaging from Combat
```json
{ "type": "mmo_disengage", "payload": { "unitId": "your-unit-uuid" } }
```

### Docking at a Station

Docking is only available at stations, orbital platforms, and the Alien Leviathan. You CANNOT dock at planets.

**Important:** The message type is `mmo_dock_unit` (NOT `mmo_dock`). Sending `mmo_dock` will return `UNKNOWN_MESSAGE_TYPE`.

**Dock at a station:**
```json
{ "type": "mmo_dock_unit", "payload": { "unitId": "your-unit-uuid", "stationId": "station-uuid" } }
```

**Dock at an orbital platform:**
```json
{ "type": "mmo_dock_unit", "payload": { "unitId": "your-unit-uuid", "platformId": "platform-uuid" } }
```

**Dock at the Alien Leviathan (requires Alien Docking Module component):**
```json
{ "type": "mmo_dock_unit", "payload": { "unitId": "your-unit-uuid", "alienUnitId": "leviathan-uuid" } }
```

Unit must be within 1 hex of the target. Docked units are safe from combat. Cargo auto-transfers to the station on dock.

**Known stations:** Earth Space Station at hex (2, 0) — `stationId: "earth_station"`, capital class, 0% fee, has shipyard.

**Undock:**
```json
{ "type": "mmo_undock_unit", "payload": { "unitId": "your-unit-uuid" } }
```

### Mining Asteroids
```json
{
  "type": "mmo_mine_asteroid",
  "payload": {
    "unitId": "your-unit-uuid",
    "asteroidId": "asteroid-uuid"
  }
}
```
Unit must be within 1 hex. Minerals are deposited into the unit's cargo. Stop mining:
```json
{ "type": "mmo_stop_mining", "payload": { "unitId": "your-unit-uuid" } }
```

### Scanning Planets
```json
{
  "type": "mmo_scan_planet",
  "payload": {
    "entityType": "unit",
    "entityId": "your-unit-uuid",
    "planetId": "planet-uuid"
  }
}
```
Reveals the planet's mineral deposits. Scan quality depends on distance and sensor stats.

### Repairing Ships (from cargo)
```json
{
  "type": "mmo_repair_unit",
  "payload": {
    "unitId": "your-unit-uuid"
  }
}
```
Uses iron from the unit's cargo (0.5 iron per HP healed, 1 iron to repair a damaged shield generator). Copper is NOT required for cargo repair. The unit must have iron in cargo before calling this command. To load iron into cargo, dock at a station that has iron in storage and use `loadCargoFromLocation()`.

### Activating Abilities
```json
{
  "type": "mmo_activate_ability",
  "payload": {
    "unitId": "your-unit-uuid",
    "abilityId": "ability-uuid"
  }
}
```

Ship abilities by class:
- **Scout**: Sensor Sweep (+3 vision, 30 tick CD), Evasive Maneuvers (+25 evasion, 20 tick CD)
- **Fighter**: Afterburner (2x speed, 25 tick CD), Missile Barrage (all weapons fire + 2x cooldowns, 30 tick CD)
- **Cruiser**: Broadside (+25% damage, 20 tick CD), Shield Overcharge (2x shields, 40 tick CD)

### Naming Your Ship
```json
{
  "type": "mmo_name_ship",
  "payload": {
    "unitId": "your-unit-uuid",
    "name": "The Harbinger"
  }
}
```

---

## Stations

### Station Types & Costs
| Type | Cost (CR) | Description |
|------|-----------|-------------|
| waypoint | 500 | Basic outpost |
| depot | 2000 | Storage facility |
| fortress | 10000 | Fortified base |
| capital | 50000 | Empire capital |

### Station Management (REST API)

**List your stations:**
```
GET /api/stations/list
Response: { stations: [{ id, name, type, position_q, position_r, status, ... }] }
```

**Purchase a station:**
```
POST /api/stations/purchase
Body: { stationType: "fortress" }
Response: { station: { id, ... } }
```

**Deploy station to map:**
```
POST /api/stations/deploy
Body: { stationId: "uuid", position: { q: 10, r: -5 } }
```

**Relocate station:**
```
POST /api/stations/relocate
Body: { stationId: "uuid", targetQ: 20, targetR: -10 }
```
Cost: 10% of station value + 1 CR per hex of distance.

**Set station fee:**
```
POST /api/stations/set-fee
Body: { stationId: "uuid", feePercent: 15 }
```

### Ship Designs at Stations

**List designs:**
```
GET /api/stations/<stationId>/designs
Response: { designs: [{ id, name, baseShipClass, techIds, cost, ... }] }
```

**Create design:**
```
POST /api/stations/<stationId>/designs
Body: { name: "Warbird", baseShipClass: "cruiser", techIds: [1, 3], markupPct: 0 }
```

**Delete design:**
```
DELETE /api/stations/<stationId>/designs/<designId>
```

---

## Wrecks & Salvage (REST API)

When ships are destroyed, they leave wrecks that can be salvaged or repaired.

**List your wrecks:**
```
GET /api/wrecks/list
Response: { wrecks: [{ id, unitType, position_q, position_r, status, expires_at, ... }] }
```

**Find nearby wrecks:**
```
GET /api/wrecks/nearby?unitId=<uuid>
Response: { wrecks: [...] }
```

**Get tow options:**
```
GET /api/wrecks/<wreckId>/tow-options
Response: { options: [{ destination, cost, distance, ... }] }
```

**Request tow:**
```
POST /api/wrecks/request-tow
Body: { wreckId: "uuid", destination: "earth" | "station", stationId?: "uuid" }
```
Towing takes 1 tick per hex of distance.

**Get repair cost:**
```
GET /api/wrecks/<wreckId>/repair-cost
Response: { costs: { iron: N, copper: N, gold: N, credits: N }, ticks: 30 }
```

**Start repair:**
```
POST /api/wrecks/start-repair
Body: { wreckId: "uuid" }
```
Requires minerals in your inventory. Repair takes 30 ticks. On completion, a new ship is created.

**Salvage a wreck (get tech relics):**
```
POST /api/wrecks/salvage
Body: { wreckId: "uuid", unitId: "your-unit-uuid" }
```
Your unit must be within 1 hex. Returns tech relics used for research.

**Claim a wreck:**
```
POST /api/wrecks/claim
Body: { wreckId: "uuid", unitId: "your-unit-uuid" }
```
Claim ownership of an unclaimed wreck near your unit.

---

## Research & Technology (REST API)

Research unlocks technologies that improve your ships and station capabilities.

**View research board:**
```
GET /api/research/board
Response: { projects: [{ id, name, technologyId, totalCost, currentFunding, contributors, ... }] }
```

**View tech tree:**
```
GET /api/research/tech-tree
Response: { technologies: [{ id, name, tier, category, description, prerequisites, ... }] }
```

**View available technologies:**
```
GET /api/research/available
Response: { technologies: [...unlocked and available to research...] }
```

**Start a research project:**
```
POST /api/research/start
Body: { technologyId: 1, worldId: 1 }
Response: { project: { id, name, totalCost, ... } }
```

**Contribute ISD to research:**
```
POST /api/research/contribute
Body: { projectId: "uuid", amount: 100 }
```
Research completes when fully funded. Multiple players can contribute to the same project.

**View your relic inventory:**
```
GET /api/research/relics/inventory
Response: { relics: [{ id, type, tier, source, ... }] }
```
Relics are found by salvaging wrecks and exploring. They're consumed when starting research projects.

**View your active projects:**
```
GET /api/research/my-projects
Response: { projects: [...] }
```

### Technology Categories
Technologies are organized in tiers (T1-T3) with prerequisites:
- **Weapons**: Increase attack power
- **Shields**: Improve shield capacity
- **Engines**: Boost movement speed
- **Sensors**: Extend vision range
- **Mining**: Improve mineral yield
- **Armor**: Increase HP

---

## Components & Ship Upgrades (REST API)

Components modify your ship's stats. They can be purchased, equipped, and enhanced.

**Browse available components:**
```
GET /api/components/available
Response: { components: [{ id, name, category, stats, cost, ... }] }
```

Categories: `weapon`, `shield`, `armor`, `engine`, `sensor`, `stealth`, `reactor`, `mining_laser`, `tractor_beam`

**Purchase a component:**
```
POST /api/components/purchase
Body: { componentId: "comp-def-id" }
Response: { instance: { id, componentId, stats, ... } }
```

**View your inventory:**
```
GET /api/components/inventory
Response: { components: [{ id, componentId, name, category, stats, equippedOn, ... }] }
```

**View ship's components:**
```
GET /api/components/ship/<shipId>
Response: { components: [...equipped components...] }
```

**Equip a component:**
```
POST /api/components/equip
Body: { instanceId: "component-instance-uuid", unitId: "ship-uuid" }
```

**Unequip a component:**
```
POST /api/components/unequip
Body: { instanceId: "component-instance-uuid" }
```

**Enhance a component (star rating gacha):**
```
POST /api/components/enhance
Body: { instanceId: "component-instance-uuid" }
```
Enhancement has a chance-based success rate. Failed attempts build pity counter toward guaranteed upgrade.

### Key Component Effects
- **Engine** components add flat speed bonus (+1 to +5 hexes/tick)
- **Weapon** components add attack damage
- **Shield** components add shield HP
- **Mining Laser** components improve mining yield and enable rare mineral discovery
- **Sensor** components extend vision range

---

## Minerals & Economy

### Mineral Types (by rarity)
| Mineral | Rarity | Uses |
|---------|--------|------|
| Iron | Common | Ship repair (HP) |
| Copper | Common | Ship repair (shields) |
| Titanium | Uncommon | Crafting |
| Platinum | Uncommon | Crafting |
| Gold | Rare | Repair fixed cost |
| Palladium | Rare | Trading |
| Iridium | Epic | Advanced crafting |
| Dark Matter | Legendary | Special items |

### Mineral Management (REST API)

**View mineral types:**
```
GET /api/minerals/types
```

**View global inventory:**
```
GET /api/minerals/inventory
Response: { minerals: { iron: N, copper: N, ... } }
```

**View minerals at a location:**
```
GET /api/minerals/location/<type>/<id>
```
Type is `station` or `planet`, id is the entity UUID.

**View cargo on a ship:**
```
GET /api/minerals/cargo/<unitId>
```

**Transfer minerals between stations:**
```
POST /api/minerals/transfer-location
Body: { mineralType: "iron", amount: 50, fromType: "station", fromId: "uuid", toType: "station", toId: "uuid" }
```
Transfers happen at 1 mineral per tick.

**Load cargo from station onto docked ship:**
```
POST /api/minerals/load-cargo
Body: { unitId: "ship-uuid", locationId: "station-uuid", locationType: "station", mineralType: "iron", amount: 20 }
```

---

## Alliances (WebSocket)

**Create an alliance:**
```json
{ "type": "mmo_alliance_create", "payload": { "name": "Star Fleet", "tag": "SF" } }
```

**List alliances:**
```json
{ "type": "mmo_alliance_list" }
```

**Join an alliance:**
```json
{ "type": "mmo_alliance_join", "payload": { "allianceId": "uuid" } }
```

**Alliance chat:**
```json
{ "type": "mmo_alliance_chat", "payload": { "message": "Hello allies!" } }
```

**Leave alliance:**
```json
{ "type": "mmo_alliance_leave" }
```

---

## Game Tick Broadcast

Every 1 second, the server broadcasts a tick update to each connected player containing:
- Updated positions of units in your vision
- Combat results (damage dealt, ships destroyed)
- Resource changes
- New entities entering your vision
- Entities leaving your vision

Listen for message type `mmo_tick_update` to track the game state.

### Movement Events

**Unit arrived at destination:** When your unit finishes moving, you receive:
```json
{ "type": "mmo_unit_arrived", "payload": { "unitId": "uuid", "position": { "q": 5, "r": -3 } } }
```

**Movement rerouted:** If your target hex is blocked (station/planet footprint), the server reroutes to the nearest free adjacent hex:
```json
{ "type": "mmo_movement_rerouted", "payload": { "unitId": "uuid", "originalTarget": { "q": 2, "r": 0 }, "actualTarget": { "q": 3, "r": 0 }, "reason": "target_hex_blocked" } }
```

**Movement failed:** If the target AND all nearby hexes are blocked, movement is rejected:
```json
{ "type": "mmo_move_failed", "payload": { "unitId": "uuid", "targetHex": { "q": 2, "r": 0 }, "reason": "all_nearby_hexes_blocked" } }
```

**Mining stopped:** When mining ends (asteroid depleted, laser insufficient, or manual stop):
```json
{ "type": "mmo_mine_stopped", "payload": { "unitId": "uuid", "reason": "depleted|laser_tier_insufficient|manual" } }
```
After receiving `mmo_mine_stopped`, issue a new `mmo_move_unit` to move elsewhere.

**Note:** Station and planet hexes are blocked for movement. When moving to dock at a station, target an adjacent hex (within 1 hex of the station), then send `mmo_dock_unit`.

---

## Fog of War

You can only see hexes within vision range of your units and stations. Vision ranges:
- Scout: ~7 hexes (best scout vision)
- Fighter/Destroyer: ~5 hexes
- Cruiser/Battleship: ~4 hexes
- Station: ~8 hexes

Explored hexes remain remembered but you only see real-time activity within current vision.

### Request Map Chunks
```json
{
  "type": "mmo_request_chunks",
  "payload": {
    "chunks": [{ "q": 0, "r": 0 }]
  }
}
```
Returns units, stations, planets, and asteroids in the requested chunk regions.

---

## Strategy Tips for AI Agents

### Early Game
1. After joining, you get a free Scout at your station near Earth
2. Explore nearby hexes to discover asteroids and planets
3. Mine asteroids for iron and copper (needed for repairs)
4. Build a Fighter for combat capability (100 CR)
5. Stay in the Core zone (radius 25 from Earth) — it's safe from PvP

### Mid Game
1. Research technologies to improve your ships
2. Build a Cruiser for serious combat power (200 CR)
3. Deploy stations in strategic locations for mineral storage
4. Salvage wrecks for tech relics
5. Join or create an alliance for protection

### Combat
1. Check attack range before engaging — Scouts have range 1, Cruisers have range 2
2. Use `mmo_follow_target` with `mode: "attack"` to auto-pursue enemies
3. Retreat with `mmo_disengage` if losing
4. Repair at stations or use cargo minerals with `mmo_repair_unit`
5. Ships with 0 HP become wrecks — tow and repair them to recover

### Economy
1. Space Tugs have 5000 cargo and 2.0 mining efficiency — best miners
2. Deposit minerals at stations near where you mine
3. Repair costs: iron for HP, copper for shields, gold as fixed cost
4. Credits are earned from golden asteroid deliveries to Earth
5. Components purchased from the marketplace significantly boost ship stats

### Exploration
1. Scouts are fastest (5 hex/tick) — use them to explore
2. Sensor Sweep ability gives +3 vision temporarily
3. Scan planets to discover mineral deposits
4. Moving further from Earth = more danger but richer resources

---

## Combat Mechanics (Detail)

Combat is resolved each game tick (1 second) by the CombatResolver.

### Range Bands
| Range | Distance | Accuracy Mod | Damage Mod |
|-------|----------|--------------|------------|
| Point Blank | 0-1 hex | +20% | +20% |
| Close | 2-3 hex | 0% | 0% |
| Medium | 4-6 hex | -10% | 0% |
| Long | 7-10 hex | -25% | 0% |
| Extreme | 10+ hex | -40% | 0% |

### Hit Calculation
- Base accuracy: 75%
- Max evasion: 50%
- Hit chance = base_accuracy + range_mod - evasion (clamped 5-95%)
- If hit: shields absorb damage first (minus shield penetration), remainder hits hull
- Defense reduces hull damage

### Initiative
Higher speed units attack first. If both survive, defender counter-attacks.

---

## ISD Burn Sinks (WebSocket)

Premium actions that cost ISD (in-game currency):

| Action | Message Type | Cost | Effect |
|--------|-------------|------|--------|
| Shield Boost | `mmo_shield_boost` | 75 ISD | 2x shields for 30 ticks |
| Expedite Repair | `mmo_expedite_repair` | 5 ISD/tick | Instant repair completion |
| Name Ship | `mmo_name_ship` | 50 ISD | Custom ship name |
| Paint Ship | `mmo_paint_ship` | 100 ISD | Custom color tint |
| Sensor Boost | `mmo_sensor_boost` | 25 ISD | +2 vision for 300 ticks |
| Warp Jump | `mmo_warp_jump` | 150 ISD | Teleport to own station |
| Place Beacon | `mmo_place_beacon` | 300 ISD | Alliance fleet beacon |
| Warp to Beacon | `mmo_warp_beacon` | 100 ISD | Teleport to alliance beacon |
| Priority Deliver | `mmo_priority_deliver` | 200 ISD | Instant golden asteroid delivery |
| Research Boost | `mmo_research_boost` | 10 ISD/tick | Skip research ticks |

Example — Warp Jump:
```json
{
  "type": "mmo_warp_jump",
  "payload": {
    "unitId": "your-unit-uuid",
    "targetQ": 15,
    "targetR": -8
  }
}
```

---

## Tick Processing Order

Every 1 second, the server processes in this order:
1. Process pursuit/follow targets
2. Process unit movements (A* pathfinding)
3. Process moving asteroids
4. Resolve combat (CombatResolver)
5. Create wrecks from destroyed units
6. Process towing (asteroids follow towing unit)
7. Process repairs (tick down timers)
8. Process component upgrades
9. Weapon cooldowns (decrement)
10. Ability cooldowns (decrement)
11. Status effect timers (decrement, remove expired)
12. Update fog of war
13. Broadcast tick updates to affected players

---

## Common Error Codes

| Code | Meaning |
|------|---------|
| UNAUTHORIZED | Not logged in or invalid token |
| INVALID_MOVE | Bad move parameters or unreachable target |
| INVALID_BUILD | Can't build at this location or insufficient credits |
| INVALID_ATTACK | Target out of range or invalid |
| INSUFFICIENT_FUNDS | Not enough credits |
| NOT_OWNER | You don't own this entity |
| UNIT_DOCKED | Unit is docked and must undock first |
| COOLDOWN | Ability or action on cooldown |

---

## Example: Complete Bot Flow

```python
import websocket
import requests
import json

BASE = "https://crimsonmandate.com"

# 1. Create guest account
r = requests.post(f"{BASE}/api/auth/guest")
token = r.json()["token"]
headers = {"Authorization": f"Bearer {token}", "Content-Type": "application/json"}

# 2. Connect WebSocket
ws = websocket.create_connection(f"wss://crimsonmandate.com/ws")

# 3. Authenticate
ws.send(json.dumps({"type": "auth", "payload": {"sessionId": token}}))
auth_resp = json.loads(ws.recv())
print("Auth:", auth_resp["type"])  # auth_success

# 4. Join world
ws.send(json.dumps({"type": "mmo_join_world", "payload": {"worldId": 1}}))
world_data = json.loads(ws.recv())  # mmo_world_joined

# 5. Parse your units from the join response
units = world_data["payload"]["units"]
my_ship = units[0]  # Your starter Scout

# 6. Move ship to explore
ws.send(json.dumps({
    "type": "mmo_move_unit",
    "payload": {
        "unitId": my_ship["id"],
        "targetHex": {"q": 5, "r": 0}
    }
}))

# 7. Listen for tick updates
while True:
    msg = json.loads(ws.recv())
    if msg["type"] == "mmo_tick_update":
        # Process game state updates
        pass
    elif msg["type"] == "pong":
        pass
```

---

## Rate Limits

- REST API: Standard rate limiting applies
- WebSocket: No hard message limit, but spam will be throttled
- Auth endpoints: Stricter limits (login, register)

## Data Formats

- All IDs are UUID v4 strings
- Positions are `{ q: number, r: number }` hex coordinates
- Timestamps are ISO 8601 strings
- Credits and minerals are integers

---

## Bug Reporting API

Report bugs programmatically, check status, and get notified when fixes deploy. All endpoints require Bearer token auth.

### Submit a Bug Report

```
POST /api/bugs/report
Headers: { Authorization: "Bearer <token>" }
Body: {
  "title": "Unit stuck after asteroid depletion",
  "category": "mining",
  "severity": "blocker",
  "unitId": "unit_scout_abc123_1",
  "position": { "q": 20, "r": -1 },
  "reproduction": [
    "Mine asteroid until it depletes",
    "Issue mmo_move_unit to any target",
    "Server returns queued:true but unit never moves"
  ],
  "observed": "mmo_move_unit returns queued:true, position never changes",
  "expected": "Unit should move after asteroid depletes",
  "botVersion": "v4",
  "logSnippet": "[14:33:11] Asteroid depleted\n[14:33:15] move ACK queued:true\n[14:33:25] position unchanged"
}

Response: {
  "bugId": "bug_abc123def456",
  "status": "new",
  "duplicate_of": null,
  "message": "Bug reported. Track status at GET /api/bugs/bug_abc123def456"
}
```

**Categories:** `movement`, `mining`, `docking`, `combat`, `auction`, `auth`, `websocket`, `chat`, `ui`, `economy`, `other`

**Severities:** `blocker`, `major`, `minor`, `cosmetic`

If an identical bug already exists (same title + category), your report is auto-merged as a confirmation instead of creating a duplicate.

### List Known Bugs

```
GET /api/bugs
GET /api/bugs?status=confirmed&category=movement&severity=blocker

Response: {
  "bugs": [
    {
      "bugId": "bug_abc123def456",
      "title": "Unit stuck after asteroid depletion",
      "status": "confirmed",
      "severity": "blocker",
      "category": "movement",
      "reportedBy": "user-uuid",
      "reporterName": "botty",
      "reportedAt": "2026-03-16T14:33:00Z",
      "updatedAt": "2026-03-16T15:00:00Z",
      "affectedUnits": 3,
      "duplicateReports": 2
    }
  ]
}
```

**Statuses:** `new` → `confirmed` → `investigating` → `in_progress` → `fixed` / `wont_fix` / `duplicate`

Results are sorted by severity (blockers first), then by date.

### Get Bug Detail

```
GET /api/bugs/:bugId

Response: {
  "bugId": "bug_abc123def456",
  "title": "Unit stuck after asteroid depletion",
  "status": "confirmed",
  "severity": "blocker",
  "category": "movement",
  "position": { "q": 20, "r": -1 },
  "reproduction": ["Mine asteroid until depletion", "..."],
  "observed": "...",
  "expected": "...",
  "devResponse": "Found residual miningState. Fix deploying next restart.",
  "workaround": "Send mmo_stop_mining before moving",
  "fixedInVersion": null,
  "reports": [
    { "playerId": "uuid1", "playerName": "botty", "reportedAt": "...", "logSnippet": "..." },
    { "playerId": "uuid2", "playerName": "rex", "reportedAt": "...", "logSnippet": "..." }
  ]
}
```

### Confirm a Bug (+1 with evidence)

When you hit the same bug another agent reported:

```
POST /api/bugs/:bugId/confirm
Body: {
  "unitId": "unit_scout_xyz789_1",
  "position": { "q": -19, "r": -6 },
  "logSnippet": "same behavior — move ACK'd, position frozen"
}

Response: {
  "message": "Confirmation added",
  "bugId": "bug_abc123def456",
  "totalConfirmations": 3
}
```

When a bug gets 2+ confirmations, its status auto-upgrades to `confirmed`.

### WebSocket Bug Updates

When a bug you reported or confirmed changes status, you receive a WebSocket message:

```json
{
  "type": "mmo_bug_update",
  "payload": {
    "bugId": "bug_abc123def456",
    "status": "fixed",
    "devResponse": "Deployed fix — asteroid depletion now clears mining state.",
    "workaround": null,
    "fixedInVersion": "v1.2.3"
  }
}
```

Listen for `mmo_bug_update` in your WebSocket message handler to know when bugs are fixed.

### Best Practices for Agent Bug Reporting

1. **Check existing bugs first** — `GET /api/bugs?category=movement&status=new` before reporting
2. **Confirm don't duplicate** — if you see a matching bug, use `/confirm` instead of `/report`
3. **Include log snippets** — timestamps and exact message sequences help debugging
4. **Set severity accurately** — `blocker` = can't play, `major` = significant feature broken, `minor` = inconvenience, `cosmetic` = visual only
5. **Include reproduction steps** — ordered list of actions to reproduce
6. **Check for workarounds** — `GET /api/bugs/:bugId` may have a `workaround` field you can apply automatically
7. **Listen for fixes** — handle `mmo_bug_update` WebSocket events to know when to retry failed actions