diff --git a/README.md b/README.md
index b2d50f1..b196a8f 100644
--- a/README.md
+++ b/README.md
@@ -86,30 +86,30 @@ function backup_file(filename)
 end
 ```
 
-## Live Demos
+## 🎯 Examples
 
-Run these demos to see luash in action:
+Explore organized examples that demonstrate Luash features:
 
 ```bash
-# Basic features demo
-./luash demo_basic.luash
+# Start with the showcase for a complete overview
+./luash examples/09_showcase.luash
 
-# Quick comparison with bash
-./luash demo_quick_examples.luash
+# Learn step-by-step with numbered examples
+./luash examples/01_basic_features.luash
+./luash examples/02_quick_comparison.luash
+./luash examples/03_interpolation.luash
 
-# System administration tasks
-./luash demo_system_admin.luash
+# Try practical use cases
+./luash examples/04_system_admin.luash
+./luash examples/05_development.luash
+./luash examples/06_data_processing.luash
 
-# Development workflow automation
-./luash demo_development.luash
-
-# Data processing and analysis
-./luash demo_data_processing.luash
-
-# Interactive demo runner
-./luash run_demos.luash
+# Or use the interactive runner
+./luash run_examples.luash
 ```
 
+See [examples/README.md](examples/README.md) for the complete learning path.
+
 ### What You Get
 
 #### File System Operations
@@ -266,9 +266,12 @@ The interactive shell supports:
 - All luash preprocessing features
 - Multiline input for functions, loops, etc.
 - Command history with `.history`
+- Screen clearing with `.clear`
 - Special commands: `.help`, `.exit`, `.clear`
 - Real-time expression evaluation
 
+See [examples/08_repl_guide.luash](examples/08_repl_guide.luash) for a comprehensive guide.
+
 ### Debug Mode
 ```bash
 LUASH_DEBUG=1 ./luash script.luash
