riffer 0.31.0 → 0.32.0

data/lib/riffer/providers/base.rb

@@ -3,35 +3,17 @@
 
 require "json"
 
-# Base class for all LLM providers in the Riffer framework.
-#
-# Provides a template-method flow for text generation and streaming.
-# Subclasses implement five hook methods; the base class orchestrates them.
-#
-# ==== Hook methods
-#
-# [build_request_params] convert messages, tools, and options into SDK params
-# [execute_generate] call the SDK and return the raw response
-# [execute_stream] call the streaming SDK, mapping events to the yielder
-# [extract_token_usage] pull token counts from the SDK response
-# [extract_content] extract text content from the SDK response
-# [extract_tool_calls] extract tool calls from the SDK response
+# Base class for all LLM providers. A template-method flow: subclasses implement
+# the hooks (+build_request_params+, +execute_generate+, +execute_stream+,
+# +extract_token_usage+, +extract_content+, +extract_tool_calls+) and the base
+# class orchestrates them.
 class Riffer::Providers::Base
   # @rbs @current_tools: Array[singleton(Riffer::Tool)]
 
-  include Riffer::Helpers::Dependencies
-  include Riffer::Messages::Converter
-
   WIRE_SEPARATOR = "__" #: String
 
-  # Returns the preferred skill adapter for this provider.
-  #
-  # Override in subclasses for provider-specific formats. Subclasses may
-  # introspect +model+ (the resolved model identifier, e.g. the part after
-  # +provider/+) to pick an adapter that matches the underlying model
-  # family — useful for proxy providers like Amazon Bedrock that host
-  # models from multiple vendors.
-  #
+  # Returns the preferred skill adapter for this provider; override in
+  # subclasses (optionally introspecting +model+) for provider-specific formats.
   #--
   #: (?String?) -> singleton(Riffer::Skills::Adapter)
   def self.skills_adapter(model = nil)
@@ -82,6 +64,11 @@ class Riffer::Providers::Base
 
   private
 
+  #: (String) -> true
+  def depends_on(gem_name)
+    Riffer::Helpers::Dependencies.depends_on(gem_name)
+  end
+
   #--
   #: (String) -> String
   def encode_tool_name(name)
@@ -175,12 +162,12 @@ class Riffer::Providers::Base
     end
 
     if messages
-      return messages.map { |msg| convert_to_message_object(msg) }
+      return messages.map { |msg| Riffer::Messages::Base.from_hash(msg) }
     end
 
     result = [] #: Array[Riffer::Messages::Base]
     result << Riffer::Messages::System.new(system) if system
-    file_parts = (files || []).map { |f| convert_to_file_part(f) }
+    file_parts = (files || []).map { |f| Riffer::Messages::FilePart.from_hash(f) }
     prompt_text = prompt #: String
     result << Riffer::Messages::User.new(prompt_text, files: file_parts)
     result

data/lib/riffer/providers/gemini.rb

@@ -17,8 +17,6 @@ class Riffer::Providers::Gemini < Riffer::Providers::Base
   DEFAULT_OPEN_TIMEOUT = 10 #: Integer
   DEFAULT_READ_TIMEOUT = 60 #: Integer
 
-  # Initializes the Gemini provider.
-  #
   #--
   #: (?api_key: String?, ?open_timeout: Integer?, ?read_timeout: Integer?, **untyped) -> void
   def initialize(api_key: nil, open_timeout: nil, read_timeout: nil, **options)
@@ -107,7 +105,8 @@ class Riffer::Providers::Gemini < Riffer::Providers::Base
 
     Riffer::Providers::TokenUsage.new(
       input_tokens: usage[:promptTokenCount] || 0,
-      output_tokens: usage[:candidatesTokenCount] || 0
+      output_tokens: usage[:candidatesTokenCount] || 0,
+      cache_read_tokens: usage[:cachedContentTokenCount]
     )
   end
 
