rails-ai-context 4.4.0 → 4.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6fa4865cb6081dbc1a243371d270db6f80304fd5c3d7ccd8052d2c7c0d672dc6
-  data.tar.gz: 055a0fc1462f6a698e004090fda64703e98478af1d8bd1ca3426d85a5e9b6f69
+  metadata.gz: 41d06a29e3165804283c9dcef76e2c1ee5625ef5ac236931fa492d76172062b6
+  data.tar.gz: 8f2f81c3186b2d16fa9c4ea2b84721fd519d437b4cbd8fb99a3978e45723a189
 SHA512:
-  metadata.gz: ac7a84cb7f54d6106c2bf33c94208f75871b9b8d25d304e0ddde0e36f73d3bd8e973dbf5f81b0665545548fd740fbdf60726a79195889cfbb9683cc733c80307
-  data.tar.gz: 440e13668f46d1578933bd5f053ea15cbae494938097f55380a0ab78c3a30a0f92dd74b20ad37edf7aed67f4aade37810e02b141e9d25e8963d40e3d63a650b9
+  metadata.gz: 94ee0d646375d50942d8d3ea186a3f5faea8795f1fee1588f63304a06ab283db79e8dd07a1460284279b9edeac9bc3604e9208b847dda6ef144f9d5e68c5df2b
+  data.tar.gz: 838c87226b6027f62aa045c3eebd2842f82434db0b6a9fa2f20234bde75a9e0f4d6407fe4d510e129c0e192141b15a75fec5c9d0d3620a2991c2860db7ad5e42

data/CHANGELOG.md

@@ -386,7 +386,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - **Phase 1 improvements** — scope definitions include lambda body, controller actions show instance variables + private methods called inline, Stimulus shows HTML data-attributes + reverse view lookup.
 - **3 new validation rules** — instance variable consistency (view uses @foo but controller never sets it), Turbo Stream channel matching (broadcast without subscriber), respond_to template existence.
 - **`rails_security_scan` tool** — Brakeman static security analysis via MCP. Detects SQL injection, XSS, mass assignment, and more. Optional dependency — returns install instructions if Brakeman isn't present. Supports file filtering, confidence levels (high/medium/weak), specific check selection, and three detail levels (summary/standard/full).
-- **`config.skip_tools`** — users can now exclude specific built-in tools: `config.skip_tools = %w[rails_security_scan]`. Defaults to empty (all 25 tools active).
+- **`config.skip_tools`** — users can now exclude specific built-in tools: `config.skip_tools = %w[rails_security_scan]`. Defaults to empty (all 39 tools active).
 - **Schema index hints** — `get_schema` standard detail now shows `[indexed]`/`[unique]` on columns, saving a round-trip to full detail.
 - **Enum backing types** — `get_model_details` now shows integer vs string backing: `status: pending(0), active(1) [integer]`.
 - **Search context lines default 2** — `search_code` now returns 2 lines of context by default (was 0). Eliminates follow-up calls for context.

data/CLAUDE.md

@@ -21,12 +21,12 @@ structure to AI assistants via the Model Context Protocol (MCP).
 - `lib/rails_ai_context/watcher.rb` — File watcher for auto-regenerating context files
 - `lib/rails_ai_context/engine.rb` — Rails Engine for auto-integration
 - `lib/generators/rails_ai_context/install/` — Install generator (creates .mcp.json, initializer, context files)
-- `exe/rails-ai-context` — Standalone Thor CLI (serve, context, inspect, watch, doctor, tool, version)
+- `exe/rails-ai-context` — Standalone Thor CLI (init, serve, context, inspect, watch, doctor, tool, version) — works without Gemfile entry via `gem install`
 
 ## Key Design Decisions
 
 1. **Built on official mcp SDK** — not a custom protocol implementation
-2. **Zero-config** — Railtie auto-registers at boot, introspects without setup
+2. **Sensible defaults** — works standalone (`gem install` + `rails-ai-context init`) or in-Gemfile with Railtie auto-registration
 3. **Graceful degradation** — works without DB by parsing schema.rb as text
 4. **Read-only tools only** — all MCP tools are annotated as non-destructive
 5. **Sensitive pattern blocking** — search/read tools reject `.env`, `*.key`, `*.pem` and other secret files via `sensitive_patterns`
@@ -58,6 +58,10 @@ structure to AI assistants via the Model Context Protocol (MCP).
 31. **Log reading** — reverse file tail with level filtering and sensitive data redaction
 32. **Config validation** — `http_port`, `cache_ttl`, `max_tool_response_chars`, `query_row_limit` validated on assignment with clear error messages
 33. **Sensitive column redaction** — query tool redacts columns by name AND by suffix pattern (password, secret, token, key, digest, hash) to prevent alias bypass
+34. **Standalone mode** — `gem install rails-ai-context && rails-ai-context init` works without Gemfile entry. CLI pre-loads gem before Rails boot, restores `$LOAD_PATH` entries stripped by `Bundler.setup`. Config from `.rails-ai-context.yml`.
+35. **YAML config** — `.rails-ai-context.yml` as alternative to initializer. Supports all config options except `custom_tools` (Ruby classes) and `excluded_concerns` (regex). Precedence: initializer > YAML > defaults.
+36. **Config auto-loading** — `Configuration.auto_load!` checks `configured_via_block?` flag. If initializer ran, YAML is skipped. Corrupted YAML degrades gracefully with a warning.
+37. **Three install paths** — In-Gemfile (`rails generate rails_ai_context:install`), Standalone (`rails-ai-context init`), Zero config (just run `rails-ai-context serve` with defaults). Users can switch between paths freely; `.mcp.json` command is updated on re-init/re-install.
 
 ## Testing
 

data/README.md

