@kradle/cli 0.2.3 → 0.2.5

package/README.md

@@ -111,6 +111,19 @@ List all challenges (local and cloud):
 kradle challenge list
 ```
 
+### Pull Challenge
+
+Download a challenge from the cloud and extract source files locally:
+
+```bash
+kradle challenge pull                                  # Interactive selection
+kradle challenge pull <challenge-name>                 # Pull your own challenge
+kradle challenge pull <team-name>:<challenge-name>     # Pull a public challenge from another team
+kradle challenge pull <challenge-name> --yes           # Skip confirmation when overwriting
+```
+
+This downloads the challenge tarball, extracts `challenge.ts` and `config.ts`, and builds the datapack locally.
+
 ### Watch Challenge
 
 Watch a challenge for changes and auto-rebuild/upload:

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

@@ -0,0 +1,15 @@
+import { Command } from "@oclif/core";
+export default class Pull extends Command {
+    static description: string;
+    static examples: string[];
+    static args: {
+        challengeSlug: import("@oclif/core/interfaces").Arg<string | undefined>;
+    };
+    static flags: {
+        "api-key": import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
+        "api-url": import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
+        "challenges-path": import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
+        yes: import("@oclif/core/interfaces").BooleanFlag<boolean>;
+    };
+    run(): Promise<void>;
+}

package/dist/commands/challenge/pull.js

@@ -0,0 +1,182 @@
+import { existsSync } from "node:fs";
+import fs from "node:fs/promises";
+import path from "node:path";
+import { Command, Flags } from "@oclif/core";
+import enquirer from "enquirer";
+import { Listr } from "listr2";
+import pc from "picocolors";
+import * as tar from "tar";
+import { ApiClient } from "../../lib/api-client.js";
+import { extractShortSlug, getChallengeSlugArgument } from "../../lib/arguments.js";
+import { Challenge, SOURCE_FOLDER } from "../../lib/challenge.js";
+import { getConfigFlags } from "../../lib/flags.js";
+export default class Pull extends Command {
+    static description = "Pull a challenge from the cloud and extract source files locally";
+    static examples = [
+        "<%= config.bin %> <%= command.id %>",
+        "<%= config.bin %> <%= command.id %> my-challenge",
+        "<%= config.bin %> <%= command.id %> username:my-challenge",
+        "<%= config.bin %> <%= command.id %> my-challenge --yes",
+    ];
+    static args = {
+        challengeSlug: getChallengeSlugArgument({
+            description: "Challenge slug to pull (interactive selection if omitted)",
+            required: false,
+            allowTeam: true,
+        }),
+    };
+    static flags = {
+        yes: Flags.boolean({ char: "y", description: "Skip confirmation prompts", default: false }),
+        ...getConfigFlags("api-key", "api-url", "challenges-path"),
+    };
+    async run() {
+        const { args, flags } = await this.parse(Pull);
+        const api = new ApiClient(flags["api-url"], flags["api-key"]);
+        let challengeSlug = args.challengeSlug;
+        if (!challengeSlug) {
+            const [kradleChallenges, cloudChallenges, localChallenges] = await Promise.all([
+                api.listKradleChallenges(),
+                api.listChallenges(),
+                Challenge.getLocalChallenges(),
+            ]);
+            const allChallenges = [...kradleChallenges, ...cloudChallenges];
+            if (allChallenges.length === 0) {
+                this.error(pc.red("No challenges found in the cloud."));
+            }
+            const localSet = new Set(localChallenges);
+            const slugs = allChallenges.map((c) => c.slug).sort();
+            const choices = slugs.map((slug) => {
+                const shortSlug = extractShortSlug(slug);
+                const isLocal = localSet.has(shortSlug);
+                const status = isLocal ? pc.yellow(" (local)") : "";
+                return {
+                    name: slug,
+                    message: `${slug}${status}`,
+                };
+            });
+            const response = await enquirer.prompt({
+                type: "select",
+                name: "challenge",
+                message: "Select a challenge to pull",
+                choices,
+            });
+            challengeSlug = response.challenge;
+        }
+        const shortSlug = extractShortSlug(challengeSlug);
+        const challenge = new Challenge(shortSlug, flags["challenges-path"]);
+        const existsInCloud = await api.challengeExists(challengeSlug);
+        if (!existsInCloud) {
+            this.error(pc.red(`Challenge "${challengeSlug}" does not exist in the cloud.`));
+        }
+        const existsLocally = existsSync(challenge.challengeDir);
+        const hasLocalFiles = existsLocally && (existsSync(challenge.challengePath) || existsSync(challenge.configPath));
+        if (hasLocalFiles && !flags.yes) {
+            this.log(pc.bold(`\nChallenge: ${pc.cyan(challenge.shortSlug)}`));
+            this.log(`  Local folder exists: ${pc.yellow(challenge.challengeDir)}`);
+            if (existsSync(challenge.challengePath)) {
+                this.log(`  challenge.ts: ${pc.yellow("exists (will be overwritten)")}`);
+            }
+            if (existsSync(challenge.configPath)) {
+                this.log(`  config.ts: ${pc.yellow("exists (will be overwritten)")}`);
+            }
+            this.log("");
+            try {
+                const response = await enquirer.prompt({
+                    type: "confirm",
+                    name: "confirm",
+                    message: `Overwrite local challenge files? ${pc.red("This cannot be undone.")}`,
+                    initial: false,
+                });
+                if (!response.confirm) {
+                    this.log(pc.yellow("Pull cancelled"));
+                    return;
+                }
+            }
+            catch {
+                this.log(pc.yellow("\nPull cancelled"));
+                return;
+            }
+        }
+        const tempTarballPath = path.join(flags["challenges-path"], `${challenge.shortSlug}-pull-temp.tar.gz`);
+        const tasks = new Listr([
+            {
+                title: "Downloading challenge tarball",
+                task: async (_, task) => {
+                    const { downloadUrl } = await api.getChallengeDownloadUrl(challengeSlug);
+                    const response = await fetch(downloadUrl);
+                    if (!response.ok) {
+                        throw new Error(`Failed to download: ${response.status} ${response.statusText}`);
+                    }
+                    const buffer = await response.arrayBuffer();
+                    await fs.mkdir(path.dirname(tempTarballPath), { recursive: true });
+                    await fs.writeFile(tempTarballPath, Buffer.from(buffer));
+                    task.title = "Downloaded challenge tarball";
+                },
+            },
+            {
+                title: "Creating challenge directory",
+                task: async (_, task) => {
+                    await fs.mkdir(challenge.challengeDir, { recursive: true });
+                    task.title = `Created directory: ${challenge.challengeDir}`;
+                },
+            },
+            {
+                title: "Extracting source files",
+                task: async (_, task) => {
+                    const filesToExtract = [`${SOURCE_FOLDER}/challenge.ts`, `${SOURCE_FOLDER}/config.ts`];
+                    const tempExtractDir = path.join(flags["challenges-path"], `${challenge.shortSlug}-extract-temp`);
+                    await fs.mkdir(tempExtractDir, { recursive: true });
+                    try {
+                        await tar.extract({
+                            file: tempTarballPath,
+                            cwd: tempExtractDir,
+                            filter: (entryPath) => filesToExtract.some((f) => entryPath === f),
+                        });
+                        const srcChallengeTs = path.join(tempExtractDir, SOURCE_FOLDER, "challenge.ts");
+                        const srcConfigTs = path.join(tempExtractDir, SOURCE_FOLDER, "config.ts");
+                        let extractedCount = 0;
+                        if (existsSync(srcChallengeTs)) {
+                            await fs.copyFile(srcChallengeTs, challenge.challengePath);
+                            extractedCount++;
+                        }
+                        if (existsSync(srcConfigTs)) {
+                            await fs.copyFile(srcConfigTs, challenge.configPath);
+                            extractedCount++;
+                        }
+                        if (extractedCount === 0) {
+                            throw new Error(`No source files found in tarball. The challenge may not have been built with source files.`);
+                        }
+                        task.title = `Extracted ${extractedCount} source file(s)`;
+                    }
+                    finally {
+                        await fs.rm(tempExtractDir, { recursive: true, force: true });
+                    }
+                },
+            },
+            {
+                title: "Cleaning up",
+                task: async (_, task) => {
+                    await fs.rm(tempTarballPath, { force: true });
+                    task.title = "Cleaned up temporary files";
+                },
+            },
+            {
+                title: "Building datapack",
+                task: async (_, task) => {
+                    await challenge.build(true);
+                    task.title = "Built datapack";
+                },
+            },
+        ]);
+        try {
+            await tasks.run();
+            this.log(pc.green(`\n✓ Challenge pulled: ${challenge.shortSlug}`));
+            this.log(pc.dim(`  → challenge.ts: ${challenge.challengePath}`));
+            this.log(pc.dim(`  → config.ts: ${challenge.configPath}`));
+        }
+        catch (error) {
+            await fs.rm(tempTarballPath, { force: true }).catch(() => { });
+            this.error(pc.red(`Pull failed: ${error instanceof Error ? error.message : String(error)}`));
+        }
+    }
+}

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

@@ -66,6 +66,12 @@ export declare class ApiClient {
      * @returns The upload URL.
      */
     getChallengeUploadUrl(slug: string): Promise<string>;
+    /**
+     * Get the download URL for a challenge datapack.
+     * @param slug - The slug of the challenge.
+     * @returns The download URL and expiration time.
+     */
+    getChallengeDownloadUrl(slug: string): Promise<RecordingDownloadUrlResponse>;
     runChallenge(runData: {
         challenge: string;
         participants: unknown[];

package/dist/lib/api-client.js

@@ -210,6 +210,14 @@ export class ApiClient {
         const response = await this.get(`challenges/${slug}/datapackUploadUrl`, {}, UploadUrlResponseSchema);
         return response.uploadUrl;
     }
+    /**
+     * Get the download URL for a challenge datapack.
+     * @param slug - The slug of the challenge.
+     * @returns The download URL and expiration time.
+     */
+    async getChallengeDownloadUrl(slug) {
+        return this.get(`challenges/${slug}/datapackDownloadUrl`, {}, RecordingDownloadUrlResponseSchema);
+    }
     async runChallenge(runData) {
         const url = "jobs";
         const payload = this.isStudio ? runData : { ...runData, jobType: "background" };

package/dist/lib/arguments.d.ts

@@ -1,10 +1,5 @@
 import type { Arg } from "@oclif/core/interfaces";
-/**
- * Returns a "challenge slug" argument, validating it to be a valid challenge slug.
- * @param description - Description for the argument
- * @param required - Whether the argument is required (default: true)
- * @param allowTeam - Whether to allow namespaced slugs like "team-name:my-challenge" (default: false)
- */
+export declare function extractShortSlug(slug: string): string;
 export declare function getChallengeSlugArgument<R extends boolean = true>({ description, required, allowTeam, }: {
     description: string;
     required?: R;

package/dist/lib/arguments.js

@@ -1,16 +1,13 @@
 import { Args } from "@oclif/core";
-// Base pattern for a slug segment (lowercase alphanumeric with hyphens, no leading/trailing hyphens)
 const SLUG_SEGMENT = "[a-z0-9]+(?:-[a-z0-9]+)*";
-// Local challenge slug pattern: just the challenge name (no namespace)
 const LOCAL_SLUG_REGEX = new RegExp(`^${SLUG_SEGMENT}$`);
-// Full challenge slug pattern: optional namespace prefix (e.g., "team-name:") followed by the challenge slug
 const NAMESPACED_SLUG_REGEX = new RegExp(`^(?:${SLUG_SEGMENT}:)?${SLUG_SEGMENT}$`);
-/**
- * Returns a "challenge slug" argument, validating it to be a valid challenge slug.
- * @param description - Description for the argument
- * @param required - Whether the argument is required (default: true)
- * @param allowTeam - Whether to allow namespaced slugs like "team-name:my-challenge" (default: false)
- */
+export function extractShortSlug(slug) {
+    if (slug.includes(":")) {
+        return slug.split(":")[1];
+    }
+    return slug;
+}
 export function getChallengeSlugArgument({ description, required, allowTeam = false, }) {
     const regex = allowTeam ? NAMESPACED_SLUG_REGEX : LOCAL_SLUG_REGEX;
     const errorMessage = allowTeam

package/oclif.manifest.json

@@ -86,6 +86,54 @@
         "list.js"
       ]
     },
+    "ai-docs:api": {
+      "aliases": [],
+      "args": {},
+      "description": "Output the Kradle API reference documentation for LLMs",
+      "examples": [
+        "<%= config.bin %> <%= command.id %>"
+      ],
+      "flags": {},
+      "hasDynamicHelp": false,
+      "hiddenAliases": [],
+      "id": "ai-docs:api",
+      "pluginAlias": "@kradle/cli",
+      "pluginName": "@kradle/cli",
+      "pluginType": "core",
+      "strict": true,
+      "enableJsonFlag": false,
+      "isESM": true,
+      "relativePath": [
+        "dist",
+        "commands",
+        "ai-docs",
+        "api.js"
+      ]
+    },
+    "ai-docs:cli": {
+      "aliases": [],
+      "args": {},
+      "description": "Output the Kradle CLI reference documentation for LLMs",
+      "examples": [
+        "<%= config.bin %> <%= command.id %>"
+      ],
+      "flags": {},
+      "hasDynamicHelp": false,
+      "hiddenAliases": [],
+      "id": "ai-docs:cli",
+      "pluginAlias": "@kradle/cli",
+      "pluginName": "@kradle/cli",
+      "pluginType": "core",
+      "strict": true,
+      "enableJsonFlag": false,
+      "isESM": true,
+      "relativePath": [
+        "dist",
+        "commands",
+        "ai-docs",
+        "cli.js"
+      ]
+    },
     "challenge:build": {
       "aliases": [],
       "args": {
@@ -357,6 +405,75 @@
         "list.js"
       ]
     },
+    "challenge:pull": {
+      "aliases": [],
+      "args": {
+        "challengeSlug": {
+          "description": "Challenge slug to pull (interactive selection if omitted)",
+          "name": "challengeSlug",
+          "required": false
+        }
+      },
+      "description": "Pull a challenge from the cloud and extract source files locally",
+      "examples": [
+        "<%= config.bin %> <%= command.id %>",
+        "<%= config.bin %> <%= command.id %> my-challenge",
+        "<%= config.bin %> <%= command.id %> username:my-challenge",
+        "<%= config.bin %> <%= command.id %> my-challenge --yes"
+      ],
+      "flags": {
+        "yes": {
+          "char": "y",
+          "description": "Skip confirmation prompts",
+          "name": "yes",
+          "allowNo": false,
+          "type": "boolean"
+        },
+        "api-key": {
+          "description": "Kradle API key",
+          "env": "KRADLE_API_KEY",
+          "name": "api-key",
+          "required": true,
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "api-url": {
+          "description": "Kradle Web API URL",
+          "env": "KRADLE_API_URL",
+          "name": "api-url",
+          "required": true,
+          "default": "https://api.kradle.ai/v0",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "challenges-path": {
+          "description": "Absolute path to the challenges directory",
+          "env": "KRADLE_CHALLENGES_PATH",
+          "name": "challenges-path",
+          "default": "~/Documents/kradle-studio/challenges",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        }
+      },
+      "hasDynamicHelp": false,
+      "hiddenAliases": [],
+      "id": "challenge:pull",
+      "pluginAlias": "@kradle/cli",
+      "pluginName": "@kradle/cli",
+      "pluginType": "core",
+      "strict": true,
+      "enableJsonFlag": false,
+      "isESM": true,
+      "relativePath": [
+        "dist",
+        "commands",
+        "challenge",
+        "pull.js"
+      ]
+    },
     "challenge:run": {
       "aliases": [],
       "args": {
@@ -518,54 +635,6 @@
         "watch.js"
       ]
     },
-    "ai-docs:api": {
-      "aliases": [],
-      "args": {},
-      "description": "Output the Kradle API reference documentation for LLMs",
-      "examples": [
-        "<%= config.bin %> <%= command.id %>"
-      ],
-      "flags": {},
-      "hasDynamicHelp": false,
-      "hiddenAliases": [],
-      "id": "ai-docs:api",
-      "pluginAlias": "@kradle/cli",
-      "pluginName": "@kradle/cli",
-      "pluginType": "core",
-      "strict": true,
-      "enableJsonFlag": false,
-      "isESM": true,
-      "relativePath": [
-        "dist",
-        "commands",
-        "ai-docs",
-        "api.js"
-      ]
-    },
-    "ai-docs:cli": {
-      "aliases": [],
-      "args": {},
-      "description": "Output the Kradle CLI reference documentation for LLMs",
-      "examples": [
-        "<%= config.bin %> <%= command.id %>"
-      ],
-      "flags": {},
-      "hasDynamicHelp": false,
-      "hiddenAliases": [],
-      "id": "ai-docs:cli",
-      "pluginAlias": "@kradle/cli",
-      "pluginName": "@kradle/cli",
-      "pluginType": "core",
-      "strict": true,
-      "enableJsonFlag": false,
-      "isESM": true,
-      "relativePath": [
-        "dist",
-        "commands",
-        "ai-docs",
-        "cli.js"
-      ]
-    },
     "experiment:create": {
       "aliases": [],
       "args": {
@@ -800,5 +869,5 @@
       ]
     }
   },
-  "version": "0.2.3"
+  "version": "0.2.5"
 }

package/package.json

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

package/static/ai_docs/LLM_API_REFERENCE.md

@@ -261,7 +261,7 @@ current_y_position: {
   type: "individual",
   objective_type: "dummy",
   updater: (value) => {
-    execute.as("@s").store.result.score(value).run.data.get.entity("@s", "Pos[1]");
+    value.set(Actions.getCurrentPlayerPosition().y)
   },
 }
 ```