@@ -163,7 +162,8 @@ class Riffer::Providers::Gemini < Riffer::Providers::Base
           yielder << Riffer::StreamEvents::TokenUsageDone.new(
             token_usage: Riffer::Providers::TokenUsage.new(
               input_tokens: usage[:promptTokenCount] || 0,
-              output_tokens: usage[:candidatesTokenCount] || 0
+              output_tokens: usage[:candidatesTokenCount] || 0,
+              cache_read_tokens: usage[:cachedContentTokenCount]
             )
           )
         end

data/lib/riffer/providers/mock.rb

@@ -1,22 +1,14 @@
 # frozen_string_literal: true
 # rbs_inline: enabled
 
-# Mock provider for mocking LLM responses in tests.
-#
-# No external gems required.
+# Mock provider for mocking LLM responses in tests; no external gems required.
 class Riffer::Providers::Mock < Riffer::Providers::Base
   # @rbs @responses: Array[Hash[Symbol, untyped]]
   # @rbs @current_index: Integer
   # @rbs @stubbed_responses: Array[Hash[Symbol, untyped]]
 
-  # Returns the preferred skill adapter for the given mock model.
-  #
-  # Mock is used to stand in for any real provider in tests, so the model
-  # string itself is the only signal we have. When the model name contains
-  # +claude+ (e.g. +mock/claude-sonnet-4-6+), pick the XML adapter to
-  # mirror what a real Claude-backed provider would do; otherwise fall
-  # back to Markdown.
-  #
+  # Returns the skill adapter for the mock model — XML when the model name
+  # contains +claude+ (mirroring a real Claude provider), else Markdown.
   #--
   #: (?String?) -> singleton(Riffer::Skills::Adapter)
   def self.skills_adapter(model = nil)
@@ -27,13 +19,8 @@ class Riffer::Providers::Mock < Riffer::Providers::Base
   # Array of recorded method calls for assertions.
   attr_reader :calls #: Array[Hash[Symbol, untyped]]
 
-  # Initializes the mock provider.
-  #
-  # +responses:+ accepts an array of response hashes in the same shape
-  # +#stub_response+ takes — raw +tool_calls:+ hashes are normalised to
-  # +Riffer::Messages::Assistant::ToolCall+ instances. This is the canonical
-  # way to pre-configure canned LLM responses on an agent via
-  # +provider_options responses: [...]+.
+  # +responses:+ pre-configures canned responses (same shape as
+  # +#stub_response+), typically set via +provider_options responses: [...]+.
   #
   #   Riffer::Providers::Mock.new(responses: [
   #     {content: "", tool_calls: [{name: "tool_a", arguments: "{}"}]},
@@ -49,9 +36,7 @@ class Riffer::Providers::Mock < Riffer::Providers::Base
     @stubbed_responses = []
   end
 
-  # Stubs the next response from the provider.
-  #
-  # Can be called multiple times to queue responses.
+  # Stubs the next response; call repeatedly to queue several.
   #
   #   provider.stub_response("Hello")
   #   provider.stub_response("", tool_calls: [{name: "my_tool", arguments: '{"key":"value"}'}])
@@ -73,11 +58,6 @@ class Riffer::Providers::Mock < Riffer::Providers::Base
 
   private
 
-  # Normalises a response hash into Mock's internal format. Accepts the
-  # +#stub_response+ kwargs shape (+content:+, +tool_calls:+, +token_usage:+)
-  # or a pre-built hash with already-converted ToolCall instances. Raw
-  # +tool_calls:+ hashes are wrapped in +Riffer::Messages::Assistant::ToolCall+.
-  #
   #--
   #: (Hash[Symbol, untyped]) -> Hash[Symbol, untyped]
   def normalize_response(response)

data/lib/riffer/providers/open_ai.rb

@@ -1,14 +1,10 @@
 # frozen_string_literal: true
 # rbs_inline: enabled
 
-# OpenAI provider for GPT models.
-#
-# Requires the +openai+ gem to be installed.
+# OpenAI provider for GPT models. Requires the +openai+ gem.
 class Riffer::Providers::OpenAI < Riffer::Providers::Base
   WEB_SEARCH_TOOL_TYPE = "web_search_preview" #: String
 