@@ -51,6 +51,15 @@ gem "rails-ai-context", group: :development
 rails generate rails_ai_context:install
 ```
 
+### Or standalone — no Gemfile needed
+
+```bash
+gem install rails-ai-context
+cd your-rails-app
+rails-ai-context init     # interactive setup
+rails-ai-context serve    # start MCP server
+```
+
 <div align="center">
 
 ![Install demo](demo.gif)
@@ -341,7 +350,7 @@ Every tool is **read-only** and returns structured, token-efficient context.
                          ▼
 ┌─────────────────────────────────────────────────────────┐
 │  rails-ai-context                                        │
-│  Parses everything. Caches results. Zero config.         │
+│  Parses everything. Caches results. Sensible defaults.    │
 └────────┬──────────────────┬──────────────┬──────────────┘
          │                  │              │
          ▼                  ▼              ▼
@@ -357,27 +366,35 @@ Every tool is **read-only** and returns structured, token-efficient context.
 
 ## Install
 
+**Option A — In Gemfile:**
+
 ```bash
 gem "rails-ai-context", group: :development
 rails generate rails_ai_context:install
 ```
 
-The installer asks which AI tools you use and whether you want MCP or CLI mode. That's it.
+**Option B — Standalone (no Gemfile entry needed):**
+
+```bash
+gem install rails-ai-context
+cd your-rails-app
+rails-ai-context init
+```
 
-`.mcp.json` is auto-detected by Claude Code and Cursor — no manual config.
+Both paths ask which AI tools you use and whether you want MCP or CLI mode. `.mcp.json` is auto-detected by Claude Code and Cursor.
 
 <br>
 
 ## Commands
 
-| Command | What it does |
-|:--------|:------------|
-| `rails ai:context` | Generate context files for your AI tools |
-| `rails 'ai:tool[NAME]'` | Run any of the 39 tools from CLI |
-| `rails ai:tool` | List all available tools |
-| `rails ai:serve` | Start MCP server (stdio) |
-| `rails ai:doctor` | Diagnostics + AI readiness score |
-| `rails ai:watch` | Auto-regenerate on file changes |
+| In-Gemfile | Standalone | What it does |
+|:-----------|:-----------|:------------|
+| `rails ai:context` | `rails-ai-context context` | Generate context files |
+| `rails 'ai:tool[NAME]'` | `rails-ai-context tool NAME` | Run any of the 39 tools |
+| `rails ai:tool` | `rails-ai-context tool --list` | List all available tools |
+| `rails ai:serve` | `rails-ai-context serve` | Start MCP server (stdio) |
+| `rails ai:doctor` | `rails-ai-context doctor` | Diagnostics + AI readiness score |
+| `rails ai:watch` | `rails-ai-context watch` | Auto-regenerate on file changes |
 
 <br>
 
@@ -427,7 +444,7 @@ end
 ## About
 
 Built by a Rails developer with 10+ years of production experience.<br>
-1529 tests. 39 tools. 33 introspectors. Zero config.<br>
+1529 tests. 39 tools. 33 introspectors. Standalone or in-Gemfile.<br>
 MIT licensed. [Contributions welcome.](CONTRIBUTING.md)
 
 <br>

data/docs/GUIDE.md

@@ -29,35 +29,35 @@
 
 ## Installation
 
-### New project
+### Option A: In Gemfile
 
 ```bash
-bundle add rails-ai-context
+gem "rails-ai-context", group: :development
+bundle install
 rails generate rails_ai_context:install
 rails ai:context
 ```
 
 This creates:
 1. `config/initializers/rails_ai_context.rb` — configuration file
-2. `.mcp.json` — MCP auto-discovery for Claude Code and Cursor
-3. 29 context files — tailored for each AI assistant
+2. `.rails-ai-context.yml` — standalone config (enables switching later)
+3. `.mcp.json` — MCP auto-discovery for Claude Code and Cursor
+4. Context files — tailored for each AI assistant
 
-### Existing project
+### Option B: Standalone (no Gemfile entry needed)
 
 ```bash
-# Add to Gemfile
-gem "rails-ai-context"
-
-# Install
-bundle install
-rails generate rails_ai_context:install
+gem install rails-ai-context
+cd your-rails-app
+rails-ai-context init
+```
 
-# Generate context files
-rails ai:context
+This creates:
+1. `.rails-ai-context.yml` — configuration file
+2. `.mcp.json` — MCP auto-discovery (if MCP mode selected)
+3. Context files — tailored for each AI assistant
 
-# Verify everything works
-rails ai:doctor
-```
+No Gemfile entry, no initializer, no files in your project besides config and context.
 
 ### What the install generator does
 
@@ -220,9 +220,10 @@ Commit **all files except `.ai-context.json`** (which is gitignored). This gives
 
 ### Standalone CLI
 
-The gem ships a `rails-ai-context` executable as an alternative to rake tasks. Useful for `.mcp.json` configs or when you prefer a shorter command.
+The gem ships a `rails-ai-context` executable that works **without adding the gem to your Gemfile**. Install globally with `gem install rails-ai-context`, then run from any Rails app directory.
 
 ```bash
+rails-ai-context init                      # Interactive setup (creates .rails-ai-context.yml + .mcp.json)
 rails-ai-context serve                     # Start MCP server (stdio)
 rails-ai-context serve --transport http    # Start MCP server (HTTP, port 6029)
 rails-ai-context serve --transport http --port 8080  # Custom port
@@ -241,6 +242,8 @@ rails-ai-context help                      # Show all commands
 
 Must be run from your Rails app root directory (requires `config/environment.rb`).
 
+**Config:** Standalone mode reads from `.rails-ai-context.yml` (created by `init`). If no config file exists, defaults are used. If the gem is also in the Gemfile, the initializer takes precedence over the YAML file.
+
 ### Legacy command
 
 ```bash
@@ -1042,8 +1045,9 @@ curl "https://registry.modelcontextprotocol.io/v0.1/servers?search=rails-ai-cont
 
 ### Auto-discovery (recommended)
 
-The install generator creates `.mcp.json` in your project root:
+The install generator (or `rails-ai-context init`) creates `.mcp.json` in your project root:
 
+**In-Gemfile:**
 ```json
 {
   "mcpServers": {
@@ -1055,6 +1059,18 @@ The install generator creates `.mcp.json` in your project root:
 }
 ```
 
+**Standalone:**
+```json
+{
+  "mcpServers": {
+    "rails-ai-context": {
+      "command": "rails-ai-context",
+      "args": ["serve"]
+    }
+  }
+}
+```
+
 **Claude Code** and **Cursor** auto-detect this file. No manual config needed — just open your project.
 
 ### Claude Code
