kradle 0.6.6 → 0.6.8

package/static/ai_docs/LLM_CLI_REFERENCE.md

@@ -119,11 +119,12 @@ kradle challenge create my-first-challenge
 
 ### `kradle challenge build <name>`
 
-Builds a challenge datapack, validates it, and uploads everything to the cloud.
+Builds a challenge datapack locally, validates it, and optionally uploads to the cloud.
 
 **Usage:**
 ```bash
 kradle challenge build <challenge-name>
+kradle challenge build <challenge-name> --no-upload
 kradle challenge build <challenge-name> --public
 kradle challenge build <challenge-name> --no-validate
 kradle challenge build --all
@@ -140,21 +141,24 @@ kradle challenge build --all --public
 |------|-------|-------------|---------|
 | `--all` | `-a` | Build all local challenges | false |
 | `--public` | `-p` | Set visibility to public after upload | false |
-| `--no-validate` | | Skip datapack validation before upload | false |
+| `--no-validate` | | Skip datapack validation | false |
+| `--no-upload` | | Build locally only (skip cloud config/datapack upload) | false |
+
+`--public` is incompatible with `--no-upload`.
 
 **What it does:**
-1. Creates the challenge in cloud if it doesn't exist
-2. Executes `challenge.ts` to generate the datapack
+1. Executes `challenge.ts` to generate the datapack
    - Passes `KRADLE_CHALLENGE_END_STATES` env var containing a JSON array of end state keys from `config.endStates` (e.g., `["victory", "defeat"]`)
    - Passes `KRADLE_CHALLENGE_ROLES` env var containing a JSON array of role names from `config.roles` (e.g., `["attacker", "defender"]`)
    - Passes `KRADLE_CHALLENGE_LOCATIONS` env var containing a JSON array of location keys from `config.challengeConfig.locations` (e.g., `["spawn", "goal"]`)
    - The `@kradle/challenges-sdk` uses these to register valid end states, roles, and locations at build time
-3. Validates the datapack using Spyglass engine (unless `--no-validate`)
+2. Validates the datapack using Spyglass engine (unless `--no-validate`)
    - Checks `.mcfunction` files for syntax errors, invalid commands, JSON text components
-   - **Errors block the upload** - fix them before the challenge can be uploaded
+   - **Errors block command completion** - fix them before the build can finish
    - Auto-detects Minecraft version from `pack.mcmeta` `pack_format`
-4. Uploads `config.ts` metadata to cloud
-5. Compresses and uploads datapack to cloud storage
+3. If upload is enabled (default), creates challenge in cloud if needed
+4. If upload is enabled (default), uploads `config.ts` metadata to cloud
+5. If upload is enabled (default), compresses and uploads datapack to cloud storage
 
 **Validation Output:**
 ```
@@ -164,7 +168,7 @@ data/kradle/functions/init.mcfunction:5:1 warning: Unused objective
 
 Found 1 error, 1 warning
 
