diff --git a/README.md b/README.md
new file mode 100644
index 0000000..6662b89
--- /dev/null
+++ b/README.md
@@ -0,0 +1,199 @@
+# Waddle Programming Language
+
+## Overview
+
+Waddle is a modern, expressive programming language designed to be intuitive, readable, and powerful. It combines elements of object-oriented and functional programming with a focus on clarity and developer productivity.
+
+## Key Features
+
+### Language Characteristics
+- Strong, static typing
+- Object-oriented with interface support
+- Functional programming constructs
+- Explicit error handling
+- Concise syntax
+
+### Core Design Principles
+- Readability first
+- Explicit over implicit
+- Minimal cognitive overhead
+- Flexible type system
+
+## Basic Syntax
+
+### Type Declaration
+
+#### Basic type definition
+```waddle
+Animal {
+    // Type implementation
+}
+```
+#### Inheritance
+```waddle
+Animal/Dog {
+    // Dog-specific implementations
+}
+```
+
+#### Interface definition
+```waddle
+@Mammal {
+    // Interface methods
+}
+```
+
+#### Interface implementation
+```waddle
+Animal/Dog -> [Mammal, Domesticated] {
+    // Multiple interface support
+}
+```
+
+### Functions
+
+#### Function declaration
+
+##### Public function
+```waddle
++fn calculateArea(width: Integer, height: Integer) -> [Decimal] {
+    rtn width.multiply(height);
+}
+```
+
+##### Protected Function
+```waddle
+fn calculateArea(width: Integer, height: Integer) -> [Decimal] {
+    rtn width.multiply(height);
+}
+```
+
+##### Private Function
+```waddle
+-fn calculateArea(width: Integer, height: Integer) -> [Decimal] {
+    rtn width.multiply(height);
+}
+```
+
+##### Lambda expression
+```waddle
+areaCalculator = fn(width: Integer, height: Integer) -> [Decimal] {
+    rtn width.multiply(height);
+}
+```
+
+### Error Handling
+```waddle
+result = riskyOperation().attempt {
+    ok {
+        // Successful execution
+        my.output.print("Operation successful");
+    }
+    
+    ValueError {
+        // Handle specific value errors
+        my.logger.log(error.getMessage());
+    }
+    
+    error {
+        // Catch-all error handling
+        my.criticalLogger.alert("Unexpected error");
+    }
+}
+
+```
+
+### Iteration
+
+#### Forward iteration
+```waddle
+loop(i, 0->10) {
+    my.output.print(i);
+}
+```
+
+#### Foward iteration, with step
+```waddle
+loop(i, 0->10, 2) {
+    my.output.print(i); // outputs 0, 2, 4, 6, 8, 10
+}
+```
+
+#### Reverse iteration
+```waddle
+rloop(i, 10->0) {
+    my.output.print(i);
+}
+```
+
+#### Reverse iteration, with step
+```waddle
+rloop(i, 10->0, 2) {
+    my.output.print(i); // outputs 10, 8, 6, 4, 2, 0
+}
+```
+
+#### Foreach loop on arrays
+```waddle
+Integer<> nums.set(<1, 2, 3, 4>);
+
+nums.each(
+    i -> {
+        if(i.mod(2).eq(0)){
+            my.output.print(i); // outputs 2, 4
+        }
+    }
+);
+
+```
+
+## Type System
+
+### Primitive Types
+ - `String`
+ - `Integer`
+ - `Decimal`
+ - `Boolean`
+
+### Advanced Types
+ - Arrays: `Type<>`
+ - Custom types
+ - Interface types
+
+## Unique Language Constructs
+
+### Dot Notation Methods
+ - All objects have built-in methods
+ - Chainable method calls
+ - Explicit operations
+
+```waddle
+my.text.set("Hello")
+    .concat(" World")
+    .length();
+```
+
+### Object Lifecycle
+ - Explicit constructors: `on_create`
+ - Explicit destructors: `on_destroy`
+
+### Planned Features
+ - Enhanced concurrency support
+ - Expanded standard library
+ - Advanced module system
+
+## Installation
+_Detailed installation instructions will be added as the language develops_
+
+## Contribution
+Interested in contributing to Waddle?
+ - Report issues on this repository
+ - Submit pull requests
+ - Provide feedback and suggestions
+
+## License
+Read the LICENSE.md file
+
+## Current Status
+Waddle is currently in active development.
+The language specification and implementation are evolving.
\ No newline at end of file