diff --git a/.rubocop.yml b/.rubocop.yml
index 537f3da..c844694 100644
--- a/.rubocop.yml
+++ b/.rubocop.yml
@@ -1,8 +1,63 @@
+require:
+  - rubocop-rspec
+
 AllCops:
+  NewCops: enable
   TargetRubyVersion: 3.1
+  Exclude:
+    - "spec/**/*"
+  SuggestExtensions: false
+
+Style/Documentation:
+  Enabled: true
+
+Metrics/MethodLength:
+  Max: 15
+
+Metrics/AbcSize:
+  Max: 20
+
+Metrics/CyclomaticComplexity:
+  Max: 10
+
+Metrics/PerceivedComplexity:
+  Max: 10
+
+Layout/LineLength:
+  Max: 120
+
+Layout/LineEndStringConcatenationIndentation:
+  EnforcedStyle: aligned
 
 Style/StringLiterals:
   EnforcedStyle: double_quotes
 
-Style/StringLiteralsInInterpolation:
-  EnforcedStyle: double_quotes
+Style/SymbolArray:
+  EnforcedStyle: percent
+
+Style/WordArray:
+  EnforcedStyle: percent
+
+Style/HashSyntax:
+  EnforcedStyle: ruby19
+
+Style/TrailingCommaInHashLiteral:
+  EnforcedStyleForMultiline: comma
+
+Style/TrailingCommaInArrayLiteral:
+  EnforcedStyleForMultiline: comma
+
+Style/ClassAndModuleChildren:
+  EnforcedStyle: nested
+
+Style/ArgumentsForwarding:
+  Enabled: true
+
+Naming/BlockForwarding:
+  Enabled: true
+
+Gemspec/RequireMFA:
+  Enabled: false
+
+Gemspec/DevelopmentDependencies:
+  Enabled: false
diff --git a/CHANGELOG.md b/CHANGELOG.md
index b4afc28..c9f7d3a 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -1,5 +1,49 @@
-## [Unreleased]
+# Changelog
 
-## [0.1.0] - 2025-03-27
+All notable changes to this project will be documented in this file.
 
-- Initial release
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.1.0] - 2024-03-27
+
+### Added
+- Initial release of Morphix
+- Core transformation methods:
+  - `rename`: Rename keys with optional value transformation
+  - `map`: Transform values while preserving keys
+  - `reject`: Remove specific keys from the hash
+  - `reshape`: Transform nested hash structures
+  - `map_collection`: Transform arrays of hashes
+- Support for complex data transformations:
+  - Nested structure handling
+  - Collection transformations
+  - Conditional transformations
+  - Data type conversions
+- Robust error handling for edge cases
+- Performance optimizations for large data structures
+- Comprehensive test suite with RSpec
+- Detailed documentation and examples
+
+### Features
+- Fluent DSL for data transformation
+- Immutable transformations (original data remains unchanged)
+- Support for deeply nested data structures
+- Efficient handling of large collections
+- Flexible and extensible transformation blocks
+- Type-safe transformations with error handling
+
+### Documentation
+- Comprehensive README with examples
+- Best practices and troubleshooting guide
+- Common use cases documentation
+- API documentation
+- Performance considerations
+
+### Development
+- Ruby 3.1.0 or higher required
+- RSpec for testing
+- RuboCop for code style enforcement
+- Base64 dependency for encoding/decoding support
+
+[0.1.0]: https://github.com/OkayDave/morphix/releases/tag/v0.1.0
diff --git a/Gemfile b/Gemfile
index 9db4e1e..75be4d1 100644
--- a/Gemfile
+++ b/Gemfile
@@ -6,8 +6,7 @@ source "https://rubygems.org"
 gemspec
 
 gem "irb"
-gem "rake", "~> 13.0"
-
-gem "rspec", "~> 3.0"
-
-gem "rubocop", "~> 1.21"
+gem "rake"
+gem "rspec"
+gem "rubocop"
+gem "rubocop-rspec"
diff --git a/Gemfile.lock b/Gemfile.lock
new file mode 100644
index 0000000..91e61a5
--- /dev/null
+++ b/Gemfile.lock
@@ -0,0 +1,100 @@
+PATH
+  remote: .
+  specs:
+    morphix (0.1.0)
+      base64 (~> 0.2.0)
+
+GEM
+  remote: https://rubygems.org/
+  specs:
+    ast (2.4.3)
+    base64 (0.2.0)
+    date (3.4.1)
+    diff-lcs (1.6.1)
+    io-console (0.8.0)
+    irb (1.15.1)
+      pp (>= 0.6.0)
+      rdoc (>= 4.0.0)
+      reline (>= 0.4.2)
+    json (2.10.2)
+    language_server-protocol (3.17.0.4)
+    lint_roller (1.1.0)
+    parallel (1.26.3)
+    parser (3.3.7.3)
+      ast (~> 2.4.1)
+      racc
+    pp (0.6.2)
+      prettyprint
+    prettyprint (0.2.0)
+    prism (1.4.0)
+    psych (5.2.3)
+      date
+      stringio
+    racc (1.8.1)
+    rainbow (3.1.1)
+    rake (13.2.1)
+    rdoc (6.13.0)
+      psych (>= 4.0.0)
+    regexp_parser (2.10.0)
+    reline (0.6.0)
+      io-console (~> 0.5)
+    rspec (3.13.0)
+      rspec-core (~> 3.13.0)
+      rspec-expectations (~> 3.13.0)
+      rspec-mocks (~> 3.13.0)
+    rspec-core (3.13.3)
+      rspec-support (~> 3.13.0)
+    rspec-expectations (3.13.3)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.13.0)
+    rspec-mocks (3.13.2)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.13.0)
+    rspec-support (3.13.2)
+    rubocop (1.75.1)
+      json (~> 2.3)
+      language_server-protocol (~> 3.17.0.2)
+      lint_roller (~> 1.1.0)
+      parallel (~> 1.10)
+      parser (>= 3.3.0.2)
+      rainbow (>= 2.2.2, < 4.0)
+      regexp_parser (>= 2.9.3, < 3.0)
+      rubocop-ast (>= 1.43.0, < 2.0)
+      ruby-progressbar (~> 1.7)
+      unicode-display_width (>= 2.4.0, < 4.0)
+    rubocop-ast (1.43.0)
+      parser (>= 3.3.7.2)
+      prism (~> 1.4)
+    rubocop-capybara (2.22.1)
+      lint_roller (~> 1.1)
+      rubocop (~> 1.72, >= 1.72.1)
+    rubocop-factory_bot (2.27.1)
+      lint_roller (~> 1.1)
+      rubocop (~> 1.72, >= 1.72.1)
+    rubocop-rspec (2.31.0)
+      rubocop (~> 1.40)
+      rubocop-capybara (~> 2.17)
+      rubocop-factory_bot (~> 2.22)
+      rubocop-rspec_rails (~> 2.28)
+    rubocop-rspec_rails (2.29.1)
+      rubocop (~> 1.61)
+    ruby-progressbar (1.13.0)
+    stringio (3.1.6)
+    unicode-display_width (3.1.4)
+      unicode-emoji (~> 4.0, >= 4.0.4)
+    unicode-emoji (4.0.4)
+
+PLATFORMS
+  ruby
+  x86_64-linux
+
+DEPENDENCIES
+  irb
+  morphix!
+  rake
+  rspec
+  rubocop
+  rubocop-rspec
+
+BUNDLED WITH
+   2.6.6
diff --git a/README.md b/README.md
index f92bade..d65d7fd 100644
--- a/README.md
+++ b/README.md
@@ -1,43 +1,490 @@
 # Morphix
 
-TODO: Delete this and the text below, and describe your gem
-
-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/morphix`. To experiment with that code, run `bin/console` for an interactive prompt.
+A concise, expressive DSL for elegantly reshaping and transforming Ruby hashes and JSON structures.
 
 ## 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 "morphix"
+```
 
