Fix documentation examples and enum numbering

docs/configuration.md

@@ -5,7 +5,8 @@ configuration.
 
 ## Standard Library Version
 
-If not provided, the latest version is picked (Updates fetched daily)
+If not provided, the latest version is picked. The selected version is cached for
+seven days before checking for updates on a subsequent build.
 
 ```toml
 std = "2.1.0" # default is unset

docs/contributing.md

@@ -29,6 +29,18 @@ nightly too:
 rustup toolchain install nightly
 ```
 
+The development scripts also require Python 3.9 or later, Node.js, and the pnpm
+version declared in `package.json`. Install Prettier separately and ensure the
+`prettier` command is available on your `PATH`. From the repository root, install
+the workspace dependencies:
+
+```bash
+pnpm install --frozen-lockfile
+```
+
+This provides `tsx` and its dependencies for schema validation. Run the development
+commands below from the repository root.
+
 ## Development
 
 To make development easier, and to validate the generated Scratch project -- use
@@ -39,7 +51,7 @@ tools/run.py --validate # or `-v`
 ```
 
 This assumes that you have set-up a testing project at `playground/`. (You can create a
-testing project by running `goboscript new -G playground`). It will compile the project,
+testing project by running `cargo run -- new -G playground`). It will compile the project,
 validate it using the schemas from `scratch-parser`. If the validation fails, Scratch
 will refuse to load the project.
 

docs/getting-started/basic-examples.md

@@ -2,6 +2,9 @@
 
 Let's start with simple examples of Goboscript syntax.
 
+Try one example at a time in your sprite's `.gs` file, keeping the existing
+`costumes` line.
+
 ```goboscript
 # This is a single-line comment
 
@@ -25,98 +28,103 @@ var not_flag = false;    # Will be compiled as 0
 ### Variables and Operators
 
 ```goboscript
-# Variable declaration and assignment
-x = 10;
-y = 20;
-sum = x + y;         # Addition: 30
-diff = x - y;        # Subtraction: -10
-product = x * y;     # Multiplication: 200
-quotient = y / x;    # Division: 2
-floor_div = y // x;  # Floor division: 2
-remainder = y % x;   # Modulo: 0
-text = "Hello" & " World"; # String concatenation: "Hello World"
-
-# Compound assignment
-x += 5;                  # x = x + 5
-y -= 3;                  # y = y - 3
-product *= 2;            # product = product * 2
-quotient /= 4;           # quotient = quotient / 4
-text &= "!";             # text = text & "!"
-
-# Comparison operators
-is_equal = x == y;   # Equal to
-not_equal = x != y;  # Not equal to
-greater = x > y;     # Greater than
-less = x < y;        # Less than
-greater_equal = x >= y; # Greater than or equal to
-less_equal = x <= y;    # Less than or equal to
-
-# Logical operators
-both = x > 0 and y > 0;  # Logical AND
-either = x > 0 or y < 0; # Logical OR
-inverse = not x > 0;     # Logical NOT
+onflag {
+    # Variable declaration and assignment
+    x = 10;
+    y = 20;
+    sum = x + y;         # Addition: 30
+    diff = x - y;        # Subtraction: -10
+    product = x * y;     # Multiplication: 200
+    quotient = y / x;    # Division: 2
+    floor_div = y // x;  # Floor division: 2
+    remainder = y % x;   # Modulo: 0
+    text = "Hello" & " World"; # String concatenation: "Hello World"
+
+    # Compound assignment
+    x += 5;                  # x = x + 5
+    y -= 3;                  # y = y - 3
+    product *= 2;            # product = product * 2
+    quotient /= 4;           # quotient = quotient / 4
+    text &= "!";             # text = text & "!"
+
+    # Comparison operators
+    is_equal = x == y;   # Equal to
+    not_equal = x != y;  # Not equal to
+    greater = x > y;     # Greater than
+    less = x < y;        # Less than
+    greater_equal = x >= y; # Greater than or equal to
+    less_equal = x <= y;    # Less than or equal to
+
+    # Logical operators
+    both = x > 0 and y > 0;  # Logical AND
+    either = x > 0 or y < 0; # Logical OR
+    inverse = not (x > 0);   # Logical NOT
+}
 ```
 
 ### Control Flow
 
 ```goboscript
-condition = true;
-x = 10;
+onflag {
+    x = 10;
 
-# Simple if statement
-if x > 5 {
-    say "x is greater than 5";
-}
+    # Simple if statement
+    if x > 5 {
+        say "x is greater than 5";
+    }
 
-# If-else statement
-if x % 2 == 0 {
-    say "x is even";
-} else {
-    say "x is odd";
-}
+    # If-else statement
+    if x % 2 == 0 {
+        say "x is even";
+    } else {
+        say "x is odd";
+    }
 
-# If-elif-else statement
-if x < 0 {
-    say "x is negative";
-} elif x == 0 {
-    say "x is zero";
-} else {
-    say "x is positive";
-}
+    # If-elif-else statement
+    if x < 0 {
+        say "x is negative";
+    } elif x == 0 {
+        say "x is zero";
+    } else {
+        say "x is positive";
+    }
 
-# Boolean coercion
-if timer() {  # Equivalent to: if timer() == 1
-    say "Timer is active";
+    # Boolean coercion
+    if timer() {  # Equivalent to: if timer() == 1
+        say "Timer equals 1";
+    }
 }
 ```
 
 ### Loops
 
 ```goboscript
-# Repeat loop (fixed number of iterations)
-repeat 5 {
-    say "Repeated message";
-}
+onflag {
+    # Repeat loop (fixed number of iterations)
+    repeat 5 {
+        say "Repeated message";
+    }
 
-# Repeat with counter
-i = 1;
-repeat 10 {
-    say "Iteration " & i;
-    i++;
-}
+    # Repeat with counter
+    i = 1;
+    repeat 10 {
+        say "Iteration " & i;
+        i++;
+    }
 
-# Until loop (continues until condition is true)
-counter = 0;
-until counter > 5 {
-    say "Counter: " & counter;
-    counter++;
-}
+    # Until loop (continues until condition is true)
+    counter = 0;
+    until counter > 5 {
+        say "Counter: " & counter;
+        counter++;
+    }
 
-# Forever loop (infinite loop)
-forever {
-    say "Press stop to exit";
-    if key space pressed? {
-        stop_this_script;
+    # Forever loop (infinite loop)
+    forever {
+        say "Press stop to exit";
+        if key_pressed("space") {
+            stop_this_script;
+        }
     }
 }
 ```
