diff --git a/lib/opencode/rails/version.rb b/lib/opencode/rails/version.rb
index 3942eb8..c187188 100644
--- a/lib/opencode/rails/version.rb
+++ b/lib/opencode/rails/version.rb
@@ -1,7 +1,15 @@
 # frozen_string_literal: true
 
+# NOTE: we deliberately do NOT define `Opencode::Rails` as a module —
+# host applications often have files inside the `Opencode::` namespace
+# that reference top-level `::Rails.something`. Defining
+# `Opencode::Rails` would shadow `::Rails` under Ruby's constant
+# lookup rules (`Rails.root` would resolve to `Opencode::Rails.root`
+# and raise NoMethodError).
+#
+# The opencode-ruby gem uses `Opencode::VERSION` for its own version.
+# We can't reuse the same constant from a second gem, so we use a
+# distinct, non-namespaced constant.
 module Opencode
-  module Rails
-    VERSION = "0.0.1.alpha1"
-  end
+  RAILS_VERSION = "0.0.1.alpha1"
 end
diff --git a/opencode-rails.gemspec b/opencode-rails.gemspec
index e2a97d9..85acb43 100644
--- a/opencode-rails.gemspec
+++ b/opencode-rails.gemspec
@@ -4,7 +4,7 @@ require_relative "lib/opencode/rails/version"
 
 Gem::Specification.new do |spec|
   spec.name          = "opencode-rails"
-  spec.version       = Opencode::Rails::VERSION
+  spec.version       = Opencode::RAILS_VERSION
   spec.authors       = ["Ajay Krishnan"]
   spec.email         = ["ajay@krishnan.ca"]
 
diff --git a/test/opencode/loading_test.rb b/test/opencode/loading_test.rb
index 059f315..859d787 100644
--- a/test/opencode/loading_test.rb
+++ b/test/opencode/loading_test.rb
@@ -49,6 +49,16 @@ class Opencode::LoadingTest < Minitest::Test
   end
 
   def test_version_constant
-    assert_match(/\A\d+\.\d+\.\d+/, Opencode::Rails::VERSION)
+    assert_match(/\A\d+\.\d+\.\d+/, Opencode::RAILS_VERSION)
+  end
+
+  def test_no_opencode_rails_module
+    # Defining Opencode::Rails as a module would shadow ::Rails for any
+    # host code that references top-level Rails.* from inside the
+    # Opencode:: namespace (e.g. lib/opencode/containers/container.rb).
+    # Verify the namespace stays clean — version lives at
+    # Opencode::RAILS_VERSION, not Opencode::Rails::VERSION.
+    refute Opencode.const_defined?(:Rails),
+      "Opencode::Rails must not be defined — it would shadow ::Rails inside the Opencode namespace"
   end
 end