rails-ai-context 5.34.1 → 5.35.0

data/docs/CLI.md

@@ -218,14 +218,28 @@ Requires the `listen` gem. `rails ai:watch` needs it in the app's Gemfile; the s
 
 ### `init` (standalone only)
 
-Interactive setup for standalone mode.
+Setup for a standalone install, interactive or answered by flags.
 
 ```bash
-rails-ai-context init
-rails-ai-context init --mcp-only   # MCP config only, no context files
+rails-ai-context init                                   # asks
+rails-ai-context init --tools claude --defaults         # asks nothing: Claude Code, MCP config + context files
+rails-ai-context init --tools claude,cursor --cli       # context files only (CLI mode)
+rails-ai-context init --tools all --mcp-only            # MCP config only, no context files
+rails-ai-context init --tools claude --prune --defaults # remove the files of tools dropped since the last run
 ```
 
-Asks which AI tools to configure and what to write: MCP config and context files, context files only (CLI mode), or MCP config only. Creates `.rails-ai-context.yml`, the MCP config files (except in CLI mode) and the context files (except with MCP config only). `--mcp-only` skips the second question. Every question - including a re-run's cleanup of dropped tools, and in CLI mode whether to take the gem's entries out of existing MCP configs - is asked before the app boots and anything is written; with MCP config only, the app is not booted at all.
+Asks which AI tools to configure and what to write: MCP config and context files, context files only (CLI mode), or MCP config only. Creates `.rails-ai-context.yml`, the MCP config files (except in CLI mode) and the context files (except with MCP config only).
+
+| Flag | Answers |
+|:-----|:--------|
+| `--tools LIST` | Which AI tools: `claude`, `cursor`, `copilot`, `opencode`, `codex`, comma-separated, or `all`. Names only, never menu numbers |
+| `--mcp` | What to write: MCP config + context files (the first install's default) |
+| `--cli` | What to write: context files only (CLI mode) |
+| `--mcp-only` | What to write: MCP config only |
+| `--prune` | Yes to every removal question: the generated files of tools dropped since the last run, the gem's MCP entries on a switch to the CLI setup, the generated context files on a switch to the MCP-only setup, and legacy files |
+| `--defaults` | Every question no flag answered, with its default: all five tools and MCP config + context files on a first run, the recorded tools and setup on a re-run; files are kept |
+
+A flag `init` cannot read (`--tools vim`, or two of `--mcp`, `--cli` and `--mcp-only`) exits 1 before anything is asked or written. A default never removes a file; only `--prune` does. The install generator takes the same flags, plus `--hook` for its pre-commit hook question. The [copy-paste prompts](PROMPTS.md) use them so an AI tool can run the setup in its own shell, and in the MCP setup the closing summary names each tool's next step: the approval or trust step that tool needs before it starts the server. Every question - including a re-run's cleanup of dropped tools, and in CLI mode whether to take the gem's entries out of existing MCP configs - is asked before the app boots and anything is written; with MCP config only, the app is not booted at all.
 
 Run inside an app, `init` sets up that app (found the way every command finds it: the [app root](#tool) above a subdirectory, or the one `--app-path` names).
 
@@ -239,7 +253,7 @@ work/                      <- run `rails-ai-context init` here
   web/  .rails-ai-context.yml, CLAUDE.md, ...
 ```
 
-The AI tools and the setup are asked once. Each app gets its own `.rails-ai-context.yml` and context files, because its server reads them from its own root; a child process generates them with the install that app's server will run. The folder's MCP configs get one server per app, because a client reads its project config from the folder it opened. Each entry is named `rails-ai-context-<app folder>` (the whole path where two apps share a folder name; a short hash where the name would pass 30 characters, since Cursor drops a tool whose server and tool names together pass 60) and points `--app-path` at its app:
+The AI tools and the setup are asked once. On a re-run whose apps recorded different setups there is no one setup to keep, so `--defaults` without `--mcp`, `--cli` or `--mcp-only` stops with exit status 1 and asks for one. Each app gets its own `.rails-ai-context.yml` and context files, because its server reads them from its own root; a child process generates them with the install that app's server will run. The folder's MCP configs get one server per app, because a client reads its project config from the folder it opened. Each entry is named `rails-ai-context-<app folder>` (the whole path where two apps share a folder name; a short hash where the name would pass 30 characters, since Cursor drops a tool whose server and tool names together pass 60) and points `--app-path` at its app:
 
 ```json
 {
@@ -268,6 +282,40 @@ The AI tools and the setup are asked once. Each app gets its own `.rails-ai-cont
 
 Start the client in the workspace folder. A client started inside one of the apps (Claude Code, Codex and OpenCode still read a config above it) runs each workspace server from there, where the relative path misses; the server says which folder the path was written for. To open an app on its own, run `init` inside it as well. `init` warns when an app declares a Ruby other than the one the workspace runs, since every server it starts runs under that one. `doctor` inside one of the apps finds the workspace's config one or two levels up.
 
+### `uninstall`
+
+Removes what the gem wrote: each AI tool's context files and MCP entries, `.rails-ai-context.yml`, `.ai-context.json`, the initializer, the `.gitignore` lines and the pre-commit hook it installed.
+
+```bash
+rails-ai-context uninstall
+bundle exec rails-ai-context uninstall   # in-Gemfile; then bundle remove rails-ai-context
+```
+
+What you wrote stays: your lines around the markers in a shared `CLAUDE.md` or `AGENTS.md`, your rule files, other servers in an MCP config, and a pre-commit hook you changed by hand (named, not touched). Its own config files go even when you edited them: `.rails-ai-context.yml` and the initializer configure nothing once the gem is gone. An HTTP entry under the gem's name goes too, since only the gem's endpoint answers it. A `mount RailsAiContext::Engine` line in `config/routes.rb` is named with its line number for you to delete. In a folder of apps it uninstalls every app below and the folder's MCP configs. It needs no boot. An entry you added by hand to another client's own config from `mcp-entry` (Claude Desktop and the like) lives outside the app, so remove it there. Its last lines say how to remove the gem itself: `bundle remove rails-ai-context` when the Gemfile lists it, `gem uninstall rails-ai-context` once no other app uses the installed copy. Details in the [Guide](GUIDE.md#uninstalling).
+
+### `mcp-entry`
+
+Prints an MCP server entry for a client the install writes no config for: Claude Desktop, Windsurf, Zed, a JetBrains IDE.
+
+```bash
+rails-ai-context mcp-entry
+bundle exec rails-ai-context mcp-entry   # in-Gemfile
+```
+
+```json
+{
+  "mcpServers": {
+    "rails-ai-context": {
+      "command": "/Users/you/.rbenv/versions/3.4.1/bin/ruby",
+      "args": ["/Users/you/.rbenv/versions/3.4.1/bin/rails-ai-context", "serve", "--app-path", "/Users/you/work/shop"],
+      "env": { "PATH": "...", "GEM_HOME": "..." }
+    }
+  }
+}
+```
+
+Such a client starts its servers from its own folder with its own `PATH`, so every path is absolute. The command is the Ruby the binary runs under, by its full path, which no version manager's shim can swap for the Ruby of the client's folder; `--app-path` names the app; `env` carries the gem variables the shell had (`PATH`, `GEM_HOME`, `GEM_PATH`, `GEM_ROOT`, `RUBY_VERSION`, `BUNDLE_PATH`). For an in-Gemfile app the entry runs `bundle exec` with `BUNDLE_GEMFILE` naming the app's Gemfile. Merge it into the client's config under the key that client uses for servers, and print it again after the app moves or its Ruby changes. See [Other MCP clients](SETUP.md#other-mcp-clients).
+
 ### `version`
 
 ```bash

data/docs/COMPATIBILITY.md

@@ -296,6 +296,13 @@ Proof sources:
    In the v5.34.1 release QA: the gem built from the release commit and its
    file list read, and the unit suite and the E2E harness on Linux, macOS and
    Windows; the code is v5.34.0's.
+   In the v5.35.0 release QA: every copy-paste prompt in `docs/PROMPTS.md`
+   pasted into Claude Code (`claude -p`) and Codex CLI (`codex exec`) and the
+   result checked on disk, 40 scenarios in fresh Rails 8.1 apps, an app that
+   cannot boot, a mountable engine, a Docker container and a copy of a
+   private production app; each AI tool's MCP config started the way its
+   client starts it; and the unit suite and the E2E harness on Linux, macOS
+   and Windows.
 2. Non-crash coverage for every built-in tool including `get_view` in
    `spec/e2e/in_gemfile_install_spec.rb`'s full-tool sweep; output correctness
    (ivar cross-check, render-form detection, partial interfaces) verified

data/docs/CONFIGURATION.md

@@ -60,6 +60,7 @@ server and nothing else:
 
 ```bash
 rails generate rails_ai_context:install --mcp-only   # or: rails-ai-context init --mcp-only
+rails generate rails_ai_context:install --tools claude --mcp-only --defaults   # asks nothing
 ```
 
 That writes the MCP config for the tools you pick and records:

data/docs/FAQ.md

@@ -18,7 +18,7 @@ It gives AI coding assistants verified, real-time access to your Rails app's str
 
 ### Which AI tools are supported?
 
-Claude Code, Cursor, GitHub Copilot, OpenCode, and Codex CLI. Each gets tailored context files and MCP auto-discovery config.
+Claude Code, Cursor, GitHub Copilot, OpenCode, and Codex CLI. Each gets tailored context files and an MCP config it finds when it opens the project; you approve the server once in the tool.
 
 ### Do I need MCP support in my AI tool?
 
@@ -39,6 +39,14 @@ Yes. The gem gracefully degrades - it parses `db/schema.rb` as text when no data
 
 ## Installation
 
+### Can my AI tool install it for me?
+
+Yes. [Copy-paste prompts](PROMPTS.md) has one prompt per setup: the usual install, no Gemfile change, CLI only, MCP only, every AI tool for a team, a folder of apps, a private setup with nothing committed, and a try-out that writes nothing. More cover changing the setup, upgrading, fixing and uninstalling. Each runs the install with every answer given as a flag, so it never waits on a question.
+
+### How do I uninstall it?
+
+`bundle exec rails-ai-context uninstall` (or `rails-ai-context uninstall` standalone), then `bundle remove rails-ai-context` if the Gemfile lists it. It removes what the gem wrote and keeps what you wrote, such as your own lines in `CLAUDE.md`. See [Uninstalling](GUIDE.md#uninstalling).
+
 ### Gemfile or standalone - which should I use?
 
 **In-Gemfile** is recommended if you own the project. Gives you the install generator, rake tasks, and initializer config.
@@ -56,7 +64,7 @@ Yes. Run `rails-ai-context init` in that folder. It asks once, gives each app it
 ### Do I need to commit the generated files?
 
 **Yes, commit these:**
-- `.mcp.json`, `.cursor/mcp.json`, `.vscode/mcp.json`, `opencode.json` - so teammates get MCP auto-discovery
+- `.mcp.json`, `.cursor/mcp.json`, `.vscode/mcp.json`, `opencode.json` - so teammates get the MCP server after approving it once in their AI tool
 - `CLAUDE.md`, `.claude/rules/`, `.cursor/rules/`, `.cursorrules`, `.github/copilot-instructions.md`, `.github/instructions/`, `AGENTS.md` - so AI has context
 - `config/initializers/rails_ai_context.rb`, `.rails-ai-context.yml` - so config is shared
 
@@ -70,6 +78,7 @@ Yes:
 
 ```bash
 rails generate rails_ai_context:install --mcp-only   # or: rails-ai-context init --mcp-only
+rails generate rails_ai_context:install --tools claude --mcp-only --defaults   # asks nothing
 ```
 
 The MCP config is written, `config.context_files = false` is recorded, and no
@@ -238,7 +247,7 @@ Those are AI coding interfaces. This gem is a data layer that makes *any* of the
 
 ### My AI tool doesn't see the MCP server
 
-Run `rails ai:doctor` - it checks each configured tool's MCP config file, and whether the command it holds can start. See [Troubleshooting](TROUBLESHOOTING.md) for detailed steps.
+Each AI tool holds a project's MCP server back until you take a step in the tool itself: approve it in Claude Code, turn it on in Cursor, trust the folder in VS Code and Codex CLI, restart OpenCode. The install's summary names the step for each tool you picked. If it is done and the tools still don't appear, run `rails ai:doctor` - it checks each configured tool's MCP config file, and whether the command it holds can start. See [Troubleshooting](TROUBLESHOOTING.md#ai-tool-doesnt-detect-the-mcp-server) for detailed steps.
 
 ### Tools return empty results
 

data/docs/GUIDE.md

@@ -18,6 +18,7 @@
 | Guide | Description |
 |:------|:------------|
 | [Quickstart](QUICKSTART.md) | Get running in 5 minutes |
+| [Copy-paste prompts](PROMPTS.md) | Let your AI tool install, change, remove or use the gem |
 | [Tools Reference](TOOLS.md) | All 45 MCP tools with parameters |
 | [Recipes](RECIPES.md) | Real-world workflows and examples |
 | [Custom Tools](CUSTOM_TOOLS.md) | Build your own MCP tools |
@@ -36,6 +37,7 @@
 ## Table of Contents
 
 - [Installation](#installation)
+- [Uninstalling](#uninstalling)
 - [Context Modes](#context-modes)
 - [Generated Files](#generated-files)
 - [All Commands](#all-commands)
@@ -69,7 +71,7 @@ rails ai:context
 This creates:
 1. `config/initializers/rails_ai_context.rb` - configuration file
 2. `.rails-ai-context.yml` - standalone config (enables switching later)
-3. Per-tool MCP config files - auto-discovery for Claude Code, Cursor, Copilot, OpenCode, and Codex
+3. Per-tool MCP config files - each AI tool finds its own when it opens the project, then asks you to approve the server once
 4. Context files - tailored for each AI assistant
 
 ### Option B: Standalone (no Gemfile entry needed)
@@ -82,16 +84,16 @@ rails-ai-context init
 
 This creates:
 1. `.rails-ai-context.yml` - configuration file
-2. Per-tool MCP config files - auto-discovery (if MCP mode selected)
+2. Per-tool MCP config files - in the MCP and MCP-only setups
 3. Context files - tailored for each AI assistant
 
 No Gemfile entry, no initializer, no files in your project besides config and context.
 
 ### What the install generator does
 
-`rails generate rails_ai_context:install` runs these steps in this order. Steps 1, 2, 3, 8 and 9 can ask a question.
+`rails generate rails_ai_context:install` runs these steps in this order. Steps 1, 2, 3, 4, 8 and 9 can ask a question.
 
-1. **Asks which AI tools you use.** It prints this menu, then `Enter numbers separated by commas (e.g. 1,2) or 'a' for all:`
+1. **Asks which AI tools you use.** It prints this menu, then `Enter numbers separated by commas (e.g. 1,2) or 'a' for all (default: all):`, or `(default: keep the current selection):` on a re-run
 
    ```
    1. Claude Code      -> CLAUDE.md + .claude/rules/
@@ -102,29 +104,34 @@ No Gemfile entry, no initializer, no files in your project besides config and co
    a. All of the above
    ```
 
-   On a re-run the menu is followed by the selection recorded last time, as `Currently selected: 1,2 (Claude Code, Cursor)`. There is no "none" choice. An empty answer selects all five, and so does one with no valid number in it, which says so (`"9" names no tool - selecting all.`).
+   On a re-run the menu is followed by the selection recorded last time, as `Currently selected: 1,2 (Claude Code, Cursor)`. There is no "none" choice. An empty answer takes the default: the recorded selection on a re-run, all five on a first install. So does an answer with no valid number in it, which says so (`"9" names no tool - keeping the current selection.`).
 2. **Offers to clean up tools you dropped.** Only on a re-run, and only when the last recorded selection (the `config.ai_tools` line in the initializer, else `.rails-ai-context.yml`) has a tool you did not pick this time. It lists them and asks `Remove their generated files?` with `y` (all), `n` (keep, the default) or numbers like `1,2`. A yes removes only what the gem generated: the rule files it names inside the tool's rules directory (the directory goes too when nothing else is left in it), and the block between the `rails-ai-context` markers in a root file such as `CLAUDE.md`. A rule file you wrote by hand, your own lines around the markers, a root file with no markers and a symlink are left alone. It keeps any file shared with a tool whose files stay (`AGENTS.md`) - one still selected, or one dropped whose files you kept by leaving its number out - and says so, and takes only the `rails-ai-context` entry out of the tool's MCP config - a config left with no other entry is deleted, and named as removed. A tool's dot-directory the cleanup emptied (`.cursor/`, `.github/`, `.codex/`, `.vscode/`) goes too; one that still holds a file of yours stays.
-3. **Asks what to write**, then `Enter number (default: 1):`
+3. **Asks what to write**, then `Enter number (default: 1):`. On a re-run it first prints the recorded setup (`Currently: Context files only (CLI mode, no MCP server)`), and that is the default
 
    ```
    1. MCP config + context files   (default)
    2. Context files only           (CLI mode, no MCP server)
-   3. MCP config only              (leaves CLAUDE.md, AGENTS.md and rules untouched)
+   3. MCP config only              (writes no CLAUDE.md, AGENTS.md or rules files)
    ```
 
-   Choices 1 and 3 set `tool_mode` to `:mcp`, choice 2 sets it to `:cli`. Choice 3 also sets `context_files` to `false`. Any other answer counts as 1.
-4. **Writes the MCP config for each selected tool** (`.mcp.json`, `.cursor/mcp.json`, `.vscode/mcp.json`, `opencode.json`, `.codex/config.toml`). Skipped for choice 2, which instead lists any config that still starts `rails-ai-context` and asks `Remove rails-ai-context from them? (y/N)`: CLI mode starts no MCP server. A yes takes out only the gem's entries, as step 2 does. An existing file is merged: only the `rails-ai-context` entry is added or replaced. One that does not parse as JSON, or holds comments a rewrite would drop, is left as it is, with a warning that names the entry to add by hand. Each file is read as its client reads it. VS Code's and OpenCode's take JSONC, comments and trailing commas (read under json 2.9 or later); Claude Code reads `.mcp.json` as plain JSON, and Cursor's `.cursor/mcp.json` is held to plain JSON too, so a comment or a trailing comma in either is reported as one the client cannot read, and the file left as it is. In `.codex/config.toml` the server's table is found however its name is quoted, and replaced where it stands; an entry of the gem's written as an inline table or with dotted keys is left as it is, with a warning, since a table added beside it would declare the server twice, which Codex refuses.
+   Choices 1 and 3 set `tool_mode` to `:mcp`, choice 2 sets it to `:cli`. Choice 3 also sets `context_files` to `false`. Any other answer takes the default.
+4. **Writes the MCP config for each selected tool** (`.mcp.json`, `.cursor/mcp.json`, `.vscode/mcp.json`, `opencode.json`, `.codex/config.toml`). Skipped for choice 2, which instead lists any config that still starts `rails-ai-context` and asks `Remove rails-ai-context from them? (y/N)`: CLI mode starts no MCP server. A yes takes out only the gem's entries, as step 2 does. With choice 3 it lists instead the context files an earlier setup generated, which nothing refreshes once the install writes no context files, and asks `Remove the generated parts? Lines you wrote stay. (y/N)`; a yes removes them the way step 2 does, and `.ai-context.json` with them. An existing file is merged: only the `rails-ai-context` entry is added or replaced. One that does not parse as JSON, or holds comments a rewrite would drop, is left as it is, with a warning that names the entry to add by hand. Each file is read as its client reads it. VS Code's and OpenCode's take JSONC, comments and trailing commas (read under json 2.9 or later); Claude Code reads `.mcp.json` as plain JSON, and Cursor's `.cursor/mcp.json` is held to plain JSON too, so a comment or a trailing comma in either is reported as one the client cannot read, and the file left as it is. In `.codex/config.toml` the server's table is found however its name is quoted, and replaced where it stands; an entry of the gem's written as an inline table or with dotted keys is left as it is, with a warning, since a table added beside it would declare the server twice, which Codex refuses.
 5. **Creates or updates `config/initializers/rails_ai_context.rb`.** A new file gets your three answers as live lines (`config.ai_tools`, `config.tool_mode`, `config.context_files`) and every other option commented out at its default, wrapped in `if defined?(RailsAiContext) && RailsAiContext.respond_to?(:configure)`; it passes the omakase Rubocop a new Rails app runs. In an existing file it rewrites those three lines where the value changed - keeping the line's indentation and any note of your own after it - appends any config section the file lacks, adds the guard if it is missing, and leaves the rest alone.
 6. **Writes `.rails-ai-context.yml`** with `ai_tools`, `tool_mode` and `context_files`. Only a key whose value changed is rewritten, where it stands; your comments and other keys are kept, and a run that changes no value leaves the file as it was.
 7. **Adds lines to `.gitignore`**, if the file exists: `.ai-context.json` (not for choice 3) and `.codex/config.toml` (always, because it holds this machine's Ruby paths). A line that is already there is not added again.
 8. **Asks about a pre-commit hook:** `Install a pre-commit hook that checks staged Ruby, ERB and JavaScript files for syntax errors? (y/N)`. Only `y` installs it. The hook runs `bundle exec rails-ai-context tool validate` (`rails-ai-context tool validate` in a standalone install) on the staged `.rb`, `.erb`, `.js`, `.mjs` and `.cjs` files and stops a commit whose files do not parse (JavaScript is parsed by `node`, as [`rails_validate`](TOOLS.md#rails_validate) describes); the Rails-reference checks (`level=rails`) are left to the tool, as Brakeman would slow every commit. An app that cannot boot (an initializer that needs a variable the shell lacks, say) is still checked, from its source, and the hook shows why it did not boot; it shows whatever else the check prints to stderr too, so a check that cannot run says why. Every staged name is read whole, one with characters outside ASCII included; a name holding a comma, which the files list cannot carry, is named and left unchecked. It goes where git runs hooks (`git rev-parse --git-path hooks`), so an app checked out as a submodule, an app inside a monorepo and a repo with `core.hooksPath` set all get it where git will run it. The hook names the apps it covers and validates each one's staged files (deleted ones aside) from inside that app; installing in a second app of the same monorepo adds it to the hook, unless the hook was changed by hand, which it says, and for an app below the top of the repository the question names the repository. A hook an earlier version wrote, and nobody changed since, is brought up to date without asking again: the oldest handed validate the files a commit deletes too, and the commit failed on them, and later ones ran `rails 'ai:tool[validate]'`, which has to boot the app, with its errors thrown away, so an app that could not boot failed every commit with no reason given. Any other hook that runs `rails-ai-context` - one changed by hand, or a team's own that calls it among other checks - is left as it is, with a message. No hook is offered for an app the repository does not track yet (an app under a dotfiles repository at `$HOME`, say), nor into a `core.hooksPath` outside the repository, which every repository using it shares; both say why. No question is asked outside a git repository or when the hook already covers the app. When another `pre-commit` hook exists there it prints `Skipped pre-commit hook (existing hook found - add manually)` and moves on.
-9. **Generates the context files** for the selected tools. Skipped for choice 3. If files that v5.0.0 stopped generating are still there (`.claude/rules/rails-ui-patterns.md`, `.claude/rules/rails-accessibility.md`, `.cursor/rules/rails-ui-patterns.mdc`, `.github/instructions/rails-ui-patterns.instructions.md`), it lists them first and asks `Delete them? [y/N]:`. Without a terminal, or under `--defaults`, it prints the `rm` command and does not ask.
-10. **Prints a summary:** the files each selected tool got and the commands to run next.
+9. **Generates the context files** for the selected tools. Skipped for choice 3. If files that v5.0.0 stopped generating are still there (`.claude/rules/rails-ui-patterns.md`, `.claude/rules/rails-accessibility.md`, `.cursor/rules/rails-ui-patterns.mdc`, `.github/instructions/rails-ui-patterns.instructions.md`), it lists them first and asks `Delete them? [y/N]:`. Without a terminal, or under `--defaults`, it prints the `rm` command and does not ask; under `--prune` it deletes them without asking.
+10. **Prints a summary:** the files each selected tool got, the commands to run next, and, in the MCP setup, each tool's next step: the approval or trust step that tool asks for before it starts a project's MCP server (approve the server in Claude Code, turn it on in Cursor, trust the folder in VS Code and Codex CLI, restart OpenCode).
 
-Two flags change the prompts:
+Every question has a flag, so an AI tool or a script can run the install to the end with nobody at the keyboard (the [copy-paste prompts](PROMPTS.md) are built on them):
 
-- `--defaults` answers every prompt with its default: all five tools, keep dropped tools' files, choice 1, no hook, keep legacy files. Piping an empty stdin does the same.
-- `--mcp-only` skips the step 3 question and acts as choice 3. Steps 1, 2 and 8 still ask.
+- `--tools claude,cursor` answers step 1. It takes the tool names `claude`, `cursor`, `copilot`, `opencode` and `codex`, comma-separated, or `all`; never the menu numbers, which would pick another tool once one is added.
+- `--mcp` answers step 3 with choice 1, `--cli` with choice 2, `--mcp-only` with choice 3. Only one of them can be given.
+- `--prune` answers yes to every removal question: step 2 (dropped tools' generated files), step 4's in the CLI setup (the gem's MCP entries) and in the MCP-only setup (the context files an earlier setup generated), and step 9's (legacy files).
+- `--hook` answers yes to step 8.
+- `--defaults` answers every question no flag answered with its default. On a first install that is all five tools and choice 1; on a re-run it is the recorded tools and setup, so running the install again with `--defaults` repairs it without switching anything. Every removal question defaults to keep, and the hook to no. Piping an empty stdin does the same. A default never removes a file; only `--prune` does.
+
+A flag the install cannot read (a name that is no tool, two setup flags at once, or a flag it does not have, such as a mistyped one) stops it with exit status 1 before anything is asked or written. [ADR-0007](adr/0007-every-install-question-has-a-flag.md) records the design.
 
 Run from a mountable engine's root, where `bin/rails` boots `test/dummy`, the install goes into the engine's root - the folder an editor is opened at, and the one every `rails-ai-context` command run there reads: the MCP configs, `.rails-ai-context.yml`, the `.gitignore` lines and the context files, which are generated from the engine's source the way its MCP server reads it there. No initializer is written, since Rails runs an engine's `config/initializers` in every app that mounts it and the gemspec ships them; one an earlier install left there is named, with a note to delete it. Step 8 offers no hook at the engine's root (its rake tasks run in the dummy app, as `app:ai:*`), and the summary lists the commands that work at the engine's root, `bundle exec rails-ai-context ...`. The context files written there name the same commands for their CLI fallback and the server, as do the tools' own hints. `bundle exec rails-ai-context doctor` at the engine's root diagnoses the dummy app and reads this install, as `bin/rails app:ai:doctor` does.
 
@@ -132,11 +139,30 @@ A team that wants no AI tool files in the repo can skip the generator. The gem n
 
 Two other entry points ask the same step 1 and step 3 questions:
 
-- `rails-ai-context init` (standalone) asks both, then the step 2 cleanup question, step 4's question about MCP configs when the answer was CLI mode, and the step 9 question. Only then does it boot the app, so that every gem the app locks loads at the app's pin, and write: the cleanup, `.rails-ai-context.yml`, the MCP configs, the `.gitignore` lines and the context files. An MCP-only run skips the step 9 question, as the generator does, and boots nothing. It never creates the initializer (in one that exists it updates `config.ai_tools`, `config.tool_mode` and `config.context_files`), never offers the pre-commit hook, and has `--mcp-only` but no `--defaults`. Typed outside the app (`init --app-path ../shop`), it names the files it wrote from there, as `../shop/.mcp.json`. Run in a folder that holds several apps, it asks once and sets them all up: each app's own `.rails-ai-context.yml` and context files, and one MCP server per app in the folder's configs ([`init`](CLI.md#init-standalone-only)).
+- `rails-ai-context init` (standalone) asks both, then the step 2 cleanup question, step 4's question about MCP configs when the answer was the CLI setup or about generated context files when it was MCP only, and the step 9 question. Only then does it boot the app, so that every gem the app locks loads at the app's pin, and write: the cleanup, `.rails-ai-context.yml`, the MCP configs, the `.gitignore` lines and the context files. An MCP-only run skips the step 9 question, as the generator does, and boots nothing. It never creates the initializer (in one that exists it updates `config.ai_tools`, `config.tool_mode` and `config.context_files`), never offers the pre-commit hook, and takes the same flags as the generator but `--hook`: `--tools`, `--mcp`, `--cli`, `--mcp-only`, `--prune` and `--defaults`. Typed outside the app (`init --app-path ../shop`), it names the files it wrote from there, as `../shop/.mcp.json`. Run in a folder that holds several apps, it asks once and sets them all up: each app's own `.rails-ai-context.yml` and context files, and one MCP server per app in the folder's configs ([`init`](CLI.md#init-standalone-only)).
 - `rails ai:context` asks step 1 only when no tool selection is recorded, and step 3 only when no `tool_mode` is recorded. It then writes `.rails-ai-context.yml`, the MCP configs and the `.gitignore` lines before generating. It does not create the initializer or offer the hook. `rails-ai-context context` brings the MCP configs of a recorded selection up to date the same way, and `rails ai:context:<tool>` writes that tool's MCP config along with its files.
 
 ---
 
+## Uninstalling
+
+```bash
+bundle exec rails-ai-context uninstall   # in the Gemfile; then: bundle remove rails-ai-context
+rails-ai-context uninstall               # standalone; then, once no app uses it: gem uninstall rails-ai-context
+```
+
+`uninstall` takes out what the gem wrote and nothing you wrote:
+
+- Each AI tool's context files. A rules file you wrote stays, and in a root file such as `CLAUDE.md` only the block between the `rails-ai-context` markers goes, so your own lines stay. A file left empty is deleted, and so is a tool's dot-directory (`.cursor/`, `.claude/`) once nothing of yours is in it.
+- The `rails-ai-context` entry in every MCP config, an HTTP one under that name included. Other servers in the file stay; a config left with none is deleted.
+- `.rails-ai-context.yml`, `.ai-context.json` and `config/initializers/rails_ai_context.rb`, edited or not: they configure nothing once the gem is gone.
+- The lines the install added to `.gitignore`, with their comments.
+- The pre-commit hook, when it is the one the install wrote and covers only this app. A hook that covers other apps of the repository loses this one; a hook changed by hand is named and left for you.
+
+A `mount RailsAiContext::Engine` line in `config/routes.rb` is your code, so it is named with its line number, not edited. Run in a folder of apps, it does the same for every app below and for the folder's MCP configs. It needs no boot, so it works on an app that cannot start, and the binary of any install can run it: in an app whose bundle pins a version from before `uninstall` existed, `gem install rails-ai-context` and run `rails-ai-context uninstall`.
+
+---
+
 ## Context Modes
 
 The gem has two context modes that control how much data goes into the generated files:
@@ -310,7 +336,8 @@ Each `rails ai:context:<tool>` adds its tool to the recorded selection and, in M
 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 configs)
+rails-ai-context init                      # Setup: asks, or takes every answer as a flag (creates .rails-ai-context.yml + MCP configs)
+rails-ai-context init --tools claude --defaults  # The same, every answer given as a flag
 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
@@ -325,6 +352,8 @@ rails-ai-context watch                     # Watch for changes
 rails-ai-context inspect                   # Print introspection JSON
 rails-ai-context facts                     # Print schema facts summary
 rails-ai-context preset architecture       # Run a multi-tool preset
+rails-ai-context uninstall                 # Remove what the gem wrote, keep what you wrote
+rails-ai-context mcp-entry                 # Print an MCP entry for Claude Desktop, Windsurf, Zed and other clients
 rails-ai-context version                   # Print version
 rails-ai-context help                      # Show all commands
 ```
@@ -1142,7 +1171,7 @@ This server is listed on the [official MCP Registry](https://registry.modelconte
 curl "https://registry.modelcontextprotocol.io/v0.1/servers?search=rails-ai-context"
 ```
 
-### Auto-discovery (recommended)
+### Per-tool MCP config files (recommended)
 
 The install generator (or `rails-ai-context init`) creates per-tool MCP config files based on your selected AI tools:
 
@@ -1185,11 +1214,11 @@ GEM_HOME = "/home/user/.rbenv/versions/3.3.0/lib/ruby/gems/3.3.0"
 
 > **Why the `[env]` section?** Codex CLI `env_clear()`s the process before spawning MCP servers, stripping Ruby version manager paths. The install generator snapshots your current Ruby environment (PATH, GEM\_HOME, GEM\_PATH, GEM\_ROOT, RUBY\_VERSION, BUNDLE\_PATH) so the MCP server can find gems regardless of version manager (rbenv, rvm, asdf, mise, chruby, or system Ruby).
 
-Each AI tool auto-detects its own config file. No manual config needed - just open your project.
+Each AI tool finds its own config file when it opens the project, then holds the server back until you approve it once: approve it in Claude Code, turn it on in Cursor, trust the folder in VS Code and Codex CLI, restart OpenCode. The install's summary names the step for each tool you picked ([AI tool setup](SETUP.md#verify-mcp-is-connected)).
 
 ### Claude Code
 
-Auto-discovered via `.mcp.json`. Or add manually:
+Read from `.mcp.json` once you approve the server. Or add manually:
 
 ```bash
 # In-Gemfile
@@ -1222,7 +1251,7 @@ Or for standalone: replace `"command": "bundle"` / `"args": ["exec", "rails-ai-c
 
 ### Cursor
 
-Auto-discovered via `.cursor/mcp.json`. Or add manually in **Cursor Settings > MCP**:
+Read from `.cursor/mcp.json` once you turn the server on. Or add manually:
 
 ```json
 {
@@ -1562,17 +1591,17 @@ config.introspectors = %i[schema models routes gems auth api]
 
 ### Claude Code
 
-**Auto-discovery:** Opens `.mcp.json` automatically. No setup needed.
+**Auto-discovery:** Reads `.mcp.json` when a session starts in the folder, and asks you to approve the `rails-ai-context` server once (`claude mcp reset-project-choices` asks again).
 
 **Context files loaded:**
 - `CLAUDE.md` - read at conversation start
 - `.claude/rules/*.md` - auto-loaded alongside CLAUDE.md (schema, models, and components rules use `paths:` frontmatter for conditional loading)
 
-**MCP tools:** Available immediately via `.mcp.json`.
+**MCP tools:** Available once the server is approved. `/mcp` lists it.
 
 ### Cursor
 
-**Auto-discovery:** Opens `.cursor/mcp.json` automatically. No setup needed.
+**Auto-discovery:** Reads `.cursor/mcp.json`. Restart Cursor after the install, and turn `rails-ai-context` on under MCP in Customize if it is off.
 
 **Context files loaded:**
 - `.cursor/rules/*.mdc` - loaded based on `alwaysApply` and `globs` settings