riffer 0.41.0 → 0.42.0

data/sig/generated/riffer/registrable.rbs

@@ -0,0 +1,51 @@
+# Generated from lib/riffer/registrable.rb with RBS::Inline
+
+# Registry of a class's named direct subclasses, keyed by identifier. Extend it
+# onto a base class to look up subclasses in constant time via +find+ and +all+.
+#
+#   class Riffer::Tool
+#     extend Riffer::Registrable
+#   end
+#
+#   Riffer::Tool.find("weather_tool") # => WeatherTool
+#
+# @rbs module-self Class
+module Riffer::Registrable : Class
+  @identifier_registry: Hash[String, Class]?
+
+  # Finds a registered subclass by identifier, or +nil+ when none matches.
+  # Only *named direct* subclasses are registered: grandchildren are not
+  # visible to a grandparent's +find+ (call +find+ on their direct parent
+  # instead), anonymous classes are never registered, and duplicate identifiers
+  # raise Riffer::DuplicateIdentifierError at first lookup.
+  #
+  # --
+  # : (String | Symbol) -> Class?
+  def find: (String | Symbol) -> Class?
+
+  # Returns all registered subclasses. Only *named direct* subclasses are
+  # registered: grandchildren are not included (call +all+ on their direct
+  # parent instead), anonymous classes are never registered, and duplicate
+  # identifiers raise Riffer::DuplicateIdentifierError at first lookup.
+  #
+  # --
+  # : () -> Array[Class]
+  def all: () -> Array[Class]
+
+  private
+
+  # Ruby invokes +inherited+ with +self+ bound to the direct superclass — the
+  # only registry the new subclass joins — so busting self's memo is exactly
+  # sufficient.
+  # --
+  # : (Class) -> void
+  def inherited: (Class) -> void
+
+  # --
+  # : () -> Hash[String, Class]
+  def identifier_registry: () -> Hash[String, Class]
+
+  # --
+  # : () -> Hash[String, Class]
+  def build_identifier_registry: () -> Hash[String, Class]
+end

data/sig/generated/riffer/tool.rbs

@@ -18,6 +18,8 @@
 class Riffer::Tool
   extend Riffer::Tools::Toolable
 
+  extend Riffer::Registrable
+
   # Executes the tool with the given arguments.
   # --
   # : (context: Riffer::Agent::Context?, **untyped) -> Riffer::Tools::Response

data/sig/generated/riffer/tools/toolable.rbs

@@ -13,7 +13,9 @@
 #       required :input, String
 #     end
 #   end
-module Riffer::Tools::Toolable
+#
+# @rbs module-self Module
+module Riffer::Tools::Toolable : Module
   @kind: Symbol?
 
   @params_builder: Riffer::Params?

data/sig/generated/riffer.rbs

@@ -23,6 +23,10 @@ module Riffer
   class ToolExecutionError < Error
   end
 
+  # Raised when two registered subclasses share the same identifier.
+  class DuplicateIdentifierError < Error
+  end
+
   # Returns the Riffer configuration.
   #
   # --

data/sig/manual/riffer/agent.rbs

@@ -0,0 +1,7 @@
+# `Riffer::Agent` extends `Riffer::Registrable`, whose generic signatures return
+# `Class`. Narrow them here so callers get the agent singleton type back.
+class Riffer::Agent
+  def self.find: (String | Symbol) -> singleton(Riffer::Agent)?
+
+  def self.all: () -> Array[singleton(Riffer::Agent)]
+end

data/sig/manual/riffer/helpers/identifier.rbs

@@ -0,0 +1,5 @@
+# `Riffer::Helpers::Identifier` uses `extend self`; rbs-inline doesn't emit
+# that, so re-extend here to expose its instance methods as singleton methods.
+module Riffer::Helpers::Identifier
+  extend ::Riffer::Helpers::Identifier
+end

data/sig/manual/riffer/tool.rbs

