riffer 0.39.0 → 0.41.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b1bf92e3bef065a4c07aadb273a7f6770b711c0f15f268726133c841cb3fd510
-  data.tar.gz: d7361c029b98ca819932e2c3d2d53113710bb434ad60092ee0578179fa844c5e
+  metadata.gz: fd309de6be56bd5fbe778bbf277b9125dd63d4ce7b360c3e5e85554a944cb81d
+  data.tar.gz: 965daf888849a0386b2826af572fd95d0a7fb8a4ac6f9f91788acb0254705f8e
 SHA512:
-  metadata.gz: 7f503377743f6629a1423234afb158570dc33ee225c82c0bc46e28938a839fe25b5bdfad6f61da274a8bf81e1e8dd6c505ad826593c5eb269251d47667fe9d7c
-  data.tar.gz: eddabf85e5416c777c3a9a441ce99cd1cb902ec1c339fa7338890ae8cb7e78c5e78628e1b886aea44cdc6228b99299fa3983816e10075d8c28b59229e4c0b376
+  metadata.gz: deedbd28b2c79faceea167422fb69147cb2453d7e06df48c46c2eb1e601068de7b9018026675a973f6de6036373d324d5120fc43269e863dd43ce39b88ee7ea4
+  data.tar.gz: 2007cc98bd5955ae2db4776e72551d546038deea60be3e397a5838e028cd2901465f2fe9c00d944b18e4ce9508599bcd7603ad61e0e75efaa8264793461cf283

data/.agents/architecture.md

