rubino-agent 0.3.0

data/docs/getting-started.md

@@ -0,0 +1,143 @@
+# Getting started
+
+From nothing to a working first answer in about five minutes. This is the happy path; the model/key decision is made interactively, not by hand-editing YAML.
+
+## 1. Install
+
+The fastest path on Linux (x86_64 / arm64) is the one-line installer. It installs a compatible Ruby via [`rv`](https://github.com/spinel-coop/rv), then the gem — all in user space, no sudo:
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/Jhonnyr97/rubino-agent/main/install.sh | bash
+```
+
+Piping a script into your shell runs whatever it contains, so review it first if you like:
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/Jhonnyr97/rubino-agent/main/install.sh -o install.sh
+less install.sh && bash install.sh
+```
+
+The installer is idempotent (safe to re-run) and prints the exact `PATH` line for the `rubino` executable when it finishes.
+
+**Already manage Ruby yourself?** Requirements are Ruby >= 3.1 and SQLite3; then:
+
+```bash
+gem install rubino-agent
+```
+
+Verify the binary is on your `PATH`:
+
+```bash
+rubino version
+```
+
+In a development checkout, prefix commands with `bundle exec` (`bundle exec rubino ...`).
+
+## 2. Run the setup wizard
+
+```bash
+rubino setup
+```
+
+`setup` creates the home directory (`~/.rubino`, mode `0700`), a default `config.yml` (`0600`), an `.env` template (`0600`), and initializes the SQLite database with all migrations. Then, **if no usable API key is configured and you're on a real terminal**, it launches the onboarding wizard:
+
+```
+Welcome to rubino — let's get you connected to a model.
+No API key is configured yet. Pick a provider (or press Enter to skip).
+
+  1) OpenAI (GPT) — recommended default
+  2) MiniMax (Anthropic-compatible)
+  3) Anthropic (Claude)
+  4) Google (Gemini)
+  5) OpenAI-compatible gateway
+Choose a provider [1-5, Enter to skip]: 1
+Paste your OPENAI_API_KEY (input hidden; Enter to skip): ••••••••
+Configured OpenAI (GPT) — recommended default with model gpt-4.1.
+Saved to ~/.rubino/config.yml and ~/.rubino/.env.
+```
+
+What the wizard does, exactly:
+
+- Writes `model.default` and `model.provider` for the chosen provider into `config.yml`.
+- Writes any provider block it needs (e.g. MiniMax sets `providers.minimax.base_url` + `anthropic_compatible: true` + `api_key: ${MINIMAX_API_KEY}`).
+- Appends `KEY=value` to `~/.rubino/.env` (mode `0600`); the key is **never echoed back** and is exported into the current process so the very next message works.
+- The **OpenAI-compatible gateway** option additionally asks for the gateway base URL.
+
+The defaults written per provider:
+
+| Choice | provider | default model | key var |
+|---|---|---|---|
+| OpenAI (default) | `openai` | `gpt-4.1` | `OPENAI_API_KEY` |
+| MiniMax | `minimax` | `MiniMax-M2.7` | `MINIMAX_API_KEY` |
+| Anthropic | `anthropic` | `claude-sonnet-4-5` | `ANTHROPIC_API_KEY` |
+| Google | `google` | `gemini-2.5-pro` | `GEMINI_API_KEY` |
+| OpenAI-compatible gateway | `gateway` | `auto` | `OPENAI_API_KEY` |
+
+Press **Enter** at the provider prompt to skip. You can also configure things by hand — see [models-and-keys.md](models-and-keys.md).
+
+## 3. Start chatting
+
+```bash
+rubino chat
+```
+
+The first thing you see is a banner with the workspace, git branch, and model. The input line leads with a red `▍` rail and a clean `❯` caret; the dim status bar underneath shows the session mode, model, and context saturation. Then ask something:
+
+```
+▍❯ what does this project do?
+ default · MiniMax-M3 · ctx ~0/128k
+```
+
+> If you skipped the wizard during `setup`, a bare `rubino chat` re-runs it before the first turn (when on a TTY). If you're piping input or using `-q`, there's no prompt to run — instead you get a clear, actionable error telling you how to set a key (see below).
+
+## 4. Make a first edit
+
+Ask the agent to change something:
+
+```
+▍❯ add a docstring to the top of lib/foo.rb
+```
+
+When the agent wants to run `shell` (or any approval-gated tool), it pauses and asks for your decision. Approve once, approve for the session, or deny — see [security.md](security.md) for the full approval model.
+
+You can keep typing while the agent works: **Enter** interrupts the current turn and runs your line next; **Alt+Enter** (or `/queued <message>`) queues it to run after the turn finishes. See [commands.md](commands.md#typing-while-the-agent-is-working).
+
+## 5. Exit and resume
+
+Type `exit` (or `/exit`, Ctrl+D, or a double Ctrl+C) to end the session. On exit you get a resume hint:
+
+```
+Resume with: rubino chat --resume "my session title"
+```
+
+Resuming:
+
+- `rubino chat` — a **bare** interactive chat auto-resumes your most recent resumable session and replays its history.
+- `rubino chat --new` — force a fresh session instead.
+- `rubino chat --continue` (`-c`) — resume the most recent session explicitly.
+- `rubino chat --resume <id|title>` (`-r`) — resume a specific session.
+
+In-chat, `/sessions` lists recent sessions and resumes one in place, and `/new` starts a fresh one without leaving the REPL.
+
+## If the first message fails
+
+A brand-new user with no key used to see ~80 seconds of silent retries then an empty answer. That trap is fixed: the run now fails fast with guidance. In a non-interactive context (e.g. `rubino prompt "hi"` with no key) you'll see:
+
+```
+No API key configured for provider 'openai' (model openai/gpt-4.1).
+Set it up one of these ways:
+  • run `rubino setup` for a guided first-run setup, or
+  • add OPENAI_API_KEY=<your-key> to ~/.rubino/.env, or
+  • set providers.openai.api_key in ~/.rubino/config.yml.
+```
+
+(The shipped default model `openai/gpt-4.1` resolves to OpenRouter in ruby_llm's registry; this is why a first run without a key or the right provider fails. The cleanest fix is `rubino setup`. See [models-and-keys.md](models-and-keys.md) and [troubleshooting.md](troubleshooting.md).)
+
+Run `rubino doctor` at any time to check config, the resolved provider, credentials, and database health.
+
+## Next steps
+
+- [Models & keys](models-and-keys.md) — per-provider setup blocks and the default→OpenRouter note.
+- [Commands](commands.md) — every CLI subcommand and slash command.
+- [Configuration](configuration.md) — full reference, env vars, precedence.
+- [Tools](tools.md) — what the agent can do and how each tool is gated.

data/docs/jobs.md

@@ -0,0 +1,332 @@
+# Jobs
+
+Background work in rubino is split into two surfaces that share the `Rubino::Jobs::*` namespace but operate independently:
+
+1. **Internal background queue** — async side-effects the agent enqueues for itself (memory extraction, context compaction, session summarization, retention sweeps).
+2. **Cron jobs** — user-defined schedules that fire fresh agent runs on a cron expression, with optional webhook delivery on completion. HTTP surface lives at [`/v1/jobs`](api/v1.md#cron-jobs).
+
+This doc describes both, plus the **Backend Adapter contract** that the queue and the scheduler are designed to be plugged into so the gem can be hosted on Sidekiq / SolidQueue / GoodJob / ActiveJob without rewriting handlers.
+
+---
+
+## Internal background queue
+
+### Purpose
+
+Defer slow or out-of-band work off the request and chat paths. Anything an agent doesn't need to block on — extracting memories from a finished turn, compacting a session that crossed the threshold, GC'ing ended sessions — goes through the queue.
+
+### Storage (default `Sqlite` backend)
+
+```sql
+CREATE TABLE jobs (
+  id           text PRIMARY KEY,        -- uuid
+  type         text NOT NULL,           -- Jobs::Registry key
+  status       text NOT NULL,           -- queued | running | completed | failed | dead
+  priority     integer NOT NULL,        -- lower runs first
+  payload_json text NOT NULL,           -- JSON-serialised hash
+  attempts     integer NOT NULL,
+  max_attempts integer NOT NULL,
+  run_at       text NOT NULL,           -- iso8601, "not before"
+  locked_at    text,
+  locked_by    text,                    -- worker_id
+  last_error   text,
+  created_at   text NOT NULL,
+  updated_at   text NOT NULL
+);
+
+CREATE TABLE job_runs (
+  id          text PRIMARY KEY,         -- uuid, one row per execution attempt
+  job_id      text NOT NULL,
+  status      text NOT NULL,
+  started_at  text,
+  finished_at text,
+  error       text
+);
+```
+
+### Lifecycle
+
+```
+enqueue ──► (status=queued) ──► dequeue (worker locks row)
+                                       │
+                                       ▼
+                                  handler.perform(payload)
+                                       │
+                            ┌──────────┴───────────┐
+                            ▼                      ▼
+                    Queue#complete!          Queue#fail!(error:)
+                    status=completed         attempts += 1
+                                             retry_at = now + backoff·attempts
+                                             status=queued (or dead at max_attempts)
+```
+
+Retry uses linear backoff: `retry_backoff_seconds * attempts`. After `max_attempts` the row stays at `status=dead` for inspection — nothing reaps it automatically.
+
+### Execution modes
+
+`config.jobs_mode` selects how enqueued jobs actually run:
+
+| Mode | Behavior | When to use |
+|---|---|---|
+| `inline` | `Queue#enqueue` runs the handler synchronously in the same call stack. A failed inline job is marked terminal (`failed`) rather than re-queued, since nothing drains it. | dev, tests, smoke runs |
+| `manual` | enqueue only — nothing runs until `rubino jobs process` is invoked. | air-gapped or CI batch flows |
+| `worker` | a long-running `rubino jobs worker` polls and dequeues. | production single-process |
+
+The worker is a single-threaded poll loop with `SIGINT`/`SIGTERM` graceful stop. It is not safe to run more than one worker per SQLite file — locking is row-level but `WAL` contention will dominate. Multi-process scaling is what the [Backend Adapter](#backend-adapter-planned-design) section is for.
+
+### Handler contract
+
+A handler is any class that responds to `#perform(payload)`. The Registry maps a type string → handler class:
+
+```ruby
+module Rubino
+  module Jobs
+    module Handlers
+      class MyJob
+        def perform(payload)
+          # payload comes back as a symbol-keyed Hash
+          session_id = payload[:session_id]
+          # ...
+        end
+      end
+    end
+  end
+end
+
+Rubino::Jobs::Registry.register("MyJob", Rubino::Jobs::Handlers::MyJob)
+```
+
+Enqueue:
+
+```ruby
+Rubino::Jobs::Queue.new.enqueue("MyJob", session_id: "abc")
+```
+
+### Built-in handlers
+
+| Type | Handler | Payload | Side-effect |
+|---|---|---|---|
+| `ExtractMemoryJob` | `Handlers::ExtractMemoryJob` | `{session_id}` | `Memory::Extractor#extract_from_session` |
+| `CompactSessionJob` | `Handlers::CompactSessionJob` | `{session_id}` | `Context::Compressor#compact!` |
+| `SummarizeSessionJob` | `Handlers::SummarizeSessionJob` | `{session_id}` | `Context::SummaryBuilder#build_and_save!` |
+| `CleanupSessionsJob` | `Handlers::CleanupSessionsJob` | `{retention_days?}` | deletes `sessions` rows with `status="ended"` older than retention (default 30d) |
+| `DistillSkillJob` | `Handlers::DistillSkillJob` | `{session_id}` | post-turn skill distillation — one aux-LLM call distils a tool-heavy turn into a reusable `SKILL.md` (gated on `skills.auto_distill`; see [skills.md](skills.md#creating-skills)) |
+
+### CLI
+
+```bash
+rubino jobs list          # show recent rows from jobs table
+rubino jobs process       # drain queued rows once (uses Runner#run_pending)
+rubino jobs worker        # start the polling worker (long-running)
+```
+
+In an interactive chat, `/jobs` shows the same list (with status counts) and
+`/jobs <id>` one job in full, including its last error — see
+[commands.md](commands.md#jobs-in-chat-jobs). Running jobs stays CLI-only.
+
+---
+
+## Cron jobs
+
+User-defined cron schedules, persisted in the `cron_jobs` table, dispatched by `Jobs::Scheduler` — a process-wide singleton wrapping `rufus-scheduler`.
+
+Each cron tick:
+
+1. Creates a fresh `Session` (source=`"cron"`).
+2. Creates a `Run` stamped with `cron_job_id`.
+3. Hands the run to `Run::Executor#start`.
+4. On completion: optionally posts a payload to `RUBINO_WEBHOOK_URL` when `deliver: "webhook"`.
+
+Configuration is HTTP-only — there is no YAML loader for cron jobs. Full request/response shapes are in [`docs/api/v1.md`](api/v1.md#cron-jobs); the routes are:
+
+```
+POST   /v1/jobs                    # create
+GET    /v1/jobs                    # list
+GET    /v1/jobs/:id                # show
+PATCH  /v1/jobs/:id                # update
+DELETE /v1/jobs/:id                # delete + unschedule
+POST   /v1/jobs/:id/pause          # disable + unschedule
+POST   /v1/jobs/:id/resume         # enable + reschedule
+POST   /v1/jobs/:id/trigger        # fire once now
+```
+
+### Scheduler boot
+
+`Jobs::Scheduler.instance.load_all!` is called once at server boot. It loads every `enabled: true` row from `cron_jobs` and registers a rufus cron handle for each.
+
+```ruby
+scheduler = Rubino::Jobs::Scheduler.instance
+scheduler.load_all!                     # at server boot
+scheduler.schedule(job_row)             # after POST /v1/jobs
+scheduler.unschedule(job_id)            # after DELETE
+scheduler.trigger(job_id)               # one-shot
+scheduler.shutdown!                     # at server stop
+```
+
+### Webhook delivery
+
+`Jobs::WebhookDelivery` is a thin Faraday + faraday-retry client. Best-effort: every failure path (no URL, non-2xx, transport error) is logged and counted, never raised.
+
+| Setting | Value |
+|---|---|
+| URL | `RUBINO_WEBHOOK_URL` env (single URL for the whole process) |
+| Timeout | 10s |
+| Retry | 2 attempts, 0.5s initial interval, exponential backoff factor 2 |
+| Retry triggers | `Faraday::TimeoutError`, `Faraday::ConnectionFailed` |
+| Payload | `{ job_id, job_name, run_id, status, session_id }` |
+| Metrics | `webhook_deliveries_total{outcome="ok"|"http_error"|"error"}` |
+
+Per-job webhook URLs and signed payloads are planned.
+
+### Multi-process limitation
+
+Because rufus lives in the Ruby heap, **every Puma worker** would run **every cron tick** if you scaled `rubino server` horizontally. The scheduler currently ships as single-instance only. The [Backend Adapter](#backend-adapter-planned-design) section sketches what cluster-safe scheduling looks like.
+
+---
+
+## Backend Adapter (planned design)
+
+The internal queue today is hardwired to SQLite via Sequel. For real production deployments — multi-process Puma, k8s pods, heavy fanout — the natural move is to plug Sidekiq / SolidQueue / GoodJob / Resque underneath without rewriting any handler.
+
+The contract below is **not implemented yet**. It is documented so that:
+
+1. Today's `Jobs::Queue` keeps a stable public method set (`enqueue / find / list / pending_count`) that can become the adapter facade later.
+2. Anyone writing a new handler today knows what *not* to depend on (DB queries on `:jobs`, transaction semantics, Sequel handles).
+3. When the adapter lands, the migration is a config flip, not a rewrite.
+
+### `Jobs::Backend` contract
+
+```ruby
+module Rubino
+  module Jobs
+    # Single point of contact between Jobs::Queue (a thin facade once this
+    # ships) and whatever runs the work in production.
+    #
+    # Implementations MUST be thread-safe AND process-safe. The agent
+    # assumes nothing about how work is durably stored or dispatched —
+    # only that the four methods below behave per their contract.
+    module Backend
+      # Schedule a job for execution.
+      #
+      # @param type     [String]  handler type (matches Jobs::Registry key)
+      # @param payload  [Hash]    JSON-serialisable. No symbols on the wire,
+      #                           no Time objects, no Sequel rows.
+      # @param priority [Integer] lower runs first; semantics are best-effort.
+      # @param run_at   [Time, nil] not-before timestamp; nil means ASAP.
+      # @return [String] backend-specific job id, round-trippable via #find.
+      def enqueue(type:, payload:, priority: 100, run_at: nil); end
+
+      # Look up a single job by the id returned from #enqueue.
+      # @return [Hash, nil] {id:, type:, status:, attempts:, last_error:, ...}
+      def find(id); end
+
+      # Snapshot for /v1/health and `rubino jobs list`.
+      # @return [Hash] e.g. {queued: 4, running: 1, dead: 0, completed: 132}
+      def stats; end
+
+      # Drain up to `limit` queued jobs in-process. Used by `inline` mode
+      # and tests. Adapters with no in-process executor (Sidekiq client-only
+      # mode) MAY raise NotImplementedError.
+      def drain!(limit: 100); end
+
+      # Optional. GC for completed/dead rows. Operators call this via
+      # `rubino jobs cleanup`. Implementations without a "completed"
+      # state (e.g. fire-and-forget transports) may no-op.
+      def purge_completed!(older_than:); end
+    end
+  end
+end
+```
+
+Wire-up:
+
+```ruby
+Rubino.configure do |c|
+  c.jobs_backend = Rubino::Jobs::Backend::Sqlite.new      # current default
+  # c.jobs_backend = MyApp::SidekiqAdapter.new               # opt-in
+end
+```
+
+`Jobs::Queue.new` becomes a façade that delegates to `Rubino.configuration.jobs_backend`. No handler changes; no API changes; `inline` / `manual` / `worker` modes collapse into whatever the adapter exposes.
+
+### Sketch adapters (NOT shipped yet)
+
+Each row below shows the **only file** an integrator would have to write. Handlers stay the same Ruby object with `#perform(payload)`.
+
+| Adapter | Underlying lib | Transport | Retry / DLQ | Cron |
+|---|---|---|---|---|
+| `Backend::Sqlite` | Sequel | SQLite table polling | linear backoff, `dead` status | rufus (in-process) |
+| `Backend::Sidekiq` | sidekiq | Redis | sidekiq retry + DLQ | sidekiq-cron |
+| `Backend::SolidQueue` | solid_queue | ActiveRecord (no Redis) | SolidQueue retry | SolidQueue recurring jobs |
+| `Backend::GoodJob` | good_job | Postgres LISTEN/NOTIFY | GoodJob retry | GoodJob cron |
+| `Backend::ActiveJob` | activejob | host app's queue_adapter | adapter-dependent | adapter-dependent |
+
+Indicative shape (informational only):
+
+```ruby
+# This file would live in the host application — NOT in the gem.
+class MyApp::Jobs::SidekiqAdapter
+  def enqueue(type:, payload:, priority: 100, run_at: nil)
+    handler = Rubino::Jobs::Registry.handler_for(type) or raise "unknown type: #{type}"
+    # Wrap the handler once so Sidekiq has a class with `perform`.
+    job_class = MyApp::Jobs::RubinoSidekiqWrapper
+    args = [type, JSON.generate(payload)]
+    if run_at
+      job_class.perform_at(run_at, *args)
+    else
+      job_class.perform_async(*args)
+    end
+  end
+  # find/stats/drain!/purge_completed! similarly
+end
+```
+
+The wrapper class on the Sidekiq side just dispatches:
+
+```ruby
+class MyApp::Jobs::RubinoSidekiqWrapper
+  include Sidekiq::Job
+  def perform(type, payload_json)
+    payload = JSON.parse(payload_json, symbolize_names: true)
+    Rubino::Jobs::Registry.handler_for(type).new.perform(payload)
+  end
+end
+```
+
+### Cron scheduler adapter (parallel design)
+
+Cron has the same shape. Today rufus is a singleton wrapping in-process callbacks; tomorrow a `Scheduler::Backend` decides whether the tick happens here or somewhere else.
+
+```ruby
+module Rubino::Jobs::Scheduler::Backend
+  def schedule(job);   end   # job row from cron_jobs
+  def unschedule(id);  end
+  def trigger(id);     end   # one-shot now
+  def load_all!;       end   # boot
+  def shutdown!;       end
+end
+```
+
+| Adapter | What ticks the cron |
+|---|---|
+| `Scheduler::Backend::Rufus` | rufus-scheduler in-process (current) |
+| `Scheduler::Backend::SidekiqCron` | sidekiq-cron / sidekiq-scheduler |
+| `Scheduler::Backend::SolidCron` | SolidQueue recurring jobs table |
+| `Scheduler::Backend::Kubernetes` | host cluster's `CronJob` POSTs `/v1/jobs/:id/trigger` on schedule; rubino never schedules anything itself |
+
+In every case the HTTP surface (`/v1/jobs`) does not change. Only **who actually fires the tick** changes.
+
+---
+
+## Non-goals
+
+- **Pluggable backends are designed, not shipped.** The default and only backend is `Sqlite`. The `Jobs::Backend` module above does not exist in the code yet — `Jobs::Queue` is the SQLite implementation directly.
+- **No cluster-safe cron.** The rufus scheduler is single-instance only. Running more than one `rubino server` in front of the same DB will multi-fire every cron job.
+- **No per-job webhook URLs**, no payload signing, no signed JWT-style retry tokens. One URL per process via `RUBINO_WEBHOOK_URL`.
+- **No queue web UI.** `rubino jobs list` and `/v1/jobs` are the only inspection surfaces.
+- **No fan-out, no per-tenant queues, no priority classes.** Priority is a single integer column, best-effort.
+- **No automatic dead-row GC.** Failed-past-max-attempts rows stay at `status=dead` until an operator removes them.
+
+## Why a contract, not just a config flag
+
+The handler classes are the API. As long as `perform(payload)` is stable and idempotent, swapping the backend is a deploy concern, not a rewrite. Documenting the contract now (and keeping `Jobs::Queue`'s public method surface aligned with `Backend`) is what keeps "let's move to Sidekiq" a one-day task instead of a one-month refactor.

data/docs/mcp.md

@@ -0,0 +1,128 @@
+# MCP Integration
+
+> **Status: EXPERIMENTAL.** stdio servers are wired end-to-end (connect at chat boot, tools registered, `doctor`/`tools`/in-chat `/mcp` surfaces). `sse`/`streamable` configs are forwarded to [ruby_llm-mcp](https://github.com/patvice/ruby_llm-mcp) but less battle-tested, and OAuth is **not implemented** on the rubino side (see below). Don't depend on it in production yet.
+
+rubino supports the [Model Context Protocol](https://modelcontextprotocol.io/) via [ruby_llm-mcp](https://github.com/patvice/ruby_llm-mcp).
+
+## Configuration
+
+Configuring at least one server under `mcp.servers` in `config.yml` **is the opt-in** — there is no separate feature flag to flip. Set `mcp.enabled: false` to switch MCP off without deleting the server definitions.
+
+```yaml
+mcp:
+  # enabled: false        # optional kill switch; defaults to true when servers exist
+  servers:
+    # Local server via stdio
+    filesystem:
+      transport: stdio
+      command: "npx"
+      args: ["@modelcontextprotocol/server-filesystem", "/path/to/project"]
+      env:
+        DEBUG: "1"
+
+    # Remote server via SSE
+    remote_api:
+      transport: sse
+      url: "https://mcp.example.com/sse"
+      headers:
+        Authorization: "Bearer {env:MCP_TOKEN}"
+
+    # Remote server via streamable HTTP
+    streaming_api:
+      transport: streamable
+      url: "https://mcp.example.com/api"
+      timeout: 15000
+```
+
+## Transport Types
+
+| Transport | Use Case | Config |
+|-----------|----------|--------|
+| `stdio` | Local MCP servers, CLI tools | `command`, `args`, `env` |
+| `sse` | Web-based servers with Server-Sent Events | `url`, `headers` |
+| `streamable` | HTTP servers with streaming support | `url`, `headers`, `oauth` |
+
+## How It Works
+
+1. At chat boot (and in `rubino tools`), `MCP::Manager` connects to all configured servers — best-effort: a server that fails to start prints a warning and is skipped, it never blocks the session
+2. Each server's tools are wrapped in `MCPToolWrapper` (adapts to `Tools::Base` interface), forwarding the server-declared input schema so the model calls them with the right argument names
+3. Wrapped tools are registered in `Tools::Registry` with a prefix (`servername_toolname`)
+4. The agent can use MCP tools like any built-in tool; a failed MCP call (including a server-side argument rejection) surfaces as an `Error: …` tool result and renders ✗ like any failed built-in tool
+5. `ruby_llm-mcp`'s own log lines (including everything a stdio server prints on its stderr) go to `<home>/logs/mcp.log`, never to stdout — one-shot `rubino prompt` output stays machine-readable
+
+MCP tools are dynamic — they come from whatever servers you configure — so they are not part of the drift-checked built-in tool list in [tools.md](tools.md) and have no `tools.<key>` config gate; disable a server (`/mcp <server> off` for the session, or set `mcp.enabled: false`) to remove its tools.
+
+## Per-Agent Scoping
+
+Control which MCP servers each agent can access in `config.yml`:
+
+```yaml
+agents:
+  explore:
+    mcp_servers: ["filesystem"]   # Only filesystem MCP
+  build:
+    mcp_servers: all              # All MCP servers (default)
+  plan:
+    mcp_servers: []               # No MCP tools
+```
+
+An agent with no `mcp_servers` key sees every server. The YAML string `all` is normalized to `:all`. The scoping is enforced in `Agent::Definition#resolved_tools` — the single seam every consumer of an agent's tool set (chat lifecycle, prompt assembler) goes through — so a scoped agent's model request simply does not contain the out-of-scope servers' tool definitions.
+
+In code (an explicit value here wins over config):
+
+```ruby
+Rubino::Agent::Definition.new(
+  name: "secure_agent",
+  mcp_servers: ["internal_api"]  # Only this server's tools
+)
+```
+
+## Authentication
+
+Remote-server credentials are passed through config: use `headers` (e.g. `Authorization: "Bearer {env:MCP_TOKEN}"`) or the server process `env` for stdio servers.
+
+An `oauth` hash on a `streamable` server is forwarded verbatim to `ruby_llm-mcp` — rubino itself implements **no** OAuth flow: there is no PKCE/browser handshake and no rubino-side token storage (no `~/.rubino/oauth_tokens.json`). Whatever OAuth behavior you get is whatever your installed `ruby_llm-mcp` version provides; treat it as not yet supported.
+
+## Managing from Chat
+
+`/mcp` is the in-chat management surface ([commands.md](commands.md#mcp-servers-mcp)):
+
+```
+/mcp                 # server list: name, transport, reachability, tool count
+/mcp <server>        # drill-in: transport + command/url, health, registered tools, last start error
+/mcp <server> off    # stop the client and deregister its tools for this session
+/mcp <server> on     # (re)start the client and register its tools
+/mcp reload          # re-read config.yml and reconnect every server (no chat restart needed)
+```
+
+`off`/`on` are session-scoped — config is untouched. `/mcp reload` is how a server added to `config.yml` mid-session becomes usable. When servers are configured, `/status` includes an `mcp` line (`2 servers · 1 reachable · 14 tools`).
+
+## Manual Management
+
+```ruby
+# Start all servers
+manager = Rubino::MCP::Manager.new
+manager.start_all!
+
+# Get tools for a specific agent (mcp_servers scoping applied)
+tools = agent_definition.resolved_tools
+
+# Health check
+manager.health_check
+# => [{ name: "filesystem", alive: true }, { name: "api", alive: false }]
+
+# Stop a server
+manager.stop_server("filesystem")
+
+# Stop all
+manager.stop_all!
+```
+
+## CLI
+
+```bash
+rubino doctor   # "Optional (MCP servers, experimental)" section: per-server reachability.
+                # Informational only — an unreachable MCP server never fails doctor.
+rubino tools    # "MCP Tools (experimental)" section: prefixed servername_toolname rows
+                # per server, after the built-in table.
+```