-  # Initializes the OpenAI provider.
-  #
   #--
   #: (**untyped) -> void
   def initialize(**options)
@@ -80,7 +76,8 @@ class Riffer::Providers::OpenAI < Riffer::Providers::Base
 
     Riffer::Providers::TokenUsage.new(
       input_tokens: usage.input_tokens,
-      output_tokens: usage.output_tokens
+      output_tokens: usage.output_tokens,
+      cache_read_tokens: usage.input_tokens_details&.cached_tokens
     )
   end
 
@@ -229,7 +226,8 @@ class Riffer::Providers::OpenAI < Riffer::Providers::Base
     yielder << Riffer::StreamEvents::TokenUsageDone.new(
       token_usage: Riffer::Providers::TokenUsage.new(
         input_tokens: usage.input_tokens,
-        output_tokens: usage.output_tokens
+        output_tokens: usage.output_tokens,
+        cache_read_tokens: usage.input_tokens_details&.cached_tokens
       )
     )
   end
@@ -251,7 +249,7 @@ class Riffer::Providers::OpenAI < Riffer::Providers::Base
       yielder << Riffer::StreamEvents::WebSearchStatus.new("open_page", url: action.url)
     when ::OpenAI::Models::Responses::ResponseFunctionWebSearch::Action::Search
       sources = (action.sources || []).map { |s| {title: nil, url: s.url} }
-      yielder << Riffer::StreamEvents::WebSearchDone.new(action.query, sources: sources)
+      yielder << Riffer::StreamEvents::WebSearchDone.new(action.query || "", sources: sources)
     end
   end
 

data/lib/riffer/providers/open_router.rb

@@ -3,19 +3,13 @@
 
 require "json"
 
-# OpenRouter provider for the OpenRouter unified gateway (https://openrouter.ai).
-#
-# Requires the +openai+ gem to be installed. OpenRouter exposes an
-# OpenAI-compatible Chat Completions endpoint, so this provider reuses
-# the OpenAI Ruby SDK with a +base_url+ override.
-#
-# The +api_key+ falls back to <tt>Riffer.config.openrouter.api_key</tt>
-# and then to +OPENROUTER_API_KEY+.
+# OpenRouter provider (https://openrouter.ai). Requires the +openai+ gem —
+# OpenRouter exposes an OpenAI-compatible endpoint, so this reuses the OpenAI
+# SDK with a +base_url+ override. +api_key+ falls back to config, then
+# +OPENROUTER_API_KEY+.
 class Riffer::Providers::OpenRouter < Riffer::Providers::Base
   BASE_URL = "https://openrouter.ai/api/v1" #: String
 
-  # Initializes the OpenRouter provider.
-  #
   #--
   #: (?api_key: String?, **untyped) -> void
   def initialize(api_key: nil, **options)

data/lib/riffer/providers/repository.rb

@@ -2,8 +2,9 @@
 # rbs_inline: enabled
 
 # Registry for finding provider classes by identifier.