-Error: Validation failed with 1 error(s). Upload aborted.
+Error: Validation failed with 1 error(s). Build aborted.
 ```
 
 **Examples:**
@@ -172,6 +176,9 @@ Error: Validation failed with 1 error(s). Upload aborted.
 # Build single challenge (with validation)
 kradle challenge build my-challenge
 
+# Build local datapack only (no cloud upload)
+kradle challenge build my-challenge --no-upload
+
 # Build and make public
 kradle challenge build my-challenge --public
 
@@ -410,11 +417,13 @@ When no agents are specified, the command enters interactive mode:
 | Flag | Short | Description |
 |------|-------|-------------|
 | `--studio` | `-s` | Run in local studio environment instead of production |
+| `--local` | `-l` | Run locally using Docker (spins up MC server + arena-minecraft containers) |
+| `--arena-image` | | Override arena-minecraft Docker image URL (env: `KRADLE_ARENA_IMAGE`) |
 | `--no-open` | | Don't open the run URL in the browser |
 | `--no-wait` | | Don't wait for completion (fire and forget) |
 | `--no-summary` | | Don't wait for the AI-generated summary |
 
-**Behavior:**
+**Behavior (remote, default):**
 1. Parses inline agents or enters interactive mode for agent selection
 2. Creates a run with the challenge and specified participants
 3. Opens the run URL in the browser (unless `--no-open`)
@@ -423,6 +432,31 @@ When no agents are specified, the command enters interactive mode:
 
 **Terminal states:** The polling stops when the run reaches: `finished`, `game_over`, `error`, `completed`, `cancelled`, `timeout`, or `failed`.
 
+**Behavior (local, with `--local`):**
+1. Parses inline agents or enters interactive mode for agent selection
+2. Fetches challenge config from the API
+3. Builds the challenge datapack locally (with validation)
+4. Creates a real backend job (`env: "studio"`) — returns full job object with agent configs, participant IDs, etc.
+5. Downloads the challenge world from the cloud
+6. Starts a Minecraft server Docker container (`marctv/minecraft-papermc-server:1.20.4`)
+7. Starts an arena-minecraft Docker container (shares MC server network), passing the full backend job response
+8. All players who join the MC server are automatically OP'd (via an auto-op datapack)
+9. Streams arena logs to stdout until the run completes
+10. Ctrl+C triggers graceful shutdown (arena `/shutdown` endpoint, then container stop/remove)
+
+**Local mode requirements:**
+- Docker Desktop must be running (Docker is only checked when `--local` is used)
+- The challenge must exist locally (with `challenge.ts` and `config.ts`)
+- First run pulls images which may take several minutes
+- The agent URL is derived from the API URL (e.g., `dev-api.kradle.ai` → `dev-agents.kradle.ai`)
+
+**Local mode incompatibilities:** `--local` cannot be combined with `--studio`, `--no-open`, `--no-wait`, `--screenshots`, or `--record`.
+
+**Arena image override:** The `--arena-image` flag (or `KRADLE_ARENA_IMAGE` env var) allows testing dev or staging arena builds:
+- Dev: `us-central1-docker.pkg.dev/mckradle-3c267/dev-arenas/minecraft:<sha>`
+- Staging: `us-central1-docker.pkg.dev/kradle-staging/staging-arenas/minecraft:<sha>`
+- Prod (default): `us-central1-docker.pkg.dev/kradle-prod-449119/prod-arenas/minecraft:<sha>`
+
 **Examples:**
 ```bash
 # Interactive mode - prompts for agent selection
@@ -447,6 +481,13 @@ kradle challenge run my-challenge team-kradle:gemini-3-flash --no-open
 
 # Fire and forget (don't wait for completion)
 kradle challenge run my-challenge team-kradle:gemini-3-flash --no-wait
+
+# Run locally with Docker
+kradle challenge run my-challenge --local team-kradle:gemini-3-flash,team-kradle:grok-4-1-fast
+
+# Run locally with a dev arena image
+kradle challenge run my-challenge --local \
+  --arena-image us-central1-docker.pkg.dev/mckradle-3c267/dev-arenas/minecraft:abc1234
 ```
 
 ---
@@ -1274,13 +1315,14 @@ kradle challenge build --all --public
 |---------|-------------|
 | `kradle init` | Initialize new project |
 | `kradle challenge create <name>` | Create new challenge |
-| `kradle challenge build <name>` | Build and upload challenge |
+| `kradle challenge build <name>` | Build challenge (uploads by default) |
 | `kradle challenge build --all` | Build all challenges |
 | `kradle challenge delete <name>` | Delete challenge |
 | `kradle challenge list` | List all challenges |
 | `kradle challenge pull [name]` | Pull challenge from cloud |
 | `kradle challenge watch <name>` | Watch and auto-rebuild |
 | `kradle challenge run <name>` | Run challenge and wait for completion |
+| `kradle challenge run <name> --local` | Run challenge locally using Docker |
 | `kradle challenge runs list` | List recent runs |
 | `kradle challenge runs get <run-id>` | Get details and logs for a run |
 | `kradle experiment create <name>` | Create new experiment |