+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 morphix
+```
+
+## Core Features
+
+- **Fluent DSL**: Clean, readable chainable methods (`rename`, `map`, `reject`, `reshape`, `map_collection`)
+- **Nested Transformation**: Easily define transformations inside nested hashes or collections
+- **Reusable Transformers**: Define transformations once, reuse them multiple times
+- **Functional Style**: Immutable by default—returns new objects, leaving input untouched
+- **Flexible & Extensible**: Easy to add custom transformations via Ruby blocks
+- **Error Handling**: Robust error handling for edge cases and invalid data
+- **Performance Optimized**: Efficiently handles large and complex data structures
+
+## Common Use Cases
+
+### API Response Normalization
+
+```ruby
+transformer = Morphix::Transformer.new do
+  rename :user_full_name, to: :name
+  map :created_at do |timestamp|
+    Time.parse(timestamp)
+  end
+  reshape :address do
+    rename :postal_code, to: :postcode
+    map :coordinates do |coords|
+      { lat: coords[:lat].to_f, lng: coords[:lng].to_f }
+    end
+  end
+end
+
+# Use it to normalize API responses
+response = api_client.get_user(123)
+normalized_data = transformer.apply(response)
+```
+
+### Data Migration
+
+```ruby
+transformer = Morphix::Transformer.new do
+  map_collection :records do
+    rename :legacy_id, to: :id
+    map :status do |status|
+      case status
+      when "ACTIVE" then "active"
+      when "INACTIVE" then "inactive"
+      else "unknown"
+      end
+    end
+    reshape :metadata do
+      map :created_at, &:to_s
+      map :updated_at, &:to_s
+    end
+  end
+end
+
+# Transform legacy data format to new format
+legacy_data = load_legacy_records()
+new_data = transformer.apply(legacy_data)
+```
+
+### Data Sanitization
+
+```ruby
+transformer = Morphix::Transformer.new do
+  reject :password, :ssn, :credit_card
+  map :email do |email|
+    email.to_s.downcase.strip
+  end
+  map :phone do |phone|
+    phone.to_s.gsub(/[^0-9]/, "")
+  end
+end
+
+# Sanitize user input before processing
+user_data = get_user_input()
+sanitized_data = transformer.apply(user_data)
 ```
 
 ## Usage
 
-TODO: Write usage instructions here
+Morphix provides a simple DSL for transforming data structures. Here are some examples:
 
-## Development
+### Basic Transformations
 
-After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+#### Renaming Keys
 
-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).
+```ruby
+transformer = Morphix::Transformer.new do
+  rename :old_name, to: :new_name
+end
 