-class Riffer::Providers::Repository
-  # Mapping of provider identifiers to provider class lambdas.
+module Riffer::Providers::Repository
+  extend self
+
   REPO = {
     amazon_bedrock: -> { Riffer::Providers::AmazonBedrock },
     anthropic: -> { Riffer::Providers::Anthropic },
@@ -18,7 +19,7 @@ class Riffer::Providers::Repository
   #
   #--
   #: ((String | Symbol)) -> singleton(Riffer::Providers::Base)?
-  def self.find(identifier)
+  def find(identifier)
     REPO.fetch(identifier.to_sym, nil)&.call
   end
 end

data/lib/riffer/providers/token_usage.rb

@@ -2,14 +2,6 @@
 # rbs_inline: enabled
 
 # Represents token usage data from an LLM API call.
-#
-# Tracks input tokens, output tokens, and optional cache statistics.
-#
-#   token_usage = Riffer::Providers::TokenUsage.new(input_tokens: 100, output_tokens: 50)
-#   token_usage.total_tokens  # => 150
-#
-#   combined = token_usage1 + token_usage2  # Combine multiple token usage objects
-#
 class Riffer::Providers::TokenUsage
   # Number of tokens in the input/prompt.
   attr_reader :input_tokens #: Integer
@@ -17,18 +9,18 @@ class Riffer::Providers::TokenUsage
   # Number of tokens in the output/response.
   attr_reader :output_tokens #: Integer
 
-  # Number of tokens written to cache (Anthropic-specific).
-  attr_reader :cache_creation_tokens #: Integer?
+  # Number of tokens written to cache, when the provider reports it.
+  attr_reader :cache_write_tokens #: Integer?
 
-  # Number of tokens read from cache (Anthropic-specific).
+  # Number of tokens read from cache, when the provider reports it.
   attr_reader :cache_read_tokens #: Integer?
 
   #--
-  #: (input_tokens: Integer, output_tokens: Integer, ?cache_creation_tokens: Integer?, ?cache_read_tokens: Integer?) -> void
-  def initialize(input_tokens:, output_tokens:, cache_creation_tokens: nil, cache_read_tokens: nil)
+  #: (input_tokens: Integer, output_tokens: Integer, ?cache_write_tokens: Integer?, ?cache_read_tokens: Integer?) -> void
+  def initialize(input_tokens:, output_tokens:, cache_write_tokens: nil, cache_read_tokens: nil)
     @input_tokens = input_tokens
     @output_tokens = output_tokens
-    @cache_creation_tokens = cache_creation_tokens
+    @cache_write_tokens = cache_write_tokens
     @cache_read_tokens = cache_read_tokens
   end
 
@@ -48,20 +40,17 @@ class Riffer::Providers::TokenUsage
     Riffer::Providers::TokenUsage.new(
       input_tokens: input_tokens + other.input_tokens,
       output_tokens: output_tokens + other.output_tokens,
-      cache_creation_tokens: add_nullable(cache_creation_tokens, other.cache_creation_tokens),
+      cache_write_tokens: add_nullable(cache_write_tokens, other.cache_write_tokens),
       cache_read_tokens: add_nullable(cache_read_tokens, other.cache_read_tokens)
     )
   end
 
-  # Converts the token usage to a hash representation.
-  #
-  # Cache tokens are omitted if nil.
-  #
+  # Converts the token usage to a hash; cache tokens are omitted when nil.
   #--
   #: () -> Hash[Symbol, Integer]
   def to_h
     hash = {input_tokens: input_tokens, output_tokens: output_tokens}
-    hash[:cache_creation_tokens] = cache_creation_tokens if cache_creation_tokens
+    hash[:cache_write_tokens] = cache_write_tokens if cache_write_tokens
     hash[:cache_read_tokens] = cache_read_tokens if cache_read_tokens
     hash
   end

data/lib/riffer/providers.rb

@@ -1,13 +1,5 @@
 # frozen_string_literal: true
 # rbs_inline: enabled
 
-# Namespace for LLM provider adapters in the Riffer framework.
-#
-# Providers connect Riffer to LLM services:
-# - Riffer::Providers::OpenAI - OpenAI GPT models
-# - Riffer::Providers::AzureOpenAI - Azure OpenAI GPT models
-# - Riffer::Providers::AmazonBedrock - AWS Bedrock models
-# - Riffer::Providers::OpenRouter - OpenRouter unified gateway
-# - Riffer::Providers::Mock - Mock provider for testing
 module Riffer::Providers
 end

data/lib/riffer/runner/fibers.rb

@@ -2,25 +2,12 @@
 # rbs_inline: enabled
 
 # Processes items concurrently using fibers via the +async+ gem.
-#
-# All items run as fibers simultaneously by default. When
-# +max_concurrency+ is set, an <tt>Async::Semaphore</tt> limits how many
-# fibers execute at once.
-#
-# If multiple fibers raise, only the first exception is re-raised
-# after all fibers finish; subsequent errors are discarded.
-#
-#   runner = Riffer::Runner::Fibers.new
-#   runner.map(items) { |item| expensive_operation(item) }
-#
+# +max_concurrency+ caps simultaneous fibers via an <tt>Async::Semaphore</tt>.
+# If multiple fibers raise, only the first exception is re-raised after all
+# finish.
 class Riffer::Runner::Fibers < Riffer::Runner
   # @rbs @max_concurrency: Integer?
 
-  include Riffer::Helpers::Dependencies
-
-  # [max_concurrency] maximum number of fibers to run simultaneously.
-  #   When +nil+, all fibers run without limit.
-  #
   #--
   #: (?max_concurrency: Integer?) -> void
   def initialize(max_concurrency: nil)
@@ -62,4 +49,11 @@ class Riffer::Runner::Fibers < Riffer::Runner
 
     results
   end
+
+  private
+
+  #: (String) -> true
+  def depends_on(gem_name)
+    Riffer::Helpers::Dependencies.depends_on(gem_name)
+  end
 end

data/lib/riffer/runner/sequential.rb

@@ -1,10 +1,7 @@
 # frozen_string_literal: true
 # rbs_inline: enabled
 
-# Processes items sequentially in the current thread.
-#
-# This is the default runner used when no concurrency is needed.
-#
+# Processes items sequentially in the current thread — the default runner.
 class Riffer::Runner::Sequential < Riffer::Runner
   #--
   #: (Array[untyped], context: Riffer::Agent::Context?) { (untyped) -> untyped } -> Array[untyped]

data/lib/riffer/runner/threaded.rb

@@ -1,25 +1,14 @@
 # frozen_string_literal: true
 # rbs_inline: enabled
 
-# Processes items concurrently using a thread pool.
-#
-# Maintains up to +max_concurrency+ worker threads that pull items from
-# a shared queue. When a worker finishes one item it immediately picks
-# up the next, so a single slow item does not block other workers.
-#
-# If multiple workers raise, only the first exception is re-raised
-# after all workers finish; subsequent errors are discarded.
-#
-#   runner = Riffer::Runner::Threaded.new(max_concurrency: 3)
-#   runner.map(items) { |item| expensive_operation(item) }
-#
+# Processes items concurrently using a thread pool of up to +max_concurrency+
+# workers pulling from a shared queue, so a slow item doesn't block others. If
+# multiple workers raise, only the first exception is re-raised after all finish.
 class Riffer::Runner::Threaded < Riffer::Runner
   # @rbs @max_concurrency: Integer
 
   DEFAULT_MAX_CONCURRENCY = 5 #: Integer
 
-  # [max_concurrency] maximum number of threads to run simultaneously.
-  #
   #--
   #: (?max_concurrency: Integer) -> void
   def initialize(max_concurrency: DEFAULT_MAX_CONCURRENCY)

data/lib/riffer/runner.rb

@@ -1,23 +1,10 @@
 # frozen_string_literal: true
 # rbs_inline: enabled
 
-# Generic concurrency primitive for batch execution.
-#
-# Subclasses implement +map+ to control how items are processed
-# (sequentially, threaded, etc.).
-#
-#   runner = Riffer::Runner::Sequential.new
-#   runner.map([1, 2, 3], context: ctx) { |n| n * 2 }
-#   # => [2, 4, 6]
-#
+# Generic concurrency primitive for batch execution. Subclasses implement
+# +map+ to control how items are processed.
 class Riffer::Runner
   # Maps over items using the provided block.
-  #
-  # [items] the items to process.
-  # [context] context hash forwarded from the agent.
-  #
-  # Raises NotImplementedError if not implemented by subclass.
-  #
   #--
   #: (Array[untyped], context: Riffer::Agent::Context?) { (untyped) -> untyped } -> Array[untyped]
   def map(items, context:, &block)

data/lib/riffer/skills/activate_tool.rb

@@ -1,12 +1,8 @@
 # frozen_string_literal: true
 # rbs_inline: enabled
 
-# Tool for the LLM to activate a skill and receive its full instructions.
-#
-# Registered automatically when an agent has skills configured.
-# The LLM calls this when a task matches an available skill's description.
-#
-# See Riffer::Skills::Context.
+# Tool the LLM calls to activate a skill and receive its instructions;
+# registered automatically when an agent has skills configured.
 class Riffer::Skills::ActivateTool < Riffer::Tool
   identifier "skill_activate"
   description "Activates a skill and returns its instructions. " \
@@ -18,11 +14,6 @@ class Riffer::Skills::ActivateTool < Riffer::Tool
   end
 
   # Activates a skill by name and returns its body.
-  #
-  # [context] the agent's +Riffer::Agent::Context+, exposing +#skills+
-  #           (a +Riffer::Skills::Context+).
-  # [name] the skill name to activate.
-  #
   #--
   #: (context: Riffer::Agent::Context?, name: String) -> Riffer::Tools::Response
   def call(context:, name:)

data/lib/riffer/skills/adapter.rb

@@ -1,27 +1,14 @@
 # frozen_string_literal: true
 # rbs_inline: enabled
 
-# Base class defining the interface for skill adapters.
-#
-# A skill adapter encapsulates the provider-specific catalog rendering for
-# skills — how the available-skills section appears in the system prompt.
-#
-# Subclass and override +render_catalog+. The activation tool is set at
-# construction time and is exposed via +#skill_activate_tool+ for use in
-# rendered output.
-#
-# See Riffer::Skills::MarkdownAdapter for the default implementation.
-# See Riffer::Skills::XmlAdapter for the Anthropic/Claude variant.
+# Interface for skill adapters — provider-specific rendering of the
+# available-skills section in the system prompt. Subclass and override
+# +render_catalog+; the activation tool is exposed via +#skill_activate_tool+
+# for the rendered output.
 class Riffer::Skills::Adapter
   # The activation tool class for this adapter.
   attr_reader :skill_activate_tool #: singleton(Riffer::Tool)
 
-  # Creates a new adapter.
-  #
-  # [skill_activate_tool] the activation tool class — referenced by name
-  #                       in the rendered catalog so the LLM knows which
-  #                       tool to call.
-  #
   #--
   #: (skill_activate_tool: singleton(Riffer::Tool)) -> void
   def initialize(skill_activate_tool:)
@@ -29,11 +16,6 @@ class Riffer::Skills::Adapter
   end
 
   # Renders a skill catalog section for the system prompt.
-  #
-  # [skills] array of Frontmatter objects to render.
-  #
-  # Raises NotImplementedError if not implemented by subclass.
-  #
   #--
   #: (Array[Riffer::Skills::Frontmatter]) -> String
   def render_catalog(skills)

data/lib/riffer/skills/backend.rb

@@ -1,38 +1,24 @@
 # frozen_string_literal: true
 # rbs_inline: enabled
 
-# Base class defining the interface for skill storage backends.
-#
-# Subclass and implement +list_skills+ and +read_skill+ to provide
-# custom skill storage (database, S3, etc.).
-#
-# Use Riffer::Skills::Frontmatter.parse to parse raw SKILL.md content.
-#
-# See Riffer::Skills::FilesystemBackend for the built-in implementation.
+# Interface for skill storage backends. Subclass and implement +list_skills+
+# and +read_skill+ for custom storage (database, S3, etc.); use
+# Riffer::Skills::Frontmatter.parse on raw SKILL.md content.
 class Riffer::Skills::Backend
   SKILL_FILENAME = "SKILL.md" #: String
 
   def initialize = nil
 
-  # Returns frontmatter for all available skills.
-  #
-  # Called once at the start of generate/stream.
-  #
-  # Raises NotImplementedError if not implemented by subclass.
-  #
+  # Returns frontmatter for all available skills; called once at the start of
+  # generate/stream.
   #--
   #: () -> Array[Riffer::Skills::Frontmatter]
   def list_skills
     raise NotImplementedError, "#{self.class} must implement #list_skills"
   end
 
-  # Returns the full SKILL.md body (without frontmatter) for a skill.
-  #
-  # [name] the skill name to read.
-  #
-  # Raises NotImplementedError if not implemented by subclass.
-  # Raises Riffer::ArgumentError if skill not found.
-  #
+  # Returns the full SKILL.md body (without frontmatter) for a skill. Raises
+  # Riffer::ArgumentError if the skill is not found.
   #--
   #: (String) -> String
   def read_skill(name)

data/lib/riffer/skills/config.rb

@@ -3,8 +3,6 @@
 
 # Configuration object for the skills block DSL.
 #
-# Used inside the +skills+ block on Riffer::Agent:
-#
 #   skills do
 #     backend Riffer::Skills::FilesystemBackend.new(".skills")
 #     adapter Riffer::Skills::XmlAdapter
@@ -16,8 +14,6 @@ class Riffer::Skills::Config
   # @rbs @activate: (Array[String] | Proc)?
   # @rbs @activate_tool: singleton(Riffer::Tool)?
 
-  # Creates a new Config with all options unset.
-  #
   #--
   #: () -> void
   def initialize
@@ -27,11 +23,7 @@ class Riffer::Skills::Config
     @activate_tool = nil
   end
 
-  # Gets or sets the skills backend.
-  #
-  # Accepts a Riffer::Skills::Backend instance, or a Proc that receives
-  # +context+ and returns a Backend.
-  #
+  # Gets or sets the skills backend (a Backend or a +context+-resolved Proc).
   #--
   #: (?(Riffer::Skills::Backend | Proc)?) -> (Riffer::Skills::Backend | Proc)?
   def backend(value = nil)
@@ -39,11 +31,8 @@ class Riffer::Skills::Config
     @backend = value
   end
 
-  # Gets or sets a custom skill adapter class.
-  #
-  # Must be a subclass of Riffer::Skills::Adapter.
-  # Defaults to the provider's preferred adapter.
-  #
+  # Gets or sets a custom skill adapter class; defaults to the provider's
+  # preferred adapter.
   #--
   #: (?singleton(Riffer::Skills::Adapter)?) -> singleton(Riffer::Skills::Adapter)?
   def adapter(value = nil)
@@ -51,14 +40,9 @@ class Riffer::Skills::Config
     @adapter = value
   end
 
-  # Gets or sets skill names to activate at startup.
-  #
-  # Activated skills have their full body included in the system prompt
-  # without requiring a tool call.
-  #
-  # Accepts an array of skill name strings or a Proc that receives
-  # +context+ and returns an array of names.
-  #
+  # Gets or sets skill names to activate at startup (an array or a
+  # +context+-resolved Proc); activated skills' bodies are included in the
+  # system prompt without a tool call.
   #--
   #: (?(Array[String] | Proc)?) -> (Array[String] | Proc)?
   def activate(value = nil)
@@ -66,15 +50,10 @@ class Riffer::Skills::Config
     @activate = value
   end
 
-  # Gets or sets the per-agent override for the skill activation tool class.
-  #
-  # Returns the configured override when set, or +nil+ when unset. The
-  # global fallback to <tt>Riffer.config.skills.default_activate_tool</tt>
-  # is applied by the agent at resolution time (see
-  # Riffer::Agent#resolve_tools), not by this getter.
-  #
-  # The override must be a subclass of Riffer::Tool.
-  #
+  # Gets or sets the per-agent skill activation tool override, or +nil+ when
+  # unset — the global fallback to <tt>Riffer.config.skills.default_activate_tool</tt>
+  # is applied by the agent at resolution, not here. Raises Riffer::ArgumentError
+  # on an invalid value.
   #--
   #: (?singleton(Riffer::Tool)?) -> singleton(Riffer::Tool)?
   def activate_tool(value = nil)