@@ -136,7 +136,7 @@ Context flow: `Agent#execute_tool_calls` → `Tools::Runtime#execute(tool_calls,
 
 ### MCP Integration (`lib/riffer/mcp/`)
 
-Register third-party MCP servers globally; agents opt-in by tag via `use_mcp`. Tags are application-defined (manifests may list several; any overlap with `use_mcp` opts in—see `docs/14_MCP.md`).
+Register third-party MCP servers globally; agents opt-in by tag via `use_mcp`. Tags are application-defined (manifests may list several; any overlap with `use_mcp` opts in—see `docs/MCP.md`).
 
 ```ruby
 Riffer::Mcp.register(
@@ -146,7 +146,7 @@ Riffer::Mcp.register(
   discovery_headers: -> { {"Authorization" => "Bearer #{ENV['GITHUB_TOKEN']}"} }
 )
 
-# Optional: per-run tools/call headers (see docs/14_MCP.md)
+# Optional: per-run tools/call headers (see docs/MCP.md)
 Riffer.configure { |c| c.mcp.credentials = ->(manifest:, matched_tags:, context:) { ... } }
 
 class ResearchAgent < Riffer::Agent

data/.agents/code-style.md

@@ -2,9 +2,10 @@
 
 ## Formatting
 
-- Use StandardRB for linting and formatting
-- Custom rules are defined in `.standard.yml`
-- Run `bin/lint` to check, `bin/lint --fix` to auto-fix
+- Use RuboCop for linting and formatting
+- Config lives in `.rubocop.yml`, with cops sorted alphabetically
+- Run `bin/lint` to check, `bin/lint -a` to auto-fix (safe autocorrect), `bin/lint -A` for unsafe autocorrect
+- Never silence violations with inline `rubocop:disable` comments — fix them, or when an exception is genuinely warranted add a narrowly scoped override in `.rubocop.yml` with a comment explaining why
 
 ## Required Header
 

data/.agents/providers.md

@@ -3,11 +3,20 @@
 ## Steps
 
 1. Create `lib/riffer/providers/your_provider.rb` extending `Riffer::Providers::Base`
-2. Implement the required hook methods (see [Custom Providers](../docs/providers/07_CUSTOM_PROVIDERS.md) for the full API)
+2. Implement the required hook methods (see [Custom Providers](../docs/providers/CUSTOM_PROVIDERS.md) for the full API)
 3. Register in `Riffer::Providers::Repository::REPO`
-4. Add provider config to `Riffer::Config` if needed
+4. Add provider config to `Riffer::Config` if needed — a `Struct` with credential members plus a `client` member
 5. Create tests in `test/riffer/providers/your_provider_test.rb`
 
+## Constructor and client contract
+
+- Constructors take **no arguments** — define one only when the provider needs `depends_on`, and give it no parameters. Credentials live in config; never accept them as kwargs or hold them in ivars.
+- Never hold a client ivar; call the private `client` method from `execute_generate`/`execute_stream`. Base resolves: `global_client` (a client instance, or a no-argument Proc resolved on every call) → memoized `build_client`.
+- Providers hold no agent state — no context, no reference to the owning agent. Client selection is process-global by design, so a configured Proc takes no arguments.
+- Implement `build_client` (build the SDK client by reading `Riffer.config.<provider>.<credential>` directly) and override `global_client` to return `Riffer.config.<provider>.client`.
+- **Never pass an SDK an explicit nil credential.** Build the kwargs as a hash and `.compact` it, so an unset value stays _absent_: SDKs distinguish absent from nil to decide whether to read their own env vars, and an explicit nil suppresses that. Passing `base_url: nil` skips `OPENAI_BASE_URL` and pins requests to api.openai.com; passing `region: nil` makes the AWS SDK raise `MissingRegionError` even with `AWS_REGION` exported.
+- **Exception — a provider borrowing another vendor's SDK** (`OpenRouter` and `AzureOpenAI` reuse `::OpenAI::Client`) must keep its credential and endpoint concrete, nil included. Compacting there would let the OpenAI SDK fall back to `OPENAI_API_KEY` / `OPENAI_BASE_URL` and send one vendor's credential to another's endpoint. Compact a key only when the SDK's env fallback for it names the same service the provider talks to.
+
 ## Architecture
 
 The base class uses the **template method** pattern. The public methods `generate_text` and `stream_text` orchestrate the flow, delegating to hook methods that each provider implements:
@@ -42,4 +51,4 @@ Use `depends_on` helper for runtime dependency checking if your provider require
 
 ## Reference
 
-For hook method signatures, structured output handling, file handling, and complete examples, see [Custom Providers](../docs/providers/07_CUSTOM_PROVIDERS.md).
+For hook method signatures, structured output handling, file handling, and complete examples, see [Custom Providers](../docs/providers/CUSTOM_PROVIDERS.md).

data/.agents/rbs-inline.md

@@ -154,8 +154,8 @@ end
 
 ### Where stubs and stdlib deps live
 
-- `sig/_private/` — signatures that must **not** ship. RBS **skips** `_`-prefixed directories in library mode, so consumers never load them; riffer's own `steep check` does (via the `Steepfile`). Two kinds, by predictable path: external-gem signatures are named by gem at the top level (`async.rbs`, `mcp.rbs`, `zeitwerk.rbs`, `openai.rbs`, `anthropic.rbs`, `aws-sdk-core/*` — full stubs for RBS-less gems plus arity patches for the provider SDKs); riffer's own hidden stubs mirror `lib/` under `riffer/` (e.g. `riffer/providers/anthropic.rbs` declares the SDK-typed `@client` ivar).
-- `sig/manual/` — hand-written riffer-only signatures that are **safe to ship**, for the few things rbs-inline can't generate _at all_ (mirroring `lib/`). In practice that's `extend self` modules (`riffer/agent/run.rbs`, `riffer/helpers/call_or_value.rbs`) and modeling an include applied dynamically (`riffer/tools/toolable.rbs`). SDK-free ivars are **not** hand-written here — declare them inline with `# @rbs` (see "Instance variables"). SDK-typed ivars can't ship, so they go in `_private/riffer/providers/` (`@client`).
+- `sig/_private/` — signatures that must **not** ship. RBS **skips** `_`-prefixed directories in library mode, so consumers never load them; riffer's own `steep check` does (via the `Steepfile`). Two kinds, by predictable path: external-gem signatures are named by gem at the top level (`async.rbs`, `mcp.rbs`, `zeitwerk.rbs`, `openai.rbs`, `anthropic.rbs`, `aws-sdk-core/*` — full stubs for RBS-less gems plus arity patches for the provider SDKs); riffer's own hidden stubs mirror `lib/` under `riffer/` (e.g. `riffer/providers/anthropic.rbs` narrows the private `client` method to the SDK-typed client).
+- `sig/manual/` — hand-written riffer-only signatures that are **safe to ship**, for the few things rbs-inline can't generate _at all_ (mirroring `lib/`). In practice that's `extend self` modules (`riffer/agent/run.rbs`, `riffer/helpers/call_or_value.rbs`) and modeling an include applied dynamically (`riffer/tools/toolable.rbs`). SDK-free ivars are **not** hand-written here — declare them inline with `# @rbs` (see "Instance variables"). SDK-typed signatures can't ship, so they go in `_private/riffer/providers/` (the narrowed `client`).
 - `sig/manifest.yaml` — declares the **stdlib** RBS the shipped sigs reference (`uri`, `net-http`) so `rbs -r riffer` resolves them.
 
 ## Workflow

data/.release-please-manifest.json

@@ -1,3 +1,3 @@
 {
-  ".": "0.39.0"
+  ".": "0.41.0"
 }

data/.rubocop.yml

@@ -0,0 +1,112 @@
+plugins:
+  - rubocop-minitest
+  - rubocop-performance
+  - rubocop-rake
+
+# ── Tier 1: house style — settings changed from RuboCop defaults everywhere ──
+
+Layout/BlockAlignment:
+  EnforcedStyleAlignWith: start_of_block
+
+Layout/DotPosition:
+  EnforcedStyle: trailing
+
+Layout/MultilineMethodCallIndentation:
+  EnforcedStyle: indented
+
+Style/HashSyntax:
+  EnforcedShorthandSyntax: either_consistent
+
+Style/NonNilCheck:
+  IncludeSemanticChanges: true
+
+Style/StringLiterals:
+  EnforcedStyle: double_quotes
+
+Style/TrailingCommaInArguments:
+  EnforcedStyleForMultiline: consistent_comma
+
+Style/TrailingCommaInArrayLiteral:
+  EnforcedStyleForMultiline: consistent_comma
+
+Style/TrailingCommaInHashLiteral:
+  EnforcedStyleForMultiline: consistent_comma
+
+# ── Tier 2: shared base — additions and deviations from the house style ──
+
+AllCops:
+  DisabledByDefault: false
+  # Stricter than the house style, which leaves pending cops as warnings;
+  # enabling adopts new cops automatically and kills the warning spam.
+  NewCops: enable
+  SuggestExtensions: false
+
+# Size thresholds are noise; BlockNesting stays — deep nesting is the one
+# limit worth enforcing.
+Metrics:
+  Enabled: false
+
+Metrics/BlockNesting:
+  Enabled: true
+
+# A comment on every class is a "what" — conflicts with the comments rule.
+Style/Documentation:
+  Enabled: false
+
+# The function-module pattern needs a working `private`.
+Style/ModuleFunction:
+  EnforcedStyle: extend_self
+
+# Compact (`class Foo::Bar`) cuts LOC and nesting and ends the nested/compact
+# mix across codebases.
+Style/ClassAndModuleChildren:
+  EnforcedStyle: compact
+
+# Keyword arguments often stay unused to keep signatures uniform across
+# interchangeable implementations.
+Lint/UnusedMethodArgument:
+  AllowUnusedKeywordArguments: true
+
+# Additions, not overrides: RBS-inline annotations must lint.
+Layout/LeadingCommentSpace:
+  AllowRBSInlineAnnotation: true
+
+Layout/LineLength:
+  AllowedPatterns: ['#:']
+
+Minitest/MultipleAssertions:
+  Max: 3
+
+# ── Tier 3: riffer deviations, each with its reason ──
+
+# Tests use deliberately empty blocks: `.each { |_| }` to drain a stream for
+# its side effects, empty `in_span` bodies to assert span lifecycle, and no-op
+# stream doubles.
+Lint/EmptyBlock:
+  Exclude:
+    - test/**/*
+
+# Keyword-argument names are the calling contract for riffer's block-based
+# hooks (tool `execute` blocks, evaluator lambdas, dynamic instructions) —
+# underscore-prefixing a block keyword renames the keyword and breaks callers.
+Lint/UnusedBlockArgument:
+  AllowUnusedKeywordArguments: true
+
+# validate_as_tool! follows the validate!/save! idiom: raise or return true.
+# Its return value is not a predicate.
+Naming/PredicateMethod:
+  AllowBangMethods: true
+
+# has_tool_calls? is shipped public API — renaming it breaks consumers.
+Naming/PredicatePrefix:
+  AllowedMethods:
+    - has_tool_calls?
+
+# Riffer::Messages::Base#+ and Riffer::Providers::TokenUsage#+ merge objects;
+# the cop's `sum` rewrite starts the fold from 0 and raises on non-numeric
+# elements.
+Performance/Sum:
+  Exclude:
+    - lib/riffer/providers/base.rb
+    - lib/riffer/evals/run_result.rb
+    - lib/riffer/evals/scenario_result.rb

data/AGENTS.md

@@ -5,16 +5,16 @@ Ruby gem framework for building AI-powered agents with LLM provider adapters.
 ## Quick Reference
 
 - **Ruby**: 3.3.0+ (CI: 3.3, 3.4, 4.0)
-- **Lint + Test**: `bin/rake` (runs the default task: test + standard + steep:check)
+- **Lint + Test**: `bin/rake` (runs the default task: test + rubocop + steep:check)
 - **Autoloading**: Zeitwerk (file paths must match module/class names)
 - **Model format**: `provider/model` (e.g., `openai/gpt-4`)
-- **Docs**: when adding a public config option or message attribute, update the matching page in `docs/` (e.g., `docs/10_CONFIGURATION.md`, `docs/08_MESSAGES.md`). RDoc ≠ user docs.
+- **Docs**: when adding a public config option or message attribute, update the matching page in `docs/` (e.g., `docs/CONFIGURATION.md`, `docs/MESSAGES.md`). Adding a NEW page under `docs/` also requires a `docs-site/manifest.yml` entry — the site build fails without one. RDoc ≠ user docs.
 
 ## Topic Guides
 
 - [Architecture](.agents/architecture.md) - Core components and project structure
 - [Testing](.agents/testing.md) - Minitest spec DSL and VCR cassettes
-- [Code Style](.agents/code-style.md) - StandardRB, comment, and RDoc conventions
+- [Code Style](.agents/code-style.md) - RuboCop, comment, and RDoc conventions
 - [Providers](.agents/providers.md) - Adding new LLM provider adapters
 - [RBS Inline](.agents/rbs-inline.md) - Type annotations with rbs-inline
 
@@ -24,13 +24,13 @@ All wrappers `exec bundle exec …` under the hood.
 
 | Command         | Description                                  |
 | --------------- | -------------------------------------------- |
-| `bin/rake`      | Default task: test + standard + steep:check  |
+| `bin/rake`      | Default task: test + rubocop + steep:check   |
 | `bin/test`      | Run tests                                    |
-| `bin/lint`      | Check code style (pass `--fix` to auto-fix)  |
+| `bin/lint`      | Check code style (pass `-a` to auto-fix)     |
 | `bin/typecheck` | Run Steep type checker                       |
 | `bin/rbs`       | Generate RBS type signatures                 |
 | `bin/rbs-watch` | Watch and regenerate RBS files               |
-| `bin/docs`      | Build RDoc HTML                              |
+| `bin/docs`      | Build the docs site + API reference          |
 | `bin/build`     | Build the gem package                        |
 | `bin/console`   | Interactive console                          |
 | `bin/setup`     | Install dependencies                         |

data/CHANGELOG.md

@@ -5,6 +5,24 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.41.0](https://github.com/janeapp/riffer/compare/riffer/v0.40.0...riffer/v0.41.0) (2026-08-14)
+
+
+### ⚠ BREAKING CHANGES
+
+* Inference providers no longer support extra configuration parameters (e.g. timeouts). Instead, a provider client object can be defined in the riffer config directly. Credential and endpoint parameters are still supported.
+
+### Features
+
+* config-injected provider clients, retire provider_options ([#391](https://github.com/janeapp/riffer/issues/391)) ([72fa0e3](https://github.com/janeapp/riffer/commit/72fa0e32ff6cfeee29bae9e2618d001cbc387d99))
+
+## [0.40.0](https://github.com/janeapp/riffer/compare/riffer/v0.39.0...riffer/v0.40.0) (2026-08-12)
+
+
+### Features
+
+* replace RDoc guide pages with a static docs site ([#390](https://github.com/janeapp/riffer/issues/390)) ([eef94e1](https://github.com/janeapp/riffer/commit/eef94e140b618ae55a0dea2e0e94cf91462ae169))
+
 ## [0.39.0](https://github.com/janeapp/riffer/compare/riffer/v0.38.1...riffer/v0.39.0) (2026-07-29)
 
 

data/README.md

@@ -45,35 +45,37 @@ puts agent.generate('Hello world')
 
 ## Documentation
 
-For comprehensive documentation, see the [docs](docs/) directory:
-
-- [Overview](docs/01_OVERVIEW.md) - Core concepts and architecture
-- [Getting Started](docs/02_GETTING_STARTED.md) - Installation and first steps
-- [Agents](docs/03_AGENTS.md) - Defining and configuring agents
-- [Agent Lifecycle](docs/04_AGENT_LIFECYCLE.md) - Generate, stream, and responses
-- [Agent Loop](docs/05_AGENT_LOOP.md) - Tool execution flow and stopping
-- [Tools](docs/06_TOOLS.md) - Creating tools for agents
-- [Advanced Tools](docs/07_TOOL_ADVANCED.md) - Timeouts, runtime, and registration
-- [Messages](docs/08_MESSAGES.md) - Message types and formats
-- [Stream Events](docs/09_STREAM_EVENTS.md) - Streaming responses
-- [Configuration](docs/10_CONFIGURATION.md) - Framework configuration
-- [Evals](docs/11_EVALS.md) - Evaluating agent quality
-- [Guardrails](docs/12_GUARDRAILS.md) - Input/output validation
-- [Skills](docs/13_SKILLS.md) - Packaged agent capabilities
-- [MCP](docs/14_MCP.md) - Integrating third-party MCP servers
-- [Serialization](docs/15_SERIALIZATION.md) - Persisting and transferring agent definitions
-- [Tracing](docs/16_TRACING.md) - OpenTelemetry span contract and host wiring
-- [Providers](docs/providers/01_PROVIDERS.md) - LLM provider adapters
+Comprehensive guides live at [riffer.ai](https://riffer.ai):
+
+- [Overview](https://riffer.ai/guides/overview/) - Core concepts and architecture
+- [Getting Started](https://riffer.ai/guides/getting-started/) - Installation and first steps
+- [Agents](https://riffer.ai/guides/agents/) - Defining and configuring agents
+- [Agent Lifecycle](https://riffer.ai/guides/agent-lifecycle/) - Generate, stream, and responses
+- [Agent Loop](https://riffer.ai/guides/agent-loop/) - Tool execution flow and stopping
+- [Tools](https://riffer.ai/guides/tools/) - Creating tools for agents
+- [Advanced Tools](https://riffer.ai/guides/advanced-tools/) - Timeouts, runtime, and registration
+- [Messages](https://riffer.ai/guides/messages/) - Message types and formats
+- [Stream Events](https://riffer.ai/guides/stream-events/) - Streaming responses
+- [Configuration](https://riffer.ai/guides/configuration/) - Framework configuration
+- [Evals](https://riffer.ai/guides/evals/) - Evaluating agent quality
+- [Guardrails](https://riffer.ai/guides/guardrails/) - Input/output validation
+- [Skills](https://riffer.ai/guides/skills/) - Packaged agent capabilities
+- [MCP](https://riffer.ai/guides/mcp/) - Integrating third-party MCP servers
+- [Serialization](https://riffer.ai/guides/serialization/) - Persisting and transferring agent definitions
+- [Tracing](https://riffer.ai/guides/tracing/) - OpenTelemetry span contract and host wiring
+- [Providers](https://riffer.ai/guides/providers/overview/) - LLM provider adapters
+
+The guide sources are in the [docs](docs/) directory.
 
 ### API Reference
 
-Generate the full API documentation with:
+The full API reference is published at [riffer.ai/api](https://riffer.ai/api/). Preview the site locally with:
 
 ```bash
-bin/docs
+bin/rake docs:serve
 ```
 
-Then open `doc/index.html` in your browser.
+Then open <http://localhost:8000>. The site uses root-absolute paths, so it must be served over HTTP — opening `_site/index.html` via `file://` won't work.
 
 ## Development
 
@@ -86,17 +88,17 @@ bin/setup
 Common workflows are wrapped in `bin/`. Each is a thin `exec bundle exec …` script — use them
 instead of typing `bundle exec` yourself:
 
-| Command         | Description                                 |
-| --------------- | ------------------------------------------- |
-| `bin/rake`      | Default task: test + standard + steep:check |
-| `bin/test`      | Run tests                                   |
-| `bin/lint`      | Check code style (pass `--fix` to auto-fix) |
-| `bin/typecheck` | Run Steep type checker                      |
-| `bin/rbs`       | Generate RBS type signatures                |
-| `bin/rbs-watch` | Watch and regenerate RBS files              |
-| `bin/docs`      | Build RDoc HTML                             |
-| `bin/build`     | Build the gem package                       |
-| `bin/console`   | Interactive console                         |
+| Command         | Description                                |
+| --------------- | ------------------------------------------ |
+| `bin/rake`      | Default task: test + rubocop + steep:check |
+| `bin/test`      | Run tests                                  |
+| `bin/lint`      | Check code style (pass `-a` to auto-fix)   |
+| `bin/typecheck` | Run Steep type checker                     |
+| `bin/rbs`       | Generate RBS type signatures               |
+| `bin/rbs-watch` | Watch and regenerate RBS files             |
+| `bin/docs`      | Build the docs site + API reference        |
+| `bin/build`     | Build the gem package                      |
+| `bin/console`   | Interactive console                        |
 
 `bin/rake <task>` is the escape hatch for any rake task without a named wrapper (e.g.
 `bin/rake test:slow`, `bin/rake release`).
@@ -138,7 +140,3 @@ All notable changes to this project are documented in `CHANGELOG.md`.
 ## License
 
 Licensed under the MIT License. See `LICENSE.txt` for details.
-
-## Maintainers
-
-- Jake Bottrall - https://github.com/bottrall

data/Rakefile

@@ -5,20 +5,40 @@ require "minitest/test_task"
 
 Minitest::TestTask.create
 
-require "standard/rake"
+require "rubocop/rake_task"
+
+RuboCop::RakeTask.new
+
 require "rdoc/task"
 
 RDoc::Task.new do |rdoc|
-  rdoc.rdoc_dir = "doc"
-  rdoc.title = "Riffer Documentation"
+  rdoc.rdoc_dir = "_site/api"
+  rdoc.title = "Riffer API Reference"
   rdoc.main = "README.md"
   rdoc.rdoc_files.include("README.md", "CHANGELOG.md", "LICENSE.txt")
   rdoc.rdoc_files.include("lib/**/*.rb")
   rdoc.options << "--charset" << "utf-8"
-  rdoc.options << "--page-dir" << "docs"
 end
 
-task docs: :rdoc
+namespace :docs do
+  desc "Build the docs site (landing, guides, 404, assets) into _site/"
+  task :site do
+    ruby "docs-site/build.rb"
+  end
+
+  desc "Build the docs site and validate all internal links and anchors"
+  task check: :site do
+    ruby "docs-site/check.rb"
+  end
+
+  desc "Build the docs site and serve it at http://localhost:8000"
+  task serve: :site do
+    ruby "-run -e httpd _site -p 8000"
+  end
+end
+
+desc "Build the full deployable docs tree (site + API reference) into _site/"
+task docs: %w[docs:site rdoc]
 
 namespace :rbs do
   desc "Generate RBS type signatures from inline annotations"
@@ -42,4 +62,4 @@ namespace :steep do
   end
 end
 
-task default: %i[test standard steep:check]
+task default: %i[test rubocop steep:check]

data/Steepfile

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 D = Steep::Diagnostic
 
 target :lib do

data/docs/{03_AGENTS.md → AGENTS.md}

@@ -126,18 +126,7 @@ end
 
 ### use_mcp
 
-Loads tools from registered [MCP](14_MCP.md) servers by tag. Like `uses_tools`, **`use_mcp` is not inherited**—add it on each subclass that should include MCP tools.
-
-### provider_options
-
-Passes options to the provider client:
-
-```ruby
-class MyAgent < Riffer::Agent
-  model 'openai/gpt-5-mini'
-  provider_options api_key: ENV['CUSTOM_OPENAI_KEY']
-end
-```
+Loads tools from registered [MCP](MCP.md) servers by tag. Like `uses_tools`, **`use_mcp` is not inherited**—add it on each subclass that should include MCP tools.
 
 ### model_options
 
@@ -263,7 +252,7 @@ class MyAgent < Riffer::Agent
 end
 ```
 
-Accepts a `Riffer::Tools::Runtime` subclass, a `Riffer::Tools::Runtime` instance, or a `Proc`. When unset, defaults to `Riffer.config.tool_runtime` (captured at agent class definition time). See [Tools — Tool Runtime](07_TOOL_ADVANCED.md#tool-runtime-experimental) for details.
+Accepts a `Riffer::Tools::Runtime` subclass, a `Riffer::Tools::Runtime` instance, or a `Proc`. When unset, defaults to `Riffer.config.tool_runtime` (captured at agent class definition time). See [Tools — Tool Runtime](TOOL_ADVANCED.md#tool-runtime-experimental) for details.
 
 ### guardrail
 
@@ -284,7 +273,7 @@ class MyAgent < Riffer::Agent
 end
 ```
 
-See [Guardrails](12_GUARDRAILS.md) for detailed documentation.
+See [Guardrails](GUARDRAILS.md) for detailed documentation.
 
 ## Configuration Object
 
@@ -333,7 +322,7 @@ Keys and values may be `String` or `Symbol`; both are stringified, and entries w
 Tags propagate to **two** places:
 
 1. The provider's native per-request metadata field (see the mapping below).
-2. Observability — stamped as `riffer.tag.<key>` on **every** span the call emits (`invoke_agent`, `chat`, `execute_tool`, `execute_guardrail`). See [Tracing](16_TRACING.md).
+2. Observability — stamped as `riffer.tag.<key>` on **every** span the call emits (`invoke_agent`, `chat`, `execute_tool`, `execute_guardrail`). See [Tracing](TRACING.md).
 
 ### Reserved key: `user_id`
 
@@ -361,12 +350,12 @@ Riffer does not validate tag count, key/value length, or charset — it forwards
 
 | Goal                          | Feature           | Guide                                                                |
 | ----------------------------- | ----------------- | -------------------------------------------------------------------- |
-| Call APIs or run functions    | Tools             | [Tools](06_TOOLS.md)                                                 |
+| Call APIs or run functions    | Tools             | [Tools](TOOLS.md)                                                 |
 | Return structured JSON        | Structured Output | [structured_output](#structured_output)                              |
-| Validate or filter content    | Guardrails        | [Guardrails](12_GUARDRAILS.md)                                       |
-| Measure output quality        | Evals             | [Evals](11_EVALS.md)                                                 |
-| Add packaged capabilities     | Skills            | [Skills](13_SKILLS.md)                                               |
-| Control the tool-use loop     | Agent Loop        | [Agent Loop](05_AGENT_LOOP.md)                                       |
-| Human-in-the-loop approval    | Interrupts        | [Agent Lifecycle](04_AGENT_LIFECYCLE.md#interrupting-the-agent-loop) |
-| Run tools concurrently        | Tool Runtime      | [Advanced Tools](07_TOOL_ADVANCED.md#tool-runtime-experimental)      |
-| Stream responses in real time | Streaming         | [Agent Lifecycle](04_AGENT_LIFECYCLE.md#stream)                      |
+| Validate or filter content    | Guardrails        | [Guardrails](GUARDRAILS.md)                                       |
+| Measure output quality        | Evals             | [Evals](EVALS.md)                                                 |
+| Add packaged capabilities     | Skills            | [Skills](SKILLS.md)                                               |
+| Control the tool-use loop     | Agent Loop        | [Agent Loop](AGENT_LOOP.md)                                       |
+| Human-in-the-loop approval    | Interrupts        | [Agent Lifecycle](AGENT_LIFECYCLE.md#interrupting-the-agent-loop) |
+| Run tools concurrently        | Tool Runtime      | [Advanced Tools](TOOL_ADVANCED.md#tool-runtime-experimental)      |
+| Stream responses in real time | Streaming         | [Agent Lifecycle](AGENT_LIFECYCLE.md#stream)                      |

data/docs/{04_AGENT_LIFECYCLE.md → AGENT_LIFECYCLE.md}

@@ -341,7 +341,7 @@ msg.structured_output?    # => true
 msg.structured_output     # => {sentiment: "positive", score: 0.95}
 ```
 
-See [Messages — Structured Output on Messages](08_MESSAGES.md#structured-output-on-messages) for details.
+See [Messages — Structured Output on Messages](MESSAGES.md#structured-output-on-messages) for details.
 
 ## Class Methods