@@ -154,64 +162,76 @@ onflag {
 
 Functions are similar to procedures but return values.
 
+The `greet_world` procedure runs without screen refresh, so it can call functions
+safely.
+
 ```goboscript
 # Define a function
-func add(x, y) {
+func sum(x, y) {
     return $x + $y;
 }
 
-# Function with type
+# Define a function returning a string
 func create_greeting(name) {
     return "Hello, " & $name & "!";
 }
 
-onflag {
+proc greet_world {
     message = create_greeting("World");
     say message;  # Outputs: "Hello, World!"
 }
+
+onflag {
+    greet_world;
+}
 ```
 
 ### Data Structures
 
 #### Lists
 
+For the file-backed list, create `data.txt` in the project directory with one item
+per line.
+
 ```goboscript
 # Declare an empty list
 list my_list;
 
-# Add items to a list
-add "apple" to my_list;
-add "banana" to my_list;
-add "cherry" to my_list;
+# Load list from file
+list data "data.txt";
 
-# Access list items (1-indexed)
-first_item = my_list[1];  # "apple"
+onflag {
+    # Add items to a list
+    add "apple" to my_list;
+    add "banana" to my_list;
+    add "cherry" to my_list;
 
-# Replace items
-my_list[2] = "blueberry";     # Replace "banana" with "blueberry"
+    # Access list items (1-indexed)
+    first_item = my_list[1];  # "apple"
 
-# Insert at position
-insert "apricot" at my_list[1]; # Insert at the beginning
+    # Replace items
+    my_list[2] = "blueberry";     # Replace "banana" with "blueberry"
 
-# Delete an item
-delete my_list[3];
+    # Insert at position
+    insert "apricot" at my_list[1]; # Insert at the beginning
 
-# Check length
-size = length my_list;
+    # Delete an item
+    delete my_list[3];
 
-# Check if an item is in the list
-if "cherry" in my_list {
-    say "Found cherry!";
-}
+    # Check length
+    size = length my_list;
 
-# Get random item
-random_fruit = my_list["random"];
+    # Check if an item is in the list
+    if "cherry" in my_list {
+        say "Found cherry!";
+    }
 
-# Clear the list
-delete my_list;
+    # Get random item
+    random_fruit = my_list["random"];
 
-# Load list from file
-list data = file ```data.txt```;
+    # Clear the list
+    delete my_list;
+}
 ```
 
 #### Structures and Enums
@@ -223,12 +243,6 @@ struct Point {
     y
 }
 
-# Create a struct instance
-Point p = Point { x: 10, y: 20 };
-
-# Access struct fields
-say "Coordinates: " & p.x & ", " & p.y;
-
 # Define an enum
 enum Direction {
     North,  # 0
@@ -237,18 +251,26 @@ enum Direction {
     West    # 3
 }
 
-# Use enum values
-current_direction = Direction.North;
-if current_direction == Direction.North {
-    say "Heading north";
-}
-
 # Enum with explicit values
 enum Color {
     Red = "red",
     Green = "green",
     Blue = "blue"
 }
 
-say "Selected color: " & Color.Red;
+onflag {
+    # Create a struct instance
+    Point p = Point { x: 10, y: 20 };
+
+    # Access struct fields
+    say "Coordinates: " & p.x & ", " & p.y;
+
+    # Use enum values
+    current_direction = Direction.North;
+    if current_direction == Direction.North {
+        say "Heading north";
+    }
+
+    say "Selected color: " & Color.Red;
+}
 ```

docs/getting-started/index.md

@@ -21,7 +21,6 @@ This will create a new project with the following structure:
 ├── .gitignore
 ├── goboscript.toml
 ├── main.gs
-├── playground.sb3
 └── stage.gs
 ```
 

docs/language/blocks/looks.md

@@ -60,7 +60,7 @@ next_costume;
 next costume
 ```
 
-### switch backdrop to (next backdrop)
+### switch backdrop to ()
 
 ```goboscript
 switch_backdrop "backdrop";