@@ -0,0 +1,7 @@
+# `Riffer::Tool` extends `Riffer::Registrable`, whose generic signatures return
+# `Class`. Narrow them here so callers get the tool singleton type back.
+class Riffer::Tool
+  def self.find: (String | Symbol) -> singleton(Riffer::Tool)?
+
+  def self.all: () -> Array[singleton(Riffer::Tool)]
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: riffer
 version: !ruby/object:Gem::Version
-  version: 0.41.0
+  version: 0.42.0
 platform: ruby
 authors:
 - Jake Bottrall
@@ -41,19 +41,15 @@ extra_rdoc_files:
 - LICENSE.txt
 - README.md
 files:
-- ".agents/architecture.md"
-- ".agents/code-style.md"
-- ".agents/providers.md"
-- ".agents/rbs-inline.md"
-- ".agents/testing.md"
 - ".bundle/config"
+- ".claude/CLAUDE.md"
+- ".claude/rules/comments.md"
+- ".claude/rules/rbs-inline.md"
 - ".release-please-config.json"
 - ".release-please-manifest.json"
 - ".rubocop.yml"
 - ".ruby-version"
-- AGENTS.md
 - CHANGELOG.md
-- CLAUDE.md
 - CODE_OF_CONDUCT.md
 - Guardfile
 - LICENSE.txt
@@ -123,8 +119,8 @@ files:
 - lib/riffer/helpers.rb
 - lib/riffer/helpers/boolean.rb
 - lib/riffer/helpers/call_or_value.rb
-- lib/riffer/helpers/class_name_converter.rb
 - lib/riffer/helpers/dependencies.rb
+- lib/riffer/helpers/identifier.rb
 - lib/riffer/mcp.rb
 - lib/riffer/mcp/authenticated_tool.rb
 - lib/riffer/mcp/client.rb
@@ -157,6 +153,7 @@ files:
 - lib/riffer/providers/open_router.rb
 - lib/riffer/providers/repository.rb
 - lib/riffer/providers/token_usage.rb
+- lib/riffer/registrable.rb
 - lib/riffer/runner.rb
 - lib/riffer/runner/fibers.rb
 - lib/riffer/runner/sequential.rb
@@ -242,8 +239,8 @@ files:
 - sig/generated/riffer/helpers.rbs
 - sig/generated/riffer/helpers/boolean.rbs
 - sig/generated/riffer/helpers/call_or_value.rbs
-- sig/generated/riffer/helpers/class_name_converter.rbs
 - sig/generated/riffer/helpers/dependencies.rbs
+- sig/generated/riffer/helpers/identifier.rbs
 - sig/generated/riffer/mcp.rbs
 - sig/generated/riffer/mcp/authenticated_tool.rbs
 - sig/generated/riffer/mcp/client.rbs
@@ -276,6 +273,7 @@ files:
 - sig/generated/riffer/providers/open_router.rbs
 - sig/generated/riffer/providers/repository.rbs
 - sig/generated/riffer/providers/token_usage.rbs
+- sig/generated/riffer/registrable.rbs
 - sig/generated/riffer/runner.rbs
 - sig/generated/riffer/runner/fibers.rbs
 - sig/generated/riffer/runner/sequential.rbs
@@ -322,20 +320,22 @@ files:
 - sig/generated/riffer/version.rbs
 - sig/manifest.yaml
 - sig/manual/riffer.rbs
+- sig/manual/riffer/agent.rbs
 - sig/manual/riffer/agent/run.rbs
 - sig/manual/riffer/agent/serializer.rbs
 - sig/manual/riffer/agent/session/repair.rbs
 - sig/manual/riffer/evals/evaluator_runner.rbs
 - sig/manual/riffer/helpers/boolean.rbs
 - sig/manual/riffer/helpers/call_or_value.rbs
-- sig/manual/riffer/helpers/class_name_converter.rbs
 - sig/manual/riffer/helpers/dependencies.rbs
+- sig/manual/riffer/helpers/identifier.rbs
 - sig/manual/riffer/mcp.rbs
 - sig/manual/riffer/mcp/authenticated_tool.rbs
 - sig/manual/riffer/mcp/registry.rbs
 - sig/manual/riffer/mcp/tool_factory.rbs
 - sig/manual/riffer/providers.rbs
 - sig/manual/riffer/providers/repository.rbs