@@ -1062,7 +1078,11 @@ The install generator creates `.mcp.json` in your project root:
 Auto-discovered via `.mcp.json`. Or add manually:
 
 ```bash
+# In-Gemfile
 claude mcp add rails-ai-context -- bundle exec rails ai:serve
+
+# Standalone
+claude mcp add rails-ai-context -- rails-ai-context serve
 ```
 
 ### Claude Desktop
@@ -1081,6 +1101,8 @@ Add to `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS)
 }
 ```
 
+Or for standalone: replace `"command": "bundle"` / `"args": ["exec", "rails", "ai:serve"]` with `"command": "rails-ai-context"` / `"args": ["serve"]`.
+
 ### Cursor
 
 Auto-discovered via `.mcp.json`. Or add manually in **Cursor Settings > MCP**:
@@ -1097,6 +1119,9 @@ Auto-discovered via `.mcp.json`. Or add manually in **Cursor Settings > MCP**:
 }
 ```
 
+For standalone: use `"command": "rails-ai-context"` / `"args": ["serve"]` instead.
+```
+
 ### HTTP transport
 
 For browser-based or remote AI clients:
@@ -1407,6 +1432,19 @@ config.introspectors = %i[schema models routes gems auth api]
 }
 ```
 
+For standalone: use `"command": ["rails-ai-context", "serve"]` instead.
+
+```json
+{
+  "mcp": {
+    "rails-ai-context": {
+      "type": "local",
+      "command": ["rails-ai-context", "serve"]
+    }
+  }
+}
+```
+
 **Context files loaded:**
 - `AGENTS.md` — project overview + MCP tool guide, read at conversation start
 - `app/models/AGENTS.md` — model listing, auto-loaded when agent reads model files

data/exe/rails-ai-context

@@ -2,43 +2,39 @@
 # frozen_string_literal: true
 
 require "thor"
+require "yaml"
 
-module RailsAiContext
-  class CLI < Thor
+# Top-level class to avoid conflict with RailsAiContext::CLI module (which contains ToolRunner).
+# The library uses RailsAiContext::CLI as a module namespace; this exe needs a class for Thor.
+class RailsAiContextCLI < Thor
     # Let Thor pass unknown options through to ToolRunner for the tool command
     stop_on_unknown_option! :tool
 
-    desc "tool [NAME]", "Run an MCP tool (25 available). Use --list to see all."
+    desc "tool [NAME]", "Run an MCP tool (39 available). Use --list to see all."
     option :json, type: :boolean, default: false, desc: "Output as JSON envelope"
     option :list, type: :boolean, default: false, desc: "List available tools"
     def tool(name = nil, *args)
       if options[:list] || name.nil?
         boot_rails!
-        require "rails_ai_context"
-        puts RailsAiContext::CLI::ToolRunner.tool_list
+        puts ::RailsAiContext::CLI::ToolRunner.tool_list
         return
       end
 
       boot_rails!
-      require "rails_ai_context"
 
       if args.include?("--help") || args.include?("-h")
-        tool_class = RailsAiContext::CLI::ToolRunner.new(name, []).tool_class
-        puts RailsAiContext::CLI::ToolRunner.tool_help(tool_class)
+        tool_class = ::RailsAiContext::CLI::ToolRunner.new(name, []).tool_class
+        puts ::RailsAiContext::CLI::ToolRunner.tool_help(tool_class)
         return
       end
 
-      runner = RailsAiContext::CLI::ToolRunner.new(name, args, json_mode: options[:json])
+      runner = ::RailsAiContext::CLI::ToolRunner.new(name, args, json_mode: options[:json])
       puts runner.run
-    rescue RailsAiContext::CLI::ToolRunner::ToolNotFoundError => e
-      $stderr.puts "Error: #{e.message}"
-      exit 1
-    rescue RailsAiContext::CLI::ToolRunner::InvalidArgumentError => e
-      $stderr.puts "Error: #{e.message}"
-      exit 3
+    rescue SystemExit
+      raise # let exit() propagate (from boot_rails!)
     rescue => e
       $stderr.puts "Error: #{e.message}"
-      exit 2
+      exit 1
     end
 
     desc "serve", "Start MCP server (stdio transport)"
@@ -46,53 +42,70 @@ module RailsAiContext
     option :port, type: :numeric, default: 6029, desc: "HTTP port (only for http transport)"
     def serve
       boot_rails!
-      require "rails_ai_context"
 
       transport = options[:transport].to_sym
       if transport == :http
-        RailsAiContext.configuration.http_port = options[:port]
+        ::RailsAiContext.configuration.http_port = options[:port]
       end
 
-      RailsAiContext.start_mcp_server(transport: transport)
+      ::RailsAiContext.start_mcp_server(transport: transport)
+    rescue SystemExit
+      raise
+    rescue => e
+      $stderr.puts "Error: #{e.message}"
+      exit 1
     end
 
     desc "context", "Generate AI context files"
-    option :format, type: :string, default: "all", desc: "Format: claude, cursor, copilot, json, all"
+    option :format, type: :string, default: nil, desc: "Format: claude, cursor, copilot, json, all (default: from config)"
     def context
       boot_rails!
-      require "rails_ai_context"
 
-      format = options[:format].to_sym
       $stderr.puts "Introspecting Rails app..."
-      result = RailsAiContext.generate_context(format: format)
-      result[:written].each { |f| $stderr.puts "  Written: #{f}" }
-      result[:skipped].each { |f| $stderr.puts "  Skipped: #{f} (unchanged)" }
+
+      if options[:format]
+        # Explicit --format flag overrides config
+        result = ::RailsAiContext.generate_context(format: options[:format].to_sym)
+        print_context_result(result)
+      else
+        # Use ai_tools from config (.rails-ai-context.yml or initializer)
+        ai_tools = ::RailsAiContext.configuration.ai_tools
+        if ai_tools.nil? || ai_tools.empty?
+          result = ::RailsAiContext.generate_context(format: :all)
+          print_context_result(result)
+        else
+          ai_tools.each do |fmt|
+            result = ::RailsAiContext.generate_context(format: fmt)
+            print_context_result(result)
+          end
+        end
+      end
+    rescue SystemExit
+      raise
+    rescue => e
+      $stderr.puts "Error: #{e.message}"
+      exit 1
     end
 
     desc "inspect", "Print introspection summary"
     def inspect_app
       boot_rails!
-      require "rails_ai_context"
       require "json"
 
-      context = RailsAiContext.introspect
+      context = ::RailsAiContext.introspect
       puts JSON.pretty_generate(context)
     end
 
     desc "watch", "Watch for changes and auto-regenerate context files"
     def watch
       boot_rails!
-      require "rails_ai_context"
-
-      RailsAiContext::Watcher.new.start
+      ::RailsAiContext::Watcher.new.start
     end
 
     desc "doctor", "Run diagnostic checks and report AI readiness score"
     def doctor
       boot_rails!
-      require "rails_ai_context"
-
-      result = RailsAiContext::Doctor.new.run
+      result = ::RailsAiContext::Doctor.new.run
       result[:checks].each do |check|
         icon = case check.status
         when :pass then "PASS"
@@ -106,6 +119,49 @@ module RailsAiContext
       $stderr.puts "AI Readiness Score: #{result[:score]}/100"
     end
 
+    desc "init", "Set up rails-ai-context for standalone use (creates .rails-ai-context.yml and .mcp.json)"
+    def init
+      config_path = File.join(Dir.pwd, "config", "environment.rb")
+      unless File.exist?(config_path)
+        $stderr.puts "Error: No Rails app found in #{Dir.pwd}"
+        $stderr.puts "Run this command from your Rails app root directory."
+        exit 1
+      end
+
+      # --- Read previous selection (before prompts) ---
+      previous_tools = read_previous_ai_tools
+
+      # --- Prompts (no Rails needed) ---
+      ai_tools = prompt_ai_tools
+      tool_mode = prompt_tool_mode
+
+      # --- Cleanup removed tools ---
+      cleanup_removed_tools(previous_tools, ai_tools) if previous_tools&.any?
+
+      # --- Write .rails-ai-context.yml ---
+      write_yaml_config(ai_tools, tool_mode)
+
+      # --- Write .mcp.json (MCP mode only) ---
+      write_standalone_mcp_json if tool_mode == :mcp
+
+      # --- Add .ai-context.json to .gitignore ---
+      add_to_gitignore
+
+      # --- Boot Rails, load config, generate context ---
+      boot_rails!
+
+      $stderr.puts ""
+      $stderr.puts "Generating AI context files..."
+      ai_tools.each do |fmt|
+        result = ::RailsAiContext.generate_context(format: fmt)
+        (result[:written] || []).each { |f| $stderr.puts "  Written: #{f}" }
+        (result[:skipped] || []).each { |f| $stderr.puts "  Skipped: #{f} (unchanged)" }
+      end
+
+      # --- Instructions ---
+      show_standalone_instructions(ai_tools, tool_mode)
+    end
+
     desc "version", "Print version"
     def version
       require_relative "../lib/rails_ai_context/version"
@@ -114,18 +170,234 @@ module RailsAiContext
 
     private
 
+    AI_TOOL_OPTIONS = {
+      "1" => { key: :claude,   name: "Claude Code",    files: "CLAUDE.md + .claude/rules/" },
+      "2" => { key: :cursor,   name: "Cursor",         files: ".cursor/rules/" },
+      "3" => { key: :copilot,  name: "GitHub Copilot", files: ".github/copilot-instructions.md + .github/instructions/" },
+      "4" => { key: :opencode, name: "OpenCode",       files: "AGENTS.md" }
+    }.freeze
+
+    def prompt_ai_tools
+      $stderr.puts ""
+      $stderr.puts "Which AI tools do you use? (select all that apply)"
+      $stderr.puts ""
+      AI_TOOL_OPTIONS.each { |num, info| $stderr.puts "  #{num}. #{info[:name].ljust(16)} -> #{info[:files]}" }
+      $stderr.puts "  a. All of the above"
+      $stderr.puts ""
+      $stderr.print "Enter numbers separated by commas (e.g. 1,2) or 'a' for all: "
+      input = $stdin.gets&.strip&.downcase || "a"
+
+      selected = if input == "a" || input == "all" || input.empty?
+        AI_TOOL_OPTIONS.values.map { |t| t[:key] }
+      else
+        input.split(/[\s,]+/).filter_map { |n| AI_TOOL_OPTIONS[n]&.dig(:key) }
+      end
+
+      if selected.empty?
+        $stderr.puts "No tools selected — using all."
+        selected = AI_TOOL_OPTIONS.values.map { |t| t[:key] }
+      end
+
+      names = AI_TOOL_OPTIONS.values.select { |t| selected.include?(t[:key]) }.map { |t| t[:name] }
+      $stderr.puts "Selected: #{names.join(', ')}"
+      selected
+    end
+
+    def prompt_tool_mode
+      $stderr.puts ""
+      $stderr.puts "Do you also want MCP server support?"
+      $stderr.puts ""
+      $stderr.puts "  1. Yes — MCP server (generates .mcp.json)"
+      $stderr.puts "  2. No  — CLI only (no server needed)"
+      $stderr.puts ""
+      $stderr.print "Enter number (default: 1): "
+      input = $stdin.gets&.strip || "1"
+
+      mode = input == "2" ? :cli : :mcp
+      label = mode == :mcp ? "MCP server" : "CLI only"
+      $stderr.puts "Selected: #{label}"
+      mode
+    end
+
+    # Files/dirs generated per AI tool format — used for cleanup on tool removal
+    FORMAT_PATHS = {
+      claude:   %w[CLAUDE.md .claude/rules],
+      cursor:   %w[.cursor/rules],
+      copilot:  %w[.github/copilot-instructions.md .github/instructions],
+      opencode: %w[AGENTS.md app/models/AGENTS.md app/controllers/AGENTS.md]
+    }.freeze
+
+    def read_previous_ai_tools
+      yaml_path = File.join(Dir.pwd, ".rails-ai-context.yml")
+      return nil unless File.exist?(yaml_path)
+
+      data = YAML.safe_load_file(yaml_path, permitted_classes: [ Symbol ]) || {}
+      tools = data["ai_tools"]
+      return nil unless tools.is_a?(Array) && tools.any?
+
+      tools.map(&:to_sym)
+    rescue => e
+      $stderr.puts "[rails-ai-context] Could not read previous config: #{e.message}" if ENV["DEBUG"]
+      nil
+    end
+
+    def cleanup_removed_tools(previous, current)
+      removed = previous.map(&:to_sym) - current.map(&:to_sym)
+      return if removed.empty?
+
+      $stderr.puts ""
+      $stderr.puts "These AI tools were removed from your selection:"
+      removed.each_with_index do |fmt, idx|
+        tool = AI_TOOL_OPTIONS.values.find { |t| t[:key] == fmt }
+        $stderr.puts "  #{idx + 1}. #{tool[:name]} (#{tool[:files]})" if tool
+      end
+      $stderr.puts ""
+      $stderr.puts "Remove their generated files?"
+      $stderr.puts "  y — remove all listed above"
+      $stderr.puts "  n — keep all (default)"
+      $stderr.puts "  1,2 — remove only specific ones by number"
+      $stderr.puts ""
+      $stderr.print "Enter choice: "
+      input = $stdin.gets&.strip&.downcase || "n"
+      return if input.empty? || input == "n" || input == "no"
+
+      to_remove = if input == "y" || input == "yes" || input == "a"
+        removed
+      else
+        nums = input.split(/[\s,]+/).filter_map { |n| n.to_i - 1 }
+        nums.filter_map { |i| removed[i] if i >= 0 && i < removed.size }
+      end
+
+      return if to_remove.empty?
+
+      require "fileutils"
+      to_remove.each do |fmt|
+        tool = AI_TOOL_OPTIONS.values.find { |t| t[:key] == fmt }
+        paths = FORMAT_PATHS[fmt] || []
+        paths.each do |rel_path|
+          full = File.join(Dir.pwd, rel_path)
+          if File.directory?(full)
+            FileUtils.rm_rf(full)
+            $stderr.puts "  Removed #{rel_path}/"
+          elsif File.exist?(full)
+            FileUtils.rm_f(full)
+            $stderr.puts "  Removed #{rel_path}"
+          end
+        end
+        $stderr.puts "  #{tool[:name]} files removed" if tool
+      end
+    end
+
+    def add_to_gitignore
+      gitignore = File.join(Dir.pwd, ".gitignore")
+      return unless File.exist?(gitignore)
+
+      content = File.read(gitignore)
+      return if content.include?(".ai-context.json")
+
+      File.open(gitignore, "a") do |f|
+        f.puts ""
+        f.puts "# rails-ai-context (JSON cache — markdown files should be committed)"
+        f.puts ".ai-context.json"
+      end
+      $stderr.puts "Updated .gitignore"
+    end
+
+    def write_yaml_config(ai_tools, tool_mode)
+      yaml_path = File.join(Dir.pwd, ".rails-ai-context.yml")
+      content = {
+        "ai_tools" => ai_tools.map(&:to_s),
+        "tool_mode" => tool_mode.to_s
+      }
+      File.write(yaml_path, YAML.dump(content))
+      $stderr.puts "Created .rails-ai-context.yml"
+    end
+
+    def write_standalone_mcp_json
+      require "json"
+      mcp_path = File.join(Dir.pwd, ".mcp.json")
+      server_entry = { "command" => "rails-ai-context", "args" => [ "serve" ] }
+
+      if File.exist?(mcp_path)
+        existing = JSON.parse(File.read(mcp_path)) rescue {}
+        existing["mcpServers"] ||= {}
+        if existing["mcpServers"]["rails-ai-context"] == server_entry
+          $stderr.puts ".mcp.json already up to date — skipped"
+        else
+          existing["mcpServers"]["rails-ai-context"] = server_entry
+          File.write(mcp_path, JSON.pretty_generate(existing) + "\n")
+          $stderr.puts "Updated rails-ai-context in .mcp.json"
+        end
+      else
+        content = JSON.pretty_generate({ mcpServers: { "rails-ai-context" => server_entry } }) + "\n"
+        File.write(mcp_path, content)
+        $stderr.puts "Created .mcp.json (auto-discovered by Claude Code, Cursor, etc.)"
+      end
+    end
+
+    def show_standalone_instructions(ai_tools, tool_mode)
+      $stderr.puts ""
+      $stderr.puts "=" * 50
+      $stderr.puts " rails-ai-context initialized!"
+      $stderr.puts "=" * 50
+      $stderr.puts ""
+      $stderr.puts "Your setup:"
+      AI_TOOL_OPTIONS.each_value do |info|
+        next unless ai_tools.include?(info[:key])
+        $stderr.puts "  #{info[:name].ljust(16)} -> #{info[:files]}"
+      end
+      $stderr.puts ""
+      $stderr.puts "Commands:"
+      $stderr.puts "  rails-ai-context context    # Regenerate context files"
+      $stderr.puts "  rails-ai-context tool NAME  # Run any of the 39 tools"
+      if tool_mode == :mcp
+        $stderr.puts "  rails-ai-context serve      # Start MCP server"
+      end
+      $stderr.puts "  rails-ai-context doctor     # Check AI readiness"
+      $stderr.puts ""
+      if tool_mode == :mcp
+        $stderr.puts "MCP auto-discovery:"
+        $stderr.puts "  .mcp.json is auto-detected by Claude Code and Cursor."
+        $stderr.puts "  No manual config needed — just open your project."
+      else
+        $stderr.puts "CLI tools:"
+        $stderr.puts "  AI agents can run `rails-ai-context tool schema table=users` directly."
+      end
+      $stderr.puts ""
+      $stderr.puts "Config: .rails-ai-context.yml (edit anytime, no restart needed)"
+      $stderr.puts ""
+    end
+
+    def print_context_result(result)
+      (result[:written] || []).each { |f| $stderr.puts "  Written: #{f}" }
+      (result[:skipped] || []).each { |f| $stderr.puts "  Skipped: #{f} (unchanged)" }
+    end
+
     def boot_rails!
-      # Try to find and boot the Rails app
       config_path = File.join(Dir.pwd, "config", "environment.rb")
-      if File.exist?(config_path)
-        require config_path
-      else
+      unless File.exist?(config_path)
         $stderr.puts "Error: No Rails app found in #{Dir.pwd}"
         $stderr.puts "Run this command from your Rails app root directory."
         exit 1
       end
+
+      # Load gem + dependencies BEFORE Rails boot.
+      # Bundler.setup (in config/boot.rb) strips $LOAD_PATH to Gemfile-only gems.
+      # In standalone mode (gem not in Gemfile), this would remove our gem and mcp.
+      # Loading first ensures Zeitwerk's autoload paths (absolute, not $LOAD_PATH-
+      # dependent) are configured, and we can restore stripped paths after boot.
+      require "mcp"
+      require "rails_ai_context"
+      pre_boot_paths = $LOAD_PATH.dup
+
+      require config_path
+
+      # Restore dependency paths that Bundler.setup stripped (standalone mode).
+      # For Gemfile users, this is a no-op — no paths were removed.
+      (pre_boot_paths - $LOAD_PATH).each { |p| $LOAD_PATH << p }
+
+      RailsAiContext::Configuration.auto_load!
     end
-  end
 end
 
-RailsAiContext::CLI.start(ARGV)
+RailsAiContextCLI.start(ARGV)

data/lib/generators/rails_ai_context/install/install_generator.rb

@@ -138,12 +138,13 @@ module RailsAiContext
           existing = JSON.parse(File.read(mcp_path)) rescue {}
           existing["mcpServers"] ||= {}
 
-          if existing["mcpServers"]["rails-ai-context"]
-            say ".mcp.json already has rails-ai-context — skipped", :yellow
+          if existing["mcpServers"]["rails-ai-context"] == server_entry
+            say ".mcp.json already up to date — skipped", :yellow
           else
             existing["mcpServers"]["rails-ai-context"] = server_entry
             File.write(mcp_path, JSON.pretty_generate(existing) + "\n")
-            say "Added rails-ai-context to existing .mcp.json", :green
+            verb = existing["mcpServers"].key?("rails-ai-context") ? "Updated" : "Added"
+            say "#{verb} rails-ai-context in .mcp.json", :green
           end
         else
           create_file ".mcp.json", JSON.pretty_generate({
@@ -383,6 +384,18 @@ module RailsAiContext
       end
       end # no_tasks
 
+      def create_yaml_config
+        yaml_path = Rails.root.join(".rails-ai-context.yml")
+        content = {
+          "ai_tools" => @selected_formats.map(&:to_s),
+          "tool_mode" => @tool_mode.to_s
+        }
+
+        require "yaml"
+        File.write(yaml_path, YAML.dump(content))
+        say "Created .rails-ai-context.yml (standalone config)", :green
+      end
+
       def add_to_gitignore
         gitignore = Rails.root.join(".gitignore")
         return unless File.exist?(gitignore)
@@ -459,6 +472,11 @@ module RailsAiContext
         say "  rails ai:context:copilot  # Generate for Copilot"
         say "  rails generate rails_ai_context:install  # Re-run to pick tools"
         say ""
+        say "Standalone (no Gemfile needed):", :yellow
+        say "  gem install rails-ai-context"
+        say "  rails-ai-context init          # interactive setup"
+        say "  rails-ai-context serve         # start MCP server"
+        say ""
         say "Commit context files and .mcp.json so your team benefits!", :green
       end
     end

data/lib/rails_ai_context/configuration.rb

@@ -1,7 +1,73 @@
 # frozen_string_literal: true
 
+require "yaml"
+
 module RailsAiContext
   class Configuration
+    CONFIG_FILENAME = ".rails-ai-context.yml"
+
+    # Keys that require symbol conversion (string → symbol or array of symbols)
+    SYMBOL_KEYS = %i[tool_mode preset context_mode live_reload].freeze
+    SYMBOL_ARRAY_KEYS = %i[ai_tools introspectors].freeze
+
+    # All YAML-supported keys (explicit allowlist for safety)
+    YAML_KEYS = %i[
+      ai_tools tool_mode preset context_mode generate_root_files claude_max_lines
+      server_name server_version cache_ttl max_tool_response_chars
+      live_reload live_reload_debounce auto_mount http_path http_bind http_port
+      output_dir skip_tools excluded_models excluded_controllers
+      excluded_route_prefixes excluded_filters excluded_middleware excluded_paths
+      sensitive_patterns search_extensions concern_paths frontend_paths mobile_paths
+      max_file_size max_test_file_size max_schema_file_size max_view_total_size
+      max_view_file_size max_search_results max_validate_files
+      query_timeout query_row_limit query_redacted_columns allow_query_in_production
+      log_lines introspectors
+    ].freeze
+
+    # Load configuration from a YAML file, applying values to the current config instance.
+    # Only keys present in the YAML are set; absent keys keep their defaults.
+    def self.load_from_yaml(path)
+      return unless File.exist?(path)
+
+      data = YAML.safe_load_file(path, permitted_classes: [ Symbol ]) || {}
+      config = RailsAiContext.configuration
+
+      data.each do |key, value|
+        key_sym = key.to_sym
+        next unless YAML_KEYS.include?(key_sym)
+        next if value.nil?
+
+        value = coerce_value(key_sym, value)
+        config.public_send(:"#{key_sym}=", value)
+      end
+
+      config
+    rescue Psych::SyntaxError, Psych::DisallowedClass => e
+      $stderr.puts "[rails-ai-context] WARNING: #{path} has invalid YAML (#{e.message}). Using defaults."
+      nil
+    end
+
+    # Auto-load config from .rails-ai-context.yml if no initializer configure block ran.
+    # Safe to call multiple times (idempotent).
+    def self.auto_load!(dir = nil)
+      return if RailsAiContext.configured_via_block?
+
+      dir ||= defined?(Rails) && Rails.respond_to?(:root) && Rails.root ? Rails.root.to_s : Dir.pwd
+      yaml_path = File.join(dir, CONFIG_FILENAME)
+      load_from_yaml(yaml_path) if File.exist?(yaml_path)
+    end
+
+    def self.coerce_value(key, value)
+      if SYMBOL_KEYS.include?(key)
+        value.respond_to?(:to_sym) ? value.to_sym : value
+      elsif SYMBOL_ARRAY_KEYS.include?(key)
+        Array(value).map(&:to_sym)
+      else
+        value
+      end
+    end
+    private_class_method :coerce_value
+
     PRESETS = {
       standard: %i[schema models routes jobs gems conventions controllers tests migrations stimulus
                    view_templates design_tokens config components

data/lib/rails_ai_context/tasks/rails_ai_context.rake

@@ -97,13 +97,24 @@ rescue => e
 end unless defined?(save_tool_mode_to_initializer)
 
 def ensure_mcp_json
+  require "json"
   mcp_path = Rails.root.join(".mcp.json")
-  return if File.exist?(mcp_path)
-
   server_entry = { "command" => "bundle", "args" => [ "exec", "rails", "ai:serve" ] }
-  content = JSON.pretty_generate({ mcpServers: { "rails-ai-context" => server_entry } }) + "\n"
-  File.write(mcp_path, content)
-  puts "✅ Created .mcp.json (MCP auto-discovery for Claude Code, Cursor, etc.)"
+
+  if File.exist?(mcp_path)
+    existing = JSON.parse(File.read(mcp_path)) rescue {}
+    existing["mcpServers"] ||= {}
+    if existing["mcpServers"]["rails-ai-context"] == server_entry
+      return # already up to date
+    end
+    existing["mcpServers"]["rails-ai-context"] = server_entry
+    File.write(mcp_path, JSON.pretty_generate(existing) + "\n")
+    puts "✅ Updated rails-ai-context in .mcp.json"
+  else
+    content = JSON.pretty_generate({ mcpServers: { "rails-ai-context" => server_entry } }) + "\n"
+    File.write(mcp_path, content)
+    puts "✅ Created .mcp.json (MCP auto-discovery for Claude Code, Cursor, etc.)"
+  end
 rescue => e
   puts "⚠️  Could not create .mcp.json: #{e.message}"
 end unless defined?(ensure_mcp_json)
@@ -143,6 +154,113 @@ rescue => e
   nil
 end unless defined?(save_ai_tools_to_initializer)
 
+def save_yaml_config(ai_tools, tool_mode)
+  require "yaml"
+  yaml_path = Rails.root.join(".rails-ai-context.yml")
+  content = {
+    "ai_tools" => Array(ai_tools).map(&:to_s),
+    "tool_mode" => tool_mode.to_s
+  }
+  File.write(yaml_path, YAML.dump(content))
+  puts "💾 Saved .rails-ai-context.yml (standalone config)"
+rescue => e
+  $stderr.puts "[rails-ai-context] save_yaml_config failed: #{e.message}" if ENV["DEBUG"]
+  nil
+end unless defined?(save_yaml_config)
+
+FORMAT_PATHS = {
+  claude:   %w[CLAUDE.md .claude/rules],
+  cursor:   %w[.cursor/rules],
+  copilot:  %w[.github/copilot-instructions.md .github/instructions],
+  opencode: %w[AGENTS.md app/models/AGENTS.md app/controllers/AGENTS.md]
+}.freeze unless defined?(FORMAT_PATHS)
+
+def read_previous_ai_tools_from_config
+  # Try initializer first
+  init_path = Rails.root.join("config/initializers/rails_ai_context.rb")
+  if File.exist?(init_path)
+    content = File.read(init_path)
+    match = content.match(/^\s*config\.ai_tools\s*=\s*%i\[([^\]]*)\]/)
+    return match[1].split.map(&:to_sym) if match
+  end
+
+  # Fall back to YAML
+  yaml_path = Rails.root.join(".rails-ai-context.yml")
+  if File.exist?(yaml_path)
+    require "yaml"
+    data = YAML.safe_load_file(yaml_path, permitted_classes: [ Symbol ]) || {}
+    tools = data["ai_tools"]
+    return tools.map(&:to_sym) if tools.is_a?(Array) && tools.any?
+  end
+
+  nil
+rescue => e
+  $stderr.puts "[rails-ai-context] read_previous_ai_tools_from_config failed: #{e.message}" if ENV["DEBUG"]
+  nil
+end unless defined?(read_previous_ai_tools_from_config)
+
+def cleanup_removed_ai_tools(previous, current)
+  removed = previous.map(&:to_sym) - current.map(&:to_sym)
+  return if removed.empty?
+
+  puts ""
+  puts "These AI tools were removed from your selection:"
+  removed.each_with_index do |fmt, idx|
+    tool = AI_TOOL_OPTIONS.values.find { |t| t[:key] == fmt }
+    puts "  #{idx + 1}. #{tool[:name]}" if tool
+  end
+  puts ""
+  puts "Remove their generated files?"
+  puts "  y — remove all listed above"
+  puts "  n — keep all (default)"
+  puts "  1,2 — remove only specific ones by number"
+  puts ""
+  print "Enter choice: "
+  input = $stdin.gets&.strip&.downcase || "n"
+  return if input.empty? || input == "n" || input == "no"
+
+  to_remove = if input == "y" || input == "yes" || input == "a"
+    removed
+  else
+    nums = input.split(/[\s,]+/).filter_map { |n| n.to_i - 1 }
+    nums.filter_map { |i| removed[i] if i >= 0 && i < removed.size }
+  end
+
+  return if to_remove.empty?
+
+  require "fileutils"
+  to_remove.each do |fmt|
+    tool = AI_TOOL_OPTIONS.values.find { |t| t[:key] == fmt }
+    paths = FORMAT_PATHS[fmt] || []
+    paths.each do |rel_path|
+      full = Rails.root.join(rel_path)
+      if File.directory?(full)
+        FileUtils.rm_rf(full)
+        puts "  Removed #{rel_path}/"
+      elsif File.exist?(full)
+        FileUtils.rm_f(full)
+        puts "  Removed #{rel_path}"
+      end
+    end
+    puts "  ✅ #{tool[:name]} files removed" if tool
+  end
+end unless defined?(cleanup_removed_ai_tools)
+
+def add_ai_context_to_gitignore
+  gitignore = Rails.root.join(".gitignore")
+  return unless File.exist?(gitignore)
+
+  content = File.read(gitignore)
+  return if content.include?(".ai-context.json")
+
+  File.open(gitignore, "a") do |f|
+    f.puts ""
+    f.puts "# rails-ai-context (JSON cache — markdown files should be committed)"
+    f.puts ".ai-context.json"
+  end
+  puts "✅ Updated .gitignore"
+end unless defined?(add_ai_context_to_gitignore)
+
 def add_ai_tool_to_initializer(format)
   init_path = Rails.root.join("config/initializers/rails_ai_context.rb")
   return unless File.exist?(init_path)
@@ -223,6 +341,7 @@ namespace :ai do
     apply_context_mode_override
 
     ai_tools = RailsAiContext.configuration.ai_tools
+    previous_tools = read_previous_ai_tools_from_config
 
     # First time — no tools configured, ask the user
     if ai_tools.nil?
@@ -237,9 +356,19 @@ namespace :ai do
       save_tool_mode_to_initializer(tool_mode)
     end
 
-    # Auto-create .mcp.json when tool_mode is :mcp and it doesn't exist
+    # Cleanup removed tools (only when re-running with different selections)
+    cleanup_removed_ai_tools(previous_tools, ai_tools) if previous_tools&.any? && ai_tools
+
+    # Write .rails-ai-context.yml alongside initializer (enables standalone mode)
+    save_yaml_config(ai_tools || RailsAiContext.configuration.ai_tools,
+                     RailsAiContext.configuration.tool_mode)
+
+    # Auto-create/update .mcp.json when tool_mode is :mcp
     ensure_mcp_json if RailsAiContext.configuration.tool_mode == :mcp
 
+    # Add .ai-context.json to .gitignore
+    add_ai_context_to_gitignore
+
     puts "🔍 Introspecting #{Rails.application.class.module_parent_name}..."
 
     if ai_tools.nil? || ai_tools.empty?
@@ -257,6 +386,11 @@ namespace :ai do
     puts ""
     puts "Done! Commit these files so your team benefits."
     puts "Change AI tools: config/initializers/rails_ai_context.rb (config.ai_tools)"
+    puts ""
+    puts "Standalone (no Gemfile needed):"
+    puts "  gem install rails-ai-context"
+    puts "  rails-ai-context init          # interactive setup"
+    puts "  rails-ai-context serve         # start MCP server"
   end
 
   desc "Generate AI context in a specific format (claude, cursor, copilot, json)"

data/lib/rails_ai_context/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module RailsAiContext
-  VERSION = "4.4.0"
+  VERSION = "4.5.0"
 end

data/lib/rails_ai_context.rb

@@ -22,9 +22,14 @@ module RailsAiContext
     end
 
     def configure
+      @configured_via_block = true
       yield(configuration)
     end
 
+    def configured_via_block?
+      @configured_via_block || false
+    end
+
     # Quick access to introspect the current Rails app
     # Returns a hash of all discovered context
     def introspect(app = nil)

data/server.json

@@ -2,16 +2,16 @@
   "$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json",
   "name": "io.github.crisnahine/rails-ai-context",
   "title": "Rails AI Context",
-  "description": "Auto-expose Rails app structure to AI via MCP or CLI. Zero config, 25 read-only tools.",
+  "description": "Auto-expose Rails app structure to AI via MCP or CLI. 39 read-only tools. Standalone or in-Gemfile.",
   "repository": {
     "url": "https://github.com/crisnahine/rails-ai-context",
     "source": "github"
   },
-  "version": "3.1.0",
+  "version": "4.5.0",
   "packages": [
     {
       "registryType": "mcpb",
-      "identifier": "https://github.com/crisnahine/rails-ai-context/releases/download/v3.1.0/rails-ai-context-mcp.mcpb",
+      "identifier": "https://github.com/crisnahine/rails-ai-context/releases/download/v4.5.0/rails-ai-context-mcp.mcpb",
       "fileSha256": "dd711a0ad6c4de943ae4da94eaf59a6dc9494b9d57f726e24649ed4e2f156990",
       "transport": {
         "type": "stdio"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: rails-ai-context
 version: !ruby/object:Gem::Version
-  version: 4.4.0
+  version: 4.5.0
 platform: ruby
 authors:
 - crisnahine
@@ -174,7 +174,7 @@ description: |
   structure on demand with semantic validation that catches cross-file errors
   (wrong columns, missing partials, broken routes) before code runs.
   Auto-generates context files for Claude Code, Cursor, GitHub Copilot, and
-  OpenCode. Zero config.
+  OpenCode. Works standalone or in-Gemfile.
 email:
 - crisjosephnahine@gmail.com
 executables:
@@ -318,11 +318,17 @@ metadata:
   funding_uri: https://github.com/sponsors/crisnahine
   rubygems_mfa_required: 'true'
 post_install_message: |
-  rails-ai-context installed! Quick start:
+  rails-ai-context installed!
+
+  Standalone (no Gemfile entry needed):
+    cd your-rails-app
+    rails-ai-context init           # interactive setup
+    rails-ai-context serve          # start MCP server
+
+  Or add to Gemfile:
+    gem "rails-ai-context", group: :development
     rails generate rails_ai_context:install
-    rails ai:context              # generate context files
-    rails 'ai:tool[schema]'      # run any of the 39 tools from CLI
-    rails ai:serve                # start MCP server (optional)
+    rails ai:serve
 rdoc_options: []
 require_paths:
 - lib
@@ -340,5 +346,5 @@ requirements: []
 rubygems_version: 3.6.9
 specification_version: 4
 summary: Give AI agents a complete mental model of your Rails app — 39 tools via MCP
-  or CLI. Zero config.
+  or CLI. Standalone or in-Gemfile.
 test_files: []