diff --git a/README.md b/README.md
index 1e787bf..f0b063e 100644
--- a/README.md
+++ b/README.md
@@ -1,28 +1,141 @@
-# Mars
+# MARS (Multi-Agent Ruby SDK)
 
-TODO: Delete this and the text below, and describe your gem
+[![Gem Version](https://badge.fury.io/rb/mars_rb.svg)](https://badge.fury.io/rb/mars_rb)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
-Welcome to your new gem! In this directory, you'll find the files you need to be able to package up your Ruby library into a gem. Put your Ruby code in the file `lib/mars`. To experiment with that code, run `bin/console` for an interactive prompt.
+MARS (Multi-Agent Ruby SDK) provides a comprehensive framework for developers to implement multi-agent solutions using pure Ruby. It offers a simple, intuitive API for orchestrating multiple agents with support for sequential and parallel workflows, conditional branching, and visual workflow diagrams.
+
+## Features
+
+- 🤖 **Agent Orchestration**: Coordinate multiple agents with ease
+- 🔄 **Sequential Workflows**: Chain agents to execute tasks in order
+- ⚡ **Parallel Workflows**: Run multiple agents concurrently
+- 🚦 **Conditional Gates**: Branch workflows based on runtime conditions
+- 🔧 **Aggregators**: Combine results from parallel operations
+- 📊 **Visual Diagrams**: Generate Mermaid diagrams of your workflows
+- 🔌 **LLM Integration**: Built-in support for LLM agents via [ruby_llm](https://github.com/gbaptista/ruby_llm)
+- 🛠️ **Tools & Schemas**: Define custom tools and structured outputs for agents
+
+## Requirements
+
+- Ruby >= 3.1.0
 
 ## Installation
 
-TODO: Replace `UPDATE_WITH_YOUR_GEM_NAME_IMMEDIATELY_AFTER_RELEASE_TO_RUBYGEMS_ORG` with your gem name right after releasing it to RubyGems.org. Please do not do it earlier due to security reasons. Alternatively, replace this section with instructions to install your gem from git if you don't plan to release to RubyGems.org.
+Add this line to your application's Gemfile:
 
-Install the gem and add to the application's Gemfile by executing:
+```ruby
+gem 'mars_rb'
+```
+
+And then execute:
 
 ```bash
-bundle add UPDATE_WITH_YOUR_GEM_NAME_IMMEDIATELY_AFTER_RELEASE_TO_RUBYGEMS_ORG
+bundle install
 ```
 
-If bundler is not being used to manage dependencies, install the gem by executing:
+Or install it yourself as:
 
 ```bash
-gem install UPDATE_WITH_YOUR_GEM_NAME_IMMEDIATELY_AFTER_RELEASE_TO_RUBYGEMS_ORG
+gem install mars_rb
+```
+
+## Quick Start
+
+Here's a simple example to get you started:
+
+```ruby
+require 'mars'
+
+# Create agents
+agent1 = Mars::Agent.new(name: "Agent 1")
+agent2 = Mars::Agent.new(name: "Agent 2")
+agent3 = Mars::Agent.new(name: "Agent 3")
+
+# Create a sequential workflow
+workflow = Mars::Workflows::Sequential.new(
+  "My First Workflow",
+  steps: [agent1, agent2, agent3]
+)
+
+# Run the workflow
+result = workflow.run("Your input here")
+```
+
+## Core Concepts
+
+### Agents
+
+Agents are the basic building blocks of MARS. They represent individual units of work:
+
+```ruby
+agent = Mars::Agent.new(
+  name: "My Agent",
+  instructions: "You are a helpful assistant",
+  options: { model: "gpt-4o" }
+)
+```
+
+### Sequential Workflows
+
+Execute agents one after another, passing outputs as inputs:
+
+```ruby
+sequential = Mars::Workflows::Sequential.new(
+  "Sequential Pipeline",
+  steps: [agent1, agent2, agent3]
+)
+```
+
+### Parallel Workflows
+
+Run multiple agents concurrently and aggregate their results:
+
+```ruby
+aggregator = Mars::Aggregator.new(
+  "Results Aggregator",
+  operation: lambda { |results| results.join(", ") }
+)
+
+parallel = Mars::Workflows::Parallel.new(
+  "Parallel Pipeline",
+  steps: [agent1, agent2, agent3],
+  aggregator: aggregator
+)
 ```
 
-## Usage
+### Gates
 
-TODO: Write usage instructions here
+Create conditional branching in your workflows:
+
+```ruby
+gate = Mars::Gate.new(
+  name: "Decision Gate",
+  condition: ->(input) { input[:score] > 0.5 ? :success : :failure },
+  branches: {
+    success: success_workflow,
+    failure: failure_workflow
+  }
+)
+```
+
+### Visualization
+
+Generate Mermaid diagrams to visualize your workflows:
+
+```ruby
+diagram = Mars::Rendering::Mermaid.new(workflow).render
+File.write("workflow_diagram.md", diagram)
+```
+
+## Examples
+
+Check out the [examples](examples/) directory for more detailed examples:
+
+- [Simple Workflow](examples/simple_workflow/) - Basic sequential workflow with gates
+- [Parallel Workflow](examples/parallel_workflow/) - Concurrent agent execution
+- [Complex Workflow](examples/complex_workflow/) - Nested workflows with multiple gates
+- [Complex LLM Workflow](examples/complex_llm_workflow/) - Real-world LLM integration with tools and schemas
 
 ## Development
 
@@ -30,14 +143,48 @@ After checking out the repo, run `bin/setup` to install dependencies. Then, run
 
 To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and the created tag, and push the `.gem` file to [rubygems.org](https://rubygems.org).
 
+## Testing
+
+Run the test suite with:
+
+```bash
+bundle exec rake spec
+```
+
 ## Contributing
 
-Bug reports and pull requests are welcome on GitHub at https://github.com/[USERNAME]/mars. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [code of conduct](https://github.com/[USERNAME]/mars/blob/main/CODE_OF_CONDUCT.md).
+Bug reports and pull requests are welcome on GitHub at https://github.com/rootstrap/mars. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [code of conduct](https://github.com/rootstrap/mars/blob/main/CODE_OF_CONDUCT.md).
+
+To contribute:
+
+1. Fork the repository
+2. Create your feature branch (`git checkout -b feature/amazing-feature`)
+3. Commit your changes (`git commit -am 'Add some amazing feature'`)
+4. Push to the branch (`git push origin feature/amazing-feature`)
+5. Open a Pull Request
+
+Please make sure to:
+- Write tests for new features
+- Update documentation as needed
+- Follow the existing code style
+- Ensure all tests pass before submitting
 
 ## License
 
 The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
 
+## Support
+
+- 🐛 [Issue Tracker](https://github.com/rootstrap/mars/issues)
+
+## Related Projects
+
+- [ruby_llm](https://github.com/gbaptista/ruby_llm) - Ruby interface for LLM providers
+
 ## Code of Conduct
 
-Everyone interacting in the Mars project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/[USERNAME]/mars/blob/main/CODE_OF_CONDUCT.md).
+Everyone interacting in the Mars project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/rootstrap/mars/blob/main/CODE_OF_CONDUCT.md).
+
+## Credits
+
+Created and maintained by [Rootstrap](https://www.rootstrap.com).
diff --git a/examples/complex_llm_workflow/diagram.md b/examples/complex_llm_workflow/diagram.md
new file mode 100644
index 0000000..3e86da4
--- /dev/null
+++ b/examples/complex_llm_workflow/diagram.md
@@ -0,0 +1,21 @@
+```mermaid
+flowchart LR
+in((In))
+out((Out))
+llm_1[LLM 1]
+gate{Gate}
+parallel_workflow_aggregator[Parallel workflow Aggregator]
+llm_2[LLM 2]
+llm_3[LLM 3]
+llm_4[LLM 4]
+in --> llm_1
+llm_1 --> gate
+gate -->|success| llm_2
+gate -->|success| llm_3
+gate -->|success| llm_4
+gate -->|default| out
+llm_2 --> parallel_workflow_aggregator
+parallel_workflow_aggregator --> out
+llm_3 --> parallel_workflow_aggregator
+llm_4 --> parallel_workflow_aggregator
+```
diff --git a/examples/complex_llm_workflow/generator.rb b/examples/complex_llm_workflow/generator.rb
index d96acd4..ce1b5e6 100755
--- a/examples/complex_llm_workflow/generator.rb
+++ b/examples/complex_llm_workflow/generator.rb
@@ -7,23 +7,62 @@
   config.openai_api_key = ENV.fetch("OPENAI_API_KEY", nil)
 end
 
+# Define schema for sports
+class SportsSchema < RubyLLM::Schema
+  array :sports do
+    object do
+      string :name
+      array :top_3_players do
+        string :name
+      end
+    end
+  end
+end
+
+sports_schema = SportsSchema.new
+
+# Define weather tool
+class Weather < RubyLLM::Tool
+  description "Gets current weather for a location"
+
+  params do
+    string :latitude, description: "Latitude (e.g., 52.5200)"
+    string :longitude, description: "Longitude (e.g., 13.4050)"
+  end
+
+  def execute(latitude:, longitude:)
+    url = "https://api.open-meteo.com/v1/forecast?latitude=#{latitude}&longitude=#{longitude}&current=temperature_2m,wind_speed_10m"
+    response = Net::HTTP.get_response(URI(url))
+    JSON.parse(response.body)
+  rescue StandardError => e
+    { error: e.message }
+  end
+end
+
+weather_tool = Weather.new
+
 # Create the LLMs
 llm1 = Mars::Agent.new(
   name: "LLM 1", options: { model: "gpt-4o" },
-  instructions: "You are a helpful assistant that can answer questions and help with tasks. Only answer with the result"
+  instructions: "You are a helpful assistant that can answer questions.
+                 When asked about a country, only answer with its name."
 )
 
 llm2 = Mars::Agent.new(name: "LLM 2", options: { model: "gpt-4o" },
                        instructions: "You are a helpful assistant that can answer questions and help with tasks.
                        Return information about the typical food of the country.")
 
-llm3 = Mars::Agent.new(name: "LLM 3", options: { model: "gpt-4o" },
+llm3 = Mars::Agent.new(name: "LLM 3", options: { model: "gpt-4o" }, schema: sports_schema,
                        instructions: "You are a helpful assistant that can answer questions and help with tasks.
                        Return information about the popular sports of the country.")
 
+llm4 = Mars::Agent.new(name: "LLM 4", options: { model: "gpt-4o" }, tools: [weather_tool],
+                       instructions: "You are a helpful assistant that can answer questions and help with tasks.
+                       Return the current weather of the country's capital.")
+
 parallel_workflow = Mars::Workflows::Parallel.new(
   "Parallel workflow",
-  steps: [llm2, llm3]
+  steps: [llm2, llm3, llm4]
 )
 
 gate = Mars::Gate.new(
@@ -39,4 +78,10 @@
   steps: [llm1, gate]
 )
 
-puts sequential_workflow.run("Which is the last country to declare independence?")
+# Generate and save the diagram
+diagram = Mars::Rendering::Mermaid.new(sequential_workflow).render
+File.write("examples/complex_llm_workflow/diagram.md", diagram)
+puts "Complex workflow diagram saved to: examples/complex_llm_workflow/diagram.md"
+
+# Run the workflow
+puts sequential_workflow.run("Which is the largest country in South America?")
diff --git a/lib/mars.rb b/lib/mars.rb
index 68e23d7..6e04847 100644
--- a/lib/mars.rb
+++ b/lib/mars.rb
@@ -3,6 +3,7 @@
 require "zeitwerk"
 require "async"
 require "ruby_llm"
+require "ruby_llm/schema"
 
 loader = Zeitwerk::Loader.for_gem
 loader.setup
diff --git a/mars.gemspec b/mars.gemspec
index 3d4bd97..00ac76e 100644
--- a/mars.gemspec
+++ b/mars.gemspec
@@ -36,7 +36,7 @@ Gem::Specification.new do |spec|
 
   # Uncomment to register a new dependency of your gem
   spec.add_dependency "async", "~> 2.34"
-  spec.add_dependency "ruby_llm", "~> 1.0"
+  spec.add_dependency "ruby_llm", "~> 1.9"
   spec.add_dependency "zeitwerk", "~> 2.7"
 
   # For more information and examples about making a new gem, check out our