Changes

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..c9f4928
--- /dev/null
+++ b/README.md
@@ -0,0 +1,102 @@
+# MacroDown
+
+MacroDown is a C++ Markdown processor that extends the CommonMark syntax with a powerful TeX-like macro system. It treats all markup elements as syntactic sugar for macro calls, allowing for extensive customization and extension.
+
+## Features
+
+*   **CommonMark Compatible**: Supports standard Markdown syntax like headers, lists, blockquotes, code blocks, emphasis, and links.
+*   **Macro System**: unique TeX-like macro system (`%macro{arg1}{arg2}`) that powers the entire rendering process.
+*   **Customizable**: Define your own macros using the `%def` intrinsic.
+*   **Two-Step Rendering**: Exposes the syntax tree for inspection or modification before rendering to HTML.
+
+## Building
+
+MacroDown uses CMake for building. You will need a C++23 compliant compiler.
+
+```bash
+mkdir build
+cd build
+cmake ..
+make
+```
+
+## Usage
+
+### CLI
+
+You can use the `macrodown` executable to convert Markdown to HTML.
+
+**From a file:**
+
+```bash
+./macrodown input.md > output.html
+```
+
+**From stdin:**
+
+```bash
+echo "# Hello World" | ./macrodown
+```
+
+### Library Interface
+
+You can integrate MacroDown into your C++ projects using the `MacroDown` class.
+
+```cpp
+#include "macrodown.h"
+#include <iostream>
+
+int main() {
+    macrodown::MacroDown md;
+    
+    std::string input = "# Hello\n\nThis is **MacroDown**.";
+    
+    // Step 1: Parse to Syntax Tree
+    auto root = md.parse(input);
+    
+    // Step 2: Render to HTML
+    std::string html = md.render(*root);
+    
+    std::cout << html << std::endl;
+    return 0;
+}
+```
+
+### Defining Macros
+
+You can define macros directly in your Markdown document:
+
+```markdown
+%def[greet]{name}{Hello, %strong{%name}!}
+
+%greet{World}
+```
+
+Output:
+```html
+<p>Hello, <strong>World</strong>!</p>
+```
+
+Or programmatically in C++:
+
+```cpp
+md.getEvaluator().define("greet", {"name"}, "Hello, %name!");
+```
+
+## Testing
+
+To run the unit tests:
+
+```bash
+cd build
+./macrodown_test
+```
+
+## Project Structure
+
+*   `include/`: Header files.
+*   `src/`: Source code.
+*   `tests/`: Unit and integration tests.
+*   `design.md`: Detailed design document.
+
+```
\ No newline at end of file