talk_to_your_app 0.1.0.pre.2 → 0.1.0.pre.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 10204bc4a2149e7f2f78edd74990df717777df92e8312cd5d71f4d628a66e732
-  data.tar.gz: 32bfa44be84cd987c93e0553328126dbca1f1efb0f13d15b62d8cecdbb4a5456
+  metadata.gz: 968cb02f102a1c4e238a3305a9b67f9b00642e3da99c30ccf9ece00799251547
+  data.tar.gz: 8d87ffd983498a0636b3e3d88b465262fa7781e0e534325cd96ef3c06ee15c28
 SHA512:
-  metadata.gz: 8b1ed1bfd86c608f3fd8867b2c376ca92068f05044506291a034e2636da306656ee218a1bf0d9cd974d6eb1879256d6dc47db4c0d8e4ddd0b3ac1bd17440bddf
-  data.tar.gz: 630827c1779170f29c971d12310cf4f77ceb51f1504e160140bf6013d90214f4d892a949a9aa04f79c00c9781b053f926ac6a523c57a56a9b2cb267d0145073e
+  metadata.gz: e6dae56486a9660bc76769312aeb9c7a0f42de81b15c0b409d084962f4e3ea20600c9b8eb2670d267c6621885c3aa0e3c5ab02b471747662dbc74f9bc179571a
+  data.tar.gz: 7c13b0d2eb1110fd16ff11e224b5be5fb73a8cb5330913d3310d561064efe8af537d0d03e5a0997bf52b27628f53c0d0a1775fbd7c24a26a7d690cd97b312910

data/LOCAL_DEVELOPMENT.md

