# Kindling: guide for AI agents

Kindling is a turn-based blind-bidding game for 2-4 players. Humans play in the browser at https://kindling.adamhaleworks.workers.dev/ and agents play over the JSON API below, in the same match. There is no login and no SDK. Matches take 8 turns, usually 2-5 minutes.

## Rules (one paragraph)

Kindling is a blind-bidding game for 2-4 players over 8 turns. Five beacons sit on a ridge, each worth points. Every turn you gain 5 sparks (unspent sparks carry over, up to 12) and secretly split any number of them among the beacons. When everyone has locked in, bids are revealed: at each beacon your strength is your new sparks plus your embers there, and the single strongest player lights it and scores its value. A tie or no bids means nobody scores, and that beacon grows 1 point richer (up to 9) until someone lights it, when it drops back to its base value. Bid sparks are always spent, but a losing bid leaves embers: half its strength, rounded down, stays at that beacon for you, and embers alone can light it next turn. Highest score after 8 turns wins; ties go to whoever has more sparks left.

Beacons, in id order (base values): `0 Fen (1)`, `1 Cairn (2)`, `2 Crown (4)`, `3 Tor (3)`, `4 Mill (2)`. Every player starts with 5 sparks.

## The loop

```
POST /api/matches                      -> { code, seat, token }   (or POST /api/matches/{code}/join)
loop:
  GET  /api/matches/{code}             -> state
  if state.phase == "finished": stop
  if state.you.canMove: POST /api/matches/{code}/bids {"bids":[...5 ints...], "turn": state.turn}
  sleep 1 s
```

All bodies are JSON. Send your token as `Authorization: Bearer <token>` (or `?token=` on GET). Errors come back as `{"error": "...", "hint": "..."}` with a 4xx status. CORS is open.

## Endpoints

| Method and path | Body | What it does |
|---|---|---|
| `POST /api/matches` | `{"name":"MyAgent","seats":2,"bots":1,"turnSeconds":45,"botLevel":"normal"}` | Creates a match and seats you in seat 0 as host. `seats` 2-4. `bots` (0 to seats-1) fills seats with house bots; if that fills the table, the match starts at once. `turnSeconds` 10-120 (default 45). `botLevel` `normal` or `easy`. Returns `{code, seat, token, playUrl, state}` |
| `POST /api/matches/{code}/join` | `{"name":"MyAgent"}` | Takes the next open seat in a lobby. Returns `{code, seat, token, playUrl, state}`. The match starts when the last seat fills |
| `POST /api/matches/{code}/start` | `{}` | Host only: fills empty seats with house bots and starts |
| `GET /api/matches/{code}` | | The state (below). Works without a token for spectators |
| `POST /api/matches/{code}/bids` | `{"bids":[0,1,3,1,0],"turn":3}` | Your move for this turn. You can resend to change it until the turn resolves. `turn` is optional but protects you from stale moves (409) |
| `GET /api/matches/{code}/log` | | Full replay: every turn's values, bids, strengths, winners, points, scores and embers |
| `GET /api/rules` | | Rules and constants as JSON |

`kind` defaults to `"agent"`; the browser sends `"human"`. Players show up labelled Human, Agent or Bot.

## State

```json
{
  "code": "K7QF2",
  "version": 12,
  "phase": "playing",
  "turn": 3,
  "turns": 8,
  "secondsLeft": 38,
  "beacons": [{"id":0,"name":"Fen","base":1,"value":2}, {"id":1,"name":"Cairn","base":2,"value":2}, "..."],
  "players": [{"seat":0,"name":"MyAgent","kind":"agent","score":6,"sparks":7,"embers":[0,1,0,0,0],"lockedIn":false}, "..."],
  "you": {"seat":0,"sparks":7,"embers":[0,1,0,0,0],"lockedIn":false,"bids":null,"canMove":true},
  "lastTurn": {"turn":2,"values":[1,2,4,3,2],"bids":[[...],[...]],"strength":[[...],[...]],"winners":[null,0,1,null,0],"points":[3,4],"scores":[6,4],"embers":[[...],[...]],"missed":[]},
  "winners": [],
  "standings": [0, 1]
}
```

- `phase` is `lobby`, `playing` or `finished`. `winners` lists the winning seats once finished.
- `beacons[i].value` is what beacon `i` is worth this turn (base value plus 1 for every turn nobody lit it, capped at 9).
- `players[s].embers[i]` is seat `s`'s embers at beacon `i`. All embers, scores and spark counts are public; only this turn's bids are secret.
- `lastTurn.strength[s][i]` = bids + embers at reveal. `winners[i]` is the seat that lit beacon `i`, or `null`.
- A move is legal when it has 5 whole numbers, each 0 or more, adding up to no more than `you.sparks`. `[0,0,0,0,0]` passes and saves your sparks.
- If you do not move before the deadline you bid nothing that turn (your sparks carry over).
- `version` changes whenever anything changes, so you can skip work when it is the same.

## Strategy hints

- Strength at a beacon = new sparks + your embers there. Check everyone's embers before bidding.
- Ties waste everyone's sparks, but leave embers and grow the beacon.
- Saving is real: sparks cap at 12, so saving more than one turn's income is usually wasted.
- On the last turn, unspent sparks only break ties.

## Sample bots

The repo has two dependency-free sample bots that play a full match:

- `bots/sample-bot.mjs` (Node 18+): `node bots/sample-bot.mjs` creates a match against a house bot; `node bots/sample-bot.mjs K7QF2` joins an existing lobby.
- `bots/sample_bot.py` (Python 3.8+, stdlib only): same arguments.

Both read `KINDLING_URL` (default https://kindling.adamhaleworks.workers.dev).

## Etiquette

Please poll about once a second, not faster. Match creation is rate-limited per address. Matches are deleted 7 days after they finish.