# Running this on the Mac

## The whole thing, once

1. Double-click `lld-trainer.zip` in Finder. You get a `lld-trainer` folder.
2. Open Terminal. Type `cd ` (with the space), drag the folder onto the Terminal window, press Return.
3. Run:

```
bash run.sh
```

That is it. Your browser opens at `http://127.0.0.1:7777`.

**From then on you can just double-click `START.command`.** The first run makes that possible — a zip
built on Windows carries no Unix permission bits, so nothing arrives executable, and the first run
fixes that for you. Which is also why step 3 says `bash run.sh` rather than `./run.sh`.

## What the first run does on its own

Nothing here needs installing beforehand, and nothing is installed system-wide.

| It needs | What happens if it is missing |
|---|---|
| Node 24+ | Fetches a private copy into `.toolchain/node` (~30 MB, once). Your system Node is used if it is new enough and left alone if it is not |
| A JDK 21+ | Finds one already on the Mac first — a JetBrains IDE bundles one, and that is usually a hit. Only downloads Temurin (~180 MB) if there is genuinely nothing usable |
| JUnit | Fetched once, ~2.5 MB |
| The interface | Already built and shipped inside the zip. No `npm` needed |

Everything lands inside the folder. Deleting the folder removes every trace.

**Node 24 is a real floor, not caution.** `node:sqlite` needs a flag on Node 22, so a Mac with 22
would start and then fail with a module error that looks like a broken download.

## The judge key

Grading works without any key — it falls back to a local model if you have Ollama, and to the
deterministic checks otherwise. For the full LLM judge, put your Gemini key in a file called `.env`
next to `run.sh`:

```
GEMINI_API_KEY=your-key-here
```

`.env` is never packaged, never uploaded and never overwritten by an update. If you would rather not
copy the key at all, point at a file you already keep:

```
DOJO_KEY_FILE="/path/to/your/keys.txt" bash run.sh
```

That file may hold other credentials in other formats; lines that are not `KEY=value` are ignored.

On startup you will see `keys: GEMINI_API_KEY (from ...)` and a tier — `T1b` means the Gemini judge
is live. A key set in your shell always beats the file, so you can override it for one run.

## Updating

`run.sh` checks for a newer published build each start and updates in place. It will never touch
`data/` (your progress), `workspace/` (attempts in flight), `.toolchain/` (the JDK) or `.env`.

If you are offline, or the network is behind a hotel login page, it says so in one line and starts
the version you have. It cannot stop you practising. To skip the check:

```
bash run.sh --no-update
```

## If something goes wrong

- **`Permission denied`** — use `bash run.sh`, not `./run.sh`. See step 3.
- **The browser does not open** — go to `http://127.0.0.1:7777` yourself. The server is fine.
- **"Node 24+ was not found" and no network** — install Node from nodejs.org and re-run. Nothing else.
- **Grading feels shallow** — check the tier on the startup line. `T3` means no LLM judge was found,
  so only the deterministic checks ran.