@@ -0,0 +1,284 @@
+# Local development
+
+How to work on the `talk_to_your_app` gem and run its test suite.
+
+## Prerequisites
+
+- **Ruby** >= 3.2 (CI runs 3.2 and 3.3).
+- **Bundler** (`gem install bundler`).
+- **SQLite** — the default test database; the `sqlite3` gem is bundled, no server needed.
+- **PostgreSQL** — _optional_ for the test suite (DB-plugin read-only-role and timeout tests skip without it) but **required to run the dummy app as a local MCP server** (see below). A running server on `localhost:5432` reachable as the `postgres` superuser (DBngin, Postgres.app, Homebrew, or Docker all work).
+- **Redis** _(optional)_ — exercises the Jobs plugin's Sidekiq adapter. A running server on `localhost:6379`.
+
+Tests that need PostgreSQL or Redis **skip cleanly** when the service is not reachable, so `bundle exec rake test` always runs; you just get fewer assertions without the services.
+
+## Setup
+
+```sh
+git clone https://github.com/igorkasyanchuk/talk_to_your_app.git
+cd talk_to_your_app
+bundle install
+```
+
+## Running tests
+
+The suite is Minitest, driven by Rake.
+
+```sh
+# Everything
+bundle exec rake test
+
+# A single file (Rake)
+bundle exec rake test TEST=test/talk_to_your_app/configuration_test.rb
+
+# A single file (plain Ruby — fastest feedback)
+bundle exec ruby -Itest -Ilib test/talk_to_your_app/configuration_test.rb
+
+# Filter by test name within a file
+bundle exec rake test TEST=test/talk_to_your_app/configuration_test.rb TESTOPTS="--name=/mount_at/"
+```
+
+### What the suite touches
+
+- **SQLite** — the dummy app's primary database, in-memory, set up automatically by `test/test_helper.rb`.
+- **PostgreSQL** — `test/support/pg_test_db.rb` connects as the `postgres` superuser and (re)creates a `ttya_test` database plus a genuinely read-only role (`ttya_ro`, `GRANT SELECT` only) on each run. Nothing to set up by hand; if Postgres is unreachable, the DB-plugin tests skip.
+- **Redis** — the Sidekiq adapter tests use database **15** at `redis://localhost:6379/15` and flush it between tests. Override with `TTYA_TEST_REDIS_URL` if your Redis lives elsewhere:
+
+  ```sh
+  TTYA_TEST_REDIS_URL=redis://localhost:6380/15 bundle exec rake test
+  ```
+
+- **MySQL/MariaDB** — the DB plugin has a MySQL statement-timeout path, but it is not exercised locally (no `mysql2` in the bundle). Its SQL is unit-tested without a server in `test/talk_to_your_app/plugins/db/timeout_statement_test.rb`.
+
+## Testing against multiple Rails versions
+
+The gem supports Rails 7.1, 7.2, and 8.0 via [Appraisal](https://github.com/thoughtbot/appraisal). The version matrix lives in `Appraisals`.
+
+```sh
+# Generate/install the per-version gemfiles under gemfiles/ (needs network)
+bundle exec appraisal install
+
+# Run the suite against one Rails version
+bundle exec appraisal rails-8.0 bundle exec rake test
+
+# …or all of them
+bundle exec appraisal rake test
+```
+
+CI runs the full Rails × Ruby matrix (see `.github/workflows/ci.yml`).
+
+## Running the dummy app as a local MCP server (and connecting Claude)
+
+The bundled `test/dummy` app can run as a real MCP server so you can point an MCP
+client such as **Claude Code** or **Claude Desktop** at it and exercise the gem
+end to end. In `development` it auto-configures **HTTP Basic auth** and enables
+the bundled plugins (see `test/dummy/config/initializers/talk_to_your_app.rb`).
+
+It runs on **PostgreSQL** so the DB plugin can connect through a genuine
+read-only database user — the same pattern you'd use in production. You need a
+local Postgres reachable as the `postgres` superuser (see Prerequisites).
+
+It ships `User`, `Post`, and `Comment` models (with associations) so there's real
+relational data to query.
+
+### 1. One-time database setup
+
+```sh
+cd test/dummy
+RAILS_ENV=development bundle exec ruby bin/rails db:prepare
+```
+
+`db:prepare` creates `ttya_dummy_development`, loads the schema, seeds sample data
+(users Alice/Bob, their posts and comments, plus a `widgets` table), **and
+provisions a read-only Postgres role** `ttya_dummy_ro` (`GRANT SELECT` only).
+The DB plugin's `:replica_readonly` connection authenticates as that role against
+the **same database**, so writes are rejected by Postgres itself — not just by
+Rails. Override any of the names with `TTYA_DEV_DB_*` / `TTYA_DEV_RO_*` env vars.
+
+Re-run `RAILS_ENV=development bundle exec ruby bin/rails db:seed` any time to
+re-grant or top up data; explore the models with
+`RAILS_ENV=development bundle exec ruby bin/rails console`.
+
+### 2. Start the server
+
+```sh
+# from test/dummy
+RAILS_ENV=development bundle exec ruby bin/rails server -p 3000
+```
+
+The MCP endpoint is now at **`http://localhost:3000/mcp`**.
+
+- **Auth (two options):**
+  - **HTTP Basic** — username `dev` / password `secret` (override with
+    `TTYA_DEV_USER` / `TTYA_DEV_PASSWORD`); the username is the logged principal.
+  - **Per-user Bearer token** — each seeded user has an `api_token`. Open
+    <http://localhost:3000/> to see the users and their tokens, and send
+    `Authorization: Bearer <token>` — the audit log then attributes calls to
+    that user's name. (Restart the server after seeding new users so their
+    tokens are picked up.)
+- **Root page:** `http://localhost:3000/` shows DB stats and the per-user tokens.
+- **Plugins enabled:** DB, **Jobs** (Solid Queue adapter), **Flipper**, and **Rake** (allow-listed tasks `demo:stats`, `demo:echo`).
+- **Tools available:** `db.query` (read-only SQL over `users` / `posts` /
+  `comments` / `widgets`), `db.tables`, `db.schema` (columns/indexes/FKs);
+  `jobs.queue_sizes` / `jobs.recent_jobs` /
+  `jobs.failed_jobs` / `jobs.rate_metrics`; `flipper.list_flags` /
+  `read_flag` / `enable_flag` / `disable_flag` / `enabled_flags`; `rake.run`
+  (allow-listed `demo:stats` and `demo:echo[message]`); and custom tools
+  `custom.make_admin` / `custom.toggle_active` (which write user state).
+- **Seed data also includes** 3 feature flags (`new_dashboard` on,
+  `beta_search` 25% of actors, `dark_mode` 10% of the time) and a few queued
+  `HeartbeatJob`s, so the Flipper and Jobs tools have something to show
+  immediately.
+- Audit log lines stream to the server's stdout, one per tool call.
+
+### Background jobs (Solid Queue)
+
+`db:prepare` loads Solid Queue's tables and enqueues a few jobs. To actually
+process them — and run the **`HeartbeatJob` every minute** (`config/recurring.yml`)
+— start the Solid Queue worker in a second terminal:
+
+```sh
+cd test/dummy
+RAILS_ENV=development bundle exec ruby bin/jobs
+```
+
+Watch the queue with the `jobs.*` MCP tools (or `bin/rails console`).
+
+### 3. Connect Claude Code
+
+Add the server with an `Authorization` header — either the Basic credential
+(`base64("dev:secret")` = `ZGV2OnNlY3JldA==`) or a per-user Bearer token copied
+from <http://localhost:3000/>:
+
+```sh
+# Basic
+claude mcp add --transport http talk-to-your-app http://localhost:3000/mcp \
+  --header "Authorization: Basic ZGV2OnNlY3JldA=="
+
+# or a per-user token (audit log attributes calls to that user)
+claude mcp add --transport http talk-to-your-app http://localhost:3000/mcp \
+  --header "Authorization: Bearer <token-from-the-home-page>"
+```
+
+Then in a Claude Code session: `/mcp` lists the server, and you can ask it to
+run a tool — e.g. *"use talk-to-your-app's db.query to count comments per user"*.
+
+### 4. Connect Claude Desktop
+
+Add an entry to your `claude_desktop_config.json` (Settings → Developer → Edit
+Config) and restart the app:
+
+```json
+{
+  "mcpServers": {
+    "talk-to-your-app": {
+      "url": "http://localhost:3000/mcp",
+      "headers": { "Authorization": "Basic ZGV2OnNlY3JldA==" }
+    }
+  }
+}
+```
+
+(Or add it through Settings → Connectors with the same URL and `Authorization`
+header.)
+
+### Removing the server
+
+- **Claude Code:** `claude mcp remove talk-to-your-app` (confirm with `claude mcp list`).
+- **Claude Desktop:** delete the `talk-to-your-app` entry from
+  `claude_desktop_config.json` and restart the app.
+- **Stop the dummy server:** Ctrl-C the `rails server` process. To wipe the demo
+  database, drop it (this also drops the `ttya_test` DB used by the suite, which
+  the tests recreate automatically):
+  `RAILS_ENV=development bundle exec ruby bin/rails db:drop`.
+
+### 5. Verify without a client (curl)
+
+MCP is stateful: `initialize` first to get an `Mcp-Session-Id`, then send it plus
+the protocol version on each call.
+
+```sh
+AUTH="Authorization: Basic ZGV2OnNlY3JldA=="
+
+# initialize → read the Mcp-Session-Id response header
+curl -i -sS -X POST http://localhost:3000/mcp -H "$AUTH" \
+  -H "Content-Type: application/json" -H "Accept: application/json" \
+  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-11-25","capabilities":{},"clientInfo":{"name":"curl","version":"1"}}}'
+
+# then call a tool (substitute the session id)
+curl -sS -X POST http://localhost:3000/mcp -H "$AUTH" \
+  -H "Content-Type: application/json" -H "Accept: application/json" \
+  -H "Mcp-Session-Id: <id-from-above>" -H "MCP-Protocol-Version: 2025-11-25" \
+  -d '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"db.query","arguments":{"sql":"SELECT u.name, p.title, COUNT(c.id) AS comments FROM users u JOIN posts p ON p.user_id = u.id LEFT JOIN comments c ON c.post_id = p.id GROUP BY u.name, p.title ORDER BY u.name","format":"text"}}}'
+```
+
+An unauthenticated request returns `401`; a write (`INSERT`/`UPDATE`/`DELETE`)
+returns a tool error — Postgres rejects it because `db.query` connects as the
+`ttya_dummy_ro` SELECT-only role.
+
+### Generating the initializer in your own app
+
+In a host application, `bundle add talk_to_your_app` then run the install
+generator to drop a commented initializer at
+`config/initializers/talk_to_your_app.rb`:
+
+```sh
+bin/rails generate talk_to_your_app:install
+```
+
+The dummy app's initializer is a worked example of the same configuration.
+
+## Debugging
+
+The [`debug`](https://github.com/ruby/debug) gem is a dev/test dependency. Drop a
+breakpoint anywhere and run the test:
+
+```ruby
+require "debug"
+# ...
+binding.break   # or: debugger
+```
+
+```sh
+bundle exec ruby -Itest -Ilib test/talk_to_your_app/configuration_test.rb
+```
+
+Execution stops at the breakpoint with an interactive console (`c` to continue,
+`n` next, `s` step, `info` for locals).
+
+## Project layout
+
+```
+lib/talk_to_your_app/        # the gem
+  configuration.rb           # TalkToYourApp.configure surface
+  connection_registry.rb     # fail-closed named connections + role switching
+  tool.rb / plugin.rb        # the Tool & Plugin DSLs
+  plugin_registry.rb         # module-level plugin registry
+  auth/                      # Bearer/Basic middleware + validators
+  transport/rails_mount.rb   # builds the MCP::Server + Rack app
+  audit_logger.rb            # one log line per tool call
+  plugins/                   # db, jobs, flipper, rake, custom_tools
+lib/generators/talk_to_your_app/  # install, custom_tool generators
+test/
+  dummy/                     # minimal Rails app for integration tests
+  support/                   # test helpers (mcp_driver, pg_test_db, …)
+  integration/               # full MCP HTTP round-trip tests
+  talk_to_your_app/          # unit tests mirroring lib/
+```
+
+## Working on a plugin or tool
+
+Writing a plugin uses the same public DSL as the bundled ones — see
+[docs/plugin_authoring.md](docs/plugin_authoring.md). The bundled plugins under
+`lib/talk_to_your_app/plugins/` are good references; each has unit tests under
+`test/talk_to_your_app/plugins/` and an end-to-end test under `test/integration/`.
+
+## Conventions
+
+- Every Ruby file starts with `# frozen_string_literal: true`.
+- No linter is configured; match the surrounding style.
+- New behavior ships with tests. Integration tests drive the real MCP stack via
+  `test/support/mcp_driver.rb` (the `initialize` handshake → `tools/list` →
+  `tools/call`).
+- Keep SDK touch points isolated to `transport/rails_mount.rb` and tool
+  compilation; the `mcp` gem is pinned `~> 0.18` (see the README upgrade note).

data/README.md

@@ -1,6 +1,10 @@
 # talk_to_your_app
 
-**Let an AI agent talk to your running Rails app — safely.** `talk_to_your_app` mounts a [Model Context Protocol](https://modelcontextprotocol.io) endpoint on your app, so a tool like Claude can query your database, inspect background jobs, flip feature flags, run health checks, and call tools you write yourself — all behind your auth, all audit-logged, and read-only unless you opt into a write-capable plugin.
+**Let an AI agent talk to your running Rails app — safely.** `talk_to_your_app` mounts a [Model Context Protocol](https://modelcontextprotocol.io) endpoint on your app, so a tool like Claude can query your database, inspect background jobs, flip feature flags, and call tools you write yourself — all behind your auth, all audit-logged, and read-only unless you opt into a write-capable plugin.
+
+[![Watch the 20-second demo](docs/demo_poster.png)](docs/demo.mp4)
+
+> ▶️ **[Watch the 20-second demo](docs/demo.mp4)** — setup, live `db.query`, and read-only enforcement.
 
 It's a thin, Rails-native layer over the official [MCP Ruby SDK](https://github.com/modelcontextprotocol/ruby-sdk): the SDK handles the wire protocol; this gem adds everything Rails — your replicas, your jobs backend, your feature flags — plus the guardrails that make pointing an agent at your app something you can actually ship.
 
@@ -8,7 +12,7 @@ It's a thin, Rails-native layer over the official [MCP Ruby SDK](https://github.
 
 - 🔌 **A Streamable HTTP MCP endpoint in two lines** — `mount TalkToYourApp.rack_app`, and you're live.
 - 🔒 **Fail-closed by design** — API-key or HTTP Basic auth required, optional per-tool authorization, and a read-only DB role the app *refuses to boot without*. Misconfiguration fails at deploy, never on the first request.
-- 🧰 **Six batteries-included plugins** — `db` (read-only SQL + schema introspection), `jobs` (Sidekiq / Solid Queue metrics + health), `flipper` (feature flags), `health` (checks you register), `rake` (allow-listed tasks), and `custom_tools` (your own tools, with a generator).
+- 🧰 **Batteries-included plugins** — `db` (read-only SQL + schema introspection), `sidekiq` and `solid_queue` (background-job metrics), `flipper` (feature flags), `rake` (allow-listed tasks), and `custom_tools` (your own tools, with a generator).
 - 📝 **Every call audit-logged** — principal, IP, params, outcome, duration. Subscribe to persist your own trail.
 - ✍️ **A Ruby DSL + generators** for writing first-class tools of your own in a few lines.
 
@@ -39,16 +43,16 @@ mount TalkToYourApp.rack_app, at: TalkToYourApp.configuration.mount_at
    ```ruby
    TalkToYourApp.configure do |config|
      config.api_keys = { "my-agent" => ENV.fetch("TTYA_KEY") }
-     config.connection :replica_readonly, database: "primary", role: :reading
-     config.plugin :db
+     config.connection :readonly, database: "primary"   # role: defaults to :reading
+     config.plugin :db, connection: :readonly
    end
    ```
 
    `"my-agent"` is the **principal** — the name this token authenticates as, recorded on every audit line. The endpoint is **secure by default**: no tool responds until auth is configured, and the app refuses to boot with a plugin enabled and no auth.
 
-   In production, point `database:` at a genuinely read-only replica (or a Postgres role with `GRANT SELECT` only). The gem enforces read-only at the Rails layer too, but the database role is the real backstop. See [docs/read_only_connections.md](docs/read_only_connections.md) for step-by-step setup on PostgreSQL, MySQL, and SQLite.
+   You declare connections by name and **wire one into each plugin** that needs a database (`connection: :readonly`). `role:` defaults to `:reading`. In production, point `database:` at a genuinely read-only replica (or a Postgres role with `GRANT SELECT` only). The gem enforces read-only at the Rails layer too, but the database role is the real backstop. See [docs/read_only_connections.md](docs/read_only_connections.md) for step-by-step setup on PostgreSQL, MySQL, and SQLite.
 
-2. **Mount it** (see above) and boot the app. If the `:replica_readonly` connection were missing, boot would fail with a clear error.
+2. **Mount it** (see above) and boot the app. If you enable `:db` without wiring a `connection:`, or name one you never declared, boot fails with a clear error.
 
 3. **Point your MCP client** (e.g. Claude Code) at `http://localhost:3000/mcp` with the bearer token `TTYA_KEY`.
 
@@ -62,12 +66,39 @@ mount TalkToYourApp.rack_app, at: TalkToYourApp.configuration.mount_at
 
    Rows come back as JSON, plain text, or an HTML table — the agent picks what it needs.
 
+## Try it locally
+
+Want to see it end to end before wiring it into your own app? The bundled
+`test/dummy` app runs as a real MCP server with HTTP Basic auth, the bundled
+plugins, and seeded data. From a clone of this repo (needs a local PostgreSQL —
+see [LOCAL_DEVELOPMENT.md](LOCAL_DEVELOPMENT.md)):
+
+```sh
+cd test/dummy
+RAILS_ENV=development bundle exec ruby bin/rails db:prepare      # creates the DB + a read-only role, seeds data
+RAILS_ENV=development bundle exec ruby bin/rails server -p 3000  # MCP endpoint at http://localhost:3000/mcp
+```
+
+Then connect Claude Code with one command (Basic auth `dev` / `secret`, where
+`ZGV2OnNlY3JldA==` is `base64("dev:secret")`):
+
+```sh
+claude mcp add --transport http talk-to-your-app http://localhost:3000/mcp \
+  --header "Authorization: Basic ZGV2OnNlY3JldA=="
+```
+
+Run `/mcp` in a Claude Code session to list the tools — e.g. *"use
+talk-to-your-app's db.query to count comments per user."* The full walkthrough
+(per-user tokens, background jobs, curl examples) is in
+**[LOCAL_DEVELOPMENT.md](LOCAL_DEVELOPMENT.md)**.
+
 ## Configuration reference
 
 Every option lives inside `TalkToYourApp.configure`:
 
 | Option | Description |
 | --- | --- |
+| `config.enabled` | Global on/off switch. When `false`, the endpoint serves `503` and boot validation is skipped, so you can ship the initializer and disable per-environment. Default `true`. |
 | `config.mount_at` | Path the endpoint serves from. Default `"/mcp"`. |
 | `config.server_name` | Server name in the `initialize` handshake. Default `"talk_to_your_app"`. |
 | `config.server_title` | Human-friendly server title shown to clients (optional). |
@@ -78,8 +109,9 @@ Every option lives inside `TalkToYourApp.configure`:
 | `config.basic_auth { \|user, pass\| ... }` | HTTP Basic callable returning truthy to authenticate. Wire it to your own user model. |
 | `config.authorize { \|principal, tool\| ... }` | Optional per-principal tool authorization. Returns truthy to allow. Without it, any authenticated principal may call any enabled tool. |
 | `config.allowed_origins` | Origins permitted for browser requests (DNS-rebinding protection). Empty allows non-browser clients. |
-| `config.connection :name, database:, role:, replica:, statement_timeout:` | Declares a named connection. `role:` is `:reading` or `:writing`. |
-| `config.plugin :name, **opts` | Enables a plugin (off by default). |
+| `config.allowed_hosts` | Extra `Host` header values accepted by the transport (DNS-rebinding protection), beyond the always-allowed loopback defaults (`127.0.0.1`, `::1`, `localhost`). A non-loopback deployment **must** list its host here or every request is rejected with "Forbidden: Invalid Host header". Each entry matches a bare host (any port) or full `host:port`. The generated initializer defaults this to `TalkToYourApp.rails_hosts` (your app's own `config.hosts`, literal strings only — add wildcard/regexp hosts explicitly). |
+| `config.connection :name, database:, role:, replica:, statement_timeout:` | Declares a named connection. `role:` defaults to `:reading`; pass `:writing` for a writer. |
+| `config.plugin :name, connection: :conn, **opts` | Enables a plugin (off by default). **Every plugin must declare `connection:`** — a declared connection name, or `connection: false` to opt out (e.g. `:sidekiq`, `:rake`, `:custom_tools` that don't read a wired SQL connection). |
 | `config.logger` | Audit logger. Defaults to `Rails.logger`. Swappable to any Logger-compatible object. |
 | `config.log_level` | Global audit level (default `:info`); overridable per plugin. |
 
@@ -131,108 +163,140 @@ All plugins are **off by default** — enable them explicitly, and an agent can
 
 | Plugin | What an agent can do | Enable with |
 | --- | --- | --- |
-| [DB](#db) | Run read-only SQL; introspect tables, columns, indexes, FKs | `config.plugin :db` |
-| [Jobs](#jobs-read-only) | Read queue sizes, recent/failed jobs, rates, worker health | `config.plugin :jobs, adapter: :sidekiq` |
-| [Flipper](#flipper) | Read and toggle feature flags (global, actor, group, %) | `config.plugin :flipper` |
-| [Health Checks](#health-checks) | Run checks you register — liveness, dependencies, queues | `config.plugin :health` |
-| [Rake](#rake-allow-listed-task-runner) | Run allow-listed rake tasks and read their output | `config.plugin :rake, allowed: [...]` |
-| [Custom Tools](#custom-tools) | Call tools you write yourself (writes allowed) | `config.plugin :custom_tools` |
+| [DB](#db) | Run SQL (read-only by default); introspect tables, columns, indexes, FKs | `config.plugin :db, connection: :readonly` |
+| [Sidekiq](#jobs-read-only) | Read Sidekiq queue sizes, recent/failed jobs, rates | `config.plugin :sidekiq, connection: false` |
+| [Solid Queue](#jobs-read-only) | Read Solid Queue queue sizes, recent/failed jobs, rates | `config.plugin :solid_queue, connection: false` |
+| [Flipper](#flipper) | Read and toggle feature flags (global, actor, group, %) | `config.plugin :flipper, connection: :writer` |
+| [Rake](#rake-allow-listed-task-runner) | Run allow-listed rake tasks and read their output | `config.plugin :rake, connection: false, allowed: [...]` |
+| [Custom Tools](#custom-tools) | Call tools you write yourself (writes allowed) | `config.plugin :custom_tools, connection: false` |
 
 ### DB
 
-A single read-only SQL tool.
+A single SQL tool — read-only by default.
 
 ```ruby
-config.connection :replica_readonly, database: "primary", role: :reading
-config.plugin :db
+# `database:` must map to a SELECT-only DB user or a replica — not your
+# writable primary. That read-only role is the security boundary.
+config.connection :readonly, database: "readonly"   # role: defaults to :reading
+config.plugin :db, connection: :readonly
 ```
 
-- **`db.query`** — `sql` (required), `format` (`json` | `text` | `html`, default `json`). Runs inside a transaction with a per-query statement timeout (default 30s, override with `statement_timeout:` on the connection). The timeout is enforced on PostgreSQL (`statement_timeout`) and MySQL (`max_execution_time`); SQLite has no per-statement timeout. Writes are rejected. Results are capped at **2000 rows by default** — raise or lower it with `config.plugin :db, max_rows: 5000`, or remove the cap with `max_rows: nil` (also accepts `false` or `:unlimited`); when a query exceeds the cap the response is truncated and flagged (`"truncated": true, "max_rows": N`). **Invalid SQL** comes back as a tool error (`isError`) carrying the database's message — it never crashes the request or leaks a stack trace.
-- **`db.tables`** — lists the table names in the read-only database.
+- **`db.query`** — `sql` (required), `format` (`json` | `text` | `html`, default `json`). Runs inside a transaction with a per-query statement timeout (default 30s, override with `statement_timeout:` on the connection). The timeout is enforced on PostgreSQL (`statement_timeout`) and MySQL (`max_execution_time`); SQLite has no per-statement timeout. **On a `:reading` connection (the default) writes are rejected by the read-only DB role** — the gem does not parse SQL (see [Read-only is enforced by the database](#read-only-is-enforced-by-the-database)). Results are capped at **2000 rows by default** — raise or lower it with `config.plugin :db, connection: :readonly, max_rows: 5000`, or remove the cap with `max_rows: nil` (also accepts `false` or `:unlimited`); when a query exceeds the cap the response is truncated and flagged (`"truncated": true, "max_rows": N`). **Invalid SQL** comes back as a tool error (`isError`) carrying the database's message — it never crashes the request or leaks a stack trace.
+- **`db.tables`** — lists the table names in the database.
 - **`db.schema`** — `table` (required): the table's columns, primary key, indexes, and foreign keys.
 
 > **Discovering the schema.** Point the model at your `db/schema.rb` or `db/structure.sql` so it knows the tables and columns before querying — or let it call `db.tables` / `db.schema` to introspect the live database directly.
 
 Setting up the read-only connection for each database engine is covered in **[docs/read_only_connections.md](docs/read_only_connections.md)**.
 
-### Jobs (read-only)
+#### Read-only is enforced by the database
 
-Common metrics across job backends. Declare which adapter you run:
+`db.query` does **not** parse or sanitize SQL, and you should not treat Rails' own write-protection as a security boundary. Rails decides "is this a write?" with a leading-keyword check, so statements that *start* with a read keyword but modify data slip through it:
 
-```ruby
-config.plugin :jobs, adapter: :sidekiq    # or :solid_queue
+```sql
+-- starts with WITH/SELECT, so Rails classifies it as a read — but it writes:
+WITH gone AS (DELETE FROM users RETURNING *) SELECT count(*) FROM gone;
+SELECT 1; UPDATE accounts SET balance = 0;   -- stacked statement (PostgreSQL)
 ```
 
-- **`jobs.queue_sizes`**, **`jobs.recent_jobs`** (`limit`, ≤500), **`jobs.failed_jobs`** (`limit`, ≤500), **`jobs.rate_metrics`** (`window` seconds, default 1800).
-- **`jobs.health`** — worker/queue health: running processes, threads/concurrency, and pending/claimed counts. The shape is **adapter-specific** (Sidekiq reports processes + concurrency + set sizes; Solid Queue reports processes + pending/claimed/scheduled/failed), with an `adapter` key to branch on.
+The **only** thing that reliably stops these is the database itself. Point the `:reading` connection at a **genuinely read-only DB account** — then a write fails at the server no matter how the SQL is shaped:
 
-Adapters return a stable shape regardless of backend. Boot fails if the adapter is unset, unknown, or its gem is missing.
+- **PostgreSQL** — create a role with no write grants and use it for the reader:
+  ```sql
+  CREATE ROLE app_readonly LOGIN PASSWORD '…';
+  GRANT CONNECT ON DATABASE app_production TO app_readonly;
+  GRANT USAGE ON SCHEMA public TO app_readonly;
+  GRANT SELECT ON ALL TABLES IN SCHEMA public TO app_readonly;
+  ALTER DEFAULT PRIVILEGES IN SCHEMA public GRANT SELECT ON TABLES TO app_readonly;
+  -- optional belt-and-suspenders: ALTER ROLE app_readonly SET default_transaction_read_only = on;
+  ```
+  …or simply point `:reading` at a **physical read replica**, which is read-only by construction.
+- **MySQL** — `GRANT SELECT ON app_production.* TO 'app_readonly'@'%';` (grant `SELECT` only), or use a replica.
 
-### Flipper
+Then declare that account as the reader and add the `db` plugin:
 
-Read and toggle feature flags, globally or per actor.
+```ruby
+# database.yml has a `readonly` entry using the SELECT-only credentials above
+config.connection :readonly, database: "readonly"   # role: defaults to :reading
+config.plugin :db, connection: :readonly
+```
+
+> ⚠️ Do **not** point a `:reading` connection at your writable primary. If the account can write, a crafted CTE or stacked statement will write — the gem cannot prevent it. The read-only role is the boundary; everything else is convenience.
+
+#### Running `:db` against a writable connection
+
+`db.query` runs read-only as shipped. If you deliberately wire a **`:writing`** connection, `db.query` can execute arbitrary writes — `UPDATE`, `INSERT`, `DELETE`, even DDL:
 
 ```ruby
-config.connection :flipper_writer, database: "primary", role: :writing
-config.plugin :flipper
+config.connection :writer, database: "primary", role: :writing
+config.plugin :db, connection: :writer   # db.query can now write — logs a loud boot warning
 ```
 
-- **`flipper.list_flags`** — names of all configured flags.
-- **`flipper.read_flag`** — a flag's effective state plus its full per-gate configuration. Optional `actor_class` + `actor_id` reads the state for that actor.
-- **`flipper.enable_flag`** / **`flipper.disable_flag`** — toggle a flag across a gate: global (default), an actor (`actor_class` + `actor_id`), a registered `group`, or a `percentage` rollout (`percentage_type`: `actors` or `time`). Each returns `{ name, enabled, gate_type, gates }` — `gate_type` is the targeted gate (`boolean`, `actor`, `group`, `percentage_of_actors`, `percentage_of_time`) and `gates` is the flag's full per-gate configuration.
-- **`flipper.enabled_flags`** — the currently-enabled flags with their gates and last-change timestamps, for inspection. (Flipper stores no enable/disable history; `updated_at` is the last feature change, available with the ActiveRecord adapter.)
+This is a deliberate, two-step opt-in (declare a `role: :writing` connection **and** wire it in); the gem logs a warning at boot but does not stop you. Before enabling it, understand what it does **not** give you:
 
-Declaring `:flipper_writer` is required (the gem refuses to boot without it) and documents that flag writes need a writable connection, kept separate from the DB plugin's read-only role. Flipper itself reads and writes through whatever adapter you configure for it (e.g. `flipper-active_record`); point that adapter at the same writable database.
+- **`config.authorize` cannot distinguish reads from writes.** The tool is always `"db.query"`, so an authorizer like `tool.start_with?("db.")` permits `SELECT` and `DELETE` identically. The real access control is the **database user's privileges** — grant only what the writes you intend require.
+- **Full SQL, including literal values, is written to the audit log.** Write statements with sensitive literals (`UPDATE users SET token = '…'`) appear in every audit destination. Scope or filter your log sinks accordingly.
+- The gem still does **not** parse SQL. Nothing inspects or restricts the statement beyond the connection's role.
 
-### Health Checks
+Prefer a read-only connection unless you specifically need writes.
 
-On-demand checks you register in Ruby — liveness, dependency reachability, queue depth, anything you can express. Each returns JSON (a Hash) with a `status:` plus whatever values you want to surface (or a bare `true`/`false`).
+### Jobs (read-only)
+
+Background-job metrics, as one plugin per backend — `:sidekiq` and
+`:solid_queue`. Enable whichever you run (or both, e.g. mid-migration). The
+backends read Redis / their own tables, not a wired SQL connection, so enable
+them with `connection: false`:
 
 ```ruby
-config.plugin :health
+config.plugin :sidekiq, connection: false
+config.plugin :solid_queue, connection: false   # both may run at once
 ```
 
-Scaffold a check with the generator (creates `app/talk_to_your_app/health/<name>.rb`):
+Each plugin exposes four adapter-namespaced tools:
 
-```sh
-bin/rails generate talk_to_your_app:health_check Database
-```
+- **Sidekiq** — `sidekiq.queue_sizes`, `sidekiq.recent_jobs` (`limit`, ≤500), `sidekiq.failed_jobs` (`limit`, ≤500), `sidekiq.rate_metrics` (`window` seconds, default 1800).
+- **Solid Queue** — `solid_queue.queue_sizes`, `solid_queue.recent_jobs`, `solid_queue.failed_jobs`, `solid_queue.rate_metrics` (same arguments).
+
+Both backends return the same response shape. Boot fails if the backend's gem is missing.
+
+### Flipper
+
+Read and toggle feature flags, globally or per actor.
 
 ```ruby
-# app/talk_to_your_app/health/database.rb
-TalkToYourApp::Health.register(:database, description: "Primary DB connectivity and row counts") do
-  {
-    status:  :pass,
-    adapter: ActiveRecord::Base.connection.adapter_name,
-    users:   User.count,
-    posts:   Post.count,
-  }
-end
+config.connection :flipper_writer, database: "primary", role: :writing
+config.plugin :flipper, connection: :flipper_writer
 ```
 
-- **`health.list`** — the registered checks with their descriptions.
-- **`health.run`** (`name`) — runs one check and returns its result. A check that raises reports `status: "error"` rather than crashing the request. No scheduling, aggregation, or alerting — just on-demand evaluation.
-- Drop one check per file under `app/talk_to_your_app/health/` and the plugin loads them automatically. Checks registered anywhere else at boot (e.g. an initializer) work too.
-- Files there load with `require` (not Zeitwerk-reloaded), so restart to pick up new or edited checks. A file that fails to load is logged and skipped — the others still register.
+Flipper writes flag state, so it requires a connection declared `role: :writing` — boot fails on a `:reading` connection.
+
+- **`flipper.list_flags`** — names of all configured flags.
+- **`flipper.read_flag`** — a flag's effective state plus its full per-gate configuration. Optional `actor_class` + `actor_id` reads the state for that actor.
+- **`flipper.enable_flag`** / **`flipper.disable_flag`** — toggle a flag across a gate: global (default), an actor (`actor_class` + `actor_id`), a registered `group`, or a `percentage` rollout (`percentage_type`: `actors` or `time`). Each returns `{ name, enabled, gate_type, gates }` — `gate_type` is the targeted gate (`boolean`, `actor`, `group`, `percentage_of_actors`, `percentage_of_time`) and `gates` is the flag's full per-gate configuration.
+- **`flipper.enabled_flags`** — the currently-enabled flags with their gates and last-change timestamps, for inspection. (Flipper stores no enable/disable history; `updated_at` is the last feature change, available with the ActiveRecord adapter.)
+
+Declaring `:flipper_writer` is required (the gem refuses to boot without it) and documents that flag writes need a writable connection, kept separate from the DB plugin's read-only role. Flipper itself reads and writes through whatever adapter you configure for it (e.g. `flipper-active_record`); point that adapter at the same writable database.
 
 ### Rake (allow-listed task runner)
 
 Runs operator-approved rake tasks and returns their status and output.
 
 ```ruby
-config.plugin :rake, allowed: ["stats", "report:generate"]
+config.plugin :rake, connection: false, allowed: ["stats", "report:generate"]
+config.plugin :rake, connection: false, allowed: [...], timeout: 60   # per-task seconds, default 20
 ```
 
-- **`rake.run`** — `task` (required, must be on the `allowed:` list), `args` (optional array of positional arguments → `task[arg1,arg2]`). Returns JSON `{ task, status, exit_code, output, error }`. The task runs in a subprocess (`bundle exec rake`), so arguments cannot inject shell commands.
+- **`rake.run`** — `task` (required, must be on the `allowed:` list), `args` (optional array of positional arguments → `task[arg1,arg2]`). Returns JSON `{ task, status, exit_code, output, error }`. The task runs in a subprocess (`bundle exec rake`), so arguments cannot inject shell commands. A task that runs longer than `timeout:` (default 20s) is hard-killed and returned as a tool error, so a hung task can't pin the web thread.
 
 > ⚠️ **Security.** Rake tasks can do anything, so this plugin is **fail-closed and allow-list-only**: it refuses to boot without a non-empty `allowed:` list, and refuses any task not on it. The allow-list is the security boundary — keep it tight and prefer read-only/reporting tasks. Combine with `config.authorize` to scope it to specific principals.
 
 ### Custom Tools
 
-Write your own tools by subclassing `TalkToYourApp::CustomTool` — the full Tool DSL, with typed arguments, and **writes allowed** (unlike the read-only DB plugin). Every subclass is exposed automatically; no explicit registration.
+Write your own tools by subclassing `TalkToYourApp::Tool` — the same base class the bundled tools use, with typed arguments and **writes allowed** (unlike the read-only DB plugin). Drop one per file in `app/talk_to_your_app/custom_tools/` and it's exposed automatically; no explicit registration.
 
 ```ruby
-config.plugin :custom_tools
+config.plugin :custom_tools, connection: false          # tools call ctx.connection(:name) explicitly
+config.plugin :custom_tools, connection: :read          # ...or wire a default; ctx.connection (no arg) uses it
 ```
 
 Scaffold one with the generator (creates `app/talk_to_your_app/custom_tools/<name>.rb`, exposed as `custom.<name>`):
@@ -243,7 +307,7 @@ bin/rails generate talk_to_your_app:custom_tool MakeAdmin
 
 ```ruby
 # app/talk_to_your_app/custom_tools/make_admin.rb
-class MakeAdmin < TalkToYourApp::CustomTool
+class MakeAdmin < TalkToYourApp::Tool
   name        "custom.make_admin"
   description "Grant admin to a user by id."
   argument    :user_id, :integer, required: true
@@ -256,7 +320,12 @@ class MakeAdmin < TalkToYourApp::CustomTool
 end
 ```
 
-- The tool list is dynamic — whatever `CustomTool` subclasses are loaded. Files in `app/talk_to_your_app/custom_tools/` load automatically (restart to pick up edits); tools defined elsewhere just need to be loaded at boot so they register before the endpoint is built.
+Namespaced generator paths are reflected in the tool name. For example,
+`bin/rails generate talk_to_your_app:custom_tool Admin/MakeAdmin` creates
+`app/talk_to_your_app/custom_tools/admin/make_admin.rb` and exposes
+`custom.admin.make_admin`.
+
+- The tool list is dynamic — one `Tool` subclass per file in `app/talk_to_your_app/custom_tools/`, loaded automatically (restart to pick up new or edited tools). Only tools in that directory are exposed by this plugin; `Tool` subclasses defined elsewhere are not.
 - Because custom tools can do anything the host app allows, including writes, enable them only when you trust the authenticated principals and scope with `config.authorize`. Every call is still audit-logged.
 
 ## Writing your own plugin