Changes

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..896ae4d
--- /dev/null
+++ b/README.md
@@ -0,0 +1,128 @@
+# Agent Smith 🕶️
+
+**Agent Smith** is a high-performance, modular C++23 framework for building LLM-powered agents. 
+
+Designed with composability and safety in mind, it provides a clean, dependency-injectable architecture for orchestrating LLM interactions, managing conversation history, and natively executing tools/functions.
+
+## Key Features
+
+*   **Modular Architecture:** Swap out LLM clients, memory storage backends, and tool registries effortlessly.
+*   **Native Tool Calling:** Fully supports structured JSON tool calling, paving the way for seamless Model Context Protocol (MCP) integrations.
+*   **Exception-Free Error Handling:** Built heavily around C++23 `std::expected` (via `mw::E<T>`), ensuring robust network and execution error propagation without crashing your application.
+*   **Async-Ready:** Core loops and LLM executions return `Task<T>` coroutine wrappers, ready for integration into modern async event loops.
+*   **Lightweight Foundation:** Powered by `libmw` for everyday HTTP networking and data handling, alongside `nlohmann/json` and `spdlog`.
+
+## Integration
+
+Agent Smith is designed to be consumed as a CMake library. The easiest way to add it to your project is via `FetchContent`.
+
+### CMakeLists.txt
+
+```cmake
+include(FetchContent)
+
+FetchContent_Declare(
+  agent_smith
+  GIT_REPOSITORY https://github.com/YourOrg/agent-smith.git
+  # GIT_TAG main
+)
+
+FetchContent_MakeAvailable(agent_smith)
+
+add_executable(my_agent src/main.cpp)
+target_link_libraries(my_agent PRIVATE agent_smith)
+```
+
+## Quick Start Example
+
+Here is a minimal example of how to configure an OpenAI-compatible client, define a custom tool, and run an agent loop.
+
+```cpp
+#include <iostream>
+#include <memory>
+#include <agent.hpp>
+#include <llm_client.hpp>
+#include <memory.hpp>
+#include <tool.hpp>
+
+// 1. Define a custom tool
+class MyCalculator : public Tool {
+public:
+    std::string name() const override { return "calculator"; }
+    std::string description() const override { return "Performs basic addition."; }
+    
+    nlohmann::json parametersSchema() const override {
+        return R"({
+            "type": "object",
+            "properties": {
+                "a": {"type": "number"},
+                "b": {"type": "number"}
+            },
+            "required": ["a", "b"]
+        })"_json;
+    }
+    
+    Task<mw::E<std::string>> execute(const nlohmann::json& args) override {
+        double a = args["a"];
+        double b = args["b"];
+        co_return std::to_string(a + b);
+    }
+};
+
+// Simple blocking runner for coroutines
+void runTask(Task<mw::E<std::string>> task) {
+    auto res = task.get();
+    if(res.has_value()) std::cout << "Agent: " << res.value() << "
+";
+    else std::cout << "Error: " << mw::errorMsg(res.error()) << "
+";
+}
+
+int main() {
+    // 2. Setup the infrastructure
+    auto client = std::make_unique<OpenAiClient>("your-api-key");
+    auto memory = std::make_unique<InMemoryMemory>();
+    ToolRegistry registry;
+    
+    registry.registerTool(std::make_unique<MyCalculator>());
+    
+    // 3. Instantiate the agent
+    Agent agent(std::move(client), std::move(memory), registry);
+    agent.allowTool("calculator");
+    
+    Skill math_skill{
+        "math_bot", 
+        "You are a helpful math bot. Use your tools to answer questions.", 
+        {"calculator"}
+    };
+    agent.activateSkill(math_skill);
+    
+    // 4. Run the conversational loop
+    runTask(agent.run("What is 42 + 8?"));
+    
+    return 0;
+}
+```
+
+## Built-in CLI
+
+The repository also builds an interactive CLI executable (`agent_smith_cli`) out of the box, which serves as a great reference implementation.
+
+```bash
+# Build the CLI and tests
+cmake -S . -B build
+cmake --build build -j
+
+# Run the CLI using a custom local endpoint
+./build/agent_smith_cli --api-key "dummy" --endpoint "http://localhost:8080/v1" --model "local-model"
+```
+
+## Dependencies
+
+*   **C++ Standard:** C++23
+*   **Build System:** CMake >= 3.24
+*   [libmw](https://github.com/MetroWind/libmw) (HTTP client, SQLite, core utils)
+*   [nlohmann/json](https://github.com/nlohmann/json)
+*   [spdlog](https://github.com/gabime/spdlog)
+*   [cxxopts](https://github.com/jarro2783/cxxopts) (CLI only)
+*   [GoogleTest](https://github.com/google/googletest) (Tests only)