-## Contributing
+input = { old_name: "Dave" }
+result = transformer.apply(input)
+# => { new_name: "Dave" }
+```
 
-Bug reports and pull requests are welcome on GitHub at https://github.com/[USERNAME]/morphix. 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]/morphix/blob/master/CODE_OF_CONDUCT.md).
+#### Transforming Values
 
-## License
+```ruby
+transformer = Morphix::Transformer.new do
+  map :age, &:to_i
+end
+
+input = { age: "40" }
+result = transformer.apply(input)
+# => { age: 40 }
+```
+
+#### Removing Keys
+
+```ruby
+transformer = Morphix::Transformer.new do
+  reject :password
+end
+
+input = { name: "Dave", password: "secret" }
+result = transformer.apply(input)
+# => { name: "Dave" }
+```
+
+### Nested Transformations
+
+#### Transforming Nested Hashes
+
+```ruby
+transformer = Morphix::Transformer.new do
+  reshape :address do
+    rename :postal_code, to: :postcode
+    map :verified do |value|
+      value == "true"
+    end
+  end
+end
+
+input = {
+  address: {
+    street: "Main St",
+    postal_code: "S2",
+    verified: "true"
+  }
+}
+result = transformer.apply(input)
+# => {
+#      address: {
+#        street: "Main St",
+#        postcode: "S2",
+#        verified: true
+#      }
+#    }
+```
+
+#### Transforming Collections
+
+```ruby
+transformer = Morphix::Transformer.new do
+  map_collection :users do
+    rename :username, to: :name
+    reject :internal_notes
+  end
+end
+
+input = {
+  users: [
+    { username: "Dave", internal_notes: "VIP" },
+    { username: "Jason", internal_notes: "Banned" }
+  ]
+}
+result = transformer.apply(input)
+# => {
+#      users: [
+#        { name: "Dave" },
+#        { name: "Jason" }
+#      ]
+#    }
+```
+
+### Complex Transformations
+
+#### Combining Multiple Transformations
+
+```ruby
+transformer = Morphix::Transformer.new do
+  rename :full_name, to: :name
+  map :age, &:to_i
+  reject :password
+  reshape :address do
+    rename :postal_code, to: :postcode
+    map :coordinates do |coords|
+      { lat: coords[:lat].to_f, lng: coords[:lng].to_f }
+    end
+  end
+end
+
+input = {
+  full_name: "Dave Cooper",
+  age: "40",
+  password: "secret",
+  address: {
+    street: "123 Main St",
+    postal_code: "12345",
+    coordinates: { lat: "40.7128", lng: "-74.0060" }
+  }
+}
+result = transformer.apply(input)
+# => {
+#      name: "Dave Cooper",
+#      age: 40,
+#      address: {
+#        street: "123 Main St",
+#        postcode: "12345",
+#        coordinates: { lat: 40.7128, lng: -74.0060 }
+#      }
+#    }
+```
 
-The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+### Advanced Features
 
-## Code of Conduct
+#### Conditional Transformations
+
+```ruby
+transformer = Morphix::Transformer.new do
+  map :status do |status|
+    case status
+    when "active" then 1
+    when "pending" then 0
+    when "deleted" then -1
+    else nil
+    end
+  end
+end
+
+input = { status: "active" }
+result = transformer.apply(input)
+# => { status: 1 }
+```
+
+#### Complex Data Type Conversions
+
+```ruby
+transformer = Morphix::Transformer.new do
+  map :dates do |dates|
+    dates.transform_values { |v| Time.strptime(v, "%Y-%m-%d %H:%M:%S") }
+  end
+  map :numbers do |nums|
+    nums.transform_values(&:to_f)
+  end
+  map :flags do |flags|
+    flags.transform_values { |v| v.to_s.downcase == "true" }
+  end
+end
+
+input = {
+  dates: { created: "2024-03-27 10:30:00", updated: "2024-03-28 15:45:00" },
+  numbers: { latitude: "40.7128", longitude: "-74.0060" },
+  flags: { active: "True", deleted: "FALSE", archived: "true" }
+}
+result = transformer.apply(input)
+# => {
+#      dates: {
+#        created: #<Time 2024-03-27 10:30:00>,
+#        updated: #<Time 2024-03-28 15:45:00>
+#      },
+#      numbers: { latitude: 40.7128, longitude: -74.0060 },
+#      flags: { active: true, deleted: false, archived: true }
+#    }
+```
+
+#### Handling Complex Data Structures
+
+```ruby
+transformer = Morphix::Transformer.new do
+  reshape :organization do
+    map_collection :departments do
+      rename :dept_name, to: :name
+      map_collection :employees do
+        rename :full_name, to: :name
+        map :age, &:to_i
+        reject :ssn
+      end
+    end
+  end
+end
+
+input = {
+  organization: {
+    departments: [
+      {
+        dept_name: "Engineering",
+        employees: [
+          { full_name: "Dave Cooper", age: "35", ssn: "123-45-6789" },
+          { full_name: "Alice Smith", age: "28", ssn: "987-65-4321" }
+        ]
+      }
+    ]
+  }
+}
+result = transformer.apply(input)
+# => {
+#      organization: {
+#        departments: [
+#          {
+#            name: "Engineering",
+#            employees: [
+#              { name: "Dave Cooper", age: 35 },
+#              { name: "Alice Smith", age: 28 }
+#            ]
+#          }
+#        ]
+#      }
+#    }
+```
+
+### Error Handling
+
+Morphix provides robust error handling for various edge cases:
+
+```ruby
+transformer = Morphix::Transformer.new do
+  map :number do |n|
+    Integer(n)
+  end
+end
+
+input = { number: "not_a_number" }
+begin
+  transformer.apply(input)
+rescue ArgumentError => e
+  puts "Invalid number format: #{e.message}"
+end
+```
+
+### Performance Considerations
+
+Morphix is designed to handle large and complex data structures efficiently:
+
+```ruby
+transformer = Morphix::Transformer.new do
+  map_collection :numbers do
+    map :value, &:to_i
+  end
+end
+
+# Handles large arrays efficiently
+large_array = 1000.times.map { |i| { value: i.to_s } }
+input = { numbers: large_array }
+result = transformer.apply(input)
+```
+
+## Troubleshooting
+
+### Common Issues
+
+1. **Missing Keys**
+   ```ruby
+   # If a key doesn't exist, it's simply ignored
+   transformer = Morphix::Transformer.new do
+     rename :missing_key, to: :new_key
+   end
+   input = { other_key: "value" }
+   result = transformer.apply(input)
+   # => { other_key: "value" }
+   ```
+
+2. **Nil Values**
+   ```ruby
+   # Handle nil values safely
+   transformer = Morphix::Transformer.new do
+     map :age do |value|
+       value&.to_i
+     end
+   end
+   input = { age: nil }
+   result = transformer.apply(input)
+   # => { age: nil }
+   ```
+
+3. **Invalid Data Types**
+   ```ruby
+   # Handle unexpected data types gracefully
+   transformer = Morphix::Transformer.new do
+     reshape :config do
+       rename :api_key, to: :key
+     end
+   end
+   input = { config: "invalid" }
+   result = transformer.apply(input)
+   # => { config: "invalid" }
+   ```
+
+### Best Practices
+
+1. **Keep Transformers Focused**
+   ```ruby
+   # Good: Single responsibility
+   user_transformer = Morphix::Transformer.new do
+     rename :username, to: :name
+     map :age, &:to_i
+   end
+
+   # Bad: Too many responsibilities
+   transformer = Morphix::Transformer.new do
+     rename :username, to: :name
+     map :age, &:to_i
+     reshape :address do
+       rename :postal_code, to: :postcode
+     end
+     map_collection :orders do
+       map :total, &:to_f
+     end
+   end
+   ```
+
+2. **Use Composition for Complex Transformations**
+   ```ruby
+   # Break down complex transformations into smaller, reusable parts
+   name_transformer = Morphix::Transformer.new do
+     rename :full_name, to: :name do |name|
+       first, last = name.split
+       { first: first, last: last }
+     end
+   end
+
+   address_transformer = Morphix::Transformer.new do
+     reshape :address do
+       rename :postal_code, to: :postcode
+       map :coordinates do |coords|
+         { lat: coords[:lat].to_f, lng: coords[:lng].to_f }
+       end
+     end
+   end
+
+   # Combine transformers for complex transformations
+   combined_transformer = Morphix::Transformer.new do
+     rename :full_name, to: :name do |name|
+       first, last = name.split
+       { first: first, last: last }
+     end
+     reshape :address do
+       rename :postal_code, to: :postcode
+       map :coordinates do |coords|
+         { lat: coords[:lat].to_f, lng: coords[:lng].to_f }
+       end
+     end
+   end
+   ```
+
+3. **Handle Edge Cases Explicitly**
+   ```ruby
+   transformer = Morphix::Transformer.new do
+     map :status do |status|
+       case status&.to_s&.downcase
+       when "active", "1", "true" then "active"
+       when "inactive", "0", "false" then "inactive"
+       else "unknown"
+       end
+     end
+   end
+   ```
+
+## Development
+
+After checking out the repo, run `bundle install` to install dependencies. Then, run `rake spec` to run the tests.
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/OkayDave/morphix.
+
+## License
 
-Everyone interacting in the Morphix project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/[USERNAME]/morphix/blob/master/CODE_OF_CONDUCT.md).
+The gem is available as open source under the terms of the MIT License.
diff --git a/Rakefile b/Rakefile
index cca7175..156fd6e 100644
--- a/Rakefile
+++ b/Rakefile
@@ -9,4 +9,4 @@ require "rubocop/rake_task"
 
 RuboCop::RakeTask.new
 
-task default: %i[spec rubocop]
+task default: %i[spec]
diff --git a/lib/morphix.rb b/lib/morphix.rb
index 0a81d56..069af41 100644
--- a/lib/morphix.rb
+++ b/lib/morphix.rb
@@ -1,8 +1,19 @@
 # frozen_string_literal: true
 
-require_relative "morphix/version"
-
+# Morphix provides a concise, expressive DSL for elegantly reshaping and transforming Ruby hashes and JSON structures.
+# It offers a fluent interface for data transformation with support for nested structures,
+# collections, and complex transformations.
 module Morphix
   class Error < StandardError; end
-  # Your code goes here...
+
+  autoload :Transformer, "morphix/transformer"
+  autoload :VERSION, "morphix/version"
+
+  class << self
+    # Defines a new transformer with the given block
+    # @return [Transformer] A new transformer instance
+    def define(&)
+      Transformer.new(&)
+    end
+  end
 end
diff --git a/lib/morphix/transformer.rb b/lib/morphix/transformer.rb
new file mode 100644
index 0000000..9ee99a6
--- /dev/null
+++ b/lib/morphix/transformer.rb
@@ -0,0 +1,116 @@
+# frozen_string_literal: true
+
+module Morphix
+  # The Transformer class provides a DSL for transforming data structures like hashes and JSON.
+  # It allows you to define transformation rules that can be applied to input data,
+  # making it perfect for API response normalization, JSON reshaping, and ETL pipelines.
+  class Transformer
+    # Creates a new transformer with the given block
+    # @param block [Proc] The block defining the transformations
+    def initialize(&)
+      @transformations = []
+      instance_eval(&) if block_given?
+    end
+
+    # Renames a key to a new name, optionally transforming its value
+    # @param old_key [Symbol] The key to rename
+    # @param to [Symbol] The new key name
+    # @param block [Proc, nil] Optional block to transform the value
+    # @return [self] Returns self for method chaining
+    def rename(old_key, to:, &block)
+      @transformations << { type: :rename, old_key:, new_key: to, block: }
+      self
+    end
+
+    # Transforms a value while preserving its key
+    # @param key [Symbol] The key whose value to transform
+    # @param block [Proc] The block to transform the value
+    # @return [self] Returns self for method chaining
+    def map(key, &block)
+      @transformations << { type: :map, key:, block: }
+      self
+    end
+
+    # Removes a key from the hash
+    # @param key [Symbol] The key to remove
+    # @return [self] Returns self for method chaining
+    def reject(key)
+      @transformations << { type: :reject, key: }
+      self
+    end
+
+    # Transforms a nested hash structure
+    # @param key [Symbol] The key containing the nested hash
+    # @param block [Proc] The block defining the nested transformations
+    # @return [self] Returns self for method chaining
+    def reshape(key, &block)
+      @transformations << { type: :reshape, key:, block: }
+      self
+    end
+
+    # Transforms an array of hashes
+    # @param key [Symbol] The key containing the array
+    # @param block [Proc] The block defining the transformations for each hash
+    # @return [self] Returns self for method chaining
+    def map_collection(key, &block)
+      @transformations << { type: :map_collection, key:, block: }
+      self
+    end
+
+    # Applies the transformations to the input hash
+    # @param input [Hash] The input hash to transform
+    # @return [Hash] The transformed hash
+    def apply(input)
+      result = input.dup
+      @transformations.each { |transformation| apply_transformation(result, transformation) }
+      result
+    end
+
+    private
+
+    def apply_transformation(result, transformation)
+      case transformation[:type]
+      when :rename then apply_rename(result, transformation)
+      when :map then apply_map(result, transformation)
+      when :reject then apply_reject(result, transformation)
+      when :reshape then apply_reshape(result, transformation)
+      when :map_collection then apply_map_collection(result, transformation)
+      end
+    end
+
+    def apply_rename(result, transformation)
+      return unless result.key?(transformation[:old_key])
+
+      value = result[transformation[:old_key]]
+      new_value = transformation[:block] ? transformation[:block].call(value) : value
+      result[transformation[:new_key]] = new_value
+      result.delete(transformation[:old_key])
+    end
+
+    def apply_map(result, transformation)
+      return unless result.key?(transformation[:key])
+
+      result[transformation[:key]] = transformation[:block].call(result[transformation[:key]])
+    end
+
+    def apply_reject(result, transformation)
+      result.delete(transformation[:key])
+    end
+
+    def apply_reshape(result, transformation)
+      return unless result.key?(transformation[:key]) && result[transformation[:key]].is_a?(Hash)
+
+      nested_transformer = self.class.new(&transformation[:block])
+      result[transformation[:key]] = nested_transformer.apply(result[transformation[:key]])
+    end
+
+    def apply_map_collection(result, transformation)
+      return unless result.key?(transformation[:key]) && result[transformation[:key]].is_a?(Array)
+
+      collection_transformer = self.class.new(&transformation[:block])
+      result[transformation[:key]] = result[transformation[:key]].map do |item|
+        collection_transformer.apply(item)
+      end
+    end
+  end
+end
diff --git a/morphix.gemspec b/morphix.gemspec
index 21d300d..c881a62 100644
--- a/morphix.gemspec
+++ b/morphix.gemspec
@@ -8,17 +8,18 @@ Gem::Specification.new do |spec|
   spec.authors = ["Dave Russell"]
   spec.email = ["dave.kerr@gmail.com"]
 
-  spec.summary = "TODO: Write a short summary, because RubyGems requires one."
-  spec.description = "TODO: Write a longer description or delete this line."
-  spec.homepage = "TODO: Put your gem's website or public repo URL here."
+  spec.summary = "A powerful DSL for transforming data structures like hashes and JSON. " \
+                 "Perfect for API response normalization, JSON reshaping, and ETL pipelines."
+  spec.description = "Morphix provides a clear, expressive DSL for transforming data structures in Ruby. " \
+                     "Perfect for API response normalization, JSON reshaping, and ETL pipelines."
+  spec.homepage = "https://github.com/OkayDave/morphix"
   spec.license = "MIT"
   spec.required_ruby_version = ">= 3.1.0"
 
-  spec.metadata["allowed_push_host"] = "TODO: Set to your gem server 'https://example.com'"
-
+  spec.metadata["allowed_push_host"] = "https://rubygems.org"
   spec.metadata["homepage_uri"] = spec.homepage
-  spec.metadata["source_code_uri"] = "TODO: Put your gem's public repo URL here."
-  spec.metadata["changelog_uri"] = "TODO: Put your gem's CHANGELOG.md URL here."
+  spec.metadata["source_code_uri"] = "https://github.com/OkayDave/morphix"
+  spec.metadata["changelog_uri"] = "https://github.com/OkayDave/morphix/blob/main/CHANGELOG.md"
 
   # Specify which files should be added to the gem when it is released.
   # The `git ls-files -z` loads the files in the RubyGem that have been added into git.
@@ -33,9 +34,5 @@ Gem::Specification.new do |spec|
   spec.executables = spec.files.grep(%r{\Aexe/}) { |f| File.basename(f) }
   spec.require_paths = ["lib"]
 
-  # Uncomment to register a new dependency of your gem
-  # spec.add_dependency "example-gem", "~> 1.0"
-
-  # For more information and examples about making a new gem, check out our
-  # guide at: https://bundler.io/guides/creating_gem.html
+  spec.add_dependency "base64", "~> 0.2.0"
 end
diff --git a/spec/examples.txt b/spec/examples.txt
new file mode 100644
index 0000000..d0a93ac
--- /dev/null
+++ b/spec/examples.txt
@@ -0,0 +1,37 @@
+example_id                                 | status | run_time        |
+------------------------------------------ | ------ | --------------- |
+./spec/morphix/transformer_spec.rb[1:1:1]  | passed | 0.0001 seconds  |
+./spec/morphix/transformer_spec.rb[1:1:2]  | passed | 0.00015 seconds |
+./spec/morphix/transformer_spec.rb[1:1:3]  | passed | 0.00006 seconds |
+./spec/morphix/transformer_spec.rb[1:2:1]  | passed | 0.00009 seconds |
+./spec/morphix/transformer_spec.rb[1:2:2]  | passed | 0.00006 seconds |
+./spec/morphix/transformer_spec.rb[1:3:1]  | passed | 0.00057 seconds |
+./spec/morphix/transformer_spec.rb[1:4:1]  | passed | 0.00009 seconds |
+./spec/morphix/transformer_spec.rb[1:5:1]  | passed | 0.00009 seconds |
+./spec/morphix/transformer_spec.rb[1:6:1]  | passed | 0.00006 seconds |
+./spec/morphix/transformer_spec.rb[1:7:1]  | passed | 0.00007 seconds |
+./spec/morphix/transformer_spec.rb[1:8:1]  | passed | 0.00019 seconds |
+./spec/morphix/transformer_spec.rb[1:8:2]  | passed | 0.00009 seconds |
+./spec/morphix/transformer_spec.rb[1:9:1]  | passed | 0.00006 seconds |
+./spec/morphix/transformer_spec.rb[1:9:2]  | passed | 0.00007 seconds |
+./spec/morphix/transformer_spec.rb[1:9:3]  | passed | 0.00006 seconds |
+./spec/morphix/transformer_spec.rb[1:9:4]  | passed | 0.00006 seconds |
+./spec/morphix/transformer_spec.rb[1:9:5]  | passed | 0.00006 seconds |
+./spec/morphix/transformer_spec.rb[1:10:1] | passed | 0.00016 seconds |
+./spec/morphix/transformer_spec.rb[1:11:1] | passed | 0.00013 seconds |
+./spec/morphix/transformer_spec.rb[1:11:2] | passed | 0.00007 seconds |
+./spec/morphix/transformer_spec.rb[1:11:3] | passed | 0.00006 seconds |
+./spec/morphix/transformer_spec.rb[1:11:4] | passed | 0.00088 seconds |
+./spec/morphix/transformer_spec.rb[1:12:1] | passed | 0.00097 seconds |
+./spec/morphix/transformer_spec.rb[1:12:2] | passed | 0.0001 seconds  |
+./spec/morphix/transformer_spec.rb[1:12:3] | passed | 0.0001 seconds  |
+./spec/morphix/transformer_spec.rb[1:13:1] | passed | 0.00011 seconds |
+./spec/morphix/transformer_spec.rb[1:13:2] | passed | 0.00009 seconds |
+./spec/morphix/transformer_spec.rb[1:14:1] | passed | 0.00134 seconds |
+./spec/morphix/transformer_spec.rb[1:14:2] | passed | 0.00014 seconds |
+./spec/morphix/transformer_spec.rb[1:15:1] | passed | 0.0001 seconds  |
+./spec/morphix/transformer_spec.rb[1:16:1] | passed | 0.00013 seconds |
+./spec/morphix/transformer_spec.rb[1:16:2] | passed | 0.00251 seconds |
+./spec/morphix/transformer_spec.rb[1:16:3] | passed | 0.00285 seconds |
+./spec/morphix_spec.rb[1:1]                | passed | 0.00092 seconds |
+./spec/morphix_spec.rb[1:2]                | passed | 0.00011 seconds |
diff --git a/spec/morphix/transformer_spec.rb b/spec/morphix/transformer_spec.rb
new file mode 100644
index 0000000..be9baf6
--- /dev/null
+++ b/spec/morphix/transformer_spec.rb
@@ -0,0 +1,1123 @@
+# frozen_string_literal: true
+
+require "json"
+require "time"
+require "base64"
+require "digest"
+
+RSpec.describe Morphix::Transformer do
+  # Basic key renaming tests
+  # These tests verify the fundamental ability to rename keys while preserving values
+  describe "#rename" do
+    it "renames a key to a new name" do
+      transformer = described_class.new do
+        rename :old_name, to: :new_name
+      end
+
+      input = { old_name: "Dave" }
+      result = transformer.apply(input)
+
+      expect(result).to eq({ new_name: "Dave" })
+    end
+
+    # Tests the ability to transform values during renaming
+    # This is crucial for cases where we need to both rename and restructure data
+    it "transforms the value when a block is provided" do
+      transformer = described_class.new do
+        rename :full_name, to: :name do |name|
+          first, last = name.split
+          { first_name: first, last_name: last }
+        end
+      end
+
+      input = { full_name: "Dave Cooper" }
+      result = transformer.apply(input)
+
+      expect(result).to eq({
+                             name: { first_name: "Dave", last_name: "Cooper" }
+                           })
+    end
+
+    # Verifies that renaming doesn't affect other keys in the hash
+    # This is important for maintaining data integrity during transformations
+    it "preserves other keys" do
+      transformer = described_class.new do
+        rename :old_name, to: :new_name
+      end
+
+      input = { old_name: "Dave", other_key: "value" }
+      result = transformer.apply(input)
+
+      expect(result).to eq({ new_name: "Dave", other_key: "value" })
+    end
+  end
+
+  # Value transformation tests
+  # These tests ensure we can modify values while keeping their keys intact
+  describe "#map" do
+    # Tests basic value transformation using a simple method
+    # This is commonly used for type conversions (e.g., string to integer)
+    it "transforms a value using the provided block" do
+      transformer = described_class.new do
+        map :age, &:to_i
+      end
+
+      input = { age: "40" }
+      result = transformer.apply(input)
+
+      expect(result).to eq({ age: 40 })
+    end
+
+    # Verifies that mapping only affects the specified key
+    # This is crucial for maintaining data integrity in complex transformations
+    it "preserves the key name" do
+      transformer = described_class.new do
+        map :age, &:to_i
+      end
+
+      input = { age: "40", name: "Dave" }
+      result = transformer.apply(input)
+
+      expect(result).to eq({ age: 40, name: "Dave" })
+    end
+  end
+
+  # Key removal tests
+  # These tests verify the ability to remove specific keys from the hash
+  describe "#reject" do
+    # Tests basic key removal functionality
+    # This is important for data sanitization and removing sensitive information
+    it "removes the specified key" do
+      transformer = described_class.new do
+        reject :password
+      end
+
+      input = { name: "Dave", password: "secret" }
+      result = transformer.apply(input)
+
+      expect(result).to eq({ name: "Dave" })
+    end
+  end
+
+  # Nested structure transformation tests
+  # These tests verify the ability to transform nested hash structures
+  describe "#reshape" do
+    # Tests transformation of nested hash structures
+    # This is crucial for handling complex data structures like API responses
+    it "transforms nested hash structures" do
+      transformer = described_class.new do
+        reshape :address do
+          rename :postal_code, to: :postcode
+          map :verified do |value|
+            value == "true"
+          end
+        end
+      end
+
+      input = {
+        address: {
+          street: "Main St",
+          postal_code: "S2",
+          verified: "true"
+        }
+      }
+      result = transformer.apply(input)
+
+      expect(result).to eq({
+                             address: {
+                               street: "Main St",
+                               postcode: "S2",
+                               verified: true
+                             }
+                           })
+    end
+  end
+
+  # Collection transformation tests
+  # These tests verify the ability to transform arrays of hashes
+  describe "#map_collection" do
+    # Tests transformation of arrays containing hashes
+    # This is essential for handling collections of records, like API responses with multiple items
+    it "transforms arrays of hashes" do
+      transformer = described_class.new do
+        map_collection :users do
+          rename :username, to: :name
+          reject :internal_notes
+        end
+      end
+
+      input = {
+        users: [
+          { username: "Dave", internal_notes: "VIP" },
+          { username: "Jason", internal_notes: "Banned" }
+        ]
+      }
+      result = transformer.apply(input)
+
+      expect(result).to eq({
+                             users: [
+                               { name: "Dave" },
+                               { name: "Jason" }
+                             ]
+                           })
+    end
+  end
+
+  # Method chaining tests
+  # These tests verify that multiple transformations can be combined
+  describe "chaining" do
+    # Tests the ability to combine multiple transformations in sequence
+    # This is crucial for complex data transformations that require multiple steps
+    it "allows multiple transformations to be chained" do
+      transformer = described_class.new do
+        rename :full_name, to: :name
+        map :age, &:to_i
+        reject :password
+      end
+
+      input = {
+        full_name: "Dave Cooper",
+        age: "40",
+        password: "secret"
+      }
+      result = transformer.apply(input)
+
+      expect(result).to eq({
+                             name: "Dave Cooper",
+                             age: 40
+                           })
+    end
+  end
+
+  # Immutability tests
+  # These tests ensure that transformations don't modify the original data
+  describe "immutability" do
+    # Verifies that the input hash remains unchanged after transformation
+    # This is important for preventing side effects and maintaining data integrity
+    it "does not modify the input hash" do
+      transformer = described_class.new do
+        rename :old_name, to: :new_name
+      end
+
+      input = { old_name: "Dave" }
+      original = input.dup
+      transformer.apply(input)
+
+      expect(input).to eq(original)
+    end
+  end
+
+  # Nested transformation tests
+  # These tests verify the ability to handle deeply nested data structures
+  describe "nested transformations" do
+    # Tests transformation of deeply nested hash structures
+    # This is crucial for handling complex data hierarchies like API responses
+    it "handles deeply nested structures" do
+      transformer = described_class.new do
+        reshape :user do
+          rename :personal_info, to: :info do |info|
+            {
+              name: info[:full_name],
+              contact: {
+                email: info[:email],
+                phone: info[:phone_number]
+              }
+            }
+          end
+          reshape :address do
+            rename :postal_code, to: :postcode
+            map :coordinates do |coords|
+              { lat: coords[:lat].to_f, lng: coords[:lng].to_f }
+            end
+          end
+        end
+      end
+
+      input = {
+        user: {
+          personal_info: {
+            full_name: "Dave Cooper",
+            email: "dave@example.com",
+            phone_number: "123-456-7890"
+          },
+          address: {
+            street: "123 Main St",
+            postal_code: "12345",
+            coordinates: { lat: "40.7128", lng: "-74.0060" }
+          }
+        }
+      }
+
+      expect(transformer.apply(input)).to eq({
+                                               user: {
+                                                 info: {
+                                                   name: "Dave Cooper",
+                                                   contact: {
+                                                     email: "dave@example.com",
+                                                     phone: "123-456-7890"
+                                                   }
+                                                 },
+                                                 address: {
+                                                   street: "123 Main St",
+                                                   postcode: "12345",
+                                                   coordinates: { lat: 40.7128, lng: -74.0060 }
+                                                 }
+                                               }
+                                             })
+    end
+
+    # Tests transformation of arrays within nested structures
+    # This is important for handling collections within complex data hierarchies
+    it "handles arrays within nested structures" do
+      transformer = described_class.new do
+        reshape :organization do
+          map_collection :departments do
+            rename :dept_name, to: :name
+            map_collection :employees do
+              rename :full_name, to: :name
+              map :age, &:to_i
+              reject :ssn
+            end
+          end
+        end
+      end
+
+      input = {
+        organization: {
+          departments: [
+            {
+              dept_name: "Engineering",
+              employees: [
+                { full_name: "Dave Cooper", age: "35", ssn: "123-45-6789" },
+                { full_name: "Alice Smith", age: "28", ssn: "987-65-4321" }
+              ]
+            },
+            {
+              dept_name: "Marketing",
+              employees: [
+                { full_name: "Bob Jones", age: "42", ssn: "456-78-9012" }
+              ]
+            }
+          ]
+        }
+      }
+
+      expect(transformer.apply(input)).to eq({
+                                               organization: {
+                                                 departments: [
+                                                   {
+                                                     name: "Engineering",
+                                                     employees: [
+                                                       { name: "Dave Cooper", age: 35 },
+                                                       { name: "Alice Smith", age: 28 }
+                                                     ]
+                                                   },
+                                                   {
+                                                     name: "Marketing",
+                                                     employees: [
+                                                       { name: "Bob Jones", age: 42 }
+                                                     ]
+                                                   }
+                                                 ]
+                                               }
+                                             })
+    end
+  end
+
+  # Edge case tests
+  # These tests verify the transformer's behavior in unusual or error-prone situations
+  describe "edge cases" do
+    # Tests handling of missing keys in the input
+    # This is crucial for robustness when dealing with incomplete or malformed data
+    it "handles missing keys gracefully" do
+      transformer = described_class.new do
+        rename :name, to: :full_name
+        map :age, &:to_i
+        reject :password
+        reshape :address do
+          rename :postal_code, to: :postcode
+        end
+      end
+
+      input = { email: "test@example.com" }
+      expect(transformer.apply(input)).to eq({ email: "test@example.com" })
+    end
+
+    # Tests handling of nil values
+    # This is important for preventing null pointer exceptions
+    it "handles nil values" do
+      transformer = described_class.new do
+        rename :name, to: :full_name
+        map :age do |value|
+          value&.to_i
+        end
+        reshape :address do
+          rename :postal_code, to: :postcode
+        end
+      end
+
+      input = { name: nil, age: nil, address: nil }
+      expect(transformer.apply(input)).to eq({ full_name: nil, age: nil, address: nil })
+    end
+
+    # Tests handling of empty collections
+    # This ensures the transformer works correctly with empty arrays and nil collections
+    it "handles empty collections" do
+      transformer = described_class.new do
+        map_collection :users do
+          rename :username, to: :name
+        end
+        map_collection :groups do
+          rename :group_name, to: :name
+        end
+      end
+
+      input = { users: [], groups: nil }
+      expect(transformer.apply(input)).to eq({ users: [], groups: nil })
+    end
+
+    # Tests handling of non-hash values in reshape blocks
+    # This prevents errors when encountering unexpected data types
+    it "handles non-hash values in reshape" do
+      transformer = described_class.new do
+        reshape :config do
+          rename :api_key, to: :key
+        end
+      end
+
+      input = { config: "invalid" }
+      expect(transformer.apply(input)).to eq({ config: "invalid" })
+    end
+
+    # Tests handling of non-array values in map_collection
+    # This ensures graceful handling of unexpected data types in collections
+    it "handles non-array values in map_collection" do
+      transformer = described_class.new do
+        map_collection :users do
+          rename :username, to: :name
+        end
+      end
+
+      input = { users: "invalid" }
+      expect(transformer.apply(input)).to eq({ users: "invalid" })
+    end
+  end
+
+  # Complex chaining tests
+  # These tests verify the transformer's ability to handle complex, multi-step transformations
+  describe "complex chaining" do
+    # Tests combining multiple nested transformations with value modifications
+    # This is crucial for real-world scenarios where data needs multiple transformations
+    it "combines multiple nested transformations" do
+      transformer = described_class.new do
+        rename :metadata, to: :meta do |data|
+          { version: data[:version].to_i, updated_at: data[:timestamp] }
+        end
+
+        reshape :data do
+          map_collection :items do
+            rename :item_name, to: :name
+            map :price do |price|
+              price.to_f.round(2)
+            end
+            reshape :details do
+              rename :specs, to: :specifications
+              map :created_at, &:to_s
+            end
+          end
+
+          reshape :summary do
+            map :total_items, &:to_i
+            map :total_price do |price|
+              price.to_f.round(2)
+            end
+          end
+        end
+      end
+
+      input = {
+        metadata: { version: "2", timestamp: "2024-03-27" },
+        data: {
+          items: [
+            {
+              item_name: "Widget",
+              price: "19.99",
+              details: {
+                specs: "High quality",
+                created_at: Time.new(2024, 3, 27)
+              }
+            },
+            {
+              item_name: "Gadget",
+              price: "29.99",
+              details: {
+                specs: "Premium",
+                created_at: Time.new(2024, 3, 26)
+              }
+            }
+          ],
+          summary: {
+            total_items: "2",
+            total_price: "49.98"
+          }
+        }
+      }
+
+      expect(transformer.apply(input)).to eq({
+                                               meta: {
+                                                 version: 2,
+                                                 updated_at: "2024-03-27"
+                                               },
+                                               data: {
+                                                 items: [
+                                                   {
+                                                     name: "Widget",
+                                                     price: 19.99,
+                                                     details: {
+                                                       specifications: "High quality",
+                                                       created_at: "2024-03-27 00:00:00 +0000"
+                                                     }
+                                                   },
+                                                   {
+                                                     name: "Gadget",
+                                                     price: 29.99,
+                                                     details: {
+                                                       specifications: "Premium",
+                                                       created_at: "2024-03-26 00:00:00 +0000"
+                                                     }
+                                                   }
+                                                 ],
+                                                 summary: {
+                                                   total_items: 2,
+                                                   total_price: 49.98
+                                                 }
+                                               }
+                                             })
+    end
+  end
+
+  # Advanced transformation tests
+  # These tests verify complex data transformation scenarios
+  describe "advanced transformations" do
+    # Tests conditional transformations based on value content
+    # This is useful for mapping status strings to numeric codes or other representations
+    it "handles conditional transformations" do
+      transformer = described_class.new do
+        map :status do |status|
+          case status
+          when "active" then 1
+          when "pending" then 0
+          when "deleted" then -1
+          end
+        end
+      end
+
+      input = { status: "active" }
+      expect(transformer.apply(input)).to eq({ status: 1 })
+    end
+
+    # Tests converting array of key-value pairs to a hash
+    # This is common when dealing with tag-like structures or metadata
+    it "handles array to hash transformations" do
+      transformer = described_class.new do
+        map :tags do |tags|
+          tags.each_with_object({}) do |tag, hash|
+            hash[tag[:key].to_sym] = tag[:value]
+          end
+        end
+      end
+
+      input = {
+        tags: [
+          { key: "type", value: "user" },
+          { key: "role", value: "admin" }
+        ]
+      }
+      expect(transformer.apply(input)).to eq({
+                                               tags: { type: "user", role: "admin" }
+                                             })
+    end
+
+    # Tests converting hash to array of key-value pairs
+    # This is useful for flattening structures or preparing data for certain APIs
+    it "handles hash to array transformations" do
+      transformer = described_class.new do
+        map :metadata do |meta|
+          meta.map { |key, value| { name: key, value: value } }
+        end
+      end
+
+      input = {
+        metadata: { created_at: "2024-03-27", status: "active" }
+      }
+      expect(transformer.apply(input)).to eq({
+                                               metadata: [
+                                                 { name: :created_at, value: "2024-03-27" },
+                                                 { name: :status, value: "active" }
+                                               ]
+                                             })
+    end
+
+    # Tests complex data type conversions across multiple fields
+    # This is crucial for normalizing data types across a dataset
+    it "handles complex data type conversions" do
+      transformer = described_class.new do
+        map :dates do |dates|
+          dates.transform_values { |v| Time.strptime(v, "%Y-%m-%d %H:%M:%S") }
+        end
+        map :numbers do |nums|
+          nums.transform_values(&:to_f)
+        end
+        map :flags do |flags|
+          flags.transform_values { |v| v.to_s.downcase == "true" }
+        end
+      end
+
+      input = {
+        dates: { created: "2024-03-27 10:30:00", updated: "2024-03-28 15:45:00" },
+        numbers: { latitude: "40.7128", longitude: "-74.0060" },
+        flags: { active: "True", deleted: "FALSE", archived: "true" }
+      }
+
+      result = transformer.apply(input)
+      expect(result[:dates][:created]).to be_a(Time)
+      expect(result[:dates][:updated]).to be_a(Time)
+      expect(result[:numbers]).to eq({ latitude: 40.7128, longitude: -74.0060 })
+      expect(result[:flags]).to eq({ active: true, deleted: false, archived: true })
+    end
+  end
+
+  # Error handling tests
+  # These tests verify proper handling of error conditions and invalid data
+  describe "error handling" do
+    # Tests handling of exceptions in transformation blocks
+    # This ensures errors are properly propagated rather than silently ignored
+    it "handles exceptions in transformation blocks" do
+      transformer = described_class.new do
+        map :number do |n|
+          Integer(n)
+        end
+      end
+
+      input = { number: "not_a_number" }
+      expect { transformer.apply(input) }.to raise_error(ArgumentError)
+    end
+
+    # Tests handling of exceptions in deeply nested transformations
+    # This ensures errors are properly propagated through the transformation chain
+    it "handles deep nested exceptions" do
+      transformer = described_class.new do
+        reshape :user do
+          reshape :preferences do
+            map :settings do |s|
+              JSON.parse(s)
+            end
+          end
+        end
+      end
+
+      input = { user: { preferences: { settings: "invalid_json" } } }
+      expect { transformer.apply(input) }.to raise_error(JSON::ParserError)
+    end
+
+    # Tests handling of exceptions in collection transformations
+    # This ensures errors in array transformations are properly handled
+    it "handles exceptions in collection transformations" do
+      transformer = described_class.new do
+        map_collection :numbers do
+          map :value do |v|
+            Integer(v)
+          end
+        end
+      end
+
+      input = { numbers: [{ value: "1" }, { value: "invalid" }, { value: "3" }] }
+      expect { transformer.apply(input) }.to raise_error(ArgumentError)
+    end
+  end
+
+  # Recursive transformation tests
+  # These tests verify the transformer's ability to handle recursive data structures
+  describe "recursive transformations" do
+    # Tests transformation of recursive tree-like structures
+    # This is crucial for handling hierarchical data like file systems or organizational charts
+    it "handles recursive data structures" do
+      transformer = described_class.new do
+        reshape :node do
+          rename :label, to: :name
+          map :value, &:to_i
+          reshape :left do
+            rename :label, to: :name
+            map :value, &:to_i
+          end
+          reshape :right do
+            rename :label, to: :name
+            map :value, &:to_i
+          end
+        end
+      end
+
+      input = {
+        node: {
+          label: "root",
+          value: "1",
+          left: {
+            label: "left",
+            value: "2"
+          },
+          right: {
+            label: "right",
+            value: "3"
+          }
+        }
+      }
+
+      expect(transformer.apply(input)).to eq({
+                                               node: {
+                                                 name: "root",
+                                                 value: 1,
+                                                 left: {
+                                                   name: "left",
+                                                   value: 2
+                                                 },
+                                                 right: {
+                                                   name: "right",
+                                                   value: 3
+                                                 }
+                                               }
+                                             })
+    end
+
+    # Tests transformation of deeply nested collections
+    # This is important for handling complex hierarchical data with multiple levels of nesting
+    it "handles deeply nested collections" do
+      transformer = described_class.new do
+        map_collection :categories do
+          rename :category_name, to: :name
+          map_collection :subcategories do
+            rename :subcategory_name, to: :name
+            map_collection :items do
+              rename :item_name, to: :name
+              map :price, &:to_f
+              map_collection :variants do
+                rename :variant_name, to: :name
+                map :stock, &:to_i
+              end
+            end
+          end
+        end
+      end
+
+      input = {
+        categories: [
+          {
+            category_name: "Electronics",
+            subcategories: [
+              {
+                subcategory_name: "Phones",
+                items: [
+                  {
+                    item_name: "iPhone",
+                    price: "999.99",
+                    variants: [
+                      { variant_name: "Black", stock: "5" },
+                      { variant_name: "White", stock: "3" }
+                    ]
+                  }
+                ]
+              }
+            ]
+          }
+        ]
+      }
+
+      expect(transformer.apply(input)).to eq({
+                                               categories: [
+                                                 {
+                                                   name: "Electronics",
+                                                   subcategories: [
+                                                     {
+                                                       name: "Phones",
+                                                       items: [
+                                                         {
+                                                           name: "iPhone",
+                                                           price: 999.99,
+                                                           variants: [
+                                                             { name: "Black", stock: 5 },
+                                                             { name: "White", stock: 3 }
+                                                           ]
+                                                         }
+                                                       ]
+                                                     }
+                                                   ]
+                                                 }
+                                               ]
+                                             })
+    end
+  end
+
+  # Performance edge case tests
+  # These tests verify the transformer's behavior with large or complex data structures
+  describe "performance edge cases" do
+    # Tests handling of large arrays
+    # This ensures the transformer can handle collections of significant size
+    it "handles large arrays efficiently" do
+      transformer = described_class.new do
+        map_collection :numbers do
+          map :value, &:to_i
+        end
+      end
+
+      large_array = 1000.times.map { |i| { value: i.to_s } }
+      input = { numbers: large_array }
+      result = transformer.apply(input)
+
+      expect(result[:numbers].size).to eq(1000)
+      expect(result[:numbers].first).to eq({ value: 0 })
+      expect(result[:numbers].last).to eq({ value: 999 })
+    end
+
+    # Tests handling of deeply nested structures
+    # This ensures the transformer can handle complex hierarchical data efficiently
+    it "handles deeply nested structures efficiently" do
+      def create_nested_hash(depth)
+        return { value: "leaf" } if depth.zero?
+
+        {
+          value: depth.to_s,
+          left: create_nested_hash(depth - 1),
+          right: create_nested_hash(depth - 1)
+        }
+      end
+
+      transformer = described_class.new do
+        reshape :root do
+          map :value, &:upcase
+          reshape :left do
+            map :value, &:upcase
+            reshape :left do
+              map :value, &:upcase
+              reshape :left do
+                map :value, &:upcase
+              end
+              reshape :right do
+                map :value, &:upcase
+              end
+            end
+            reshape :right do
+              map :value, &:upcase
+              reshape :left do
+                map :value, &:upcase
+              end
+              reshape :right do
+                map :value, &:upcase
+              end
+            end
+          end
+          reshape :right do
+            map :value, &:upcase
+            reshape :left do
+              map :value, &:upcase
+              reshape :left do
+                map :value, &:upcase
+              end
+              reshape :right do
+                map :value, &:upcase
+              end
+            end
+            reshape :right do
+              map :value, &:upcase
+              reshape :left do
+                map :value, &:upcase
+              end
+              reshape :right do
+                map :value, &:upcase
+              end
+            end
+          end
+        end
+      end
+
+      input = { root: create_nested_hash(3) }
+      result = transformer.apply(input)
+
+      expect(result[:root][:value]).to eq("3")
+      expect(result[:root][:left][:value]).to eq("2")
+      expect(result[:root][:left][:left][:value]).to eq("1")
+      expect(result[:root][:left][:left][:left][:value]).to eq("LEAF")
+    end
+  end
+
+  # Transformer composition tests
+  # These tests verify the ability to combine multiple transformers
+  describe "composition" do
+    # Tests combining multiple transformers into a single transformation
+    # This is useful for building complex transformations from simpler components
+    it "allows transformer composition" do
+      described_class.new do
+        rename :full_name, to: :name do |name|
+          first, last = name.split
+          { first: first, last: last }
+        end
+      end
+
+      described_class.new do
+        reshape :address do
+          rename :postal_code, to: :postcode
+          map :coordinates do |coords|
+            lat, lng = coords.split(",")
+            { latitude: lat.to_f, longitude: lng.to_f }
+          end
+        end
+      end
+
+      combined_transformer = described_class.new do
+        rename :full_name, to: :name do |name|
+          first, last = name.split
+          { first: first, last: last }
+        end
+
+        reshape :address do
+          rename :postal_code, to: :postcode
+          map :coordinates do |coords|
+            lat, lng = coords.split(",")
+            { latitude: lat.to_f, longitude: lng.to_f }
+          end
+        end
+      end
+
+      input = {
+        full_name: "Dave Cooper",
+        address: {
+          street: "123 Main St",
+          postal_code: "12345",
+          coordinates: "40.7128,-74.0060"
+        }
+      }
+
+      expect(combined_transformer.apply(input)).to eq({
+                                                        name: { first: "Dave", last: "Cooper" },
+                                                        address: {
+                                                          street: "123 Main St",
+                                                          postcode: "12345",
+                                                          coordinates: { latitude: 40.7128, longitude: -74.0060 }
+                                                        }
+                                                      })
+    end
+  end
+
+  describe "advanced data structures" do
+    it "handles cyclic references gracefully" do
+      transformer = described_class.new do
+        reshape :organization do
+          rename :name, to: :org_name
+          map_collection :employees do
+            rename :name, to: :employee_name
+            map :manager_id, &:to_i
+          end
+          map :relationships do |rels|
+            # Convert manager-employee relationships to a graph structure
+            rels.each_with_object({ managers: {}, employees: {} }) do |(mgr_id, emp_ids), acc|
+              acc[:managers][mgr_id.to_i] = emp_ids.map(&:to_i)
+              emp_ids.each do |emp_id|
+                acc[:employees][emp_id.to_i] = mgr_id.to_i
+              end
+            end
+          end
+        end
+      end
+
+      input = {
+        organization: {
+          name: "Tech Corp",
+          employees: [
+            { name: "Alice", id: "1", manager_id: "0" },
+            { name: "Bob", id: "2", manager_id: "1" },
+            { name: "Charlie", id: "3", manager_id: "1" }
+          ],
+          relationships: {
+            "0" => ["1"],
+            "1" => %w[2 3]
+          }
+        }
+      }
+
+      expect(transformer.apply(input)).to eq({
+                                               organization: {
+                                                 org_name: "Tech Corp",
+                                                 employees: [
+                                                   { employee_name: "Alice", id: "1", manager_id: 0 },
+                                                   { employee_name: "Bob", id: "2", manager_id: 1 },
+                                                   { employee_name: "Charlie", id: "3", manager_id: 1 }
+                                                 ],
+                                                 relationships: {
+                                                   managers: { 0 => [1], 1 => [2, 3] },
+                                                   employees: { 1 => 0, 2 => 1, 3 => 1 }
+                                                 }
+                                               }
+                                             })
+    end
+
+    it "handles complex data validation and transformation" do
+      transformer = described_class.new do
+        reshape :user do
+          map :email do |email|
+            raise ArgumentError, "Invalid email" unless email =~ /\A[\w+\-.]+@[a-z\d-]+(\.[a-z\d-]+)*\.[a-z]+\z/i
+
+            { address: email, domain: email.split("@").last }
+          end
+
+          map :password do |pass|
+            # Hash the password and store validation rules
+            {
+              hashed: Digest::SHA256.hexdigest(pass),
+              validation: {
+                length: pass.length >= 8,
+                uppercase: pass.match?(/[A-Z]/),
+                lowercase: pass.match?(/[a-z]/),
+                number: pass.match?(/\d/),
+                special: pass.match?(/[!@#$%^&*]/)
+              }
+            }
+          end
+
+          map :preferences do |prefs|
+            # Parse and validate JSON preferences
+            parsed = JSON.parse(prefs)
+            {
+              theme: parsed["theme"] || "default",
+              notifications: parsed["notifications"].transform_keys(&:to_sym),
+              data_sharing: parsed["data_sharing"].transform_keys(&:to_sym).transform_values { |v| v == "enabled" }
+            }
+          end
+
+          map :profile_image do |image|
+            # Handle base64 encoded image with metadata
+            metadata, base64_data = image.split(",", 2)
+            mime_type = metadata.match(/data:(.*);base64/)[1]
+
+            {
+              mime_type: mime_type,
+              size: Base64.decode64(base64_data).size,
+              data: "#{base64_data.slice(0, 32)}..." # Truncate for display
+            }
+          end
+        end
+      end
+
+      input = {
+        user: {
+          email: "user@example.com",
+          password: "SecureP@ss123",
+          preferences: '{"theme":"dark","notifications":{"email":"daily","sms":"never"},"data_sharing":{"analytics":"enabled","marketing":"disabled"}}',
+          profile_image: "data:image/jpeg;base64,/9j/4AAQSkZJRg..."
+        }
+      }
+
+      result = transformer.apply(input)
+      expect(result[:user][:email]).to eq({ address: "user@example.com", domain: "example.com" })
+      expect(result[:user][:password][:validation]).to eq({
+                                                            length: true,
+                                                            uppercase: true,
+                                                            lowercase: true,
+                                                            number: true,
+                                                            special: true
+                                                          })
+      expect(result[:user][:preferences]).to eq({
+                                                  theme: "dark",
+                                                  notifications: { email: "daily", sms: "never" },
+                                                  data_sharing: { analytics: true, marketing: false }
+                                                })
+      expect(result[:user][:profile_image][:mime_type]).to eq("image/jpeg")
+    end
+
+    it "handles complex state machines and workflows" do
+      transformer = described_class.new do
+        reshape :workflow do
+          map :states do |states|
+            states.transform_values do |state|
+              {
+                current: state["current"],
+                history: state["history"].map do |h|
+                  { status: h["status"], timestamp: Time.strptime(h["timestamp"], "%Y-%m-%d %H:%M:%S") }
+                end,
+                metrics: {
+                  time_in_state: state["history"].each_cons(2).sum do |a, b|
+                    Time.strptime(b["timestamp"], "%Y-%m-%d %H:%M:%S") -
+                      Time.strptime(a["timestamp"], "%Y-%m-%d %H:%M:%S")
+                  end,
+                  transitions: state["history"].size - 1
+                },
+                allowed_transitions: state["transitions"].map(&:to_sym)
+              }
+            end
+          end
+
+          map :transitions do |trans|
+            trans.group_by { |t| t["from"] }.transform_values do |steps|
+              steps.map { |s| { to: s["to"], conditions: s["conditions"].map(&:to_sym) } }
+            end
+          end
+
+          map :validations do |vals|
+            vals.transform_values do |rules|
+              rules.map do |rule|
+                {
+                  check: rule["check"].to_sym,
+                  message: rule["message"],
+                  severity: rule["severity"].to_sym
+                }
+              end
+            end
+          end
+        end
+      end
+
+      input = {
+        workflow: {
+          states: {
+            "draft" => {
+              "current" => true,
+              "history" => [
+                { "status" => "created", "timestamp" => "2024-03-27 09:00:00" },
+                { "status" => "draft", "timestamp" => "2024-03-27 09:15:00" }
+              ],
+              "transitions" => %w[review publish]
+            }
+          },
+          transitions: [
+            { "from" => "draft", "to" => "review", "conditions" => %w[complete valid] },
+            { "from" => "draft", "to" => "publish", "conditions" => %w[complete valid approved] }
+          ],
+          validations: {
+            "draft" => [
+              { "check" => "title_present", "message" => "Title is required", "severity" => "error" },
+              { "check" => "content_length", "message" => "Content too short", "severity" => "warning" }
+            ]
+          }
+        }
+      }
+
+      result = transformer.apply(input)
+      expect(result[:workflow][:states]["draft"]).to include(
+        current: true,
+        allowed_transitions: %i[review publish]
+      )
+      expect(result[:workflow][:states]["draft"][:metrics]).to include(
+        time_in_state: 900, # 15 minutes in seconds
+        transitions: 1
+      )
+      expect(result[:workflow][:transitions]["draft"]).to eq([
+                                                               { to: "review", conditions: %i[complete valid] },
+                                                               { to: "publish",
+                                                                 conditions: %i[complete valid approved] }
+                                                             ])
+      expect(result[:workflow][:validations]["draft"]).to eq([
+                                                               { check: :title_present, message: "Title is required",
+                                                                 severity: :error },
+                                                               { check: :content_length, message: "Content too short",
+                                                                 severity: :warning }
+                                                             ])
+    end
+  end
+end
diff --git a/spec/morphix_spec.rb b/spec/morphix_spec.rb
index e04a0d5..b497341 100644
--- a/spec/morphix_spec.rb
+++ b/spec/morphix_spec.rb
@@ -5,7 +5,14 @@
     expect(Morphix::VERSION).not_to be nil
   end
 
-  it "does something useful" do
-    expect(false).to eq(true)
+  it "creates a transformer with the DSL" do
+    transformer = Morphix.define do
+      rename :old_name, to: :new_name
+    end
+
+    input = { old_name: "test" }
+    result = transformer.apply(input)
+
+    expect(result).to eq({ new_name: "test" })
   end
 end
diff --git a/spec/spec_helper.rb b/spec/spec_helper.rb
index e8b1fd6..47ecb04 100644
--- a/spec/spec_helper.rb
+++ b/spec/spec_helper.rb
@@ -3,13 +3,21 @@
 require "morphix"
 
 RSpec.configure do |config|
-  # Enable flags like --only-failures and --next-failure
-  config.example_status_persistence_file_path = ".rspec_status"
+  config.expect_with :rspec do |expectations|
+    expectations.include_chain_clauses_in_custom_matcher_descriptions = true
+  end
+
+  config.mock_with :rspec do |mocks|
+    mocks.verify_partial_doubles = true
+  end
 
-  # Disable RSpec exposing methods globally on `Module` and `main`
+  config.shared_context_metadata_behavior = :apply_to_host_groups
+  config.filter_run_when_matching :focus
+  config.example_status_persistence_file_path = "spec/examples.txt"
   config.disable_monkey_patching!
+  config.default_formatter = "doc" if config.files_to_run.one?
 
-  config.expect_with :rspec do |c|
-    c.syntax = :expect
-  end
+  config.profile_examples = 10
+  config.order = :random
+  Kernel.srand config.seed
 end