+- sig/manual/riffer/tool.rbs
 - sig/manual/riffer/tracing.rbs
 - sig/manual/riffer/tracing/capture.rbs
 - sig/manual/riffer/tracing/no_op.rbs

data/.agents/architecture.md

@@ -1,265 +0,0 @@
-# Architecture
-
-## Core Components
-
-### Agent (`lib/riffer/agent.rb`)
-
-Base class for AI agents. Subclass and use DSL methods `model`, `instructions`, `structured_output`, and `skills` to configure. Orchestrates message flow, LLM calls, tool execution, structured output parsing, and skill activation via a generate/stream loop.
-
-Class-level DSL settings live on a per-class `Riffer::Agent::Config` object accessible via `MyAgent.config`. DSL methods read and mutate this Config in place. Instances read from `@config`, which defaults to `self.class.config` but can be replaced via `Agent.new(config: ...)`.
-
-```ruby
-class EchoAgent < Riffer::Agent
-  model 'openai/gpt-5-mini' # provider/model
-  instructions 'You are an assistant that repeats what the user says.'
-end
-
-agent = EchoAgent.new
-puts agent.generate('Hello world')
-```
-
-`instructions` also accepts a Proc for dynamic instructions resolved at generate time. The Proc receives the `context` hash:
-
-```ruby
-class PersonalAgent < Riffer::Agent
-  model 'openai/gpt-5-mini'
-  instructions ->(context) { "You are assisting #{context[:name]}" }
-end
-
-PersonalAgent.generate('Hello!', context: { name: 'Jane' })
-```
-
-### Providers (`lib/riffer/providers/`)
-
-Adapters for LLM APIs. The base class uses a template-method pattern — `generate_text` and `stream_text` orchestrate the flow, delegating to five hook methods each provider implements:
-
-- `build_request_params(messages, model, options)` — convert messages, tools, and options into SDK params
-- `execute_generate(params)` — call the SDK and return the raw response
-- `execute_stream(params, yielder)` — call the streaming SDK, mapping events to the yielder
-- `extract_token_usage(response)` — pull token counts from the SDK response
-- `extract_content(response)` — extract text content from the SDK response
-- `extract_tool_calls(response)` — extract tool calls from the SDK response
-
-Providers are registered in `Riffer::Providers::Repository::REPO` with identifiers (e.g., `openai`, `amazon_bedrock`).
-
-Each provider declares a preferred skill adapter via `self.skills_adapter(model = nil)`. Default is Markdown; Anthropic returns XML; Amazon Bedrock returns XML when the model identifier matches an Anthropic model (e.g. `anthropic.claude-…` or `us.anthropic.claude-…`); Mock returns XML when the model name contains `claude`. The agent passes the resolved model identifier so proxy providers (Bedrock, Mock) can pick the right adapter without per-agent overrides.
-
-### Skills (`lib/riffer/skills/`)
-
-Support for the [Agent Skills spec](https://agentskills.io/). Skills are packaged as directories containing `SKILL.md` files with YAML frontmatter. The framework discovers skills through a pluggable backend, injects metadata into the system prompt, and provides a tool (`skill_activate`) for the LLM to load full skill instructions on demand.
-
-- `Config` - DSL configuration object (`backend`, `adapter`, `activate`)
-- `Backend` - base class interface (`list_skills`, `read_skill`)
-- `FilesystemBackend` - built-in filesystem scanner
-- `Frontmatter` - parsed YAML frontmatter value object with `.parse(raw)` class method
-- `Context` - coordinates discovery, activation, caching, and prompt rendering for a generation cycle
-- `Adapter` - base class for skill adapters (`render_catalog`, `activate_tool`)
-- `MarkdownAdapter` - default Markdown skill adapter
-- `XmlAdapter` - XML skill adapter for Anthropic/Claude
-- `ActivateTool` - default tool the LLM calls to activate a skill
-
-### Messages (`lib/riffer/messages/`)
-
-Typed message objects that extend `Riffer::Messages::Base`:
-
-- `System` - system instructions
-- `User` - user input (supports file attachments via `Riffer::Messages::FilePart`)
-- `Assistant` - AI responses
-- `Tool` - tool execution results
-
-`Riffer::Messages::FilePart` represents file attachments (images and documents) that can be included with User messages. Supports file paths, URLs, and raw base64 data.
-
-The `Converter` module handles hash-to-object conversion, including file hash-to-`FilePart` conversion.
-
-### StreamEvents (`lib/riffer/stream_events/`)
-
-Structured events for streaming responses:
-
-- `TextDelta` - incremental text chunks
-- `TextDone` - completion signals
-- `ReasoningDelta` - reasoning process chunks
-- `ReasoningDone` - reasoning completion
-- `WebSearchStatus` - web search status updates
-- `WebSearchDone` - web search completion with query and sources
-- `Interrupt` - callback interrupted the agent loop
-
-### Per-Call State Reset
-
-Each call to `generate` or `stream` resets `context`, tools, tool runtime, model, skills state, and the interrupted flag via `prepare_run`. Only the message history and cumulative `token_usage` persist across calls. This means `context:` must be passed on every call.
-
-### Stopping the Loop Early
-
-Two mechanisms can stop the agent loop before the LLM finishes naturally:
-
-**Guardrail tripwires** — declarative policy enforcement registered at class level. A `:before` guardrail can block the request before the LLM is called; an `:after` guardrail can block the response. Tripwires are not resumable — the caller must change the input and start over. `Response#blocked?` returns `true`.
-
-**Callback interrupts** — imperative flow control via `on_message` callbacks. Use `throw :riffer_interrupt` to pause the loop at any point. `Response#interrupted?` returns `true`. In streaming, yields an `Interrupt` event.
-
-### Resuming After an Interrupt
-
-Two resume paths:
-
-- **In-memory** — call `generate` or `stream` again with a string on the same agent instance. The message history is preserved and the new user message is appended.
-- **Cross-process** — pass persisted messages as an array to a new agent instance. Array input uses messages as-is (no system message prepend). Passing an array to an agent that already has messages raises `Riffer::ArgumentError`.
-
-```ruby
-agent.generate('Continue')              # in-memory resume
-MyAgent.new.stream(persisted_messages)  # cross-process resume
-```
-
-On resume, `execute_pending_tool_calls` detects tool calls from the last assistant message that lack corresponding tool result messages and executes them before entering the LLM loop. This handles the case where an interrupt fired mid-way through tool execution.
-
-### Runner (`lib/riffer/runner.rb`)
-
-Concurrency primitive for batch execution. Subclasses implement `#map(items, context: nil, &block)` to control how items are processed. The `context` keyword carries the agent's context hash, enabling runners that need it for job serialization or routing.
-
-Built-in runners:
-
-- `Sequential` — processes items in the current thread via `Array#map`
-- `Threaded` — processes items concurrently using a thread pool with configurable `max_concurrency`
-
-```ruby
-runner = Riffer::Runner::Threaded.new(max_concurrency: 3)
-runner.map(items, context: ctx) { |item| process(item) }
-```
-
-### Tools::Runtime (`lib/riffer/tools/runtime.rb`)
-
-Composes with a Runner to execute tool calls. Provides `#execute` as the public entry point and `#around_tool_call` as a hook for instrumentation. Passes the agent context through to the runner.
-
-Built-in runtimes:
-
-- `Inline` — uses `Runner::Sequential` (default)
-- `Threaded` — uses `Runner::Threaded`
-
-Context flow: `Agent#execute_tool_calls` → `Tools::Runtime#execute(tool_calls, tools:, context:)` → `Runner#map(tool_calls, context:) { dispatch }` → `Tool#call(context:, **args)`
-
-### 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/MCP.md`).
-
-```ruby
-Riffer::Mcp.register(
-  name: "github",
-  tags: [:github],
-  endpoint: "https://mcp.github.com",
-  discovery_headers: -> { {"Authorization" => "Bearer #{ENV['GITHUB_TOKEN']}"} }
-)
-
-# Optional: per-run tools/call headers (see docs/MCP.md)
-Riffer.configure { |c| c.mcp.credentials = ->(manifest:, matched_tags:, context:) { ... } }
-
-class ResearchAgent < Riffer::Agent
-  model "openai/gpt-5-mini"
-  use_mcp :github                      # picks up any :github-tagged registration
-  use_mcp :search, on_pending: :wait   # per-call override
-end
-```
-
-Key types: `Manifest` (`discovery_headers`, optional `credentials_scope` hint), `Registry` (thread-safe store), `Registration` (spawns discovery thread → `ToolFactory`), `Client` (wraps `mcp` gem), `AuthenticatedTool` (wraps MCP tools when `credentials` proc is set).
-
-**on_pending strategies** (global default `:ignore`): `:ignore` skips the server; `:wait` blocks until ready, re-raises failed discovery immediately, or times out; `:raise` re-raises failed discovery or `NotReadyError` while still pending.
-
-## Key Patterns
-
-- Model config accepts a `provider/model` string (e.g., `openai/gpt-5-mini`) or a Proc/lambda that returns one
-- Configuration via `Riffer.configure { |c| c.openai.api_key = "..." }`
-- Providers use `depends_on` helper for runtime dependency checking
-- Zeitwerk for autoloading - file structure must match module/class names
-
-## Project Structure
-
-```
-examples/
-  evaluators/            # Reference evaluator implementations (copy-paste)
-  guardrails/            # Reference guardrail implementations (copy-paste)
-lib/
-  riffer.rb              # Main entry point, uses Zeitwerk for autoloading
-  riffer/
-    version.rb           # VERSION constant
-    config.rb            # Configuration class
-    agent.rb             # Agent class
-    agent/
-      config.rb          # Per-class DSL configuration value object
-      session.rb         # Conversation handle (message array + invariants)
-      session/
-        repair.rb        # tool_use ↔ tool_result invariant repair
-      structured_output.rb # Structured output schema wrapper
-      structured_output/
-        result.rb        # Parse/validation result object
-    messages.rb          # Messages namespace/module
-    providers.rb         # Providers namespace/module
-    params.rb            # Parameter collection with DSL and validation
-    params/
-      param.rb           # Single parameter definition (shared by tools and structured output)
-      boolean.rb         # Boolean sentinel type
-    stream_events.rb     # Stream events namespace/module
-    skills.rb            # Skills namespace/module
-    skills/
-      config.rb          # DSL configuration object
-      adapter.rb         # Adapter base class (render_catalog, activate_tool)
-      markdown_adapter.rb # Default Markdown skill adapter
-      xml_adapter.rb     # XML skill adapter for Anthropic/Claude
-      backend.rb         # Backend base class (interface)
-      filesystem_backend.rb # Built-in filesystem backend
-      frontmatter.rb     # Parsed YAML frontmatter value object with .parse
-      context.rb         # Skills context for a generation cycle
-      activate_tool.rb   # Default skill_activate tool
-    helpers/
-      class_name_converter.rb  # Class name conversion utilities
-      dependencies.rb          # Dependency management
-    messages/
-      base.rb            # Base message class
-      assistant.rb       # Assistant message
-      converter.rb       # Message converter
-      system.rb          # System message
-      user.rb            # User message
-      tool.rb            # Tool message
-      file_part.rb       # File attachment (images and documents)
-    providers/
-      base.rb            # Base provider class
-      open_ai.rb         # OpenAI provider
-      amazon_bedrock.rb  # Amazon Bedrock provider
-      anthropic.rb       # Anthropic provider
-      repository.rb      # Provider registry
-      mock.rb            # Mock provider
-    stream_events/
-      base.rb            # Base stream event
-      interrupt.rb       # Interrupt event
-      text_delta.rb      # Text delta event
-      text_done.rb       # Text done event
-      reasoning_delta.rb # Reasoning delta event
-      reasoning_done.rb  # Reasoning done event
-      web_search_status.rb # Web search status event
-      web_search_done.rb   # Web search done event
-    mcp.rb               # MCP public API + error classes
-    mcp/
-      manifest.rb        # Server config value object
-      registry.rb        # Thread-safe global store
-      registration.rb    # Per-server state + discovery thread
-      client.rb          # Thin mcp gem wrapper
-      authenticated_tool.rb  # Wraps MCP tools when credentials proc is configured
-      tool_factory.rb    # Generates Riffer::Tool subclasses from MCP tools
-test/
-  test_helper.rb         # Minitest configuration with VCR
-  riffer_test.rb         # Main module tests
-  riffer/
-    [feature]_test.rb    # Feature tests mirror lib/riffer/ structure
-```
-
-## Configuration Example
-
-```ruby
-Riffer.configure do |config|
-  config.openai.api_key = ENV['OPENAI_API_KEY']
-end
-```
-
-## Streaming Example
-
-```ruby
-agent = EchoAgent.new
-agent.stream('Tell me a story').each do |event|
-  print event.content
-end
-```

data/.agents/code-style.md

@@ -1,110 +0,0 @@
-# Code Style
-
-## Formatting
-
-- 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
-
-All Ruby files in `lib/` must include:
-
-```ruby
-# frozen_string_literal: true
-# rbs_inline: enabled
-```
-
-## Error Handling
-
-Define custom errors as subclasses of `Riffer::Error`:
-
-```ruby
-class MyCustomError < Riffer::Error
-end
-```
-
-## Comments & Documentation
-
-A comment exists to explain a **why** the code itself cannot — never a **how**, and never a restatement of what the code already says. This bar governs all prose, from inline `#` comments to RDoc descriptions on the public API. Types are not prose's job: parameters, return values, and attribute/constant types live in rbs-inline `#:` annotations (see [rbs-inline.md](rbs-inline.md)).
-
-**What's a comment (in scope):** RDoc descriptions and inline `#` explanations. **Not comments (never touched):** rbs-inline `#:` annotations, magic comments (`frozen_string_literal`, `rbs_inline`), and RDoc directives (`:nodoc:`, `:nocov:`).
-
-### Public surface
-
-Everything public — classes, modules, constants, attributes, public methods, and `protected` subclass-contract methods (e.g. the `pass` / `transform` / `block` helpers a custom `Riffer::Guardrail` calls) — gets **at minimum a very brief description**:
-
-- **One verb-first sentence, one line.** `Creates a new agent.`, `Serializes the definition to JSON.`
-- An optional **second sentence is reserved strictly for a "why"** — a non-obvious constraint or rationale the code can't convey. Never a second sentence of "how".
-- If a description needs more than one sentence to say _what_ it does, that's a smell the method does too much.
-- **Exempt:** a constant whose name and value already carry the full meaning (`VERSION = "0.30.0"`, `PHASES = %i[before after]`) — describe a constant only when its name doesn't; an empty namespace module (a Zeitwerk placeholder with no usable members of its own, e.g. `module Riffer::Messages; end`) — its children are documented individually; and a constructor (`initialize`) — the class doc and RDoc's `::new` already cover plain construction, so describe it only when it carries a contract or non-obvious construction behavior (a raise, a dup guard).
-
-Do not document parameters or return values in prose — the `#:` line is the single source of truth for types. Attributes and constants still carry a brief description on the line above their inline `#:`.
-
-```ruby
-# Serializes the agent definition to a transferable JSON payload.
-#--
-#: (Riffer::Agent) -> String
-def serialize(agent)
-
-# The agent's display name.
-attr_reader :name #: String
-```
-
-### Private methods
-
-A comment survives on a private method **only** if it explains a why a competent reader cannot recover from the code and names alone — a non-local constraint, an external-system quirk, a deliberate non-obvious tradeoff. A description of what it does, or a why that's evident from the code, gets cut.
-
-### Inline comments
-
-Same bar: kept only to explain the why of something genuinely ambiguous. `TODO` / `FIXME` / `HACK` markers are tracked work and stay; `NOTE` / `REVIEW` are subject to the why-rule.
-
-### No history
-
-A comment describes the present, never how the code got there. Change narration — "was X, now Y", "previously used Z" — has no place; the reader cares about what is, not what was. The one thing worth stating is a still-true constraint, and it belongs in the present tense ("the API returns null for empty results — guard"), never told as the story of the bug that revealed it.
-
-### RDoc mechanics
-
-**The `#--` stop directive.** Place `#--` on the line immediately before a **standalone** `#:` type annotation. Without it, RDoc treats `#:` as a label-list marker and corrupts the preceding description into a `<pre>` block. Inline `#:` on the same line as code (attributes, constants) does not need it.
-
-**Raises.** Document a raise **only when it's part of the caller's contract** — something a caller should reasonably anticipate and handle. Skip programmer-error guards and "should never happen" assertions. Reserved for public methods. When the raise condition merely restates the declared `#:` type, phrase it by intent ("Raises Riffer::ArgumentError on an invalid value") rather than re-listing the type union — but keep the runtime constraints a type can't express (enum value sets, coercion rules, validation failure).
-
-```ruby
-# Builds a param from a schema hash.
-# Raises Riffer::ArgumentError if the schema is missing a +type+.
-```
-
-**Examples.** Include an example only when a **consumer is likely to use the thing themselves** — a public entry point they construct, subclass, or call (an `Agent` subclass, `Riffer::Mcp.register`, the `params` DSL). Skip examples on framework-internal types even though they're technically public (value objects the framework constructs and hands back, internal engines). When included, keep them sparing — only when they teach something the signature can't — and write them as indented code blocks (2 extra spaces of indent). Usage walkthroughs belong in `docs/`.
-
-**Inline code formatting.** Use `+word+` for single-word inline code; for multi-word expressions (spaces, colons, brackets) use `<tt>multi word expression</tt>`, e.g. `Equivalent to <tt>throw :riffer_interrupt, reason</tt>`.
-
-**Internal APIs.** Mark with `:nodoc:` to exclude from generated documentation:
-
-```ruby
-def internal_method # :nodoc:
-end
-```
-
-## Hash Key Convention
-
-- Use **symbol keys** for all internal hashes
-- Use `JSON.parse(str, symbolize_names: true)` at parse boundaries — never `JSON.parse` followed by `transform_keys(&:to_sym)`
-- String keys are only used at serialization boundaries (JSON Schema output, external API payloads)
-- Do not write dual-access patterns like `hash[:key] || hash["key"]` — normalize to symbol keys at the boundary instead
-
-## Reserved Tool Identifiers
-
-- Internal-use-only tools use plain descriptive names without a prefix (e.g. `mcp_search`, `mcp_call`, `evaluation`, `skill_activate`)
-
-## Module Structure
-
-```ruby
-# frozen_string_literal: true
-
-module Riffer::Feature
-  class MyClass
-    # Implementation
-  end
-end
-```

data/.agents/providers.md

@@ -1,54 +0,0 @@
-# Adding a New Provider
-
-## Steps
-
-1. Create `lib/riffer/providers/your_provider.rb` extending `Riffer::Providers::Base`
-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 — 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:
-
-```
-generate_text
-  ├─ build_request_params
-  ├─ execute_generate
-  ├─ extract_content
-  ├─ extract_tool_calls
-  └─ extract_token_usage
-
-stream_text
-  ├─ build_request_params
-  └─ execute_stream
-```
-
-## Registration
-
-Add to `Riffer::Providers::Repository::REPO`:
-
-```ruby
-REPO = {
-  # ... existing providers
-  your_provider: -> { YourProvider }
-}.freeze
-```
-
-## Dependencies
-
-Use `depends_on` helper for runtime dependency checking if your provider requires external gems.
-
-## Reference
-
-For hook method signatures, structured output handling, file handling, and complete examples, see [Custom Providers](../docs/providers/CUSTOM_PROVIDERS.md).