diff --git a/demos/quick_examples.luash b/demos/quick_examples.luash
deleted file mode 100644
index bfa8acb..0000000
--- a/demos/quick_examples.luash
+++ /dev/null
@@ -1,75 +0,0 @@
-#!/usr/bin/env luash
--- Quick Examples: Bite-sized demos showing luash vs bash
-
-print("=== Luash vs Bash: Quick Examples ===\n")
-
-print("1. Environment Variables")
-print("   Bash: echo $USER")
-print("   Luash: print($USER)")
-print("   → " .. $USER)
-
-print("\n2. Variable Assignment")
-print("   Bash: MY_VAR=\"hello\"")
-print("   Luash: $MY_VAR = \"hello\"")
-$MY_VAR = "hello"
-print("   → " .. $MY_VAR)
-
-print("\n3. Command Substitution")
-print("   Bash: current_dir=$(pwd)")
-print("   Luash: current_dir = `pwd`")
-current_dir = `pwd`
-print("   → " .. current_dir)
-
-print("\n4. Conditional Logic")
-print("   Bash: if [ -f \"README.md\" ]; then echo \"exists\"; fi")
-print("   Luash: if `test -f README.md` == \"\" then print(\"missing\") else print(\"exists\") end")
-if `test -f README.md && echo "yes"` == "yes" then
-    print("   → exists")
-else
-    print("   → missing")
-end
-
-print("\n5. Loops with Arrays")
-print("   Bash: for file in *.lua; do echo $file; done")
-print("   Luash: files = `ls *.lua`; for file in files:gmatch(\"[^\\n]+\") do print(file) end")
-files = `ls *.luash`
-print("   → Files found:")
-for file in files:gmatch("[^\n]+") do
-    print("     " .. file)
-end
-
-print("\n6. String Processing")
-print("   Bash: echo \"hello world\" | tr '[:lower:]' '[:upper:]'")
-print("   Luash: string.upper(\"hello world\")")
-print("   → " .. string.upper("hello world"))
-
-print("\n7. Math Operations")
-print("   Bash: result=$((5 + 3))")
-print("   Luash: result = 5 + 3")
-result = 5 + 3
-print("   → " .. result)
-
-print("\n8. File Operations")
-print("   Bash: cat file.txt | wc -l")
-print("   Luash: line_count = `cat luash | wc -l`")
-line_count = `cat luash | wc -l`
-print("   → " .. line_count .. " lines in luash script")
-
-print("\n9. Error Handling")
-print("   Bash: command || echo \"failed\"")
-print("   Luash: if `command 2>/dev/null` == \"\" then print(\"failed\") end")
-if `nonexistent_command 2>/dev/null` == "" then
-    print("   → command failed (as expected)")
-end
-
-print("\n10. Complex Data Structures")
-print("   Bash: (limited array support)")
-print("   Luash: Full Lua tables!")
-data = {
-    users = {"alice", "bob", "charlie"},
-    scores = {alice = 95, bob = 87, charlie = 92}
-}
-print("   → Users: " .. table.concat(data.users, ", "))
-print("   → Alice's score: " .. data.scores.alice)
-
-print("\n✨ Luash combines the best of shell scripting with Lua's power!")
diff --git a/demos/run_demo.luash_ b/demos/run_demo.luash_
deleted file mode 100644
index e9c6d7f..0000000
--- a/demos/run_demo.luash_
+++ /dev/null
@@ -1,47 +0,0 @@
-#!/usr/bin/env luash
--- Demo Runner: Showcase all luash capabilities
-
-print("🚀 Welcome to Luash Demos!")
-print("=" .. string.rep("=", 50))
-
-demos = {
-    {name = "Basic Features", file = "demo_basic.luash", description = "Environment variables, shell commands, and string handling"},
-    {name = "Quick Examples", file = "demo_quick_examples.luash", description = "Side-by-side comparison with bash"},
-    {name = "System Administration", file = "demo_system_admin.luash", description = "Real-world sysadmin tasks"},
-    {name = "Development Workflow", file = "demo_development.luash", description = "Git, building, and deployment automation"},
-    {name = "Data Processing", file = "demo_data_processing.luash", description = "File processing and text analysis"}
-}
-
-print("\nAvailable demos:")
-for i = 1, #demos do
-    print("  " .. i .. ". " .. demos[i].name)
-    print("     " .. demos[i].description)
-end
-
-print("\nEnter demo number (1-" .. #demos .. "), 'all' to run all demos, or 'q' to quit:")
-
--- In a real interactive version, we'd read input
--- For now, let's run a specific demo or all
-demo_choice = "1"  -- Change this to test different demos
-
-if demo_choice == "all" then
-    for i = 1, #demos do
-        print("\n" .. string.rep("=", 60))
-        print("Running Demo " .. i .. ": " .. demos[i].name)
-        print(string.rep("=", 60))
-        !./luash $demos[i].file
-        print("\nPress Enter to continue...")
-        !read
-    end
-elseif tonumber(demo_choice) and tonumber(demo_choice) >= 1 and tonumber(demo_choice) <= #demos then
-    local choice = tonumber(demo_choice)
-    print("\n" .. string.rep("=", 60))
-    print("Running Demo: " .. demos[choice].name)
-    print(string.rep("=", 60))
-    !./luash demos[choice].file
-else
-    print("Running basic demo...")
-    !./luash demo_basic.luash
-end
-
-print("\n✨ Thanks for trying Luash!")
diff --git a/demos/test.luash b/demos/test.luash
deleted file mode 100644
index 2d6e26d..0000000
--- a/demos/test.luash
+++ /dev/null
@@ -1,20 +0,0 @@
-
--- Test environment variables
-print("Current shell: " .. $SHELL)
-
--- Test environment variable assignment
-$HELLO = "my variable"
-print("HELLO = " .. $HELLO)
-
--- Test $VAR inside strings (should NOT be substituted)
-print("This should print literally: $SHELL and $HOME")
-
--- Test $VAR outside strings (should be substituted)
-print("Home directory: " .. $HOME)
-
--- Test shell commands
-current_dir = `pwd`
-print("Current directory: " .. current_dir)
-
--- Test interactive command
-!echo "Running interactive command"
\ No newline at end of file
diff --git a/demos/basic.luash b/examples/01_basic_features.luash
similarity index 100%
rename from demos/basic.luash
rename to examples/01_basic_features.luash
diff --git a/demo_quick_examples.luash b/examples/02_quick_comparison.luash
similarity index 100%
rename from demo_quick_examples.luash
rename to examples/02_quick_comparison.luash
diff --git a/interpolation_demo.luash b/examples/03_interpolation.luash
similarity index 100%
rename from interpolation_demo.luash
rename to examples/03_interpolation.luash
diff --git a/demos/system_admin.luash b/examples/04_system_admin.luash
similarity index 100%
rename from demos/system_admin.luash
rename to examples/04_system_admin.luash
diff --git a/demos/development.luash b/examples/05_development.luash
similarity index 100%
rename from demos/development.luash
rename to examples/05_development.luash
diff --git a/demos/data_processing.luash b/examples/06_data_processing.luash
similarity index 100%
rename from demos/data_processing.luash
rename to examples/06_data_processing.luash
diff --git a/interactive.luash b/examples/07_interactive_demo.luash
similarity index 100%
rename from interactive.luash
rename to examples/07_interactive_demo.luash
diff --git a/repl_demo.luash b/examples/08_repl_guide.luash
similarity index 100%
rename from repl_demo.luash
rename to examples/08_repl_guide.luash
diff --git a/demos/showcase.luash b/examples/09_showcase.luash
similarity index 100%
rename from demos/showcase.luash
rename to examples/09_showcase.luash
diff --git a/examples/README.md b/examples/README.md
new file mode 100644
index 0000000..f0ba92b
--- /dev/null
+++ b/examples/README.md
@@ -0,0 +1,36 @@
+# Luash Examples
+
+This directory contains examples demonstrating Luash features, organized in a logical learning order:
+
+## 📚 Learning Path
+
+1. **[01_basic_features.luash](01_basic_features.luash)** - Core Luash features (env vars, commands, strings)
+2. **[02_quick_comparison.luash](02_quick_comparison.luash)** - Side-by-side comparison with Bash
+3. **[03_interpolation.luash](03_interpolation.luash)** - Variable interpolation in shell commands
+4. **[04_system_admin.luash](04_system_admin.luash)** - System administration tasks
+5. **[05_development.luash](05_development.luash)** - Development workflows
+6. **[06_data_processing.luash](06_data_processing.luash)** - Data analysis and processing
+7. **[07_interactive_demo.luash](07_interactive_demo.luash)** - Building interactive applications
+8. **[08_repl_guide.luash](08_repl_guide.luash)** - Interactive shell usage guide
+9. **[09_showcase.luash](09_showcase.luash)** - Complete feature showcase
+
+## 🚀 Quick Start
+
+```bash
+# Run individual examples
+../luash 01_basic_features.luash
+
+# Run the showcase (best overview)
+../luash 09_showcase.luash
+
+# Try the interactive shell
+../luash -i
+```
+
+## 📝 Example Categories
+
+- **Basics**: Examples 1-3 cover fundamental syntax and features
+- **Use Cases**: Examples 4-6 show practical applications
+- **Advanced**: Examples 7-9 cover interactive features and comprehensive demos
+
+Each example is self-contained and includes explanatory comments.
diff --git a/run_examples.luash b/run_examples.luash
new file mode 100755
index 0000000..314733c
--- /dev/null
+++ b/run_examples.luash
@@ -0,0 +1,70 @@
+-- Example Runner - Run all Luash examples in order
+-- Usage: ./luash run_examples.luash
+
+print("🚀 Luash Examples Runner")
+print("=" .. string.rep("=", 25))
+
+-- Get list of examples
+examples = `ls examples/*.luash | sort`
+
+if examples == "" then
+    print("❌ No examples found in examples/ directory")
+    os.exit(1)
+end
+
+local example_files = {}
+for file in examples:gmatch("[^\n]+") do
+    table.insert(example_files, file)
+end
+
+print("\nFound " .. #example_files .. " examples:")
+for i, file in ipairs(example_files) do
+    local name = file:match("examples/(.+)%.luash")
+    print(string.format("  %d. %s", i, name))
+end
+
+print("\n" .. string.rep("-", 50))
+print("Choose an option:")
+print("  1-" .. #example_files .. ": Run specific example")
+print("  a: Run all examples")
+print("  q: Quit")
+print(string.rep("-", 50))
+
+io.write("Your choice: ")
+io.flush()
+choice = io.read()
+
+if choice == "q" then
+    print("Goodbye!")
+    os.exit(0)
+elseif choice == "a" then
+    print("\n🎬 Running all examples...\n")
+    for i, file in ipairs(example_files) do
+        local name = file:match("examples/(.+)%.luash")
+        print(string.format("\n[%d/%d] Running %s", i, #example_files, name))
+        print(string.rep("=", 60))
+        
+        local result = os.execute("./luash " .. file)
+        if result ~= 0 then
+            print("❌ Example failed!")
+        end
+        
+        if i < #example_files then
+            print("\nPress Enter to continue...")
+            io.read()
+        end
+    end
+    print("\n✅ All examples completed!")
+else
+    local num = tonumber(choice)
+    if num and num >= 1 and num <= #example_files then
+        local file = example_files[num]
+        local name = file:match("examples/(.+)%.luash")
+        print("\n🎬 Running " .. name .. "...")
+        print(string.rep("=", 60))
+        os.execute("./luash " .. file)
+    else
+        print("❌ Invalid choice: " .. choice)
+        os.exit(1)
+    end
+end
diff --git a/showcase.luash b/showcase.luash
deleted file mode 100644
index 9957c5a..0000000
--- a/showcase.luash
+++ /dev/null
@@ -1,124 +0,0 @@
-#!/usr/bin/env luash
--- Luash Showcase: Highlight the best features
-
-print("🚀 Luash - Minimal Lua Shell Scripting")
-print("=" .. string.rep("=", 45))
-
-print("\n💡 Why Luash?")
-print("✓ Clean syntax - no more bash quoting nightmares")
-print("✓ Real programming language features")  
-print("✓ Seamless shell integration")
-print("✓ Minimal and focused")
-
-print("\n📊 Quick Comparison:")
-print("┌─────────────────┬─────────────────────┬─────────────────────┐")
-print("│ Task            │ Bash                │ Luash               │")
-print("├─────────────────┼─────────────────────┼─────────────────────┤")
-print("│ Variables       │ VAR=\"value\"         │ $VAR = \"value\"      │")
-print("│ Command Sub     │ result=$(cmd)       │ result = `cmd`      │")
-print("│ Conditionals    │ if [ -f file ]; fi  │ if `test -f file`   │")
-print("│ Arrays          │ arr=(a b c)         │ arr = {\"a\",\"b\",\"c\"} │")
-print("│ Functions       │ Limited             │ Full Lua functions  │")
-print("└─────────────────┴─────────────────────┴─────────────────────┘")
-
-print("\n🎯 Live Examples:")
-
-print("\n1. Environment & Variables")
-print("   Current user: " .. $USER)
-$GREETING = "Hello from Luash"
-print("   Custom var: " .. $GREETING)
-
-print("\n2. Shell Integration")
-system_info = `uname -a`
-print("   System: " .. system_info)
-
-file_count = `ls | wc -l`
-print("   Files here: " .. file_count)
-
-print("\n3. Real Programming")
--- Lua's power: functions, tables, proper data types
-function analyze_directory(path)
-    local files = `ls -la ` .. (path or ".")
-    local lines = {}
-    local file_count = 0
-    local total_size = 0
-    
-    for line in files:gmatch("[^\n]+") do
-        if not line:match("^total") and not line:match("^d") then
-            file_count = file_count + 1
-            -- Extract size (5th field in ls -la)
-            local size = line:match("%S+%s+%S+%s+%S+%s+%S+%s+(%d+)")
-            if size then
-                total_size = total_size + tonumber(size)
-            end
-        end
-    end
-    
-    return file_count, total_size
-end
-
-files, size = analyze_directory()
-print("   Analysis: " .. files .. " files, " .. size .. " bytes total")
-
-print("\n4. Error Handling")
-if `which git 2>/dev/null` ~= "" then
-    print("   ✓ Git is available")
-    if `git status 2>/dev/null` ~= "" then
-        branch = `git branch --show-current 2>/dev/null`
-        print("   Current branch: " .. branch)
-    else
-        print("   Not in a git repository")
-    end
-else
-    print("   ✗ Git not installed")
-end
-
-print("\n5. Data Processing")
--- Create and process some data
-sample_data = {
-    {name = "Alice", score = 95},
-    {name = "Bob", score = 87}, 
-    {name = "Charlie", score = 92}
-}
-
-total_score = 0
-for i = 1, #sample_data do
-    total_score = total_score + sample_data[i].score
-end
-average = total_score / #sample_data
-
-print("   Student scores processed:")
-print("   Average: " .. string.format("%.1f", average))
-
--- Find highest scorer
-best_student = sample_data[1]
-for i = 2, #sample_data do
-    if sample_data[i].score > best_student.score then
-        best_student = sample_data[i]
-    end
-end
-print("   Top student: " .. best_student.name .. " (" .. best_student.score .. ")")
-
-print("\n🎪 Interactive Demo:")
-print("   Let's see what's running on your system...")
-!ps aux | head -5
-
-print("\n📈 Performance:")
-start_time = `date +%s.%N`
--- Simulate some work
-for i = 1, 1000 do
-    local _ = string.upper("performance test " .. i)
-end
-end_time = `date +%s.%N`
-
--- Calculate duration (requires bash-style arithmetic)
-duration = tonumber(end_time) - tonumber(start_time)
-print("   Processed 1000 operations in " .. string.format("%.3f", duration) .. " seconds")
-
-print("\n✨ Try these demos:")
-print("   ./luash demo_quick_examples.luash  # Side-by-side with bash")
-print("   ./luash demo_system_admin.luash    # Sysadmin tasks")
-print("   ./luash demo_development.luash     # Dev workflows") 
-print("   ./luash demo_data_processing.luash # Data analysis")
-
-print("\n🎉 Luash: Shell scripting that doesn't make you cry!")
diff --git a/system_report.txt b/system_report.txt
deleted file mode 100644
index 36ee363..0000000
--- a/system_report.txt
+++ /dev/null
@@ -1,4 +0,0 @@
-System Report - Fri Aug 29 00:17:34 BST 2025
-User: nik
-System: Darwin arm64
-Processes:      750