@@ -323,6 +323,8 @@ score.lowerOrEqualThan(number | Score);
 
 ### Lifecycle Events
 
+All lifecycle events run globally (not per-player).
+
 #### `start_challenge`
 
 Runs once when the challenge starts. Use for global setup.
@@ -337,19 +339,19 @@ start_challenge: () => {
 
 #### `init_participants`
 
-Runs once per player after start (delayed 1 second). Use for player setup.
+Runs 1 second after start_challenge. Use for player setup. It still runs globally.
 
 ```typescript
 init_participants: () => {
-  Actions.give({ target: "self", item: "minecraft:diamond_sword", count: 1 });
-  Actions.setAttribute({ target: "self", attribute_: "generic.max_health", value: 40 });
-  Actions.teleport({ target: "self", x: 0, y: 100, z: 0, absolute: true });
+  Actions.give({ target: "all", item: "minecraft:diamond_sword", count: 1 });
+  Actions.setAttribute({ target: "all", attribute_: "generic.max_health", value: 40 });
+  Actions.teleport({ target: "all", x: 0, y: 100, z: 0, absolute: true });
 }
 ```
 
 #### `on_tick`
 
-Runs every tick for each player. Use sparingly for performance.
+Runs every tick. Use sparingly for performance.
 
 ```typescript
 on_tick: () => {
@@ -402,7 +404,7 @@ Score events watch a variable and trigger when it reaches a specified target val
 ```typescript
 {
   score: variables.death_count,
-  mode: "fire_once",  // Triggers once when death_count changes from 0
+  mode: "fire_once",  // Triggers once when death_count changes away from initial value
   actions: () => {
     Actions.announce({ message: "First death!" });
   },
@@ -417,6 +419,8 @@ Score events watch a variable and trigger when it reaches a specified target val
 
 Advancement events trigger when a Minecraft advancement criterion is met. Internally, an advancement is created that grants when the criterion triggers, which then fires the event. The `criteria` array follows the [Minecraft Advancement JSON format](https://minecraft.fandom.com/wiki/Advancement/JSON_format).
 
+Advancement-based events always fire per-player.
+
 **Parameters:**
 - `criteria` (required): Array of advancement trigger objects with optional conditions
 - `mode` (required): `"fire_once"` or `"repeatable"`
@@ -476,6 +480,13 @@ See the [Minecraft Wiki](https://minecraft.fandom.com/wiki/Advancement/JSON_form
 
 ## Actions
 
+Actions are higher-level functions that wrap common Minecraft operations. They provide:
+- Automatic target mapping (`"all"`, `"self"`, team names → proper selectors)
+- Integration with Kradle's interface (e.g., `Actions.announce` messages appear in Kradle)
+- Consistent API for common operations
+
+For advanced use cases not covered by Actions, you can fall back to Sandstone's lower-level functions directly (`give`, `tellraw`, `effect`, `kill`, `execute`, etc.). See [Sandstone Integration](#sandstone-integration).
+
 All actions are called via the `Actions` object:
 
 ```typescript
@@ -497,28 +508,44 @@ Broadcast message to all players with KRADLE tag.
 
 ```typescript
 Actions.announce({
-  message: string;  // Message text
+  message: JSONTextComponent;  // Message (string or formatted object)
+});
+
+// Simple string:
+Actions.announce({ message: "Game starting!" });
+
+// Formatted JSONTextComponent:
+Actions.announce({
+  message: [
+    { text: "Player ", color: "white" },
+    { selector: "@s", color: "gold", bold: true },
+    { text: " won the game!", color: "green" }
+  ]
 });
 ```
 
 #### `Actions.tellraw(params)`
 
-Send formatted message to specific target.
+Send formatted message to specific target. **Note:** These messages are only visible to players in-game and will not appear in Kradle's interface. Use `Actions.announce` for messages that should be visible in Kradle.
 
 ```typescript
 Actions.tellraw({
-  target: TargetNames;  // "all", "self", or any selector
-  message: string[];    // Message array
+  target: TargetNames;       // "all", "self", or any selector
+  message: JSONTextComponent; // Message (string or formatted object)
 });
 
-// Example:
+// Examples:
 Actions.tellraw({
   target: "all",
   message: ["Hello, ", { text: "world!", color: "gold", bold: true }]
 });
 Actions.tellraw({
   target: "self",
-  message: ["You won!"]
+  message: "You won!"
+});
+Actions.tellraw({
+  target: "self",
+  message: { text: "Critical hit!", color: "red", bold: true }
 });
 ```
 
@@ -611,6 +638,39 @@ variables.my_diamond_count.set(count);
 
 **Note:** This action creates a temporary variable internally using `Variable()` and uses `execute.store.result.score` with `clear` command (count 0) to count items without removing them from the inventory.
 
+#### `Actions.getCurrentPlayerPosition()`
+
+Get the current player's position as x, y, z Score variables. Must be called in a player context (e.g., inside `forEveryPlayer`, individual variables updaters, or when `@s` is a player). This is the prefered way of checking a player's position.
+
+```typescript
+Actions.getCurrentPlayerPosition(): { x: Score; y: Score; z: Score }
+
+// Example - Check if player is above Y=100:
+const pos = Actions.getCurrentPlayerPosition();
+_.if(pos.y.greaterThan(100), () => {
+  Actions.announce({ message: "You reached the sky!" });
+});
+
+// Example - Store position in custom variables:
+const { x, y, z } = Actions.getCurrentPlayerPosition();
+variables.player_x.set(x);
+variables.player_y.set(y);
+variables.player_z.set(z);
+
+// Example - Check if player is in a specific area:
+const pos = Actions.getCurrentPlayerPosition();
+_.if(_.and(
+  pos.x.greaterThan(0),
+  pos.x.lowerThan(100),
+  pos.z.greaterThan(0),
+  pos.z.lowerThan(100)
+), () => {
+  Actions.announce({ message: "You're in the zone!" });
+});
+```
+
+**Note:** This returns integer coordinates (block position). The values are truncated from the player's exact floating-point position.
+
 ### Entities
 
 #### `Actions.summonMultiple(params)`
@@ -1045,7 +1105,7 @@ createChallenge({
       Actions.announce({ message: "First to kill 2 pigs wins!" });
     },
     init_participants: () => {
-      Actions.give({ target: "self", item: "minecraft:iron_sword", count: 1 });
+      Actions.give({ target: "all", item: "minecraft:iron_sword", count: 1 });
     },
   }))
   .custom_events(({ pigs_farmed }) => [
@@ -1080,7 +1140,7 @@ createChallenge({
       type: "individual",
       objective_type: "dummy",
       updater: (value) => {
-        execute.as("@s").store.result.score(value).run.data.get.entity("@s", "Pos[1]");
+        value.set(Actions.getCurrentPlayerPosition().y)
       },
     },
     max_height: {
@@ -1124,8 +1184,8 @@ createChallenge({
       Actions.announce({ message: "Climb as high as you can!" });
     },
     init_participants: () => {
-      Actions.give({ target: "self", item: "minecraft:cobblestone", count: 64 });
-      Actions.give({ target: "self", item: "minecraft:cobblestone", count: 64 });
+      Actions.give({ target: "all", item: "minecraft:cobblestone", count: 64 });
+      Actions.give({ target: "all", item: "minecraft:cobblestone", count: 64 });
     },
   }))
   .custom_events(() => [])
@@ -1176,9 +1236,9 @@ createChallenge({
       Actions.announce({ message: "Last player standing wins!" });
     },
     init_participants: () => {
-      Actions.give({ target: "self", item: "minecraft:stone_sword", count: 1 });
-      Actions.give({ target: "self", item: "minecraft:leather_chestplate", count: 1 });
-      Actions.give({ target: "self", item: "minecraft:cooked_beef", count: 10 });
+      Actions.give({ target: "all", item: "minecraft:stone_sword", count: 1 });
+      Actions.give({ target: "all", item: "minecraft:leather_chestplate", count: 1 });
+      Actions.give({ target: "all", item: "minecraft:cooked_beef", count: 10 });
     },
   }))
   .custom_events(({ kills }) => [
@@ -1237,7 +1297,7 @@ createChallenge({
     },
     init_participants: () => {
       // Different items based on role would be set via role-specific logic
-      Actions.give({ target: "self", item: "minecraft:wooden_sword", count: 1 });
+      Actions.give({ target: "all", item: "minecraft:wooden_sword", count: 1 });
     },
   }))
   .custom_events(() => [])
@@ -1301,7 +1361,7 @@ createChallenge({
       Actions.announce({ message: "Capture the enemy flag and return to base!" });
     },
     init_participants: () => {
-      Actions.give({ target: "self", item: "minecraft:iron_sword", count: 1 });
+      Actions.give({ target: "all", item: "minecraft:iron_sword", count: 1 });
     },
   }))
   .custom_events(({ captured_flag }) => [
@@ -1378,6 +1438,10 @@ current_y: {
   type: "individual",
   objective_type: "dummy",
   updater: (value) => {
+    // Prefered way: using the dedicated Action
+    value.set(Actions.getCurrentPlayerPosition().y)
+
+    // Alternative way: using execute.store + data.get
     execute.as("@s").store.result.score(value).run.data.get.entity("@s", "Pos[1]");
   },
 }

package/static/ai_docs/LLM_CLI_REFERENCE.md

@@ -223,6 +223,61 @@ kradle challenge list
 
 ---
 
+### `kradle challenge pull [name]`
+
+Downloads a challenge from the cloud and extracts source files locally.
+
+**Usage:**
+```bash
+kradle challenge pull
+kradle challenge pull <challenge-name>
+kradle challenge pull <team-name>:<challenge-name>
+kradle challenge pull <challenge-name> --yes
+```
+
+**Arguments:**
+| Argument | Description | Required |
+|----------|-------------|----------|
+| `challenge-name` | Challenge slug to pull. Can be a short slug (e.g., `my-challenge`) or include a team/user namespace (e.g., `team-name:my-challenge`). If omitted, shows interactive selection. | No |
+
+**Flags:**
+| Flag | Short | Description | Default |
+|------|-------|-------------|---------|
+| `--yes` | `-y` | Skip confirmation prompts when overwriting local files | false |
+
+**What it does:**
+1. Downloads the challenge tarball from cloud storage
+2. Extracts `challenge.ts` and `config.ts` from the `.src` folder in the tarball
+3. Places files in `challenges/<short-slug>/` directory
+4. Builds the datapack locally
+
+**Interactive mode (no slug argument):**
+- Shows list of all cloud challenges (your own + team-kradle)
+- Marks challenges that exist locally with "(local)" indicator
+- Select a challenge to pull
+
+**Confirmation prompt:**
+When pulling over existing local files (without `--yes`), shows:
+- Which files will be overwritten
+- Asks for confirmation before proceeding
+
+**Examples:**
+```bash
+# Interactive selection from all cloud challenges
+kradle challenge pull
+
+# Pull your own challenge
+kradle challenge pull my-challenge
+
+# Pull a public challenge from another team
+kradle challenge pull team-kradle:example-challenge
+
+# Pull without confirmation prompt
+kradle challenge pull my-challenge --yes
+```
+
+---
+
 ### `kradle challenge watch <name>`
 
 Watches a challenge for file changes and automatically rebuilds/uploads.
@@ -663,6 +718,7 @@ kradle challenge build --all --visibility public
 | `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 |
 | `kradle experiment create <name>` | Create new experiment |