kradle 0.6.3 → 0.6.5

package/dist/commands/ai-docs/workflow.d.ts

@@ -0,0 +1,6 @@
+import { Command } from "@oclif/core";
+export default class Workflow extends Command {
+    static description: string;
+    static examples: string[];
+    run(): Promise<void>;
+}

package/dist/commands/ai-docs/workflow.js

@@ -0,0 +1,13 @@
+import fs from "node:fs/promises";
+import { Command } from "@oclif/core";
+import { getStaticResourcePath } from "../../lib/utils.js";
+export default class Workflow extends Command {
+    static description = "Output the challenge creation and edition workflow documentation for LLMs";
+    static examples = ["<%= config.bin %> <%= command.id %>"];
+    async run() {
+        await this.parse(Workflow);
+        const docPath = getStaticResourcePath("ai_docs/WORKFLOW.md");
+        const content = await fs.readFile(docPath, "utf-8");
+        this.log(content);
+    }
+}

package/dist/commands/challenge/run.d.ts

@@ -13,6 +13,7 @@ export default class Run extends Command {
         "studio-api-url": import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
         "studio-url": import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
         studio: import("@oclif/core/interfaces").BooleanFlag<boolean>;
+        record: import("@oclif/core/interfaces").BooleanFlag<boolean>;
         "no-open": import("@oclif/core/interfaces").BooleanFlag<boolean>;
         "no-wait": import("@oclif/core/interfaces").BooleanFlag<boolean>;
         "no-summary": import("@oclif/core/interfaces").BooleanFlag<boolean>;

package/dist/commands/challenge/run.js

@@ -15,6 +15,7 @@ export default class Run extends Command {
     static examples = [
         "<%= config.bin %> <%= command.id %> my-challenge",
         "<%= config.bin %> <%= command.id %> my-challenge --studio",
+        "<%= config.bin %> <%= command.id %> my-challenge --record",
         "<%= config.bin %> <%= command.id %> team-name:my-challenge",
         "<%= config.bin %> <%= command.id %> my-challenge --no-open",
         "<%= config.bin %> <%= command.id %> my-challenge --no-wait",
@@ -28,6 +29,7 @@ export default class Run extends Command {
     };
     static flags = {
         studio: Flags.boolean({ char: "s", description: "Run in studio environment", default: false }),
+        record: Flags.boolean({ char: "r", description: "Record the run (enables video recording)", default: false }),
         "no-open": Flags.boolean({
             description: "Don't open the run URL in the browser",
             default: false,
@@ -279,11 +281,12 @@ export default class Run extends Command {
             this.error("No participants specified. Use inline syntax or select agents interactively.");
         }
         try {
-            this.log(pc.blue(`\n>> Running challenge: ${challengeSlug}${flags.studio ? " (studio)" : ""}...`));
+            const jobType = flags.record ? "foreground_with_recording" : "foreground";
+            this.log(pc.blue(`\n>> Running challenge: ${challengeSlug}${flags.studio ? " (studio)" : ""}${flags.record ? " (recording)" : ""}...`));
             const response = await api.runChallenge({
                 challenge: challengeSlug,
                 participants,
-                jobType: "foreground",
+                jobType,
             });
             if (response.runIds && response.runIds.length > 0) {
                 const runId = response.runIds[0];

package/dist/commands/update.d.ts

@@ -0,0 +1,13 @@
+import { Command } from "@oclif/core";
+export default class Update extends Command {
+    static description: string;
+    static examples: string[];
+    static flags: {
+        "dry-run": import("@oclif/core/interfaces").BooleanFlag<boolean>;
+        yes: import("@oclif/core/interfaces").BooleanFlag<boolean>;
+        "add-missing": import("@oclif/core/interfaces").BooleanFlag<boolean>;
+    };
+    private compareFiles;
+    private showDiff;
+    run(): Promise<void>;
+}

package/dist/commands/update.js

@@ -0,0 +1,165 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { Command, Flags } from "@oclif/core";
+import enquirer from "enquirer";
+import pc from "picocolors";
+import { getStaticResourcePath } from "../lib/utils.js";
+// Files that should be synced on update (documentation files only)
+const SYNC_FILES = ["AGENTS.md", "CLAUDE.md"];
+export default class Update extends Command {
+    static description = "Update project template files (AGENTS.md, CLAUDE.md) to the latest version from the CLI";
+    static examples = [
+        "<%= config.bin %> <%= command.id %>",
+        "<%= config.bin %> <%= command.id %> --dry-run",
+        "<%= config.bin %> <%= command.id %> --yes",
+    ];
+    static flags = {
+        "dry-run": Flags.boolean({
+            description: "Preview changes without applying them",
+            default: false,
+        }),
+        yes: Flags.boolean({
+            char: "y",
+            description: "Skip confirmation prompts",
+            default: false,
+        }),
+        "add-missing": Flags.boolean({
+            description: "Add files that exist in template but not locally",
+            default: false,
+        }),
+    };
+    async compareFiles() {
+        const templateDir = getStaticResourcePath("project_template");
+        const cwd = process.cwd();
+        const comparisons = [];
+        for (const filename of SYNC_FILES) {
+            const templatePath = path.join(templateDir, filename);
+            const localPath = path.join(cwd, filename);
+            let templateContent;
+            let localContent = null;
+            try {
+                templateContent = await fs.readFile(templatePath, "utf-8");
+            }
+            catch {
+                // Template file doesn't exist (shouldn't happen)
+                continue;
+            }
+            try {
+                localContent = await fs.readFile(localPath, "utf-8");
+            }
+            catch {
+                // Local file doesn't exist
+            }
+            let status;
+            if (localContent === null) {
+                status = "missing_local";
+            }
+            else if (templateContent === localContent) {
+                status = "identical";
+            }
+            else {
+                status = "different";
+            }
+            comparisons.push({
+                filename,
+                templatePath,
+                localPath,
+                templateContent,
+                localContent,
+                status,
+            });
+        }
+        return comparisons;
+    }
+    showDiff(comparison) {
+        this.log(pc.bold(`\n--- ${comparison.filename} ---`));
+        if (comparison.status === "missing_local") {
+            this.log(pc.green("+ (new file)"));
+            const lines = comparison.templateContent.split("\n").slice(0, 10);
+            for (const line of lines) {
+                this.log(pc.green(`+ ${line}`));
+            }
+            if (comparison.templateContent.split("\n").length > 10) {
+                this.log(pc.dim(`  ... and ${comparison.templateContent.split("\n").length - 10} more lines`));
+            }
+            return;
+        }
+        if (comparison.status === "identical") {
+            this.log(pc.dim("(no changes)"));
+            return;
+        }
+        // Show simple line count diff for different files
+        const templateLines = comparison.templateContent.split("\n").length;
+        const localLines = comparison.localContent?.split("\n").length || 0;
+        this.log(pc.yellow(`  Local: ${localLines} lines`));
+        this.log(pc.green(`  Template: ${templateLines} lines`));
+        this.log(pc.dim("  (file contents differ - will be replaced with template version)"));
+    }
+    async run() {
+        const { flags } = await this.parse(Update);
+        const isDryRun = flags["dry-run"];
+        const skipPrompts = flags.yes;
+        const addMissing = flags["add-missing"];
+        this.log(pc.blue(">> Checking for template updates...\n"));
+        const comparisons = await this.compareFiles();
+        // Categorize files
+        const identical = comparisons.filter((c) => c.status === "identical");
+        const different = comparisons.filter((c) => c.status === "different");
+        const missingLocal = comparisons.filter((c) => c.status === "missing_local");
+        // Show summary
+        if (identical.length > 0) {
+            this.log(pc.green(`✓ Up to date: ${identical.map((c) => c.filename).join(", ")}`));
+        }
+        if (different.length === 0 && (missingLocal.length === 0 || !addMissing)) {
+            this.log(pc.green("\n✓ All template files are up to date!"));
+            if (missingLocal.length > 0) {
+                this.log(pc.dim(`  (${missingLocal.length} file(s) missing locally, use --add-missing to create them)`));
+            }
+            return;
+        }
+        // Show files that need updating
+        if (different.length > 0) {
+            this.log(pc.yellow(`\n⚠ Files to update: ${different.map((c) => c.filename).join(", ")}`));
+            for (const comparison of different) {
+                this.showDiff(comparison);
+            }
+        }
+        if (missingLocal.length > 0 && addMissing) {
+            this.log(pc.cyan(`\n+ Files to create: ${missingLocal.map((c) => c.filename).join(", ")}`));
+            for (const comparison of missingLocal) {
+                this.showDiff(comparison);
+            }
+        }
+        if (isDryRun) {
+            this.log(pc.dim("\n(dry run - no changes applied)"));
+            return;
+        }
+        // Determine which files to update
+        const filesToUpdate = [...different];
+        if (addMissing) {
+            filesToUpdate.push(...missingLocal);
+        }
+        if (filesToUpdate.length === 0) {
+            return;
+        }
+        // Confirm update
+        if (!skipPrompts) {
+            const { confirm } = await enquirer.prompt({
+                type: "confirm",
+                name: "confirm",
+                message: `Update ${filesToUpdate.length} file(s)?`,
+                initial: true,
+            });
+            if (!confirm) {
+                this.log(pc.dim("Update cancelled."));
+                return;
+            }
+        }
+        // Apply updates
+        for (const comparison of filesToUpdate) {
+            await fs.writeFile(comparison.localPath, comparison.templateContent);
+            this.log(pc.green(`✓ Updated ${comparison.filename}`));
+        }
+        this.log(pc.green(`\n✓ Successfully updated ${filesToUpdate.length} file(s)!`));
+    }
+}

package/dist/lib/api-client.d.ts

@@ -75,7 +75,7 @@ export declare class ApiClient {
     runChallenge(runData: {
         challenge: string;
         participants: unknown[];
-        jobType: "background" | "foreground";
+        jobType: "background" | "foreground" | "foreground_with_recording";
     }): Promise<{
         runIds?: string[] | undefined;
         participants?: Record<string, {

package/oclif.manifest.json

@@ -42,6 +42,51 @@
         "init.js"
       ]
     },
+    "update": {
+      "aliases": [],
+      "args": {},
+      "description": "Update project template files (AGENTS.md, CLAUDE.md) to the latest version from the CLI",
+      "examples": [
+        "<%= config.bin %> <%= command.id %>",
+        "<%= config.bin %> <%= command.id %> --dry-run",
+        "<%= config.bin %> <%= command.id %> --yes"
+      ],
+      "flags": {
+        "dry-run": {
+          "description": "Preview changes without applying them",
+          "name": "dry-run",
+          "allowNo": false,
+          "type": "boolean"
+        },
+        "yes": {
+          "char": "y",
+          "description": "Skip confirmation prompts",
+          "name": "yes",
+          "allowNo": false,
+          "type": "boolean"
+        },
+        "add-missing": {
+          "description": "Add files that exist in template but not locally",
+          "name": "add-missing",
+          "allowNo": false,
+          "type": "boolean"
+        }
+      },
+      "hasDynamicHelp": false,
+      "hiddenAliases": [],
+      "id": "update",
+      "pluginAlias": "kradle",
+      "pluginName": "kradle",
+      "pluginType": "core",
+      "strict": true,
+      "enableJsonFlag": false,
+      "isESM": true,
+      "relativePath": [
+        "dist",
+        "commands",
+        "update.js"
+      ]
+    },
     "agent:list": {
       "aliases": [],
       "args": {},
@@ -142,6 +187,30 @@
         "cli.js"
       ]
     },
+    "ai-docs:workflow": {
+      "aliases": [],
+      "args": {},
+      "description": "Output the challenge creation and edition workflow documentation for LLMs",
+      "examples": [
+        "<%= config.bin %> <%= command.id %>"
+      ],
+      "flags": {},
+      "hasDynamicHelp": false,
+      "hiddenAliases": [],
+      "id": "ai-docs:workflow",
+      "pluginAlias": "kradle",
+      "pluginName": "kradle",
+      "pluginType": "core",
+      "strict": true,
+      "enableJsonFlag": false,
+      "isESM": true,
+      "relativePath": [
+        "dist",
+        "commands",
+        "ai-docs",
+        "workflow.js"
+      ]
+    },
     "challenge:build": {
       "aliases": [],
       "args": {
@@ -495,6 +564,7 @@
       "examples": [
         "<%= config.bin %> <%= command.id %> my-challenge",
         "<%= config.bin %> <%= command.id %> my-challenge --studio",
+        "<%= config.bin %> <%= command.id %> my-challenge --record",
         "<%= config.bin %> <%= command.id %> team-name:my-challenge",
         "<%= config.bin %> <%= command.id %> my-challenge --no-open",
         "<%= config.bin %> <%= command.id %> my-challenge --no-wait",
@@ -509,6 +579,13 @@
           "allowNo": false,
           "type": "boolean"
         },
+        "record": {
+          "char": "r",
+          "description": "Record the run (enables video recording)",
+          "name": "record",
+          "allowNo": false,
+          "type": "boolean"
+        },
         "no-open": {
           "description": "Don't open the run URL in the browser",
           "name": "no-open",
@@ -1435,5 +1512,5 @@
       ]
     }
   },
-  "version": "0.6.3"
+  "version": "0.6.5"
 }

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "kradle",
-	"version": "0.6.3",
+	"version": "0.6.5",
 	"description": "Kradle's CLI. Manage challenges, experiments, agents and more!",
 	"keywords": [
 		"cli"

package/static/ai_docs/WORKFLOW.md

@@ -0,0 +1,130 @@
+# Challenge Creation and Edition Workflow
+
+This document provides guidance on how to create a challenge using the cli
+
+## Challenge Creation
+
+### Phase 1: Challenge Definition
+
+Gather requirements by asking these questions. Save answers in a markdown summary in the challenge's `config.ts` description field.
+
+#### Questions to Ask
+
+| # | Question | Notes |
+|---|----------|-------|
+| 1 | **Solo or multi-agent?** | Determines roles configuration |
+| 2 | **World selection?** | New world → use flat world (ground Y = -60). Existing world → run `kradle world list` |
+| 3 | **Research goal?** | Agent efficiency? Emergent behavior? Collaboration vs competition? |
+| 4 | **Expected insights?** | What would be surprising or interesting to discover? |
+| 5 | **Success conditions?** | When does an agent "win"? |
+| 6 | **Optimization target?** | What metric should agents optimize? |
+| 7 | **Possible end states?** | All ways a run can terminate |
+| 8 | **Initial positioning?** | Where should agents spawn? |
+
+#### Objective Configuration Reference
+
+**`objective.fieldName`** (what to measure):
+
+| Value | Description |
+|-------|-------------|
+| `successful_run_count` | Number of successful runs |
+| `success_rate` | Percentage of successful runs |
+| `min_time_to_success` | Fastest completion time |
+| `max_time_to_success` | Slowest completion time |
+| `mean_time_to_success` | Average completion time |
+| `min_score` | Lowest score achieved |
+| `max_score` | Highest score achieved |
+| `mean_score` | Average score |
+
+
+**`objective.direction`**: `minimize` or `maximize`
+
+**`objective.thresholdFieldName`**: `runCount`
+
+> **Important:** If optimizing for score, define the score logic and report it with `main_score.set(value);`
+
+**Important**: roles should just be alphanumeric, no hypen no underscore
+
+### Things to consider when building a challenge:
+
+- Agents don't "see" the world with images, they get JSON observations about the world, so if you want them to take a specific path, you need to put a marker and tell the agent to follow that marker. The agent will use A* algorithm to go to the marker.
+
+- If you want your marker to be configurable by the user, use the location mechanism: create a location for each marker, and reference these locations by id in your code.
+
+---
+
+### Phase 2: Challenge Building
+
+#### Build Checklist
+
+1. **Create challenge** using CLI:
+   ```bash
+   kradle challenge create <name>
+   ```
+
+2. **Run TypeScript checks** to ensure compilation:
+   ```bash
+   npx tsc --noEmit
+   ```
+
+3. **Build and inspect datapack**:
+   ```bash
+   npx tsx challenges/<name>/challenge.ts
+   ```
+   Review generated `.mcfunction` files in `kradle-studio/challenges/<name>/datapack/`
+
+   IMPORTANT: do not change datapack files directly, always edit `challenge.ts` file
+
+4. **Update the `description` field in config.ts** with a markdown summary containing:
+   - Overview (what the challenge is)
+   - Setup (world, agents, duration)
+   - Mechanics (how the challenge works)
+   - Objective (what to optimize)
+   - Research goal (what insights we're looking for)
+   - What would be fun, suprising, bewildering to observe (what would go viral)
+   - End states (all ways the challenge can end)
+
+   > **Important:** Always update this field when mechanics change during development.
+
+5. **locations**
+   Worlds have locations. you can find out able them by running `kradle world info <world_slug>`
+   Make sure you use these coordinates when building things. 
+
+---
+
+### Phase 3: Challenge Testing
+
+#### Test Run Configuration
+- **Agent:** Use `gemini-2-5-flash` for all test runs
+- by default don't use the --no-open flag so the user can follow the runs
+- you can also ask the user if they want to record the run, in which case you'll add a --record to the `kradle challenge run` command
+
+#### Test Checklist
+
+1. **Check spawn positions** — Review `initial_state` observation in run logs to confirm agents spawn at expected coordinates
+
+2. **Verify world setup** — `kradle challenge run <challenge_slug> --screenshot` will generate screenshots of the scene. you will find the url of the screenshots in the logs. use these screenshots to confirm that you have built the right structures and that the agents are spawned at the right location.
+
+3. **Validate success conditions** — Run tests to confirm win conditions trigger correctly
+
+4. **Validate end states** — Test each possible end state fires appropriately
+
+
+#### Debugging Tips
+
+- Use `Actions.log_variable()` to create debug traces
+- As soon as the challenge starts, download the logs and start looking into them
+  ```bash
+  kradle challenge runs get <run_id>
+  ```
+- if the challenge doesn't end at the maximum set duration or on certain conditions, it is likely that the datapack failed at runtime and the timer doesn't work
+- if you don't see the structure you think you've built, it could be that the coordinates are off, or again that the datapack failed at runtime
+
+
+## Challenge Edition
+
+When editing a challenge first look at the `description` field in the `config.ts` file for instructions.
+
+If the challenge is remixed from another challenge, ask the user what they want to change/update, and why?
+
+Otherwise ask the user where they want to start. It's a good idea to look for past runs to understand what was the summary of these runs, and suggest further directions.

package/static/project_template/AGENTS.md

@@ -1,8 +1,8 @@
 # Kradle Challenge Development Guide
 
-## API & CLI Reference
+## API, CLI, Workflow References
 
-Always read both references before starting:
+Always read all 3 references before starting:
 
 ```bash
 # CLI reference (commands, flags, workflows)
@@ -10,108 +10,13 @@ kradle ai-docs cli
 
 # SDK reference (@kradle/challenges-sdk package documentation)
 kradle ai-docs challenges-sdk
+
+# Challenge creation and edition workflows
+kradle ai-docs workflow
 ```
 
 **Key principles:**
 - Use CLI commands to create challenges/experiments (avoid creating from scratch)
 - Comment all generated code for clarity
 
----
-
-## Workflow
-
-### Phase 1: Challenge Definition
-
-Gather requirements by asking these questions. Save answers in a markdown summary in the challenge's `config.ts` description field.
-
-#### Questions to Ask
-
-| # | Question | Notes |
-|---|----------|-------|
-| 1 | **Solo or multi-agent?** | Determines roles configuration |
-| 2 | **World selection?** | New world → use flat world (ground Y = -60). Existing world → run `kradle world list` |
-| 3 | **Research goal?** | Agent efficiency? Emergent behavior? Collaboration vs competition? |
-| 4 | **Expected insights?** | What would be surprising or interesting to discover? |
-| 5 | **Success conditions?** | When does an agent "win"? |
-| 6 | **Optimization target?** | What metric should agents optimize? |
-| 7 | **Possible end states?** | All ways a run can terminate |
-| 8 | **Initial positioning?** | Where should agents spawn? |
-
-#### Objective Configuration Reference
-
-**`objective.fieldName`** (what to measure):
-
-| Value | Description |
-|-------|-------------|
-| `successfulRunCount` | Number of successful runs |
-| `successRate` | Percentage of successful runs |
-| `minTimeToSuccess` | Fastest completion time |
-| `maxTimeToSuccess` | Slowest completion time |
-| `meanTimeToSuccess` | Average completion time |
-| `minScore` | Lowest score achieved |
-| `maxScore` | Highest score achieved |
-| `meanScore` | Average score |
-
-**`objective.direction`**: `minimize` or `maximize`
-
-**`objective.thresholdFieldName`**: `runCount`
-
-> **Important:** If optimizing for score, define the score logic and report it with `main_score.set(value);`
-
-**Important**: roles should just be alphanumeric, no hypen no underscore
-
----
-
-### Phase 2: Challenge Building
-
-#### Build Checklist
-
-1. **Create challenge** using CLI:
-   ```bash
-   kradle challenge create <name>
-   ```
-
-2. **Run TypeScript checks** to ensure compilation:
-   ```bash
-   npx tsc --noEmit
-   ```
-
-3. **Build and inspect datapack**:
-   ```bash
-   npx tsx challenges/<name>/challenge.ts
-   ```
-   Review generated `.mcfunction` files in `kradle-studio/challenges/<name>/datapack/`
-
-4. **Make sure the description field in config.ts is up to date**
-
-5. **locations**
-   Worlds have locations. you can find out able them by running `kradle world info <world_slug>`
-   Make sure you use these coordinates when building things. 
-
----
-
-### Phase 3: Challenge Testing
-
-#### Test Configuration
-- **Agent:** Use `gemini-2-5-flash` for all test runs
-
-#### Test Checklist
-
-1. **Check spawn positions** — Review `initial_state` observation in run logs to confirm agents spawn at expected coordinates
-
-2. **Verify world setup** — `kradle challenge run <challenge_slug> --screenshot` will generate screenshots of the scene. you will find the url of the screenshots in the logs. use these screenshots to confirm that you have built the right structures and that the agents are spawned at the right location.
-
-3. **Validate success conditions** — Run tests to confirm win conditions trigger correctly
-
-4. **Validate end states** — Test each possible end state fires appropriately
-
-
-#### Debugging Tips
-
-- Use `Actions.log_variable()` to create debug traces
-- As soon as the challenge starts, download the logs and start looking into them
-  ```bash
-  kradle challenge runs get <run_id>
-  ```
-- if the challenge doesn't end at the maximum set duration or on certain conditions, it is likely that the datapack failed at runtime and the timer doesn't work
-- if you don't see the structure you think you've built, it could be that the coordinates are off, or again that the datapack failed at runtime
+---