talk_to_your_app 0.1.0.pre.1 → 0.1.0.pre.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: cab6705b5c1fffe989fa665c452b433bc245e3f4f367009714ca36c97b4b55c4
-  data.tar.gz: 21044992a79652e184e174bf867bae2b3569d56420299c96ac3487f5098d2385
+  metadata.gz: 593eb7d10a1e55f810002c8890fe4eb9e650d5001c2f252c17c79c78c70f9b8d
+  data.tar.gz: 73bfc284f8ce0081c3af5d40a1b30e7ed14a644d0340e1c7603f98d07d76ecb7
 SHA512:
-  metadata.gz: 9c1679d7a4b0fcea64c7c3007b6925dd7a7eabb513990b4247b35092b453d0c3f0488d39e511b15593ff43cb5aa4adc6800bc19b71dcc28a92c2a8b4c447a232
-  data.tar.gz: 7855f1866f5fba865424544ae143176e727f569b621e7c5e950e3df592f63c1babb828d82aa6b460e3cf40b5e81966bc3ec82f99832c8997d04b3739409ba2ea
+  metadata.gz: d537fc75c1a3d5e59591829de61792610089e8fb4c55c3327abe8ceb228d26fe27bd8802895785940f84fec29d33e1677c3af85ce078e4ff160e14185cfa4766
+  data.tar.gz: '091db0b41b51ea0dfa3862b3fdade99ae30980c7b80d8c03e323e77be8f957fb7cc34129c79e4e2766f39e056d2f6fac3cecd85287df61ebf4c2dc7861c52dad'

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,6 @@
 # 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.
 
 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 +8,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).
+- 🧰 **Five batteries-included plugins** — `db` (read-only SQL + schema introspection), `jobs` (Sidekiq / Solid Queue 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.
 
@@ -62,6 +62,32 @@ 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`:
@@ -132,9 +158,8 @@ 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` |
+| [Jobs](#jobs-read-only) | Read queue sizes, recent/failed jobs, rates | `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` |
 
@@ -143,11 +168,13 @@ All plugins are **off by default** — enable them explicitly, and an agent can
 A single read-only SQL tool.
 
 ```ruby
-config.connection :replica_readonly, database: "primary", role: :reading
+# `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 :replica_readonly, database: "readonly", role: :reading
 config.plugin :db
 ```
 
-- **`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.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 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, 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.schema`** — `table` (required): the table's columns, primary key, indexes, and foreign keys.
 
@@ -155,6 +182,40 @@ config.plugin :db
 
 Setting up the read-only connection for each database engine is covered in **[docs/read_only_connections.md](docs/read_only_connections.md)**.
 
+#### Read-only is enforced by the database
+
+`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:
+
+```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)
+```
+
+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:
+
+- **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.
+
+Then declare that account as the reader and add the `db` plugin:
+
+```ruby
+# database.yml has a `readonly` entry using the SELECT-only credentials above
+config.connection :replica_readonly, database: "readonly", role: :reading
+config.plugin :db
+```
+
+> ⚠️ Do **not** point `:reading` 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.
+
 ### Jobs (read-only)
 
 Common metrics across job backends. Declare which adapter you run:
@@ -164,7 +225,6 @@ config.plugin :jobs, adapter: :sidekiq    # or :solid_queue
 ```
 
 - **`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.
 
 Adapters return a stable shape regardless of backend. Boot fails if the adapter is unset, unknown, or its gem is missing.
 
@@ -184,52 +244,22 @@ config.plugin :flipper
 
 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.
 
-### Health Checks
-
-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`).
-
-```ruby
-config.plugin :health
-```
-
-Scaffold a check with the generator (creates `app/talk_to_your_app/health/<name>.rb`):
-
-```sh
-bin/rails generate talk_to_your_app:health_check Database
-```
-
-```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
-```
-
-- **`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.
-
 ### 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, 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
@@ -243,7 +273,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 +286,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