> ## Documentation Index
> Fetch the complete documentation index at: https://docs.alakazam.gg/llms.txt
> Use this file to discover all available pages before exploring further.

# Quickstart

> Submit your first dream-training job and read the oracle's verdict.

Everything is bearer-key authenticated. Keys are provisioned per partner;
there is no self-serve signup for Train yet. The API lives at
`https://api.alakazam.gg/train`. The serving box wakes on your first request:
during boot you get `503 {"status": "waking"}` with a `phase` field; retry the
same call until it succeeds (4 to 8 minutes).

## 1. Submit a smoke job

```bash theme={null}
curl -s -X POST https://api.alakazam.gg/train/jobs \
  -H "Authorization: Bearer $TRAIN_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "job_id": "my-smoke-001",
    "train": {"pop": 6, "gens": 2, "T": 20, "seed": 4242},
    "exam":  {"episodes": 20}
  }'
```

```json theme={null}
{"job_id": "my-smoke-001", "status": "spawned",
 "poll": "/jobs/my-smoke-001", "log": "/jobs/my-smoke-001/log"}
```

The POST returns immediately. Job ids are one-shot: reusing one returns
`409`, so pick a new id per run.

## 2. Poll until done

```bash theme={null}
curl -s https://api.alakazam.gg/train/jobs/my-smoke-001 -H "Authorization: Bearer $TRAIN_KEY"
```

`job.json` updates after every training generation (`per_gen`) and every
stage transition, so this endpoint doubles as live progress. `status` walks
`running → done` (or `failed`). For a human-readable tail:

```bash theme={null}
curl -s "https://api.alakazam.gg/train/jobs/my-smoke-001/log?n=100" -H "Authorization: Bearer $TRAIN_KEY"
```

## 3. Read the result

When `status` is `done`:

* `genome6` / `genome9`: the champion controller,
* `dream_F`: dream fitness (not a capability claim),
* `oracle.verdict`: the frozen exam's 4-bar verdict,
* `oracle.worlds.{arena,slalom}`: per-episode physics rows + summary.

<Warning>
  A smoke champion fails the exam loudly (20/20 contact episodes). That is the
  anti-exploit machinery working, not a bug. Real training runs warm-started
  from a good parent achieve 0 contacts in 40/40 episodes. See
  [The exam](/train/exam-contract) for how to read verdicts.
</Warning>

## 4. Scale up with lineage

```bash theme={null}
curl -s -X POST https://api.alakazam.gg/train/jobs \
  -H "Authorization: Bearer $TRAIN_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "job_id": "my-real-001",
    "train": {"pop": 10, "gens": 8, "T": 60, "seed": 61,
              "parent": {"job_id": "my-smoke-001"}},
    "exam":  {"episodes": 20}
  }'
```

* Use `T: 60` for `dream_F` comparable to campaign history (`T: 20` scores are
  not comparable).
* `parent` warm-starts CMA-ES at the prior champion (`sigma0 = 2.0`); a parent
  `job_id` with no champion is refused with `422`, never silently cold-started.
* Keep `episodes: 20`. Webots startup dominates the cost, so reduced-episode
  exams are barely cheaper and their results are not comparable.

## Timings

| Job                                 | Serving VM (measured) |
| ----------------------------------- | --------------------- |
| Smoke (`pop 6, gens 2, T 20`)       | 12–17 min             |
| Real-scale (`pop 10, gens 8, T 60`) | 3–4 h                 |
| Exam stage alone                    | 4–6 min               |